µGFX  2.9
version 2.9
Widget

Detailed Description

The basic widget implementation (base class).

A widget is a Window that supports interacting with the user via an input device such as a mouse or toggle buttons. It is the base class for widgets such as buttons and sliders.

Precondition
GFX_USE_GWIN and GWIN_NEED_WIDGET must be set to GFXON in your gfxconf.h

Data Structures

struct  GColorSet
 The GColorSet structure. More...
 
struct  GWidgetStyle
 The GWidgetStyle structure. More...
 
struct  GWidgetInit
 The structure to initialise a widget. More...
 
struct  GWidgetObject
 The GWIN Widget structure. More...
 
struct  GEventGWin
 A Generic GWIN Event. More...
 

Functions

void gwinWidgetClearInit (GWidgetInit *pwi)
 Clear a GWidgetInit structure to all zero's. More...
 
void gwinSetDefaultStyle (const GWidgetStyle *pstyle, gBool updateAll)
 Set the default style for widgets created hereafter. More...
 
const GWidgetStylegwinGetDefaultStyle (void)
 Get the current default style. More...
 
void gwinSetText (GHandle gh, const char *text, gBool useAlloc)
 Set the text of a widget. More...
 
const char * gwinGetText (GHandle gh)
 Get the text of a widget. More...
 
void gwinPrintg (GHandle gh, const char *fmt,...)
 Set the text of a widget using a printf style format. More...
 
gBool gwinIsWidget (GHandle gh)
 Check whether a handles is a widget handle or not. More...
 
void gwinSetTag (GHandle gh, WidgetTag tag)
 Set the tag of a widget. More...
 
WidgetTag gwinGetTag (GHandle gh)
 Get the tag of a widget. More...
 
void gwinSetStyle (GHandle gh, const GWidgetStyle *pstyle)
 Set the style of a widget. More...
 
const GWidgetStylegwinGetStyle (GHandle gh)
 Get the style of a widget. More...
 
void gwinSetCustomDraw (GHandle gh, CustomWidgetDrawFunction fn, void *param)
 Set the routine to perform a custom widget drawing. More...
 
gBool gwinAttachListener (GListener *pl)
 Attach a Listener to listen for widget events. More...
 
gBool gwinAttachToggle (GHandle gh, gU16 role, gU16 instance)
 Attach a toggle to a widget. More...
 
gBool gwinDetachToggle (GHandle gh, gU16 role)
 Detach a toggle from a widget. More...
 
gBool gwinAttachDial (GHandle gh, gU16 role, gU16 instance)
 Attach a toggle to a widget. More...
 
gBool gwinSetFocus (GHandle gh)
 Set the keyboard focus to a specific window. More...
 
GHandle gwinGetFocus (void)
 Get the widget that is currently in focus. More...
 
typedef struct GColorSet GColorSet
 The GColorSet structure. More...
 
typedef struct GWidgetStyle GWidgetStyle
 The GWidgetStyle structure. More...
 
typedef struct GWidgetInit GWidgetInit
 The structure to initialise a widget. More...
 
typedef struct GWidgetObject GWidgetObject
 The GWIN Widget structure. More...
 
typedef struct GEventGWin GEventGWin
 A Generic GWIN Event. More...
 
const GWidgetStyle BlackWidgetStyle
 We define a couple of GWidgetStyle's that you can use in your application. The Black style is the default style if you don't specify one. More...
 
#define GEVENT_GWIN_OPEN   (GEVENT_GWIN_FIRST+0x00)
 The list of predefined GWIN events. More...
 

Typedefs

typedef void(* CustomWidgetDrawFunction) (struct GWidgetObject *gw, void *param)
 Defines a custom drawing function for a widget. More...
 
typedef gU16 WidgetTag
 Defines a the type of a tag on a widget. More...
 

Function Documentation

◆ gwinAttachDial()

gBool gwinAttachDial ( GHandle  gh,
gU16  role,
gU16  instance 
)

Attach a toggle to a widget.

Returns
gTrue on success
Parameters
[in]ghThe widget handle
[in]roleThe function the dial will perform for the widget
[in]instanceThe dial instance
Note
See the documentation on the specific widget to see the possible values for the role parameter. If it is out of range, this function will return gFalse
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinAttachListener()

gBool gwinAttachListener ( GListener *  pl)

Attach a Listener to listen for widget events.

Returns
gTrue on success
Parameters
[in]plThe listener
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinAttachToggle()

gBool gwinAttachToggle ( GHandle  gh,
gU16  role,
gU16  instance 
)

Attach a toggle to a widget.

Returns
gTrue on success
Parameters
[in]ghThe widget handle
[in]roleThe function the toggle will perform for the widget
[in]instanceThe toggle instance
Note
See the documentation on the specific widget to see the possible values for the role parameter. If it is out of range, this function will return gFalse
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinDetachToggle()

gBool gwinDetachToggle ( GHandle  gh,
gU16  role 
)

Detach a toggle from a widget.

Returns
gTrue on success
Parameters
[in]ghThe widget handle
[in]roleThe function the toggle will perform for the widget
Note
See the documentation on the specific widget to see the possible values for the role parameter. If it is out of range, this function will return gFalse
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinGetDefaultStyle()

const GWidgetStyle* gwinGetDefaultStyle ( void  )

Get the current default style.

Returns
The current default style.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinGetFocus()

GHandle gwinGetFocus ( void  )

Get the widget that is currently in focus.

The widget that is currently in focus is the widget that receives mouse and keyboard events.

Returns
The handle of the widget that is currently in focus. May be NULL.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinGetStyle()

const GWidgetStyle* gwinGetStyle ( GHandle  gh)

Get the style of a widget.

Returns
The widget style or NULL if it isn't a widget
Parameters
[in]ghThe widget handle
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinGetTag()

WidgetTag gwinGetTag ( GHandle  gh)

Get the tag of a widget.

Returns
The widget tag value (or 0 if it is not a widget)
Parameters
[in]ghThe widget handle
Precondition
Requires GWIN_WIDGET_TAGS to be GFXON
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinGetText()

const char* gwinGetText ( GHandle  gh)

Get the text of a widget.

Returns
The widget text or NULL if it isn't a widget
Parameters
[in]ghThe widget handle
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinIsWidget()

gBool gwinIsWidget ( GHandle  gh)

Check whether a handles is a widget handle or not.

Parameters
[in]ghThe handle to check.
Returns
gTrue if the passed handle is a widget handle. gFalse otherwise.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinPrintg()

void gwinPrintg ( GHandle  gh,
const char *  fmt,
  ... 
)

Set the text of a widget using a printf style format.

Precondition
GFX_USE_GFILE, GFILE_NEED_PRINTG and GFILE_NEED_STRINGS must all be GFXON
Parameters
[in]ghThe widget handle
[in]fmtThe format string using a printf/g syntax. See vsnprintg()
[in]...The printg paramters.
Note
The widget is automatically redrawn
Non-widgets will ignore this call.
The memory for the text is always allocated by this function.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinSetCustomDraw()

void gwinSetCustomDraw ( GHandle  gh,
CustomWidgetDrawFunction  fn,
void *  param 
)

Set the routine to perform a custom widget drawing.

Parameters
[in]ghThe widget handle
[in]fnThe function to use to draw the widget
[in]paramA parameter to pass to the widget drawing function
Note
The widget is not automatically redrawn. Call gwinDraw() to redraw the widget.
Non-widgets will ignore this call.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinSetDefaultStyle()

void gwinSetDefaultStyle ( const GWidgetStyle pstyle,
gBool  updateAll 
)

Set the default style for widgets created hereafter.

Parameters
[in]pstyleThe default style. Passing NULL uses the system compiled style.
[in]updateAllIf gTrue then all existing widgets that are using the current default style will be updated to use this new style. Widgets that have custom styles different from the default style will not be updated.
Note
The style must be allocated statically (not on the stack) as only the pointer is stored.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinSetFocus()

gBool gwinSetFocus ( GHandle  gh)

Set the keyboard focus to a specific window.

Returns
Returns gTrue if the focus could be set to that window
Parameters
[in]ghThe window
Note
Passing NULL will remove the focus from any window.
Only visible enabled widgets are capable of getting the focus.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinSetStyle()

void gwinSetStyle ( GHandle  gh,
const GWidgetStyle pstyle 
)

Set the style of a widget.

Parameters
[in]ghThe widget handle
[in]pstyleThe style to set. This must be a static structure (not allocated on a transient stack). Use NULL to reset to the default style.
Note
The widget is automatically redrawn
Non-widgets will ignore this call.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinSetTag()

void gwinSetTag ( GHandle  gh,
WidgetTag  tag 
)

Set the tag of a widget.

Parameters
[in]ghThe widget handle
[in]tagThe tag to set.
Note
Non-widgets will ignore this call.
Precondition
Requires GWIN_WIDGET_TAGS to be GFXON
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinSetText()

void gwinSetText ( GHandle  gh,
const char *  text,
gBool  useAlloc 
)

Set the text of a widget.

Parameters
[in]ghThe widget handle
[in]textThe text to set. This must be a constant string unless useAlloc is set.
[in]useAllocIf gTrue the string specified will be copied into dynamically allocated memory.
Note
The widget is automatically redrawn
Non-widgets will ignore this call.
Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinWidgetClearInit()

void gwinWidgetClearInit ( GWidgetInit pwi)

Clear a GWidgetInit structure to all zero's.

Note
This function is provided just to prevent problems on operating systems where using memset() causes issues in the users application.
Parameters
[in]pwiThe GWidgetInit structure to clear
Function Class: Normal API, this function can be invoked by regular system threads.

Variable Documentation

◆ BlackWidgetStyle

const GWidgetStyle BlackWidgetStyle
extern

We define a couple of GWidgetStyle's that you can use in your application. The Black style is the default style if you don't specify one.

Note
BlackWidgetStyle means that it is designed for a Black background. Similarly WhiteWidgetStyle is designed for a White background.

Macro Definition Documentation

◆ GEVENT_GWIN_OPEN

#define GEVENT_GWIN_OPEN   (GEVENT_GWIN_FIRST+0x00)

The list of predefined GWIN events.

Note
The definition of an event type does not mean it is always sent. For example, close events are sent by Frame windows but by little else. They are normally only sent if there is a specific reason that the event should be sent.

Definition at line 165 of file gwin_widget.h.

Typedef Documentation

◆ CustomWidgetDrawFunction

typedef void(* CustomWidgetDrawFunction) (struct GWidgetObject *gw, void *param)

Defines a custom drawing function for a widget.

Definition at line 76 of file gwin_widget.h.

◆ GColorSet

typedef struct GColorSet GColorSet

The GColorSet structure.

◆ GEventGWin

typedef struct GEventGWin GEventGWin

A Generic GWIN Event.

A comment/rant on the above structure: We would really like the GWindowObject member to be anonymous. While this is allowed under the C11, C99, GNU and various other standards which have been around forever - compiler support often requires special flags e.g gcc requires the -fms-extensions flag (no wonder the language and compilers have not really progressed in 30 years). As portability is a key requirement we unfortunately won't use this useful feature in case we get a compiler that won't support it even with special flags.

Note
All gwin windows when sending events will either use this structure or a structure that is 100% compatible except that it may also have extra fields.
There are currently no GEventGWin listening flags - use 0 as the flags to gwinAttachListener()

◆ GWidgetInit

typedef struct GWidgetInit GWidgetInit

The structure to initialise a widget.

Note
Some widgets may have extra parameters.
If you create this structure on the stack, you should always memset it to all zero's first in case a future version of the software add's extra fields. Alternatively you can use gwinWidgetClearInit() to clear it.
The text element must be static string (not stack allocated). If you want to use a dynamic string (eg a stack allocated string) use NULL for this member and then call gwinSetText() with useAlloc set to gTrue.

◆ GWidgetObject

typedef struct GWidgetObject GWidgetObject

The GWIN Widget structure.

Note
A widget is a GWIN window that accepts user input. It also has a number of other properties such as its ability to redraw itself (a widget maintains drawing state).
Do not access the members directly. Treat it as a black-box and use the method functions.

◆ GWidgetStyle

typedef struct GWidgetStyle GWidgetStyle

The GWidgetStyle structure.

A GWidgetStyle is a set of colors that together form a "style". These colors should not be confused with the GWindow foreground and background colors which are used for drawing operations.

◆ WidgetTag

typedef gU16 WidgetTag

Defines a the type of a tag on a widget.

Definition at line 81 of file gwin_widget.h.