version 2.8
gwin_widget.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_widget.h
10  * @brief GWIN Widgets header file.
11  *
12  * @defgroup Widget Widget
13  * @ingroup Widgets
14  *
15  * @brief The basic widget implementation (base class).
16  *
17  * @details A widget is a Window that supports interacting with the user
18  * via an input device such as a mouse or toggle buttons. It is the
19  * base class for widgets such as buttons and sliders.
20  *
21  * @pre GFX_USE_GWIN and GWIN_NEED_WIDGET must be set to TRUE in your gfxconf.h
22  * @{
23  */
24 
25 #ifndef _GWIDGET_H
26 #define _GWIDGET_H
27 
28 /* This file is included within "src/gwin/gwin.h" */
29 
30 // Forward definition
31 struct GWidgetObject;
32 
33 /**
34  * @brief The GColorSet structure
35  * @{
36  */
37 typedef struct GColorSet {
38  color_t text; /**< The text color */
39  color_t edge; /**< The edge color */
40  color_t fill; /**< The fill color */
41  color_t progress; /**< The color of progress bars */
42 } GColorSet;
43 /** @} */
44 
45 /**
46  * @brief The GWidgetStyle structure
47  * @details A GWidgetStyle is a set of colors that together form a "style".
48  * These colors should not be confused with the GWindow foreground
49  * and background colors which are used for drawing operations.
50  * @{
51  */
52 typedef struct GWidgetStyle {
53  color_t background; /**< The window background color */
54  color_t focus; /**< The color when a widget is focused */
55  GColorSet enabled; /**< The colors when enabled */
56  GColorSet disabled; /**< The colors when disabled */
57  GColorSet pressed; /**< The colors when pressed */
58 } GWidgetStyle;
59 /** @} */
60 
61 /**
62  * @brief We define a couple of GWidgetStyle's that you can use in your
63  * application. The Black style is the default style if you don't
64  * specify one.
65  * @note BlackWidgetStyle means that it is designed for a Black background.
66  * Similarly WhiteWidgetStyle is designed for a White background.
67  * @{
68  */
69 extern const GWidgetStyle BlackWidgetStyle;
70 extern const GWidgetStyle WhiteWidgetStyle;
71 /** @} */
72 
73 /**
74  * @brief Defines a custom drawing function for a widget
75  */
76 typedef void (*CustomWidgetDrawFunction)(struct GWidgetObject *gw, void *param);
77 
78 /**
79  * @brief Defines a the type of a tag on a widget
80  */
81 typedef uint16_t WidgetTag;
82 
83 /**
84  * @brief The structure to initialise a widget.
85  *
86  * @note Some widgets may have extra parameters.
87  * @note If you create this structure on the stack, you should always memset
88  * it to all zero's first in case a future version of the software
89  * add's extra fields. Alternatively you can use @p gwinWidgetClearInit()
90  * to clear it.
91  * @note The text element must be static string (not stack allocated). If you want to use
92  * a dynamic string (eg a stack allocated string) use NULL for this member and then call
93  * @p gwinSetText() with useAlloc set to TRUE.
94  *
95  * @{
96  */
97 typedef struct GWidgetInit {
98  GWindowInit g; /**< The GWIN initializer */
99  const char * text; /**< The initial text */
100  CustomWidgetDrawFunction customDraw; /**< A custom draw function - use NULL for the standard */
101  void * customParam; /**< A parameter for the custom draw function (default = NULL) */
102  const GWidgetStyle * customStyle; /**< A custom style to use - use NULL for the default style */
103  #if GWIN_WIDGET_TAGS || defined(__DOXYGEN__)
104  WidgetTag tag; /**< The tag to associate with the widget */
105  #endif
106 } GWidgetInit;
107 /** @} */
108 
109 /**
110  * @brief The GWIN Widget structure
111  * @note A widget is a GWIN window that accepts user input.
112  * It also has a number of other properties such as its ability
113  * to redraw itself (a widget maintains drawing state).
114  * @note Do not access the members directly. Treat it as a black-box and use the method functions.
115  *
116  * @{
117  */
118 typedef struct GWidgetObject {
119  GWindowObject g; /**< This is still a GWIN */
120  const char * text; /**< The widget text */
121  CustomWidgetDrawFunction fnDraw; /**< The current draw function */
122  void * fnParam; /**< A parameter for the current draw function */
123  const GWidgetStyle * pstyle; /**< The current widget style colors */
124  #if GWIN_WIDGET_TAGS || defined(__DOXYGEN__)
125  WidgetTag tag; /**< The widget tag */
126  #endif
127 } GWidgetObject;
128 /** @} */
129 
130 /**
131  * A comment/rant on the above structure:
132  * We would really like the GWindowObject member to be anonymous. While this is
133  * allowed under the C11, C99, GNU and various other standards which have been
134  * around forever - compiler support often requires special flags e.g
135  * gcc requires the -fms-extensions flag (no wonder the language and compilers have
136  * not really progressed in 30 years). As portability is a key requirement
137  * we unfortunately won't use this useful feature in case we get a compiler that
138  * won't support it even with special flags.
139  */
140 
141 /**
142  * @brief A Generic GWIN Event
143  * @note All gwin windows when sending events will either use this structure or a
144  * structure that is 100% compatible except that it may also have extra fields.
145  * @note There are currently no GEventGWin listening flags - use 0 as the flags to @p gwinAttachListener()
146  *
147  * @{
148  */
149 typedef struct GEventGWin {
150  GEventType type; /**< The type of this event */
151  GHandle gwin; /**< The gwin window handle */
152  #if GWIN_NEED_WIDGET && GWIN_WIDGET_TAGS
153  WidgetTag tag; /**< The tag (if applicable) */
154  #endif
155 } GEventGWin;
156 /** @} */
157 
158 /**
159  * @brief The list of predefined GWIN events.
160  * @note The definition of an event type does not mean it is always sent. For example,
161  * close events are sent by Frame windows but by little else. They are normally
162  * only sent if there is a specific reason that the event should be sent.
163  * @{
164  */
165 #define GEVENT_GWIN_OPEN (GEVENT_GWIN_FIRST+0x00)
166 #define GEVENT_GWIN_CLOSE (GEVENT_GWIN_FIRST+0x01)
167 #define GEVENT_GWIN_RESIZE (GEVENT_GWIN_FIRST+0x02)
168 #define GEVENT_GWIN_CTRL_FIRST (GEVENT_GWIN_FIRST+0x40)
169 /** @} */
170 
171 #ifdef __cplusplus
172 extern "C" {
173 #endif
174 
175 /**
176  * @brief Clear a GWidgetInit structure to all zero's
177  * @note This function is provided just to prevent problems
178  * on operating systems where using memset() causes issues
179  * in the users application.
180  *
181  * @param[in] pwi The GWidgetInit structure to clear
182  *
183  * @api
184  */
186 
187 /**
188  * @brief Set the default style for widgets created hereafter.
189  *
190  * @param[in] pstyle The default style. Passing NULL uses the system compiled style.
191  * @param[in] updateAll If TRUE then all existing widgets that are using the current default style
192  * will be updated to use this new style. Widgets that have custom styles different
193  * from the default style will not be updated.
194  *
195  * @note The style must be allocated statically (not on the stack) as only the pointer is stored.
196  *
197  * @api
198  */
199 void gwinSetDefaultStyle(const GWidgetStyle *pstyle, bool_t updateAll);
200 
201 /**
202  * @brief Get the current default style.
203  *
204  * @return The current default style.
205  *
206  * @api
207  */
208 const GWidgetStyle *gwinGetDefaultStyle(void);
209 
210 /**
211  * @brief Set the text of a widget.
212  *
213  * @param[in] gh The widget handle
214  * @param[in] text The text to set. This must be a constant string unless useAlloc is set.
215  * @param[in] useAlloc If TRUE the string specified will be copied into dynamically allocated memory.
216  *
217  * @note The widget is automatically redrawn
218  * @note Non-widgets will ignore this call.
219  *
220  * @api
221  */
222 void gwinSetText(GHandle gh, const char *text, bool_t useAlloc);
223 
224 /**
225  * @brief Get the text of a widget.
226  * @return The widget text or NULL if it isn't a widget
227  *
228  * @param[in] gh The widget handle
229  *
230  * @api
231  */
232 const char *gwinGetText(GHandle gh);
233 
234 #if (GFX_USE_GFILE && GFILE_NEED_PRINTG && GFILE_NEED_STRINGS) || defined(__DOXYGEN__)
235  /**
236  * @brief Set the text of a widget using a printf style format.
237  * @pre GFX_USE_GFILE, GFILE_NEED_PRINTG and GFILE_NEED_STRINGS must all be TRUE
238  *
239  * @param[in] gh The widget handle
240  * @param[in] fmt The format string using a printf/g syntax. See @p vsnprintg()
241  * @param[in] ... The printg paramters.
242  *
243  * @note The widget is automatically redrawn
244  * @note Non-widgets will ignore this call.
245  * @note The memory for the text is always allocated by this function.
246  *
247  * @api
248  */
249  void gwinPrintg(GHandle gh, const char * fmt,...);
250 #endif
251 
252 /**
253  * @brief Check whether a handles is a widget handle or not
254  *
255  * @param[in] gh The handle to check.
256  *
257  * @return TRUE if the passed handle is a widget handle. FALSE otherwise.
258  *
259  * @api
260  */
261 bool_t gwinIsWidget(GHandle gh);
262 
263 #if GWIN_WIDGET_TAGS || defined(__DOXYGEN__)
264  /**
265  * @brief Set the tag of a widget.
266  *
267  * @param[in] gh The widget handle
268  * @param[in] tag The tag to set.
269  *
270  * @note Non-widgets will ignore this call.
271  *
272  * @pre Requires GWIN_WIDGET_TAGS to be TRUE
273  *
274  * @api
275  */
276  void gwinSetTag(GHandle gh, WidgetTag tag);
277 
278  /**
279  * @brief Get the tag of a widget.
280  * @return The widget tag value (or 0 if it is not a widget)
281  *
282  * @param[in] gh The widget handle
283  *
284  * @pre Requires GWIN_WIDGET_TAGS to be TRUE
285  *
286  * @api
287  */
289 #endif
290 
291 /**
292  * @brief Set the style of a widget.
293  *
294  * @param[in] gh The widget handle
295  * @param[in] pstyle The style to set. This must be a static structure (not allocated on a transient stack).
296  * Use NULL to reset to the default style.
297  *
298  * @note The widget is automatically redrawn
299  * @note Non-widgets will ignore this call.
300  *
301  * @api
302  */
303 void gwinSetStyle(GHandle gh, const GWidgetStyle *pstyle);
304 
305 /**
306  * @brief Get the style of a widget.
307  * @return The widget style or NULL if it isn't a widget
308  *
309  * @param[in] gh The widget handle
310  *
311  * @api
312  */
314 
315 /**
316  * @brief Set the routine to perform a custom widget drawing.
317  *
318  * @param[in] gh The widget handle
319  * @param[in] fn The function to use to draw the widget
320  * @param[in] param A parameter to pass to the widget drawing function
321  *
322  * @note The widget is not automatically redrawn. Call @p gwinDraw() to redraw the widget.
323  * @note Non-widgets will ignore this call.
324  *
325  * @api
326  */
327 void gwinSetCustomDraw(GHandle gh, CustomWidgetDrawFunction fn, void *param);
328 
329 /**
330  * @brief Attach a Listener to listen for widget events
331  * @return TRUE on success
332  *
333  * @param[in] pl The listener
334  *
335  * @api
336  */
337 bool_t gwinAttachListener(GListener *pl);
338 
339 #if (GFX_USE_GINPUT && GINPUT_NEED_MOUSE) || defined(__DOXYGEN__)
340  bool_t DEPRECATED("This call can now be removed. Attaching the mouse to GWIN is now automatic.") gwinAttachMouse(uint16_t instance);
341 #endif
342 
343 #if (GFX_USE_GINPUT && GINPUT_NEED_TOGGLE) || defined(__DOXYGEN__)
344  /**
345  * @brief Attach a toggle to a widget
346  * @return TRUE on success
347  *
348  * @param[in] gh The widget handle
349  * @param[in] role The function the toggle will perform for the widget
350  * @param[in] instance The toggle instance
351  *
352  * @note See the documentation on the specific widget to see the possible
353  * values for the role parameter. If it is out of range, this function
354  * will return FALSE
355  *
356  * @api
357  */
358  bool_t gwinAttachToggle(GHandle gh, uint16_t role, uint16_t instance);
359  /**
360  * @brief Detach a toggle from a widget
361  * @return TRUE on success
362  *
363  * @param[in] gh The widget handle
364  * @param[in] role The function the toggle will perform for the widget
365  *
366  * @note See the documentation on the specific widget to see the possible
367  * values for the role parameter. If it is out of range, this function
368  * will return FALSE
369  *
370  * @api
371  */
372  bool_t gwinDetachToggle(GHandle gh, uint16_t role);
373 #endif
374 
375 #if (GFX_USE_GINPUT && GINPUT_NEED_DIAL) || defined(__DOXYGEN__)
376  /**
377  * @brief Attach a toggle to a widget
378  * @return TRUE on success
379  *
380  * @param[in] gh The widget handle
381  * @param[in] role The function the dial will perform for the widget
382  * @param[in] instance The dial instance
383  *
384  * @note See the documentation on the specific widget to see the possible
385  * values for the role parameter. If it is out of range, this function
386  * will return FALSE
387  *
388  * @api
389  */
390  bool_t gwinAttachDial(GHandle gh, uint16_t role, uint16_t instance);
391 #endif
392 
393 #if (GFX_USE_GINPUT && GINPUT_NEED_KEYBOARD) || GWIN_NEED_KEYBOARD || defined(__DOXYGEN__)
394  /**
395  * @brief Set the keyboard focus to a specific window
396  * @return Returns TRUE if the focus could be set to that window
397  *
398  * @param[in] gh The window
399  *
400  * @note Passing NULL will remove the focus from any window.
401  * @note Only visible enabled widgets are capable of getting the focus.
402  *
403  * @api
404  */
405  bool_t gwinSetFocus(GHandle gh);
406 
407  /**
408  * @brief Get the widget that is currently in focus
409  *
410  * @details The widget that is currently in focus is the widget that
411  * receives mouse and keyboard events.
412  *
413  * @return The handle of the widget that is currently in focus. May be NULL.
414  *
415  * @api
416  */
417  GHandle gwinGetFocus(void);
418 #else
419  #define gwinGetFocus() (0)
420  #define gwinSetFocus(gh) (FALSE)
421 #endif
422 
423 #ifdef __cplusplus
424 }
425 #endif
426 
427 /* Include extra widget types */
428 #if GWIN_NEED_BUTTON || defined(__DOXYGEN__)
429  #include "gwin_button.h"
430 #endif
431 
432 #if GWIN_NEED_SLIDER || defined(__DOXYGEN__)
433  #include "gwin_slider.h"
434 #endif
435 
436 #if GWIN_NEED_CHECKBOX || defined(__DOXYGEN__)
437  #include "gwin_checkbox.h"
438 #endif
439 
440 #if GWIN_NEED_RADIO || defined(__DOXYGEN__)
441  #include "gwin_radio.h"
442 #endif
443 
444 #if GWIN_NEED_LABEL || defined(__DOXYGEN__)
445  #include "gwin_label.h"
446 #endif
447 
448 #if GWIN_NEED_LIST || defined(__DOXYGEN__)
449  #include "gwin_list.h"
450 #endif
451 
452 #if GWIN_NEED_PROGRESSBAR || defined(__DOXYGEN__)
453  #include "gwin_progressbar.h"
454 #endif
455 
456 #if GWIN_NEED_KEYBOARD || defined(__DOXYGEN__)
457  #include "gwin_keyboard.h"
458 #endif
459 
460 #if GWIN_NEED_TEXTEDIT || defined(__DOXYGEN__)
461  #include "gwin_textedit.h"
462 #endif
463 
464 #endif /* _GWIDGET_H */
465 /** @} */
GWIN Graphic window subsystem header file.
struct GWidgetStyle GWidgetStyle
The GWidgetStyle structure.
const char * text
Definition: gwin_widget.h:99
GWIN Graphic window subsystem header file.
GWIN Graphic window subsystem header file.
GWIN Graphic window subsystem header file.
The structure to initialise a GWIN.
Definition: gwin.h:75
#define DEPRECATED(msg)
Mark a function as deprecated.
The structure to initialise a widget.
Definition: gwin_widget.h:97
bool_t gwinSetFocus(GHandle gh)
Set the keyboard focus to a specific window.
The GWidgetStyle structure.
Definition: gwin_widget.h:52
GWIN label widget header file.
color_t background
Definition: gwin_widget.h:53
const GWidgetStyle BlackWidgetStyle
We define a couple of GWidgetStyle&#39;s that you can use in your application. The Black style is the def...
WidgetTag gwinGetTag(GHandle gh)
Get the tag of a widget.
void(* CustomWidgetDrawFunction)(struct GWidgetObject *gw, void *param)
Defines a custom drawing function for a widget.
Definition: gwin_widget.h:76
WidgetTag tag
Definition: gwin_widget.h:104
bool_t gwinAttachListener(GListener *pl)
Attach a Listener to listen for widget events.
color_t text
Definition: gwin_widget.h:38
GWindowInit g
Definition: gwin_widget.h:98
The GColorSet structure.
Definition: gwin_widget.h:37
GWindowObject g
Definition: gwin_widget.h:119
void gwinSetCustomDraw(GHandle gh, CustomWidgetDrawFunction fn, void *param)
Set the routine to perform a custom widget drawing.
const char * gwinGetText(GHandle gh)
Get the text of a widget.
void gwinWidgetClearInit(GWidgetInit *pwi)
Clear a GWidgetInit structure to all zero&#39;s.
void gwinSetDefaultStyle(const GWidgetStyle *pstyle, bool_t updateAll)
Set the default style for widgets created hereafter.
struct GEventGWin GEventGWin
A Generic GWIN Event.
GEventType type
Definition: gwin_widget.h:150
GColorSet pressed
Definition: gwin_widget.h:57
GColorSet disabled
Definition: gwin_widget.h:56
GColorSet enabled
Definition: gwin_widget.h:55
const char * text
Definition: gwin_widget.h:120
GWIN list widget header file.
struct GWidgetObject GWidgetObject
The GWIN Widget structure.
const GWidgetStyle * pstyle
Definition: gwin_widget.h:123
CustomWidgetDrawFunction fnDraw
Definition: gwin_widget.h:121
The GWIN Widget structure.
Definition: gwin_widget.h:118
GHandle gwinGetFocus(void)
Get the widget that is currently in focus.
struct GWidgetInit GWidgetInit
The structure to initialise a widget.
GWIN textedit widget header file.
const GWidgetStyle * customStyle
Definition: gwin_widget.h:102
WidgetTag tag
Definition: gwin_widget.h:125
const GWidgetStyle * gwinGetStyle(GHandle gh)
Get the style of a widget.
color_t focus
Definition: gwin_widget.h:54
GWIN Graphic window subsystem header file.
GWIN Graphic window subsystem header file.
void gwinSetStyle(GHandle gh, const GWidgetStyle *pstyle)
Set the style of a widget.
uint16_t WidgetTag
Defines a the type of a tag on a widget.
Definition: gwin_widget.h:81
color_t progress
Definition: gwin_widget.h:41
void * customParam
Definition: gwin_widget.h:101
void gwinPrintg(GHandle gh, const char *fmt,...)
Set the text of a widget using a printf style format.
bool_t gwinAttachToggle(GHandle gh, uint16_t role, uint16_t instance)
Attach a toggle to a widget.
const GWidgetStyle * gwinGetDefaultStyle(void)
Get the current default style.
color_t fill
Definition: gwin_widget.h:40
A window object structure.
Definition: gwin.h:40
void gwinSetTag(GHandle gh, WidgetTag tag)
Set the tag of a widget.
struct GColorSet GColorSet
The GColorSet structure.
COLOR_TYPE color_t
The color type definition.
Definition: gdisp_colors.h:412
void * fnParam
Definition: gwin_widget.h:122
bool_t gwinAttachDial(GHandle gh, uint16_t role, uint16_t instance)
Attach a toggle to a widget.
GHandle gwin
Definition: gwin_widget.h:151
bool_t gwinIsWidget(GHandle gh)
Check whether a handles is a widget handle or not.
CustomWidgetDrawFunction customDraw
Definition: gwin_widget.h:100
bool_t gwinDetachToggle(GHandle gh, uint16_t role)
Detach a toggle from a widget.
A Generic GWIN Event.
Definition: gwin_widget.h:149
color_t edge
Definition: gwin_widget.h:39
void gwinSetText(GHandle gh, const char *text, bool_t useAlloc)
Set the text of a widget.