version 2.8
gwin_list.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.org/license.html
6  */
7 
8 /**
9  * @file src/gwin/gwin_list.h
10  * @brief GWIN list widget header file
11  *
12  * @defgroup List List
13  * @ingroup Widgets
14  *
15  * @brief List Widget. Used to display lists of items.
16  *
17  * @details Provides advanced features such as multi-selection, smooth scrolling and item icons.
18  *
19  * @pre GFX_USE_GDISP must be set to TRUE in your gfxconf.h
20  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
21  * @pre GDISP_NEED_TEXT must be set to TRUE in your gfxconf.h
22  * @pre GWIN_NEED_LIST must be set to TRUE in your gfxconf.h
23  * @pre The font you want to use must be enabled in your gfxconf.h
24  *
25  * @{
26  */
27 
28 #ifndef _GWIN_LIST_H
29 #define _GWIN_LIST_H
30 
31 // This file is included within "src/gwin/gwin_widget.h"
32 
33 /**
34  * @brief The event type for a list event
35  */
36 #define GEVENT_GWIN_LIST (GEVENT_GWIN_CTRL_FIRST+4)
37 
38 /**
39  * @brief A list event
40  */
41 typedef struct GEventGWinList {
42  GEventType type; // The type of this event (GEVENT_GWIN_LIST)
43  GHandle gwin; // The list
44  #if GWIN_WIDGET_TAGS
45  WidgetTag tag; // The list tag
46  #endif
47  int item; // The item that has been selected (or unselected in a multi-select listbox)
49 
50 // A list window
51 typedef struct GListObject {
52  GWidgetObject w;
53 
54  #if GINPUT_NEED_MOUSE
55  coord_t start_mouse_x;
56  coord_t start_mouse_y;
57  coord_t last_mouse_y;
58  #endif
59  #if GINPUT_NEED_TOGGLE
60  uint16_t t_up;
61  uint16_t t_dn;
62  #endif
63 
64  int cnt; // Number of items currently in the list (quicker than counting each time)
65  int top; // Viewing offset in pixels from the top of the list
66  gfxQueueASync list_head; // The list of items
67 } GListObject;
68 
69 /**
70  * @brief Enum to change the behaviour of the scroll bar
71  *
72  * @note Used with @p gwinListSetScroll()
73  * @note @p scrollAlways always show the scrollbar
74  * @note @p scrollAuto show the scrollbar when there are more items on the list then fit on the screen
75  * @note @p scrollSmooth enable touch screen smooth scrolling
76  */
77 typedef enum scroll_t { scrollAlways, scrollAuto, scrollSmooth } scroll_t;
78 
79 /**
80  * @brief The internal list object flags
81  * @note Used only for writing a custom draw routine.
82  * @{
83  */
84 #define GLIST_FLG_MULTISELECT 0x01
85 #define GLIST_FLG_HASIMAGES 0x02
86 #define GLIST_FLG_SCROLLALWAYS 0x04
87 #define GLIST_FLG_SCROLLSMOOTH 0x08
88 #define GLIST_FLG_ENABLERENDER 0x10
89 /** @} */
90 
91 /**
92  * @brief The internal list item structure
93  * @note Used only for writing a custom draw routine.
94  */
95 typedef struct ListItem {
96  gfxQueueASyncItem q_item; // This must be the first member in the struct
97 
98  uint16_t flags;
99  #define GLIST_FLG_SELECTED 0x0001
100  uint16_t param; // A parameter the user can specify himself
101  const char* text;
102  #if GWIN_NEED_LIST_IMAGES
103  gdispImage* pimg;
104  #endif
105 } ListItem;
106 
107 
108 #ifdef __cplusplus
109 extern "C" {
110 #endif
111 
112 /**
113  * @brief Create a list widget
114  *
115  * @note The drawing color and the background color get set to the current defaults. If you haven't called
116  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are Black and White.
117  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then
118  * there is no default font and text drawing operations will not display anything.
119  * @note A list remembers its normal drawing state. If there is a window manager then it is automatically
120  * redrawn if the window is moved or its visibility state is changed.
121  * @note The list contains no elements after creation.
122  * @note A slider supports mouse, toggle. Note: toggle only works correctly for single-select lists.
123  * @note When assigning a toggle, only one toggle is supported per role. If you try to assign more than
124  * one toggle to a role, it will forget the previous toggle. Two roles are supported:
125  * Role 0 = toggle for down, role 1 = toggle for up
126  *
127  * @param[in] g The GDisplay to display this window on
128  * @param[in] widget The GListObject structure to initialize. If this is NULL, the structure is dynamically allocated.
129  * @param[in] pInit The initialization parameters to use
130  * @param[in] multiselect If TRUE the list is multi-select instead of single-select.
131  *
132  * @return NULL if there is no resulting drawing area, otherwise a window handle.
133  *
134  * @api
135  */
136 GHandle gwinGListCreate(GDisplay *g, GListObject *widget, GWidgetInit *pInit, bool_t multiselect);
137 #define gwinListCreate(w, pInit, m) gwinGListCreate(GDISP, w, pInit, m)
138 
139 /**
140  * @brief Enable or disable the rendering of the list
141  *
142  * @details Usually the list is being re-rendered when an item is added to the list. This can cause
143  * flickering and performance issues when many items are added at once. This can be prevented
144  * by temporarely disabling the render using this function.
145  *
146  * @param[in] gh The widget handle (must be a list handle)
147  * @param[in] ena TRUE or FALSE
148  *
149  * @api
150  */
151 void gwinListEnableRender(GHandle gh, bool_t ena);
152 
153 /**
154  * @brief Change the behaviour of the scroll bar
155  *
156  * @note Current possible values: @p scrollAlways, @p scrollAuto and @p scrollSmooth
157  *
158  * @param[in] gh The widget handle (must be a list handle)
159  * @param[in] flag The behaviour to be set
160  *
161  * @api
162  */
163 void gwinListSetScroll(GHandle gh, scroll_t flag);
164 
165 /**
166  * @brief Add an item to the list
167  *
168  * @note The ID you get returned is not static. If items get removed from the list, the list items get
169  * reordered.
170  *
171  * @param[in] gh The widget handle (must be a list handle)
172  * @param[in] text The string which shall be displayed in the list afterwards
173  * @param[in] useAlloc If set to TRUE, the string will be dynamically allocated. A static buffer must be passed otherwise
174  *
175  * @return The current ID of the item. The ID might change if you remove items from the middle of the list
176  *
177  * @api
178  */
179 int gwinListAddItem(GHandle gh, const char* text, bool_t useAlloc);
180 
181 /**
182  * @brief Set the custom parameter of an item with a given ID
183  *
184  * @param[in] gh The widget handle (must be a list handle)
185  * @param[in] item The item ID
186  * @param[in] text The text to replace the existing text
187  * @param[in] useAlloc If set to TRUE, the string will be dynamically allocated. A static buffer must be passed otherwise
188  *
189  * @api
190  */
191 void gwinListItemSetText(GHandle gh, int item, const char* text, bool_t useAlloc);
192 
193 /**
194  * @brief Get the name behind an item with a given ID
195  *
196  * @param[in] gh The widget handle (must be a list handle)
197  * @param[in] item The item ID
198  *
199  * @return The string of the list item or NULL on error
200  *
201  * @api
202  */
203 const char* gwinListItemGetText(GHandle gh, int item);
204 
205 /**
206  * @brief Get the ID of an item with a given name
207  *
208  * @param[in] gh The widget handle (must be a list handle)
209  * @param[in] text The item name
210  *
211  * @return The id of the list item or -1 on error
212  *
213  * @api
214  */
215 int gwinListFindText(GHandle gh, const char* text);
216 
217 /**
218  * @brief Set the custom parameter of an item with a given ID
219  *
220  * @param[in] gh The widget handle (must be a list handle)
221  * @param[in] item The item ID
222  * @param[in] param The parameter to be set
223  *
224  * @api
225  */
226 void gwinListItemSetParam(GHandle gh, int item, uint16_t param);
227 
228 /**
229  * @brief Get the custom parameter of an item with a given ID
230  *
231  * @param[in] gh The widget handle (must be a list handle)
232  * @param[in] item The item ID
233  *
234  * @return The parameter
235  *
236  * @api
237  */
238 uint16_t gwinListItemGetParam(GHandle gh, int item);
239 
240 /**
241  * @brief Delete all the items of the list
242  *
243  * @param[in] gh The widget handle (must be a list handle)
244  *
245  * @api
246  */
247 void gwinListDeleteAll(GHandle gh);
248 
249 /**
250  * @brief Delete an item from the list
251  *
252  * @param[in] gh The widget handle (must be a list handle)
253  * @param[in] item The item ID
254  *
255  * @api
256  */
257 void gwinListItemDelete(GHandle gh, int item);
258 
259 /**
260  * @brief Get the amount of items within the list
261  *
262  * @param[in] gh The widget handle (must be a list handle)
263  *
264  * @return The amount of items in the list
265  *
266  * @api
267  */
268 int gwinListItemCount(GHandle gh);
269 
270 /**
271  * @brief Check if an item with a given ID is selected
272  *
273  * @param[in] gh The widget handle (must be a list handle)
274  * @param[in] item The item ID
275  *
276  * @return TRUE if the item is selected, FALSE otherwise
277  *
278  * @api
279  */
280 bool_t gwinListItemIsSelected(GHandle gh, int item);
281 
282 /**
283  * @brief Get the ID of the selected item
284  *
285  * @param[in] gh The widget handle (must be a list handle)
286  *
287  * @return The ID of the selected list item for a single-select list.
288  *
289  * @note It always returns -1 (nothing selected) for a multi-select list.
290  * Instead use @p gwinListItemIsSelected() to get the selection status
291  * for a multi-select list.
292  *
293  * @api
294  */
296 
297 /**
298  * @brief Get the text of the selected item
299  *
300  * @param[in] gh The widget handle (must be a list handle)
301  *
302  * @return The test of the selected list item for a single-select list.
303  *
304  * @note It always returns NULL (nothing selected) for a multi-select list.
305  *
306  * @api
307  */
308 const char* gwinListGetSelectedText(GHandle gh);
309 
310 /**
311  * @brief Set whether a specific item is selected or not
312  *
313  * @param[in] gh The widget handle (must be a list handle)
314  * @param[in] item The item ID
315  * @param[in] doSelect TRUE to select the item or FALSE to deselect the item
316  *
317  * @note Changing the selection using this api call will NOT send the list selection
318  * change event.
319  * @note With a single select list selecting an item with this call will deselect
320  * any existing selected item. De-selecting an item with this call will not
321  * cause a new item to be automatically selected.
322  * @note De-selecting an item that is not selected will not effect any items that
323  * are selected, even in single-select mode.
324  * @api
325  */
326 void gwinListSetSelected(GHandle gh, int item, bool_t doSelect);
327 
328 /**
329  * @brief Scroll the list so the specified item is in view
330  *
331  * @param[in] gh The widget handle (must be a list handle)
332  * @param[in] item The item ID
333  *
334  * @note This will typically scroll the selected item to the top of the list
335  * unless the item is in the last page of list items.
336  *
337  * @api
338  */
339 void gwinListViewItem(GHandle gh, int item);
340 
341 #if GWIN_NEED_LIST_IMAGES || defined(__DOXYGEN__)
342  /**
343  * @brief Set the image for a list item
344  *
345  * @pre GWIN_NEED_LIST_IMAGES must be set to true in your gfxconf.h
346  *
347  * @param[in] gh The widget handle (must be a list handle)
348  * @param[in] item The item ID
349  * @param[in] pimg The image to be displayed or NULL to turn off the image for this list item.
350  *
351  * @note The image should be up to 4 x (the font height) and a width of (the font height).
352  * The 1st (top) part of the image is displayed for a selected item.
353  * The 2nd part of the image is displayed for an unselected item.
354  * The 3rd part of the image is displayed for a disabled selected item.
355  * The 4th part of the image is displayed for a disabled unselected item.
356  * If the image is less than 4 times the font height then the image use is collapsed
357  * into the available height. For example, an image that equals the font height will use
358  * the same image for all four states.
359  * @note The image is only displayed while it is open. It is up to the application to open
360  * the image.
361  * @note The same image can be used on more than one list item.
362  * @note Images are aligned with the top (not the baseline) of the list item.
363  * @note When any item in the list has an image attached, space is allocated to display
364  * the images even if the image is closed or has been removed by calling @p gwinListItemSetImage()
365  * with a NULL image or by calling @p gwinListItemDelete(). The only way to turn-off the image area
366  * for this list is to call gwinListDeleteAll().
367  *
368  */
369  void gwinListItemSetImage(GHandle gh, int item, gdispImage *pimg);
370 #endif
371 
372 /**
373  * @defgroup Renderings_List Renderings
374  *
375  * @brief Built-in rendering functions for the list widget.
376  *
377  * @details These function may be passed to @p gwinSetCustomDraw() to get different list drawing styles.
378  *
379  * @note In your custom list drawing function you may optionally call these
380  * standard functions and then draw your extra details on top.
381  * @note These custom drawing routines don't have to worry about setting clipping as the framework
382  * sets clipping to the object window prior to calling these routines.
383  *
384  * @{
385  */
386 
387 /**
388  * @brief The default rendering function for the list widget
389  *
390  * @param[in] gw The widget object (must be a list object)
391  * @param[in] param A parameter passed in from the user. Ignored by this function.
392  *
393  * @api
394  */
395 void gwinListDefaultDraw(GWidgetObject* gw, void* param);
396 
397 /** @} */
398 
399 #ifdef __cplusplus
400 }
401 #endif
402 
403 #endif // _GWIN_LIST_H
404 /** @} */
405 
void gwinListItemSetImage(GHandle gh, int item, gdispImage *pimg)
Set the image for a list item.
int gwinListFindText(GHandle gh, const char *text)
Get the ID of an item with a given name.
The internal list item structure.
Definition: gwin_list.h:95
uint16_t gwinListItemGetParam(GHandle gh, int item)
Get the custom parameter of an item with a given ID.
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
int gwinListItemCount(GHandle gh)
Get the amount of items within the list.
The structure to initialise a widget.
Definition: gwin_widget.h:97
scroll_t
Enum to change the behaviour of the scroll bar.
Definition: gwin_list.h:77
struct GEventGWinList GEventGWinList
A list event.
A queue item.
Definition: gqueue.h:40
const char * gwinListGetSelectedText(GHandle gh)
Get the text of the selected item.
int gwinListGetSelected(GHandle gh)
Get the ID of the selected item.
void gwinListItemDelete(GHandle gh, int item)
Delete an item from the list.
GHandle gwinGListCreate(GDisplay *g, GListObject *widget, GWidgetInit *pInit, bool_t multiselect)
Create a list widget.
void gwinListDefaultDraw(GWidgetObject *gw, void *param)
The default rendering function for the list widget.
A queue.
Definition: gqueue.h:54
void gwinListSetSelected(GHandle gh, int item, bool_t doSelect)
Set whether a specific item is selected or not.
A list event.
Definition: gwin_list.h:41
The GWIN Widget structure.
Definition: gwin_widget.h:118
void gwinListEnableRender(GHandle gh, bool_t ena)
Enable or disable the rendering of the list.
void gwinListDeleteAll(GHandle gh)
Delete all the items of the list.
void gwinListViewItem(GHandle gh, int item)
Scroll the list so the specified item is in view.
struct ListItem ListItem
The internal list item structure.
void gwinListSetScroll(GHandle gh, scroll_t flag)
Change the behaviour of the scroll bar.
void gwinListItemSetText(GHandle gh, int item, const char *text, bool_t useAlloc)
Set the custom parameter of an item with a given ID.
void gwinListItemSetParam(GHandle gh, int item, uint16_t param)
Set the custom parameter of an item with a given ID.
uint16_t WidgetTag
Defines a the type of a tag on a widget.
Definition: gwin_widget.h:81
The structure for an image.
Definition: gdisp_image.h:59
A window object structure.
Definition: gwin.h:40
int gwinListAddItem(GHandle gh, const char *text, bool_t useAlloc)
Add an item to the list.
bool_t gwinListItemIsSelected(GHandle gh, int item)
Check if an item with a given ID is selected.
const char * gwinListItemGetText(GHandle gh, int item)
Get the name behind an item with a given ID.