aboutsummaryrefslogtreecommitdiffstats
path: root/src/gwin/gwin_button.h
blob: 4a80cdf712d42c5554da2479c4955318f0049a26 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
/*
 * This file is subject to the terms of the GFX License. If a copy of
 * the license was not distributed with this file, you can obtain one at:
 *
 *              http://ugfx.io/license.html
 */

/**
 * @file    src/gwin/gwin_button.h
 * @brief   GWIN Graphic window subsystem header file.
 *
 * @defgroup Button Button
 * @ingroup Widgets
 *
 * @brief		PushButton widget.
 *
 * @details		GWIN allows it to easily create buttons with different styles
 *				and check for different meta states such as: PRESSED, CLICKED,
 *				RELEASED etc.
 *
 * @pre			GFX_USE_GWIN must be set to GFXON in your gfxconf.h
 * @pre			GWIN_NEED_BUTTON must be set to GFXON in your gfxconf.h
 * @{
 */

#ifndef _GWIN_BUTTON_H
#define _GWIN_BUTTON_H

/* This file is included within "src/gwin/gwin_widget.h" */

/**
 * @brief	The Event Type for a Button Event
 */
#define GEVENT_GWIN_BUTTON		(GEVENT_GWIN_CTRL_FIRST+0)

/**
 * @brief	A Button Event
 * @note	There are currently no GEventGWinButton listening flags - use 0 as the flags to @p gwinAttachListener()
 */
typedef GEventGWin		GEventGWinButton;

/**
 * @brief	The internal button flags
 * @note	Used only for writing a custom draw routine.
 * @{
 */
#define GBUTTON_FLG_PRESSED		0x01
/** @} */

/**
 * @brief	The button widget structure
 * @note	Do not use the members directly - treat it as a black-box.
 */
typedef struct GButtonObject {
	GWidgetObject		w;
	#if GINPUT_NEED_TOGGLE
		uint16_t		toggle;
	#endif
} GButtonObject;

/**
 * @brief   Create a button widget.
 * @return  NULL if there is no resultant drawing area, otherwise a window handle.
 *
 * @param[in] g			The GDisplay to display this window on
 * @param[in] gb		The GButtonObject structure to initialise. If this is NULL the structure is dynamically allocated.
 * @param[in] pInit		The initialisation parameters
 *
 * @note				The drawing color and the background color get set to the current defaults. If you haven't called
 * 						@p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are GFX_WHITE and GFX_BLACK respectively.
 * @note				The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
 * 						is no default font and text drawing operations will no nothing.
 * @note				A button remembers its normal drawing state. If there is a window manager then it is automatically
 * 						redrawn if the window is moved or its visibility state is changed.
 * @note				A button supports mouse and a toggle input.
 * @note				When assigning a toggle, only one toggle is supported. If you try to assign more than one toggle it will
 * 						forget the previous toggle. When assigning a toggle the role parameter must be 0.
 *
 * @api
 */	
GHandle gwinGButtonCreate(GDisplay *g, GButtonObject *gb, const GWidgetInit *pInit);
#define gwinButtonCreate(gb, pInit)			gwinGButtonCreate(GDISP, gb, pInit)

/**
 * @brief	Is the button current pressed
 * @return	gTrue if the button is pressed
 *
 * @param[in] gh	The window handle (must be a button widget)
 *
 * @api
 */
gBool gwinButtonIsPressed(GHandle gh);

/**
 * @defgroup Renderings_Button Renderings
 *
 * @brief				Built-in rendering functions for the button widget.
 *
 * @details				These function may be passed to @p gwinSetCustomDraw() to get different button drawing styles.
 *
 * @note				In your custom button drawing function you may optionally call these
 * 						standard functions and then draw your extra details on top.
 * @note				The standard functions below ignore the param parameter except for @p gwinButtonDraw_Image().
 * @note				The image custom draw function  @p gwinButtonDraw_Image() uses param to pass in the gdispImage pointer.
 * @note				These custom drawing routines don't have to worry about setting clipping as the framework
 * 						sets clipping to the object window prior to calling these routines.
 *
 * @{
 */

/**
 * @brief				The default rendering function for the button widget
 *
 * @param[in] gw		The widget object (must be a button object)
 * @param[in] param		A parameter passed in from the user. Ignored by this function.
 *
 * @api
 */
void gwinButtonDraw_Normal(GWidgetObject *gw, void *param);

#if GDISP_NEED_ARC || defined(__DOXYGEN__)
	/**
	 * @brief				Renders a rectangular button with rounded corners
	 *
	 * @param[in] gw		The widget object (must be a button object)
	 * @param[in] param		A parameter passed in from the user. Ignored by this function.
	 *
	 * @pre					GDISP_NEED_ARC must be set to GFXON
	 *
	 * @api
	 */
	void gwinButtonDraw_Rounded(GWidgetObject *gw, void *param);
#endif

#if GDISP_NEED_ELLIPSE || defined(__DOXYGEN__)
	/**
	 * @brief				Renders a button with an elliptical shape
	 *
	 * @param[in] gw		The widget object (must be a button object)
	 * @param[in] param		A parameter passed in from the user. Ignored by this function.
	 *
	 * @pre					GDISP_NEED_ELLIPSE must be set to GFXON
	 *
	 * @api
	 */
	void gwinButtonDraw_Ellipse(GWidgetObject *gw, void *param);
#endif

#if GDISP_NEED_CONVEX_POLYGON || defined(__DOXYGEN__)
	/**
	 * @brief				Renders a button in a shape of an arrow pointing up.
	 *
	 * @param[in] gw		The widget object (must be a button object)
	 * @param[in] param		A parameter passed in from the user. Ignored by this function.
	 *
	 * @pre					GDISP_NEED_CONVEX_POLYGON must be set to GFXON
	 *
	 * @api
	 */
	void gwinButtonDraw_ArrowUp(GWidgetObject *gw, void *param);

	/**
	 * @brief				Renders a button in a shape of an arrow pointing down.
	 *
	 * @param[in] gw		The widget object (must be a button object)
	 * @param[in] param		A parameter passed in from the user. Ignored by this function.
	 *
	 * @pre					GDISP_NEED_CONVEX_POLYGON must be set to GFXON
	 *
	 * @api
	 */
	void gwinButtonDraw_ArrowDown(GWidgetObject *gw, void *param);

	/**
	 * @brief				Renders a button in a shape of an arrow pointing left.
	 *
	 * @param[in] gw		The widget object (must be a button object)
	 * @param[in] param		A parameter passed in from the user. Ignored by this function.
	 *
	 * @pre					GDISP_NEED_CONVEX_POLYGON must be set to GFXON
	 *
	 * @api
	 */
	void gwinButtonDraw_ArrowLeft(GWidgetObject *gw, void *param);

	/**
	 * @brief				Renders a button in a shape of an arrow pointing right.
	 *
	 * @param[in] gw		The widget object (must be a button object)
	 * @param[in] param		A parameter passed in from the user. Ignored by this function.
	 *
	 * @pre					GDISP_NEED_CONVEX_POLYGON must be set to GFXON
	 *
	 * @api
	 */
	void gwinButtonDraw_ArrowRight(GWidgetObject *gw, void *param);
#endif

#if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
	/**
	 * @brief				Renders a button using individual images for each button state.
	 *
	 * @param[in] gw		The widget object (must be a button object)
	 * @param[in] param		A parameter passed in from the user. Must be an image handle. See note below.
	 *
	 * @note				The image must be already opened before calling  @p gwinSetCustomDraw(). The image should be 3
	 * 						times the height of the button. The button image is repeated 3 times vertically, the first (top) for
	 * 						the "up" image, the 2nd for the "down" image, and the third (bottom) image for the disabled state. If
	 * 						the disabled state is never going to be used then the image can be just 2 times the button height.
	 * 						No checking is done to compare the size of the button to the size of the image.
	 * 						Note text is drawn on top of the image.
	 *
	 * @pre					GDISP_NEED_IMAGE must be set to GFXON
	 *
	 * @api
	 */
	void gwinButtonDraw_Image(GWidgetObject *gw, void *param);
#endif
/** @} */

#endif /* _GWIN_BUTTON_H */
/** @} */