µGFX  2.9
version 2.9
List

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]gThe GDisplay to display this window on
[in]widgetThe GListObject structure to initialize. If this is NULL, the structure is dynamically allocated.
[in]pInitThe initialization parameters to use
[in]multiselectIf 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]ghThe widget handle (must be a list handle)
[in]textThe string which shall be displayed in the list afterwards
[in]useAllocIf 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]ghThe 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]ghThe widget handle (must be a list handle)
[in]enagTrue 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]ghThe widget handle (must be a list handle)
[in]textThe 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]ghThe 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]ghThe 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]ghThe 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]ghThe widget handle (must be a list handle)
[in]itemThe 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]ghThe widget handle (must be a list handle)
[in]itemThe 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]ghThe widget handle (must be a list handle)
[in]itemThe 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]ghThe widget handle (must be a list handle)
[in]itemThe 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]ghThe widget handle (must be a list handle)
[in]itemThe item ID
[in]pimgThe 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]ghThe widget handle (must be a list handle)
[in]itemThe item ID
[in]paramThe 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]ghThe widget handle (must be a list handle)
[in]itemThe item ID
[in]textThe text to replace the existing text
[in]useAllocIf 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]ghThe widget handle (must be a list handle)
[in]flagThe 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]ghThe widget handle (must be a list handle)
[in]itemThe item ID
[in]doSelectgTrue 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]ghThe widget handle (must be a list handle)
[in]itemThe 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

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.