µGFX  2.9
version 2.9
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.io/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 GFXON in your gfxconf.h
22  * @pre GWIN_NEED_BUTTON must be set to GFXON 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  gU16 toggle;
58  #endif
60 
61 /**
62  * @brief Create a button widget.
63  * @return NULL if there is no resultant drawing area, otherwise a window handle.
64  *
65  * @param[in] g The GDisplay to display this window on
66  * @param[in] gb The GButtonObject structure to initialise. If this is NULL the structure is dynamically allocated.
67  * @param[in] pInit The initialisation parameters
68  *
69  * @note The drawing color and the background color get set to the current defaults. If you haven't called
70  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are GFX_WHITE and GFX_BLACK respectively.
71  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
72  * is no default font and text drawing operations will no nothing.
73  * @note A button remembers its normal drawing state. If there is a window manager then it is automatically
74  * redrawn if the window is moved or its visibility state is changed.
75  * @note A button supports mouse and a toggle input.
76  * @note When assigning a toggle, only one toggle is supported. If you try to assign more than one toggle it will
77  * forget the previous toggle. When assigning a toggle the role parameter must be 0.
78  *
79  * @api
80  */
81 GHandle gwinGButtonCreate(GDisplay *g, GButtonObject *gb, const GWidgetInit *pInit);
82 #define gwinButtonCreate(gb, pInit) gwinGButtonCreate(GDISP, gb, pInit)
83 
84 /**
85  * @brief Is the button current pressed
86  * @return gTrue if the button is pressed
87  *
88  * @param[in] gh The window handle (must be a button widget)
89  *
90  * @api
91  */
93 
94 /**
95  * @defgroup Renderings_Button Renderings
96  *
97  * @brief Built-in rendering functions for the button widget.
98  *
99  * @details These function may be passed to @p gwinSetCustomDraw() to get different button drawing styles.
100  *
101  * @note In your custom button drawing function you may optionally call these
102  * standard functions and then draw your extra details on top.
103  * @note The standard functions below ignore the param parameter except for @p gwinButtonDraw_Image().
104  * @note The image custom draw function @p gwinButtonDraw_Image() uses param to pass in the gImage pointer.
105  * @note These custom drawing routines don't have to worry about setting clipping as the framework
106  * sets clipping to the object window prior to calling these routines.
107  *
108  * @{
109  */
110 
111 /**
112  * @brief The default rendering function for the button widget
113  *
114  * @param[in] gw The widget object (must be a button object)
115  * @param[in] param A parameter passed in from the user. Ignored by this function.
116  *
117  * @api
118  */
119 void gwinButtonDraw_Normal(GWidgetObject *gw, void *param);
120 
121 #if GDISP_NEED_ARC || defined(__DOXYGEN__)
122  /**
123  * @brief Renders a rectangular button with rounded corners
124  *
125  * @param[in] gw The widget object (must be a button object)
126  * @param[in] param A parameter passed in from the user. Ignored by this function.
127  *
128  * @pre GDISP_NEED_ARC must be set to GFXON
129  *
130  * @api
131  */
132  void gwinButtonDraw_Rounded(GWidgetObject *gw, void *param);
133 #endif
134 
135 #if GDISP_NEED_ELLIPSE || defined(__DOXYGEN__)
136  /**
137  * @brief Renders a button with an elliptical shape
138  *
139  * @param[in] gw The widget object (must be a button object)
140  * @param[in] param A parameter passed in from the user. Ignored by this function.
141  *
142  * @pre GDISP_NEED_ELLIPSE must be set to GFXON
143  *
144  * @api
145  */
146  void gwinButtonDraw_Ellipse(GWidgetObject *gw, void *param);
147 #endif
148 
149 #if GDISP_NEED_CONVEX_POLYGON || defined(__DOXYGEN__)
150  /**
151  * @brief Renders a button in a shape of an arrow pointing up.
152  *
153  * @param[in] gw The widget object (must be a button object)
154  * @param[in] param A parameter passed in from the user. Ignored by this function.
155  *
156  * @pre GDISP_NEED_CONVEX_POLYGON must be set to GFXON
157  *
158  * @api
159  */
160  void gwinButtonDraw_ArrowUp(GWidgetObject *gw, void *param);
161 
162  /**
163  * @brief Renders a button in a shape of an arrow pointing down.
164  *
165  * @param[in] gw The widget object (must be a button object)
166  * @param[in] param A parameter passed in from the user. Ignored by this function.
167  *
168  * @pre GDISP_NEED_CONVEX_POLYGON must be set to GFXON
169  *
170  * @api
171  */
172  void gwinButtonDraw_ArrowDown(GWidgetObject *gw, void *param);
173 
174  /**
175  * @brief Renders a button in a shape of an arrow pointing left.
176  *
177  * @param[in] gw The widget object (must be a button object)
178  * @param[in] param A parameter passed in from the user. Ignored by this function.
179  *
180  * @pre GDISP_NEED_CONVEX_POLYGON must be set to GFXON
181  *
182  * @api
183  */
184  void gwinButtonDraw_ArrowLeft(GWidgetObject *gw, void *param);
185 
186  /**
187  * @brief Renders a button in a shape of an arrow pointing right.
188  *
189  * @param[in] gw The widget object (must be a button object)
190  * @param[in] param A parameter passed in from the user. Ignored by this function.
191  *
192  * @pre GDISP_NEED_CONVEX_POLYGON must be set to GFXON
193  *
194  * @api
195  */
196  void gwinButtonDraw_ArrowRight(GWidgetObject *gw, void *param);
197 #endif
198 
199 #if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
200  /**
201  * @brief Renders a button using individual images for each button state.
202  *
203  * @param[in] gw The widget object (must be a button object)
204  * @param[in] param A parameter passed in from the user. Must be an image handle. See note below.
205  *
206  * @note The image must be already opened before calling @p gwinSetCustomDraw(). The image should be 3
207  * times the height of the button. The button image is repeated 3 times vertically, the first (top) for
208  * the "up" image, the 2nd for the "down" image, and the third (bottom) image for the disabled state. If
209  * the disabled state is never going to be used then the image can be just 2 times the button height.
210  * No checking is done to compare the size of the button to the size of the image.
211  * Note text is drawn on top of the image.
212  *
213  * @pre GDISP_NEED_IMAGE must be set to GFXON
214  *
215  * @api
216  */
217  void gwinButtonDraw_Image(GWidgetObject *gw, void *param);
218 #endif
219 /** @} */
220 
221 #endif /* _GWIN_BUTTON_H */
222 /** @} */
223 
GEventGWin GEventGWinButton
A Button Event.
Definition: gwin_button.h:40
struct GButtonObject GButtonObject
The button widget structure.
gBool gwinButtonIsPressed(GHandle gh)
Is the button current pressed.
GHandle gwinGButtonCreate(GDisplay *g, GButtonObject *gb, const GWidgetInit *pInit)
Create a button widget.
void gwinButtonDraw_Normal(GWidgetObject *gw, void *param)
The default rendering function for the button widget.
void gwinButtonDraw_ArrowRight(GWidgetObject *gw, void *param)
Renders a button in a shape of an arrow pointing right.
void gwinButtonDraw_ArrowDown(GWidgetObject *gw, void *param)
Renders a button in a shape of an arrow pointing down.
void gwinButtonDraw_Ellipse(GWidgetObject *gw, void *param)
Renders a button with an elliptical shape.
void gwinButtonDraw_Image(GWidgetObject *gw, void *param)
Renders a button using individual images for each button state.
void gwinButtonDraw_ArrowLeft(GWidgetObject *gw, void *param)
Renders a button in a shape of an arrow pointing left.
void gwinButtonDraw_ArrowUp(GWidgetObject *gw, void *param)
Renders a button in a shape of an arrow pointing up.
void gwinButtonDraw_Rounded(GWidgetObject *gw, void *param)
Renders a rectangular button with rounded corners.
The button widget structure.
Definition: gwin_button.h:54
A Generic GWIN Event.
Definition: gwin_widget.h:149
The structure to initialise a widget.
Definition: gwin_widget.h:97
The GWIN Widget structure.
Definition: gwin_widget.h:118
A window object structure.
Definition: gwin.h:40