version 2.8
gwin_slider.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_slider.h
10  * @brief GWIN Graphic window subsystem header file.
11  *
12  * @defgroup Slider Slider
13  * @ingroup Widgets
14  *
15  * @brief Slider widget.
16  *
17  * @details Extended events can be enabled using @p gwinSliderSendExtendedEvents().
18  *
19  * @pre GFX_USE_GWIN must be set to TRUE in your gfxconf.h
20  * @pre GWIN_NEED_SLIDER must be set to TRUE in your gfxconf.h
21  * @{
22  */
23 
24 #ifndef _GWIN_SLIDER_H
25 #define _GWIN_SLIDER_H
26 
27 /* This file is included within "src/gwin/gwin_widget.h" */
28 
29 #define GEVENT_GWIN_SLIDER (GEVENT_GWIN_CTRL_FIRST+1)
30 
31 typedef struct GEventGWinSlider {
32  GEventType type; // The type of this event (GEVENT_GWIN_SLIDER)
33  GHandle gwin; // The slider that is returning results
34  #if GWIN_WIDGET_TAGS
35  WidgetTag tag; // The slider tag
36  #endif
37  int position;
38 
39  uint8_t action;
40  #define GSLIDER_EVENT_SET 4 /* Slider position is set. This is the only event returned by default */
41  #define GSLIDER_EVENT_CANCEL 3 /* Slider position changing has been cancelled */
42  #define GSLIDER_EVENT_START 2 /* Slider position has started changing */
43  #define GSLIDER_EVENT_MOVE 1 /* Slider position has been moved */
44 } GEventGWinSlider;
45 
46 // There are currently no GEventGWinSlider listening flags - use 0
47 
48 /**
49  * @brief The internal slider object flags
50  * @note Used only for writing a custom draw routine.
51  * @{
52  */
53 #define GSLIDER_FLG_EXTENDED_EVENTS 0x01
54 /** @} */
55 
56 // A slider window
57 typedef struct GSliderObject {
58  GWidgetObject w;
59  #if GINPUT_NEED_TOGGLE
60  uint16_t t_dn;
61  uint16_t t_up;
62  #endif
63  #if GINPUT_NEED_DIAL
64  uint16_t dial;
65  #endif
66  coord_t dpos;
67  int min;
68  int max;
69  int pos;
70 } GSliderObject;
71 
72 #ifdef __cplusplus
73 extern "C" {
74 #endif
75 
76 /**
77  * @brief Create a slider window.
78  * @return NULL if there is no resultant drawing area, otherwise a window handle.
79  *
80  * @param[in] g The GDisplay to display this window on
81  * @param[in] gb The GSliderObject structure to initialise. If this is NULL the structure is dynamically allocated.
82  * @param[in] pInit The initialization parameters to use
83  *
84  * @note The drawing color and the background color get set to the current defaults. If you haven't called
85  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are White and Black respectively.
86  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
87  * is no default font and text drawing operations will no nothing.
88  * @note A slider remembers its normal drawing state. If there is a window manager then it is automatically
89  * redrawn if the window is moved or its visibility state is changed.
90  * @note The initial slider range is from 0 to 100 with an initial position of 0.
91  * @note A slider supports mouse, toggle and dial input.
92  * @note When assigning a toggle, only one toggle is supported per role. If you try to assign more than
93  * one toggle to a role it will forget the previous toggle. Two roles are supported:
94  * Role 0 = toggle for down, Role 1 = toggle for up.
95  * @note When assigning a dial, only one dial is supported. If you try to assign more than one dial
96  * it will forget the previous dial. Only dial role 0 is supported.
97  *
98  * @api
99  */
100 GHandle gwinGSliderCreate(GDisplay *g, GSliderObject *gb, const GWidgetInit *pInit);
101 #define gwinSliderCreate(w, pInit) gwinGSliderCreate(GDISP, w, pInit)
102 
103 /**
104  * @brief Set the slider range.
105  *
106  * @param[in] gh The window handle (must be a slider window)
107  * @param[in] min The minimum value
108  * @param[in] max The maximum value
109  * @note Sets the position to the minimum value.
110  * @note The slider is not automatically drawn. Call gwinRedraw() after changing the range.
111  *
112  * @api
113  */
114 void gwinSliderSetRange(GHandle gh, int min, int max);
115 
116 /**
117  * @brief Set the slider position.
118  *
119  * @param[in] gh The window handle (must be a slider window)
120  * @param[in] pos The new position
121  * @note If the new position is outside the slider range then the position
122  * is set to the closest end of the range.
123  * @note The slider is not automatically drawn. Call gwinRedraw() after changing the position.
124  *
125  * @api
126  */
127 void gwinSliderSetPosition(GHandle gh, int pos);
128 
129 /**
130  * @brief Get the current slider position.
131  * @return The slider position
132  *
133  * @param[in] gh The window handle (must be a slider window)
134  *
135  * @note The use of a listener to get the slider position is recommended if you
136  * want continuous updates on the slider position.
137  *
138  * @api
139  */
140 #define gwinSliderGetPosition(gh) (((GSliderObject *)(gh))->pos)
141 
142 /**
143  * @brief Should the slider send extended events.
144  *
145  * @param[in] gh The window handle (must be a slider window)
146  * @param[in] enabled TRUE to enable extended events, FALSE to disable them
147  *
148  * @note The slider by default will only send slider events with an action of GSLIDER_EVENT_SET.
149  * This call can be used to enable other slider action's to be sent as events
150  *
151  * @api
152  */
153 void gwinSliderSendExtendedEvents(GHandle gh, bool_t enabled);
154 
155 /**
156  * @defgroup Renderings_Slider Renderings
157  *
158  * @brief Built-in rendering functions for the slider widget.
159  *
160  * @details These function may be passed to @p gwinSetCustomDraw() to get different slider drawing styles.
161  *
162  * @note In your custom slider drawing function you may optionally call these
163  * standard functions and then draw your extra details on top.
164  * @note These custom drawing routines don't have to worry about setting clipping as the framework
165  * sets clipping to the object window prior to calling these routines.
166  *
167  * @{
168  */
169 
170 /**
171  * @brief The default rendering function for the slider widget.
172  *
173  * @param[in] gw The widget object (must be a slider object).
174  * @param[in] param A parameter passed in from the user. Ignored by this function.
175  *
176  * @api
177  */
178 void gwinSliderDraw_Std(GWidgetObject *gw, void *param);
179 
180 #if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
181  /**
182  * @brief The default rendering function
183  *
184  * @param[in] gw The widget object (must be a slider object).
185  * @param[in] param A parameter passed in from the user. Must be an image handle. See note below.
186  *
187  * @note The image must be already opened before calling @p gwinSetCustomDraw(). The image should be 3
188  * times the height of the button. The button image is repeated 3 times vertically, the first (top) for
189  * the "up" image, the 2nd for the "down" image, and the third (bottom) image for the disabled state. If
190  * the disabled state is never going to be used then the image can be just 2 times the button height.
191  * No checking is done to compare the size of the button to the size of the image.
192  * No text is drawn on top of the image.
193  *
194  * @pre GDISP_NEED_IMAGE must be set to TRUE
195  *
196  * @api
197  */
198 void gwinSliderDraw_Image(GWidgetObject *gw, void *param);
199 #endif /* GDISP_NEED_IMAGE */
200 /** @} */
201 
202 #ifdef __cplusplus
203 }
204 #endif
205 
206 #endif /* _GWIN_SLIDER_H */
207 /** @} */
void gwinSliderSendExtendedEvents(GHandle gh, bool_t enabled)
Should the slider send extended events.
Definition: gwin_slider.c:329
void gwinSliderSetPosition(GHandle gh, int pos)
Set the slider position.
Definition: gwin_slider.c:308
int16_t coord_t
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
The structure to initialise a widget.
Definition: gwin_widget.h:97
The GWIN Widget structure.
Definition: gwin_widget.h:118
uint16_t WidgetTag
Defines a the type of a tag on a widget.
Definition: gwin_widget.h:81
A window object structure.
Definition: gwin.h:40
void gwinSliderDraw_Image(GWidgetObject *gw, void *param)
The default rendering function.
void gwinSliderDraw_Std(GWidgetObject *gw, void *param)
The default rendering function for the slider widget.
Definition: gwin_slider.c:343
void gwinSliderSetRange(GHandle gh, int min, int max)
Set the slider range.
Definition: gwin_slider.c:293
GHandle gwinGSliderCreate(GDisplay *g, GSliderObject *gb, const GWidgetInit *pInit)
Create a slider window.
Definition: gwin_slider.c:275