version 2.8
gwin_checkbox.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_checkbox.h
10  * @brief GWIN Graphic window subsystem header file.
11  *
12  * @defgroup Checkbox Checkbox
13  * @ingroup Widgets
14  *
15  * @brief CheckBox widget.
16  *
17  * @details GWIN allows it to easily create a group of checkbox buttons.
18  *
19  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
20  * @pre GWIN_NEED_CHECKBOX must be set to TRUE in your gfxconf.h
21  * @{
22  */
23 
24 #ifndef _GWIN_CHECKBOX_H
25 #define _GWIN_CHECKBOX_H
26 
27 /* This file is included within "src/gwin/gwin_widget.h" */
28 
29 /*===========================================================================*/
30 /* Driver constants. */
31 /*===========================================================================*/
32 
33 #define GEVENT_GWIN_CHECKBOX (GEVENT_GWIN_CTRL_FIRST+2)
34 
35 /*===========================================================================*/
36 /* Type definitions */
37 /*===========================================================================*/
38 
39 typedef struct GEventGWinCheckbox {
40  GEventType type; // The type of this event (GEVENT_GWIN_CHECKBOX)
41  GHandle gwin; // The checkbox that has been depressed (actually triggered on release)
42  #if GWIN_WIDGET_TAGS
43  WidgetTag tag; // The checkbox tag
44  #endif
45  bool_t isChecked; // Is the checkbox currently checked or unchecked?
46 } GEventGWinCheckbox;
47 
48 /**
49  * @brief The internal checkbox flags
50  * @note Used only for writing a custom draw routine.
51  * @{
52  */
53 #define GCHECKBOX_FLG_CHECKED 0x01
54 /** @} */
55 
56 /* A Checkbox window */
57 typedef struct GCheckboxObject {
58  GWidgetObject w;
59  #if GINPUT_NEED_TOGGLE
60  uint16_t toggle;
61  #endif
62 } GCheckboxObject;
63 
64 #ifdef __cplusplus
65 extern "C" {
66 #endif
67 
68 /**
69  * @brief Create a checkbox window.
70  * @return NULL if there is no resultant drawing area, otherwise a window handle.
71  *
72  * @param[in] g The GDisplay to display this window on
73  * @param[in] gb The GCheckboxObject structure to initialise. If this is NULL, the structure is dynamically allocated.
74  * @param[in] pInit The initialization parameters to use
75  *
76  * @note The drawing color and the background color get set to the current defaults. If you haven't called
77  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively.
78  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
79  * is no default font and text drawing operations will no nothing.
80  * @note A checkbox remembers its normal drawing state. If there is a window manager then it is automatically
81  * redrawn if the window is moved or its visibility state is changed.
82  * @note A checkbox supports mouse and a toggle input.
83  * @note When assigning a toggle, only one toggle is supported. If you try to assign more than one toggle it will
84  * forget the previous toggle. When assigning a toggle the role parameter must be 0.
85  *
86  * @api
87  */
88 GHandle gwinGCheckboxCreate(GDisplay *g, GCheckboxObject *gb, const GWidgetInit *pInit);
89 #define gwinCheckboxCreate(gb, pInit) gwinGCheckboxCreate(GDISP, gb, pInit)
90 
91 /**
92  * @brief Set the state of a checkbox
93  *
94  * @param[in] gh The window handle (must be a checkbox window)
95  * @param[in] isChecked TRUE to set the check, FALSE to uncheck.
96  *
97  * @api
98  */
99 void gwinCheckboxCheck(GHandle gh, bool_t isChecked);
100 
101 /**
102  * @brief Get the state of a checkbox
103  * @return TRUE if the checkbox is currently checked
104  *
105  * @param[in] gh The window handle (must be a checkbox window)
106  *
107  * @api
108  */
109 bool_t gwinCheckboxIsChecked(GHandle gh);
110 
111 /**
112  * @defgroup Renderings_Checkbox Renderings
113  *
114  * @brief Built-in rendering functions for the checkbox widget.
115  *
116  * @details These function may be passed to @p gwinSetCustomDraw() to get different checkbox drawing styles.
117  *
118  * @note In your custom checkbox drawing function you may optionally call these
119  * standard functions and then draw your extra details on top.
120  * @note These custom drawing routines don't have to worry about setting clipping as the framework
121  * sets clipping to the object window prior to calling these routines.
122  *
123  * @{
124  */
125 
126 /**
127  * @brief Renders a square checkbox where the text is on the right side of the checkbox.
128  *
129  * @param[in] gw The widget (must be a checkbox)
130  * @param[in] param A parameter passed in from the user. Ignored by this function.
131  *
132  * @api
133  */
134 void gwinCheckboxDraw_CheckOnLeft(GWidgetObject *gw, void *param);
135 
136 /**
137  * @brief Renders a square checkbox where the text is on the left side of the checkbox.
138  *
139  * @param[in] gw The widget (must be a checkbox)
140  * @param[in] param A parameter passed in from the user. Ignored by this function.
141  *
142  * @api
143  */
144 void gwinCheckboxDraw_CheckOnRight(GWidgetObject *gw, void *param);
145 
146 /**
147  * @brief Renders a checkbox in form of a rectangular button with the text inside of it.
148  *
149  * @details This behaves like a button that can be toggled.
150  *
151  * @param[in] gw The widget (must be a checkbox)
152  * @param[in] param A parameter passed in from the user. Ignored by this function.
153  *
154  * @api
155  */
156 void gwinCheckboxDraw_Button(GWidgetObject *gw, void *param);
157 /** @} */
158 
159 #ifdef __cplusplus
160 }
161 #endif
162 
163 #endif /* _GWIN_CHECKBOX_H */
164 /** @} */
165 
The structure to initialise a widget.
Definition: gwin_widget.h:97
void gwinCheckboxDraw_Button(GWidgetObject *gw, void *param)
Renders a checkbox in form of a rectangular button with the text inside of it.
The GWIN Widget structure.
Definition: gwin_widget.h:118
void gwinCheckboxCheck(GHandle gh, bool_t isChecked)
Set the state of a checkbox.
void gwinCheckboxDraw_CheckOnRight(GWidgetObject *gw, void *param)
Renders a square checkbox where the text is on the left side of the checkbox.
GHandle gwinGCheckboxCreate(GDisplay *g, GCheckboxObject *gb, const GWidgetInit *pInit)
Create a checkbox window.
uint16_t WidgetTag
Defines a the type of a tag on a widget.
Definition: gwin_widget.h:81
bool_t gwinCheckboxIsChecked(GHandle gh)
Get the state of a checkbox.
A window object structure.
Definition: gwin.h:40
void gwinCheckboxDraw_CheckOnLeft(GWidgetObject *gw, void *param)
Renders a square checkbox where the text is on the right side of the checkbox.