version 2.8
gwin_button.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_button.h
10  * @brief GWIN Graphic window subsystem header file.
11  *
12  * @defgroup Button Button
13  * @ingroup Widgets
14  *
15  * @brief PushButton widget.
16  *
17  * @details GWIN allows it to easily create buttons with different styles
18  * and check for different meta states such as: PRESSED, CLICKED,
19  * RELEASED etc.
20  *
21  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
22  * @pre GWIN_NEED_BUTTON must be set to TRUE in your gfxconf.h
23  * @{
24  */
25 
26 #ifndef _GWIN_BUTTON_H
27 #define _GWIN_BUTTON_H
28 
29 /* This file is included within "src/gwin/gwin_widget.h" */
30 
31 /**
32  * @brief The Event Type for a Button Event
33  */
34 #define GEVENT_GWIN_BUTTON (GEVENT_GWIN_CTRL_FIRST+0)
35 
36 /**
37  * @brief A Button Event
38  * @note There are currently no GEventGWinButton listening flags - use 0 as the flags to @p gwinAttachListener()
39  */
41 
42 /**
43  * @brief The internal button flags
44  * @note Used only for writing a custom draw routine.
45  * @{
46  */
47 #define GBUTTON_FLG_PRESSED 0x01
48 /** @} */
49 
50 /**
51  * @brief The button widget structure
52  * @note Do not use the members directly - treat it as a black-box.
53  */
54 typedef struct GButtonObject {
55  GWidgetObject w;
56  #if GINPUT_NEED_TOGGLE
57  uint16_t toggle;
58  #endif
60 
61 #ifdef __cplusplus
62 extern "C" {
63 #endif
64 
65 /**
66  * @brief Create a button widget.
67  * @return NULL if there is no resultant drawing area, otherwise a window handle.
68  *
69  * @param[in] g The GDisplay to display this window on
70  * @param[in] gb The GButtonObject structure to initialise. If this is NULL the structure is dynamically allocated.
71  * @param[in] pInit The initialisation parameters
72  *
73  * @note The drawing color and the background color get set to the current defaults. If you haven't called
74  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively.
75  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
76  * is no default font and text drawing operations will no nothing.
77  * @note A button remembers its normal drawing state. If there is a window manager then it is automatically
78  * redrawn if the window is moved or its visibility state is changed.
79  * @note A button supports mouse and a toggle input.
80  * @note When assigning a toggle, only one toggle is supported. If you try to assign more than one toggle it will
81  * forget the previous toggle. When assigning a toggle the role parameter must be 0.
82  *
83  * @api
84  */
85 GHandle gwinGButtonCreate(GDisplay *g, GButtonObject *gb, const GWidgetInit *pInit);
86 #define gwinButtonCreate(gb, pInit) gwinGButtonCreate(GDISP, gb, pInit)
87 
88 /**
89  * @brief Is the button current pressed
90  * @return TRUE if the button is pressed
91  *
92  * @param[in] gh The window handle (must be a button widget)
93  *
94  * @api
95  */
96 bool_t gwinButtonIsPressed(GHandle gh);
97 
98 /**
99  * @defgroup Renderings_Button Renderings
100  *
101  * @brief Built-in rendering functions for the button widget.
102  *
103  * @details These function may be passed to @p gwinSetCustomDraw() to get different button drawing styles.
104  *
105  * @note In your custom button drawing function you may optionally call these
106  * standard functions and then draw your extra details on top.
107  * @note The standard functions below ignore the param parameter except for @p gwinButtonDraw_Image().
108  * @note The image custom draw function @p gwinButtonDraw_Image() uses param to pass in the gdispImage pointer.
109  * @note These custom drawing routines don't have to worry about setting clipping as the framework
110  * sets clipping to the object window prior to calling these routines.
111  *
112  * @{
113  */
114 
115 /**
116  * @brief The default rendering function for the button widget
117  *
118  * @param[in] gw The widget object (must be a button object)
119  * @param[in] param A parameter passed in from the user. Ignored by this function.
120  *
121  * @api
122  */
123 void gwinButtonDraw_Normal(GWidgetObject *gw, void *param);
124 
125 #if GDISP_NEED_ARC || defined(__DOXYGEN__)
126  /**
127  * @brief Renders a rectangular button with rounded corners
128  *
129  * @param[in] gw The widget object (must be a button object)
130  * @param[in] param A parameter passed in from the user. Ignored by this function.
131  *
132  * @pre GDISP_NEED_ARC must be set to TRUE
133  *
134  * @api
135  */
136  void gwinButtonDraw_Rounded(GWidgetObject *gw, void *param);
137 #endif
138 
139 #if GDISP_NEED_ELLIPSE || defined(__DOXYGEN__)
140  /**
141  * @brief Renders a button with an elliptical shape
142  *
143  * @param[in] gw The widget object (must be a button object)
144  * @param[in] param A parameter passed in from the user. Ignored by this function.
145  *
146  * @pre GDISP_NEED_ELLIPSE must be set to TRUE
147  *
148  * @api
149  */
150  void gwinButtonDraw_Ellipse(GWidgetObject *gw, void *param);
151 #endif
152 
153 #if GDISP_NEED_CONVEX_POLYGON || defined(__DOXYGEN__)
154  /**
155  * @brief Renders a button in a shape of an arrow pointing up.
156  *
157  * @param[in] gw The widget object (must be a button object)
158  * @param[in] param A parameter passed in from the user. Ignored by this function.
159  *
160  * @pre GDISP_NEED_CONVEX_POLYGON must be set to TRUE
161  *
162  * @api
163  */
164  void gwinButtonDraw_ArrowUp(GWidgetObject *gw, void *param);
165 
166  /**
167  * @brief Renders a button in a shape of an arrow pointing down.
168  *
169  * @param[in] gw The widget object (must be a button object)
170  * @param[in] param A parameter passed in from the user. Ignored by this function.
171  *
172  * @pre GDISP_NEED_CONVEX_POLYGON must be set to TRUE
173  *
174  * @api
175  */
176  void gwinButtonDraw_ArrowDown(GWidgetObject *gw, void *param);
177 
178  /**
179  * @brief Renders a button in a shape of an arrow pointing left.
180  *
181  * @param[in] gw The widget object (must be a button object)
182  * @param[in] param A parameter passed in from the user. Ignored by this function.
183  *
184  * @pre GDISP_NEED_CONVEX_POLYGON must be set to TRUE
185  *
186  * @api
187  */
188  void gwinButtonDraw_ArrowLeft(GWidgetObject *gw, void *param);
189 
190  /**
191  * @brief Renders a button in a shape of an arrow pointing right.
192  *
193  * @param[in] gw The widget object (must be a button object)
194  * @param[in] param A parameter passed in from the user. Ignored by this function.
195  *
196  * @pre GDISP_NEED_CONVEX_POLYGON must be set to TRUE
197  *
198  * @api
199  */
200  void gwinButtonDraw_ArrowRight(GWidgetObject *gw, void *param);
201 #endif
202 
203 #if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
204  /**
205  * @brief Renders a button using individual images for each button state.
206  *
207  * @param[in] gw The widget object (must be a button object)
208  * @param[in] param A parameter passed in from the user. Must be an image handle. See note below.
209  *
210  * @note The image must be already opened before calling @p gwinSetCustomDraw(). The image should be 3
211  * times the height of the button. The button image is repeated 3 times vertically, the first (top) for
212  * the "up" image, the 2nd for the "down" image, and the third (bottom) image for the disabled state. If
213  * the disabled state is never going to be used then the image can be just 2 times the button height.
214  * No checking is done to compare the size of the button to the size of the image.
215  * Note text is drawn on top of the image.
216  *
217  * @pre GDISP_NEED_IMAGE must be set to TRUE
218  *
219  * @api
220  */
221  void gwinButtonDraw_Image(GWidgetObject *gw, void *param);
222 #endif
223 /** @} */
224 
225 #ifdef __cplusplus
226 }
227 #endif
228 
229 #endif /* _GWIN_BUTTON_H */
230 /** @} */
231 
void gwinButtonDraw_Normal(GWidgetObject *gw, void *param)
The default rendering function for the button widget.
The structure to initialise a widget.
Definition: gwin_widget.h:97
void gwinButtonDraw_ArrowRight(GWidgetObject *gw, void *param)
Renders a button in a shape of an arrow pointing right.
void gwinButtonDraw_ArrowUp(GWidgetObject *gw, void *param)
Renders a button in a shape of an arrow pointing up.
struct GButtonObject GButtonObject
The button widget structure.
void gwinButtonDraw_Image(GWidgetObject *gw, void *param)
Renders a button using individual images for each button state.
bool_t gwinButtonIsPressed(GHandle gh)
Is the button current pressed.
The button widget structure.
Definition: gwin_button.h:54
The GWIN Widget structure.
Definition: gwin_widget.h:118
GEventGWin GEventGWinButton
A Button Event.
Definition: gwin_button.h:40
GHandle gwinGButtonCreate(GDisplay *g, GButtonObject *gb, const GWidgetInit *pInit)
Create a button widget.
void gwinButtonDraw_ArrowLeft(GWidgetObject *gw, void *param)
Renders a button in a shape of an arrow pointing left.
void gwinButtonDraw_Rounded(GWidgetObject *gw, void *param)
Renders a rectangular button with rounded corners.
A window object structure.
Definition: gwin.h:40
void gwinButtonDraw_Ellipse(GWidgetObject *gw, void *param)
Renders a button with an elliptical shape.
void gwinButtonDraw_ArrowDown(GWidgetObject *gw, void *param)
Renders a button in a shape of an arrow pointing down.
A Generic GWIN Event.
Definition: gwin_widget.h:149