µGFX  2.9
version 2.9
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.io/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 GFXON in your gfxconf.h
21  * @pre GWIN_NEED_RADIO must be set to GFXON 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  gU16 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  gU16 toggle;
64  #endif
65  gU16 group;
67 
68 /**
69  * @brief Create a radio widget.
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 GRadioObject structure to initialise. If this is NULL the structure is dynamically allocated.
74  * @param[in] pInit The initialisation parameters
75  * @param[in] group The group of radio buttons this radio button belongs to.
76  *
77  * @note Only one radio button in any group is ever pressed at one time. Pressing one radio button will
78  * release all others in the group.
79  * @note The drawing color and the background color get set to the current defaults. If you haven't called
80  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are GFX_WHITE and GFX_BLACK respectively.
81  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
82  * is no default font and text drawing operations will no nothing.
83  * @note A radio button remembers its normal drawing state. If there is a window manager then it is automatically
84  * redrawn if the window is moved or its visibility state is changed.
85  * @note A radio button supports mouse and a toggle input.
86  * @note When assigning a toggle, only one toggle is supported. If you try to assign more than one toggle it will
87  * forget the previous toggle. When assigning a toggle the role parameter must be 0.
88  *
89  * @api
90  */
91 GHandle gwinGRadioCreate(GDisplay *g, GRadioObject *gb, const GWidgetInit *pInit, gU16 group);
92 #define gwinRadioCreate(w, pInit, gr) gwinGRadioCreate(GDISP, w, pInit, gr)
93 
94 /**
95  * @brief Press this radio button (and by definition unset any others in the group)
96  *
97  * @param[in] gh The window handle (must be a radio widget)
98  *
99  * @api
100  */
102 
103 /**
104  * @brief Is the radio button currently pressed
105  * @return gTrue if the button is pressed
106  *
107  * @param[in] gh The window handle (must be a radio widget)
108  *
109  * @api
110  */
112 
113 /**
114  * @brief Find the currently pressed radio button in the specified group
115  * @return The handle of the pressed radio button or NULL if none are pressed
116  *
117  * @param[in] group The radio button group to be examined
118  *
119  * @return The handle of the currently pressed radio button
120  *
121  * @api
122  */
124 
125 /**
126  * @defgroup Renderings_Radiobutton Renderings
127  *
128  * @brief Built-in rendering functions for the radiobutton widget.
129  *
130  * @details These function may be passed to @p gwinSetCustomDraw() to get different radiobutton drawing styles.
131  *
132  * @note In your custom radiobutton drawing function you may optionally call these
133  * standard functions and then draw your extra details on top.
134  * @note These custom drawing routines don't have to worry about setting clipping as the framework
135  * sets clipping to the object window prior to calling these routines.
136  *
137  * @{
138  */
139 
140 /**
141  * @brief The default rendering function for the radiobutton widget
142  *
143  * @param[in] gw The widget object (must be a button radioobject)
144  * @param[in] param A parameter passed in from the user. Ignored by this function.
145  *
146  * @api
147  */
148 void gwinRadioDraw_Radio(GWidgetObject *gw, void *param);
149 
150 /**
151  * @brief Renders the radiobutton in form of a regular rectangular button
152  *
153  * @param[in] gw The widget object (must be a button radioobject)
154  * @param[in] param A parameter passed in from the user. Ignored by this function.
155  *
156  * @api
157  */
158 void gwinRadioDraw_Button(GWidgetObject *gw, void *param);
159 
160 /**
161  * @brief Used to render tabbed menus.
162  *
163  * @details Multiple radiobutton widgets can be placed right next to each other and be used to implement
164  * a tabbed menu using this rendering function.
165  *
166  * @note This exists for legacy reasons. Have a look at the @p Tabset widget instead.
167  *
168  * @param[in] gw The widget object (must be a button radioobject)
169  * @param[in] param A parameter passed in from the user. Ignored by this function.
170  *
171  * @api
172  */
173 void gwinRadioDraw_Tab(GWidgetObject *gw, void *param);
174 /** @} */
175 
176 #endif /* _GWIN_RADIO_H */
177 /** @} */
GHandle gwinGRadioCreate(GDisplay *g, GRadioObject *gb, const GWidgetInit *pInit, gU16 group)
Create a radio widget.
struct GRadioObject GRadioObject
The radio button widget structure.
GHandle gwinRadioGetActive(gU16 group)
Find the currently pressed radio button in the specified group.
void gwinRadioPress(GHandle gh)
Press this radio button (and by definition unset any others in the group)
gBool gwinRadioIsPressed(GHandle gh)
Is the radio button currently pressed.
struct GEventGWinRadio GEventGWinRadio
A Button Event.
void gwinRadioDraw_Button(GWidgetObject *gw, void *param)
Renders the radiobutton in form of a regular rectangular button.
void gwinRadioDraw_Radio(GWidgetObject *gw, void *param)
The default rendering function for the radiobutton widget.
void gwinRadioDraw_Tab(GWidgetObject *gw, void *param)
Used to render tabbed menus.
gU16 WidgetTag
Defines a the type of a tag on a widget.
Definition: gwin_widget.h:81
A Button Event.
Definition: gwin_radio.h:39
The radio button widget structure.
Definition: gwin_radio.h:60
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