µGFX  2.9
version 2.9
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.io/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 GFXON in your gfxconf.h
20  * @pre GWIN_NEED_SLIDER must be set to GFXON 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  gU8 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  gU16 t_dn;
61  gU16 t_up;
62  #endif
63  #if GINPUT_NEED_DIAL
64  gU16 dial;
65  #endif
66  gCoord dpos;
67  int min;
68  int max;
69  int pos;
70 } GSliderObject;
71 
72 /**
73  * @brief Create a slider window.
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 GSliderObject structure to initialise. If this is NULL the structure is dynamically allocated.
78  * @param[in] pInit The initialization parameters to use
79  *
80  * @note The drawing color and the background color get set to the current defaults. If you haven't called
81  * @p gwinSetDefaultColor() or @p gwinSetDefaultBgColor() then these are GFX_WHITE and GFX_BLACK respectively.
82  * @note The font gets set to the current default font. If you haven't called @p gwinSetDefaultFont() then there
83  * is no default font and text drawing operations will no nothing.
84  * @note A slider remembers its normal drawing state. If there is a window manager then it is automatically
85  * redrawn if the window is moved or its visibility state is changed.
86  * @note The initial slider range is from 0 to 100 with an initial position of 0.
87  * @note A slider supports mouse, toggle and dial input.
88  * @note When assigning a toggle, only one toggle is supported per role. If you try to assign more than
89  * one toggle to a role it will forget the previous toggle. Two roles are supported:
90  * Role 0 = toggle for down, Role 1 = toggle for up.
91  * @note When assigning a dial, only one dial is supported. If you try to assign more than one dial
92  * it will forget the previous dial. Only dial role 0 is supported.
93  *
94  * @api
95  */
96 GHandle gwinGSliderCreate(GDisplay *g, GSliderObject *gb, const GWidgetInit *pInit);
97 #define gwinSliderCreate(w, pInit) gwinGSliderCreate(GDISP, w, pInit)
98 
99 /**
100  * @brief Set the slider range.
101  *
102  * @param[in] gh The window handle (must be a slider window)
103  * @param[in] min The minimum value
104  * @param[in] max The maximum value
105  * @note Sets the position to the minimum value.
106  * @note The slider is not automatically drawn. Call gwinRedraw() after changing the range.
107  *
108  * @api
109  */
110 void gwinSliderSetRange(GHandle gh, int min, int max);
111 
112 /**
113  * @brief Set the slider position.
114  *
115  * @param[in] gh The window handle (must be a slider window)
116  * @param[in] pos The new position
117  * @note If the new position is outside the slider range then the position
118  * is set to the closest end of the range.
119  * @note The slider is not automatically drawn. Call gwinRedraw() after changing the position.
120  *
121  * @api
122  */
123 void gwinSliderSetPosition(GHandle gh, int pos);
124 
125 /**
126  * @brief Get the current slider position.
127  * @return The slider position
128  *
129  * @param[in] gh The window handle (must be a slider window)
130  *
131  * @note The use of a listener to get the slider position is recommended if you
132  * want continuous updates on the slider position.
133  *
134  * @api
135  */
136 #define gwinSliderGetPosition(gh) (((GSliderObject *)(gh))->pos)
137 
138 /**
139  * @brief Should the slider send extended events.
140  *
141  * @param[in] gh The window handle (must be a slider window)
142  * @param[in] enabled gTrue to enable extended events, gFalse to disable them
143  *
144  * @note The slider by default will only send slider events with an action of GSLIDER_EVENT_SET.
145  * This call can be used to enable other slider action's to be sent as events
146  *
147  * @api
148  */
149 void gwinSliderSendExtendedEvents(GHandle gh, gBool enabled);
150 
151 /**
152  * @defgroup Renderings_Slider Renderings
153  *
154  * @brief Built-in rendering functions for the slider widget.
155  *
156  * @details These function may be passed to @p gwinSetCustomDraw() to get different slider drawing styles.
157  *
158  * @note In your custom slider drawing function you may optionally call these
159  * standard functions and then draw your extra details on top.
160  * @note These custom drawing routines don't have to worry about setting clipping as the framework
161  * sets clipping to the object window prior to calling these routines.
162  *
163  * @{
164  */
165 
166 /**
167  * @brief The default rendering function for the slider widget.
168  *
169  * @param[in] gw The widget object (must be a slider object).
170  * @param[in] param A parameter passed in from the user. Ignored by this function.
171  *
172  * @api
173  */
174 void gwinSliderDraw_Std(GWidgetObject *gw, void *param);
175 
176 #if GDISP_NEED_IMAGE || defined(__DOXYGEN__)
177  /**
178  * @brief The default rendering function
179  *
180  * @param[in] gw The widget object (must be a slider object).
181  * @param[in] param A parameter passed in from the user. Must be an image handle. See note below.
182  *
183  * @note The image must be already opened before calling @p gwinSetCustomDraw(). The image should be 3
184  * times the height of the button. The button image is repeated 3 times vertically, the first (top) for
185  * the "up" image, the 2nd for the "down" image, and the third (bottom) image for the disabled state. If
186  * the disabled state is never going to be used then the image can be just 2 times the button height.
187  * No checking is done to compare the size of the button to the size of the image.
188  * No text is drawn on top of the image.
189  *
190  * @pre GDISP_NEED_IMAGE must be set to GFXON
191  *
192  * @api
193  */
194 void gwinSliderDraw_Image(GWidgetObject *gw, void *param);
195 #endif /* GDISP_NEED_IMAGE */
196 /** @} */
197 
198 #endif /* _GWIN_SLIDER_H */
199 /** @} */
gI16 gCoord
The type for a coordinate or length on the screen.
Definition: gdisp.h:39
void gwinSliderDraw_Std(GWidgetObject *gw, void *param)
The default rendering function for the slider widget.
Definition: gwin_slider.c:343
void gwinSliderDraw_Image(GWidgetObject *gw, void *param)
The default rendering function.
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
void gwinSliderSetPosition(GHandle gh, int pos)
Set the slider position.
Definition: gwin_slider.c:308
void gwinSliderSendExtendedEvents(GHandle gh, gBool enabled)
Should the slider send extended events.
Definition: gwin_slider.c:329
gU16 WidgetTag
Defines a the type of a tag on a widget.
Definition: gwin_widget.h:81
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