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 GWidgetStyle *	gwinGetDefaultStyle (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 GWidgetStyle *	gwinGetStyle (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]	gh	The widget handle
[in]	role	The function the dial will perform for the widget
[in]	instance	The 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] pl The 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]	gh	The widget handle
[in]	role	The function the toggle will perform for the widget
[in]	instance	The 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]	gh	The widget handle
[in]	role	The 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] gh The 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] gh The 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] gh The 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] gh The 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]	gh	The widget handle
[in]	fmt	The 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]	gh	The widget handle
[in]	fn	The function to use to draw the widget
[in]	param	A 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]	pstyle	The default style. Passing NULL uses the system compiled style.
[in]	updateAll	If 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] gh The 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]	gh	The widget handle
[in]	pstyle	The 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]	gh	The widget handle
[in]	tag	The 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]	gh	The widget handle
[in]	text	The text to set. This must be a constant string unless useAlloc is set.
[in]	useAlloc	If 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] pwi The 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.

Detailed Description

Data Structures

Functions

Typedefs

Function Documentation

◆ gwinAttachDial()

◆ gwinAttachListener()

◆ gwinAttachToggle()

◆ gwinDetachToggle()

◆ gwinGetDefaultStyle()

◆ gwinGetFocus()

◆ gwinGetStyle()

◆ gwinGetTag()

◆ gwinGetText()

◆ gwinIsWidget()

◆ gwinPrintg()

◆ gwinSetCustomDraw()

◆ gwinSetDefaultStyle()

◆ gwinSetFocus()

◆ gwinSetStyle()

◆ gwinSetTag()

◆ gwinSetText()

◆ gwinWidgetClearInit()

Variable Documentation

◆ BlackWidgetStyle

Macro Definition Documentation

◆ GEVENT_GWIN_OPEN

Typedef Documentation

◆ CustomWidgetDrawFunction

◆ GColorSet

◆ GEventGWin

◆ GWidgetInit

◆ GWidgetObject

◆ GWidgetStyle

◆ WidgetTag