aboutsummaryrefslogtreecommitdiffstats
path: root/src/gwin/gwin_list.h
blob: 81db7c34591d65349a7d66ddda1ec08de3004699 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
/*
 * This file is subject to the terms of the GFX License. If a copy of
 * the license was not distributed with this file, you can obtain one at:
 *
 *              http://ugfx.org/license.html
 */

/**
 * @file	src/gwin/gwin_list.h
 * @brief	GWIN list widget header file
 *
 * @defgroup List List
 * @ingroup Widgets
 *
 * @brief		List Widget. Used to display lists of items.
 *
 * @details		Provides advanced features such as multi-selection, smooth scrolling and item icons.
 *
 * @pre			GFX_USE_GDISP must be set to TRUE in your gfxconf.h
 * @pre			GFX_USE_GWIN must be set to TRUE in your gfxconf.h
 * @pre			GDISP_NEED_TEXT must be set to TRUE in your gfxconf.h
 * @pre			GWIN_NEED_LIST must be set to TRUE in your gfxconf.h
 * @pre			The font you want to use must be enabled in your gfxconf.h
 *
 * @{
 */

#ifndef _GWIN_LIST_H
#define _GWIN_LIST_H

// This file is included within "src/gwin/gwin_widget.h"

/**
 * @brief	The event type for a list event
 */
#define GEVENT_GWIN_LIST	(GEVENT_GWIN_CTRL_FIRST+4)

/**
 * @brief	A list event
 */
typedef struct GEventGWinList {
	GEventType		type;		// The type of this event (GEVENT_GWIN_LIST)
	GHandle			gwin;		// The list
	#if GWIN_WIDGET_TAGS
		WidgetTag	tag;		// The list tag
	#endif
	int				item;		// The item that has been selected (or unselected in a multi-select listbox)
} GEventGWinList;

// A list window
typedef struct GListObject {
	GWidgetObject	w;

    #if GINPUT_NEED_MOUSE
        coord_t start_mouse_x;
        coord_t start_mouse_y;
        coord_t last_mouse_y;
    #endif
	#if GINPUT_NEED_TOGGLE
		uint16_t	t_up;
		uint16_t	t_dn;
	#endif

	int				cnt;		// Number of items currently in the list (quicker than counting each time)
	int				top;		// Viewing offset in pixels from the top of the list
	gfxQueueASync	list_head;	// The list of items
} GListObject;

/**
 * @brief	Enum to change the behaviour of the scroll bar
 *
 * @note	Used with @p gwinListSetScroll()
 * @note    @p scrollAlways always show the scrollbar
 * @note    @p scrollAuto show the scrollbar when there are more items on the list then fit on the screen
 * @note    @p scrollSmooth enable touch screen smooth scrolling
 */
typedef enum scroll_t { scrollAlways, scrollAuto, scrollSmooth } scroll_t;

/**
 * @brief	The internal list object flags
 * @note	Used only for writing a custom draw routine.
 * @{
 */
#define GLIST_FLG_MULTISELECT		0x01
#define GLIST_FLG_HASIMAGES			0x02
#define GLIST_FLG_SCROLLALWAYS		0x04
#define GLIST_FLG_SCROLLSMOOTH      0x08
#define GLIST_FLG_ENABLERENDER      0x10
/** @} */

/**
 * @brief	The internal list item structure
 * @note	Used only for writing a custom draw routine.
 */
typedef struct ListItem {
	gfxQueueASyncItem	q_item;		// This must be the first member in the struct

	uint16_t			flags;
		#define GLIST_FLG_SELECTED			0x0001
	uint16_t			param;		// A parameter the user can specify himself
	const char*			text;
	#if GWIN_NEED_LIST_IMAGES
		gdispImage*		pimg;
	#endif
} ListItem;


#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief				Create a list widget
 *
 * @note				The drawing color and the background color get set to the current defaults. If you haven't called
 *						@p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are Black and White.
 * @note				The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then
 *						there is no default font and text drawing operations will not display anything.
 * @note				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.
 * @note				The list contains no elements after creation.
 * @note				A slider supports mouse, toggle. Note: toggle only works correctly for single-select lists.
 * @note				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
 *
 * @param[in] g			The GDisplay to display this window on
 * @param[in] widget	The GListObject structure to initialize. If this is NULL, the structure is dynamically allocated.
 * @param[in] pInit		The initialization parameters to use
 * @param[in] multiselect	If TRUE the list is multi-select instead of single-select.
 *
 * @return				NULL if there is no resulting drawing area, otherwise a window handle.
 *
 * @api
 */
GHandle gwinGListCreate(GDisplay *g, GListObject *widget, GWidgetInit *pInit, bool_t multiselect);
#define gwinListCreate(w, pInit, m)			gwinGListCreate(GDISP, w, pInit, m)

/**
 * @brief				Enable or disable the rendering of the list
 *
 * @details				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.
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] ena		TRUE or FALSE
 *
 * @api
 */
void gwinListEnableRender(GHandle gh, bool_t ena);

/**
 * @brief				Change the behaviour of the scroll bar
 *
 * @note				Current possible values: @p scrollAlways, @p scrollAuto and  @p scrollSmooth
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] flag		The behaviour to be set
 *
 * @api
 */
void gwinListSetScroll(GHandle gh, scroll_t flag);

/**
 * @brief				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.
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] text		The string which shall be displayed in the list afterwards
 * @param[in] useAlloc	If set to TRUE, the string will be dynamically allocated. A static buffer must be passed otherwise
 *
 * @return				The current ID of the item. The ID might change if you remove items from the middle of the list
 *
 * @api
 */
int gwinListAddItem(GHandle gh, const char* text, bool_t useAlloc);

/**
 * @brief				Set the custom parameter of an item with a given ID
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] item		The item ID
 * @param[in] text		The text to replace the existing text
 * @param[in] useAlloc	If set to TRUE, the string will be dynamically allocated. A static buffer must be passed otherwise
 *
 * @api
 */
void gwinListItemSetText(GHandle gh, int item, const char* text, bool_t useAlloc);

/**
 * @brief				Get the name behind an item with a given ID
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] item		The item ID
 *
 * @return				The string of the list item or NULL on error
 *
 * @api
 */
const char* gwinListItemGetText(GHandle gh, int item);

/**
 * @brief				Get the ID of an item with a given name
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] text		The item name
 *
 * @return				The id of the list item or -1 on error
 *
 * @api
 */
int gwinListFindText(GHandle gh, const char* text);

/**
 * @brief				Set the custom parameter of an item with a given ID
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] item		The item ID
 * @param[in] param		The parameter to be set
 *
 * @api
 */
void gwinListItemSetParam(GHandle gh, int item, uint16_t param);

/**
 * @brief				Get the custom parameter of an item with a given ID
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] item		The item ID
 *
 * @return				The parameter
 *
 * @api
 */
uint16_t gwinListItemGetParam(GHandle gh, int item);

/**
 * @brief				Delete all the items of the list
 *
 * @param[in] gh		The widget handle (must be a list handle)
 *
 * @api
 */
void gwinListDeleteAll(GHandle gh);

/**
 * @brief				Delete an item from the list
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] item		The item ID
 *
 * @api
 */
void gwinListItemDelete(GHandle gh, int item);

/**
 * @brief				Get the amount of items within the list
 *
 * @param[in] gh		The widget handle (must be a list handle)
 *
 * @return				The amount of items in the list
 *
 * @api
 */
int gwinListItemCount(GHandle gh);

/**
 * @brief				Check if an item with a given ID is selected
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] item		The item ID
 *
 * @return				TRUE if the item is selected, FALSE otherwise
 *
 * @api
 */
bool_t gwinListItemIsSelected(GHandle gh, int item);

/**
 * @brief				Get the ID of the selected item
 *
 * @param[in] gh		The widget handle (must be a list handle)
 *
 * @return				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 @p gwinListItemIsSelected() to get the selection status
 * 						for a multi-select list.
 *
 * @api
 */
int gwinListGetSelected(GHandle gh);

/**
 * @brief				Get the text of the selected item
 *
 * @param[in] gh		The widget handle (must be a list handle)
 *
 * @return				The test of the selected list item for a single-select list.
 *
 * @note				It always returns NULL (nothing selected) for a multi-select list.
 *
 * @api
 */
const char* gwinListGetSelectedText(GHandle gh);

/**
 * @brief				Set whether a specific item is selected or not
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[in] item		The item ID
 * @param[in] doSelect	TRUE to select the item or FALSE to deselect the item
 *
 * @note				Changing the selection using this api call will NOT send the list selection
 * 						change event.
 * @note				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.
 * @note				De-selecting an item that is not selected will not effect any items that
 * 						are selected, even in single-select mode.
 * @api
 */
void gwinListSetSelected(GHandle gh, int item, bool_t doSelect);

/**
 * @brief				Scroll the list so the specified item is in view
 *
 * @param[in] gh		The widget handle (must be a list handle)
 * @param[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.
 *
 * @api
 */
void gwinListViewItem(GHandle gh, int item);

#if GWIN_NEED_LIST_IMAGES || defined(__DOXYGEN__)
	/**
	 * @brief				Set the image for a list item
	 *
	 * @pre					GWIN_NEED_LIST_IMAGES must be set to true in your gfxconf.h
	 *
	 * @param[in] gh		The widget handle (must be a list handle)
	 * @param[in] item		The item ID
	 * @param[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.
	 * @note				The image is only displayed while it is open. It is up to the application to open
	 * 						the image.
	 * @note				The same image can be used on more than one list item.
	 * @note				Images are aligned with the top (not the baseline) of the list item.
	 * @note				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 @p gwinListItemSetImage()
	 * 						with a NULL image or by calling @p gwinListItemDelete(). The only way to turn-off the image area
	 * 						for this list is to call gwinListDeleteAll().
	 *
	 */
	void gwinListItemSetImage(GHandle gh, int item, gdispImage *pimg);
#endif

/**
 * @defgroup Renderings_List Renderings
 *
 * @brief				Built-in rendering functions for the list widget.
 *
 * @details				These function may be passed to @p gwinSetCustomDraw() to get different list drawing styles.
 *
 * @note				In your custom list drawing function you may optionally call these
 * 						standard functions and then draw your extra details on top.
 * @note				These custom drawing routines don't have to worry about setting clipping as the framework
 * 						sets clipping to the object window prior to calling these routines.
 *
 * @{
 */

/**
 * @brief				The default rendering function for the list widget
 *
 * @param[in] gw		The widget object (must be a list object)
 * @param[in] param		A parameter passed in from the user. Ignored by this function.
 *
 * @api
 */
void gwinListDefaultDraw(GWidgetObject* gw, void* param);

/** @} */

#ifdef __cplusplus
}
#endif

#endif // _GWIN_LIST_H
/** @} */