version 2.8
gwin_radio.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_radio.h
10  * @brief GWIN Graphic window subsystem header file.
11  *
12  * @defgroup RadioButton RadioButton
13  * @ingroup Widgets
14  *
15  * @brief RadioButton widget.
16  *
17  * @details RadioButtons need to be grouped together. This is archived by passing a group parameter through
18  * @p gwinRadioCreate().
19  *
20  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
21  * @pre GWIN_NEED_RADIO must be set to TRUE in your gfxconf.h
22  * @{
23  */
24 
25 #ifndef _GWIN_RADIO_H
26 #define _GWIN_RADIO_H
27 
28 /* This file is included within "src/gwin/gwin_widget.h" */
29 
30 /**
31  * @brief The Event Type for a Radio Event
32  */
33 #define GEVENT_GWIN_RADIO (GEVENT_GWIN_CTRL_FIRST+3)
34 
35 /**
36  * @brief A Button Event
37  * @note There are currently no GEventGWinRadio listening flags - use 0 as the flags to @p gwinAttachListener()
38  */
39 typedef struct GEventGWinRadio {
40  GEventType type; // The type of this event (GEVENT_GWIN_RADIO)
41  GHandle gwin; // The radio button that has been depressed
42  #if GWIN_WIDGET_TAGS
43  WidgetTag tag; // The radio tag
44  #endif
45  uint16_t group; // The group for this radio button
47 
48 /**
49  * @brief The internal radio button object flags
50  * @note Used only for writing a custom draw routine.
51  * @{
52  */
53 #define GRADIO_FLG_PRESSED 0x01
54 /** @} */
55 
56 /**
57  * @brief The radio button widget structure
58  * @note Do not use the members directly - treat it as a black-box.
59  */
60 typedef struct GRadioObject {
61  GWidgetObject w;
62  #if GINPUT_NEED_TOGGLE
63  uint16_t toggle;
64  #endif
65  uint16_t group;
66 } GRadioObject;
67 
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71 
72 /**
73  * @brief Create a radio widget.
74  * @return NULL if there is no resultant drawing area, otherwise a window handle.
75  *
76  * @param[in] g The GDisplay to display this window on
77  * @param[in] gb The GRadioObject structure to initialise. If this is NULL the structure is dynamically allocated.
78  * @param[in] pInit The initialisation parameters
79  * @param[in] group The group of radio buttons this radio button belongs to.
80  *
81  * @note Only one radio button in any group is ever pressed at one time. Pressing one radio button will
82  * release all others in the group.
83  * @note The drawing color and the background color get set to the current defaults. If you haven't called
84  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively.
85  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
86  * is no default font and text drawing operations will no nothing.
87  * @note A radio button remembers its normal drawing state. If there is a window manager then it is automatically
88  * redrawn if the window is moved or its visibility state is changed.
89  * @note A radio button supports mouse and a toggle input.
90  * @note When assigning a toggle, only one toggle is supported. If you try to assign more than one toggle it will
91  * forget the previous toggle. When assigning a toggle the role parameter must be 0.
92  *
93  * @api
94  */
95 GHandle gwinGRadioCreate(GDisplay *g, GRadioObject *gb, const GWidgetInit *pInit, uint16_t group);
96 #define gwinRadioCreate(w, pInit, gr) gwinGRadioCreate(GDISP, w, pInit, gr)
97 
98 /**
99  * @brief Press this radio button (and by definition unset any others in the group)
100  *
101  * @param[in] gh The window handle (must be a radio widget)
102  *
103  * @api
104  */
105 void gwinRadioPress(GHandle gh);
106 
107 /**
108  * @brief Is the radio button currently pressed
109  * @return TRUE if the button is pressed
110  *
111  * @param[in] gh The window handle (must be a radio widget)
112  *
113  * @api
114  */
115 bool_t gwinRadioIsPressed(GHandle gh);
116 
117 /**
118  * @brief Find the currently pressed radio button in the specified group
119  * @return The handle of the pressed radio button or NULL if none are pressed
120  *
121  * @param[in] group The radio button group to be examined
122  *
123  * @return The handle of the currently pressed radio button
124  *
125  * @api
126  */
127 GHandle gwinRadioGetActive(uint16_t group);
128 
129 /**
130  * @defgroup Renderings_Radiobutton Renderings
131  *
132  * @brief Built-in rendering functions for the radiobutton widget.
133  *
134  * @details These function may be passed to @p gwinSetCustomDraw() to get different radiobutton drawing styles.
135  *
136  * @note In your custom radiobutton drawing function you may optionally call these
137  * standard functions and then draw your extra details on top.
138  * @note These custom drawing routines don't have to worry about setting clipping as the framework
139  * sets clipping to the object window prior to calling these routines.
140  *
141  * @{
142  */
143 
144 /**
145  * @brief The default rendering function for the radiobutton widget
146  *
147  * @param[in] gw The widget object (must be a button radioobject)
148  * @param[in] param A parameter passed in from the user. Ignored by this function.
149  *
150  * @api
151  */
152 void gwinRadioDraw_Radio(GWidgetObject *gw, void *param);
153 
154 /**
155  * @brief Renders the radiobutton in form of a regular rectangular button
156  *
157  * @param[in] gw The widget object (must be a button radioobject)
158  * @param[in] param A parameter passed in from the user. Ignored by this function.
159  *
160  * @api
161  */
162 void gwinRadioDraw_Button(GWidgetObject *gw, void *param);
163 
164 /**
165  * @brief Used to render tabbed menus.
166  *
167  * @details Multiple radiobutton widgets can be placed right next to each other and be used to implement
168  * a tabbed menu using this rendering function.
169  *
170  * @note This exists for legacy reasons. Have a look at the @p Tabset widget instead.
171  *
172  * @param[in] gw The widget object (must be a button radioobject)
173  * @param[in] param A parameter passed in from the user. Ignored by this function.
174  *
175  * @api
176  */
177 void gwinRadioDraw_Tab(GWidgetObject *gw, void *param);
178 /** @} */
179 
180 #ifdef __cplusplus
181 }
182 #endif
183 
184 #endif /* _GWIN_RADIO_H */
185 /** @} */
The structure to initialise a widget.
Definition: gwin_widget.h:97
void gwinRadioDraw_Radio(GWidgetObject *gw, void *param)
The default rendering function for the radiobutton widget.
struct GEventGWinRadio GEventGWinRadio
A Button Event.
A Button Event.
Definition: gwin_radio.h:39
struct GRadioObject GRadioObject
The radio button widget structure.
The GWIN Widget structure.
Definition: gwin_widget.h:118
bool_t gwinRadioIsPressed(GHandle gh)
Is the radio button currently pressed.
void gwinRadioDraw_Tab(GWidgetObject *gw, void *param)
Used to render tabbed menus.
void gwinRadioDraw_Button(GWidgetObject *gw, void *param)
Renders the radiobutton in form of a regular rectangular button.
uint16_t WidgetTag
Defines a the type of a tag on a widget.
Definition: gwin_widget.h:81
void gwinRadioPress(GHandle gh)
Press this radio button (and by definition unset any others in the group)
A window object structure.
Definition: gwin.h:40
GHandle gwinGRadioCreate(GDisplay *g, GRadioObject *gb, const GWidgetInit *pInit, uint16_t group)
Create a radio widget.
The radio button widget structure.
Definition: gwin_radio.h:60
GHandle gwinRadioGetActive(uint16_t group)
Find the currently pressed radio button in the specified group.