Detailed Description

List Widget. Used to display lists of items.

Provides advanced features such as multi-selection, smooth scrolling and item icons.

Precondition: GFX_USE_GDISP must be set to GFXON in your gfxconf.h; GFX_USE_GWIN must be set to GFXON in your gfxconf.h; GDISP_NEED_TEXT must be set to GFXON in your gfxconf.h; GWIN_NEED_LIST must be set to GFXON in your gfxconf.h; The font you want to use must be enabled in your gfxconf.h

Data Structures
struct	GEventGWinList
	A list event. More...

struct	ListItem
	The internal list item structure. More...

Modules
	Renderings
	Built-in rendering functions for the list widget.

Functions
GHandle	gwinGListCreate (GDisplay g, GListObject widget, GWidgetInit *pInit, gBool multiselect)
	Create a list widget. More...

void	gwinListEnableRender (GHandle gh, gBool ena)
	Enable or disable the rendering of the list. More...

void	gwinListSetScroll (GHandle gh, scroll_t flag)
	Change the behaviour of the scroll bar. More...

int	gwinListAddItem (GHandle gh, const char *text, gBool useAlloc)
	Add an item to the list. More...

void	gwinListItemSetText (GHandle gh, int item, const char *text, gBool useAlloc)
	Set the custom parameter of an item with a given ID. More...

const char *	gwinListItemGetText (GHandle gh, int item)
	Get the name behind an item with a given ID. More...

int	gwinListFindText (GHandle gh, const char *text)
	Get the ID of an item with a given name. More...

void	gwinListItemSetParam (GHandle gh, int item, gU16 param)
	Set the custom parameter of an item with a given ID. More...

gU16	gwinListItemGetParam (GHandle gh, int item)
	Get the custom parameter of an item with a given ID. More...

void	gwinListDeleteAll (GHandle gh)
	Delete all the items of the list. More...

void	gwinListItemDelete (GHandle gh, int item)
	Delete an item from the list. More...

int	gwinListItemCount (GHandle gh)
	Get the amount of items within the list. More...

gBool	gwinListItemIsSelected (GHandle gh, int item)
	Check if an item with a given ID is selected. More...

int	gwinListGetSelected (GHandle gh)
	Get the ID of the selected item. More...

const char *	gwinListGetSelectedText (GHandle gh)
	Get the text of the selected item. More...

void	gwinListSetSelected (GHandle gh, int item, gBool doSelect)
	Set whether a specific item is selected or not. More...

void	gwinListViewItem (GHandle gh, int item)
	Scroll the list so the specified item is in view. More...

void	gwinListItemSetImage (GHandle gh, int item, gImage *pimg)
	Set the image for a list item. More...

#define	GLIST_FLG_MULTISELECT 0x01
	The internal list object flags. More...

Macros
#define	GEVENT_GWIN_LIST (GEVENT_GWIN_CTRL_FIRST+4)
	The event type for a list event. More...

Typedefs
typedef struct GEventGWinList	GEventGWinList
	A list event. More...

typedef enum scroll_t	scroll_t
	Enum to change the behaviour of the scroll bar. More...

typedef struct ListItem	ListItem
	The internal list item structure. More...

Enumerations
enum	scroll_t
	Enum to change the behaviour of the scroll bar. More...

Function Documentation

◆ gwinGListCreate()

GHandle gwinGListCreate	(	GDisplay *	g,
		GListObject *	widget,
		GWidgetInit *	pInit,
		gBool	multiselect
	)

Create a list widget.

Note: The drawing color and the background color get set to the current defaults. If you haven't called gwinSetDefaultColor() or gwinSetDefaultBgColor() then these are GFX_BLACK and GFX_WHITE.; The font gets set to the current default font. If you haven't called gwinSetDefaultFont() then there is no default font and text drawing operations will not display anything.; A list remembers its normal drawing state. If there is a window manager then it is automatically redrawn if the window is moved or its visibility state is changed.; The list contains no elements after creation.; A slider supports mouse, toggle. Note: toggle only works correctly for single-select lists.; When assigning a toggle, only one toggle is supported per role. If you try to assign more than one toggle to a role, it will forget the previous toggle. Two roles are supported: Role 0 = toggle for down, role 1 = toggle for up

Parameters

[in]	g	The GDisplay to display this window on
[in]	widget	The GListObject structure to initialize. If this is NULL, the structure is dynamically allocated.
[in]	pInit	The initialization parameters to use
[in]	multiselect	If gTrue the list is multi-select instead of single-select.

Returns: NULL if there is no resulting drawing area, otherwise a window handle.

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListAddItem()

int gwinListAddItem	(	GHandle	gh,
		const char *	text,
		gBool	useAlloc
	)

Add an item to the list.

Note: The ID you get returned is not static. If items get removed from the list, the list items get reordered.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	text	The string which shall be displayed in the list afterwards
[in]	useAlloc	If set to gTrue, the string will be dynamically allocated. A static buffer must be passed otherwise

Returns: The current ID of the item. The ID might change if you remove items from the middle of the list

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListDeleteAll()

void gwinListDeleteAll ( GHandle gh )

Delete all the items of the list.

Parameters

[in] gh The widget handle (must be a list handle)

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListEnableRender()

void gwinListEnableRender	(	GHandle	gh,
		gBool	ena
	)

Enable or disable the rendering of the list.

Usually the list is being re-rendered when an item is added to the list. This can cause flickering and performance issues when many items are added at once. This can be prevented by temporarely disabling the render using this function.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	ena	gTrue or gFalse

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListFindText()

int gwinListFindText	(	GHandle	gh,
		const char *	text
	)

Get the ID of an item with a given name.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	text	The item name

Returns: The id of the list item or -1 on error

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListGetSelected()

int gwinListGetSelected ( GHandle gh )

Get the ID of the selected item.

Parameters

[in] gh The widget handle (must be a list handle)

Returns: The ID of the selected list item for a single-select list.

Note: It always returns -1 (nothing selected) for a multi-select list. Instead use gwinListItemIsSelected() to get the selection status for a multi-select list.

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListGetSelectedText()

const char* gwinListGetSelectedText ( GHandle gh )

Get the text of the selected item.

Parameters

[in] gh The widget handle (must be a list handle)

Returns: The test of the selected list item for a single-select list.

Note: It always returns NULL (nothing selected) for a multi-select list.

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListItemCount()

int gwinListItemCount ( GHandle gh )

Get the amount of items within the list.

Parameters

[in] gh The widget handle (must be a list handle)

Returns: The amount of items in the list

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListItemDelete()

void gwinListItemDelete	(	GHandle	gh,
		int	item
	)

Delete an item from the list.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListItemGetParam()

gU16 gwinListItemGetParam	(	GHandle	gh,
		int	item
	)

Get the custom parameter of an item with a given ID.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID

Returns: The parameter

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListItemGetText()

const char* gwinListItemGetText	(	GHandle	gh,
		int	item
	)

Get the name behind an item with a given ID.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID

Returns: The string of the list item or NULL on error

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListItemIsSelected()

gBool gwinListItemIsSelected	(	GHandle	gh,
		int	item
	)

Check if an item with a given ID is selected.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID

Returns: gTrue if the item is selected, gFalse otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListItemSetImage()

void gwinListItemSetImage	(	GHandle	gh,
		int	item,
		gImage *	pimg
	)

Set the image for a list item.

Precondition: GWIN_NEED_LIST_IMAGES must be set to true in your gfxconf.h

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID
[in]	pimg	The image to be displayed or NULL to turn off the image for this list item.

Note: The image should be up to 4 x (the font height) and a width of (the font height). The 1st (top) part of the image is displayed for a selected item. The 2nd part of the image is displayed for an unselected item. The 3rd part of the image is displayed for a disabled selected item. The 4th part of the image is displayed for a disabled unselected item. If the image is less than 4 times the font height then the image use is collapsed into the available height. For example, an image that equals the font height will use the same image for all four states.; The image is only displayed while it is open. It is up to the application to open the image.; The same image can be used on more than one list item.; Images are aligned with the top (not the baseline) of the list item.; When any item in the list has an image attached, space is allocated to display the images even if the image is closed or has been removed by calling gwinListItemSetImage() with a NULL image or by calling gwinListItemDelete(). The only way to turn-off the image area for this list is to call gwinListDeleteAll().

◆ gwinListItemSetParam()

void gwinListItemSetParam	(	GHandle	gh,
		int	item,
		gU16	param
	)

Set the custom parameter of an item with a given ID.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID
[in]	param	The parameter to be set

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListItemSetText()

void gwinListItemSetText	(	GHandle	gh,
		int	item,
		const char *	text,
		gBool	useAlloc
	)

Set the custom parameter of an item with a given ID.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID
[in]	text	The text to replace the existing text
[in]	useAlloc	If set to gTrue, the string will be dynamically allocated. A static buffer must be passed otherwise

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListSetScroll()

void gwinListSetScroll	(	GHandle	gh,
		scroll_t	flag
	)

Change the behaviour of the scroll bar.

Note: Current possible values: scrollAlways, scrollAuto and scrollSmooth

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	flag	The behaviour to be set

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListSetSelected()

void gwinListSetSelected	(	GHandle	gh,
		int	item,
		gBool	doSelect
	)

Set whether a specific item is selected or not.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID
[in]	doSelect	gTrue to select the item or gFalse to deselect the item

Note: Changing the selection using this api call will NOT send the list selection change event.; With a single select list selecting an item with this call will deselect any existing selected item. De-selecting an item with this call will not cause a new item to be automatically selected.; De-selecting an item that is not selected will not effect any items that are selected, even in single-select mode.

Function Class: Normal API, this function can be invoked by regular system threads.

◆ gwinListViewItem()

void gwinListViewItem	(	GHandle	gh,
		int	item
	)

Scroll the list so the specified item is in view.

Parameters

[in]	gh	The widget handle (must be a list handle)
[in]	item	The item ID

Note: This will typically scroll the selected item to the top of the list unless the item is in the last page of list items.

Function Class: Normal API, this function can be invoked by regular system threads.

Macro Definition Documentation

◆ GEVENT_GWIN_LIST

#define GEVENT_GWIN_LIST (GEVENT_GWIN_CTRL_FIRST+4)

The event type for a list event.

Definition at line 36 of file gwin_list.h.

◆ GLIST_FLG_MULTISELECT

#define GLIST_FLG_MULTISELECT 0x01

The internal list object flags.

Note: Used only for writing a custom draw routine.

Definition at line 84 of file gwin_list.h.

Typedef Documentation

◆ GEventGWinList

typedef struct GEventGWinList GEventGWinList

A list event.

◆ ListItem

typedef struct ListItem ListItem

The internal list item structure.

Note: Used only for writing a custom draw routine.

◆ scroll_t

typedef enum scroll_t scroll_t

Enum to change the behaviour of the scroll bar.

Note: Used with gwinListSetScroll(); scrollAlways always show the scrollbar; scrollAuto show the scrollbar when there are more items on the list then fit on the screen; scrollSmooth enable touch screen smooth scrolling

Enumeration Type Documentation

◆ scroll_t

enum scroll_t

Enum to change the behaviour of the scroll bar.

Note: Used with gwinListSetScroll(); scrollAlways always show the scrollbar; scrollAuto show the scrollbar when there are more items on the list then fit on the screen; scrollSmooth enable touch screen smooth scrolling

Definition at line 77 of file gwin_list.h.

Detailed Description

Data Structures

Modules

Functions

Macros

Typedefs

Enumerations

Function Documentation

◆ gwinGListCreate()

◆ gwinListAddItem()

◆ gwinListDeleteAll()

◆ gwinListEnableRender()

◆ gwinListFindText()

◆ gwinListGetSelected()

◆ gwinListGetSelectedText()

◆ gwinListItemCount()

◆ gwinListItemDelete()

◆ gwinListItemGetParam()

◆ gwinListItemGetText()

◆ gwinListItemIsSelected()

◆ gwinListItemSetImage()

◆ gwinListItemSetParam()

◆ gwinListItemSetText()

◆ gwinListSetScroll()

◆ gwinListSetSelected()

◆ gwinListViewItem()

Macro Definition Documentation

◆ GEVENT_GWIN_LIST

◆ GLIST_FLG_MULTISELECT

Typedef Documentation

◆ GEventGWinList

◆ ListItem

◆ scroll_t

Enumeration Type Documentation

◆ scroll_t