1 /***********************************************************************
2 	created:	13/4/2004
3 	author:		Paul D Turner
4 
5 	purpose:	Interface to base class for Slider widget
6 *************************************************************************/
7 /***************************************************************************
8  *   Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team
9  *
10  *   Permission is hereby granted, free of charge, to any person obtaining
11  *   a copy of this software and associated documentation files (the
12  *   "Software"), to deal in the Software without restriction, including
13  *   without limitation the rights to use, copy, modify, merge, publish,
14  *   distribute, sublicense, and/or sell copies of the Software, and to
15  *   permit persons to whom the Software is furnished to do so, subject to
16  *   the following conditions:
17  *
18  *   The above copyright notice and this permission notice shall be
19  *   included in all copies or substantial portions of the Software.
20  *
21  *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22  *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23  *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
24  *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
25  *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
26  *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
27  *   OTHER DEALINGS IN THE SOFTWARE.
28  ***************************************************************************/
29 #ifndef _CEGUISlider_h_
30 #define _CEGUISlider_h_
31 
32 #include "../Base.h"
33 #include "../Window.h"
34 
35 
36 #if defined(_MSC_VER)
37 #	pragma warning(push)
38 #	pragma warning(disable : 4251)
39 #endif
40 
41 
42 // Start of CEGUI namespace section
43 namespace CEGUI
44 {
45 
46 /*!
47 \brief
48     Base class for ItemEntry window renderer objects.
49 */
50 class CEGUIEXPORT SliderWindowRenderer : public WindowRenderer
51 {
52 public:
53     /*!
54     \brief
55         Constructor
56     */
57     SliderWindowRenderer(const String& name);
58 
59     /*!
60     \brief
61         update the size and location of the thumb to properly represent the current state of the slider
62     */
63     virtual void    updateThumb(void)   = 0;
64 
65     /*!
66     \brief
67         return value that best represents current slider value given the current location of the thumb.
68 
69     \return
70         float value that, given the thumb widget position, best represents the current value for the slider.
71     */
72     virtual float   getValueFromThumb(void) const   = 0;
73 
74     /*!
75     \brief
76         Given window location \a pt, return a value indicating what change should be
77         made to the slider.
78 
79     \param pt
80         Point object describing a pixel position in window space.
81 
82     \return
83         - -1 to indicate slider should be moved to a lower setting.
84         -  0 to indicate slider should not be moved.
85         - +1 to indicate slider should be moved to a higher setting.
86     */
87     virtual float   getAdjustDirectionFromPoint(const Vector2f& pt) const  = 0;
88 };
89 
90 
91 /*!
92 \brief
93 	Base class for Slider widgets.
94 
95 	The slider widget has a default range of 0.0f - 1.0f.  This enables use of the slider value to scale
96 	any value needed by way of a simple multiplication.
97 */
98 class CEGUIEXPORT Slider : public Window
99 {
100 public:
101 	static const String EventNamespace;				//!< Namespace for global events
102     static const String WidgetTypeName;             //!< Window factory name
103 
104 	/*************************************************************************
105 		Event name constants
106 	*************************************************************************/
107     /** Event fired when the slider value changes.
108      * Handlers are passed a const WindowEventArgs reference with
109      * WindowEventArgs::window set to the Slider whose value has changed.
110      */
111 	static const String EventValueChanged;
112     /** Event fired when the user begins dragging the thumb.
113      * Handlers are passed a const WindowEventArgs reference with
114      * WindowEventArgs::window set to the Slider whose thumb has started to
115      * be dragged.
116      */
117 	static const String EventThumbTrackStarted;
118     /** Event fired when the user releases the thumb.
119      * Handlers are passed a const WindowEventArgs reference with
120      * WindowEventArgs::window set to the Slider whose thumb has been released.
121      */
122 	static const String EventThumbTrackEnded;
123 
124     /*************************************************************************
125         Child Widget name suffix constants
126     *************************************************************************/
127     static const String ThumbName;            //!< Widget name for the thumb component.
128 
129 	/*************************************************************************
130 		Accessors
131 	*************************************************************************/
132 	/*!
133 	\brief
134 		return the current slider value.
135 
136 	\return
137 		float value equal to the sliders current value.
138 	*/
getCurrentValue(void)139 	float	getCurrentValue(void) const			{return d_value;}
140 
141 
142 	/*!
143 	\brief
144 		return the maximum value set for this widget
145 
146 	\return
147 		float value equal to the currently set maximum value for this slider.
148 	*/
getMaxValue(void)149 	float	getMaxValue(void) const				{return d_maxValue;}
150 
151 
152 	/*!
153 	\brief
154 		return the current click step setting for the slider.
155 
156 		The click step size is the amount the slider value will be adjusted when the widget
157 		is clicked wither side of the slider thumb.
158 
159 	\return
160 		float value representing the current click step setting.
161 	*/
getClickStep(void)162 	float	getClickStep(void) const		{return d_step;}
163 
164 
165     /*!
166     \brief
167         Return a pointer to the Thumb component widget for this Slider.
168 
169     \return
170         Pointer to a Thumb object.
171 
172     \exception UnknownObjectException
173         Thrown if the Thumb component does not exist.
174     */
175     Thumb* getThumb() const;
176 
177 
178 	/*************************************************************************
179 		Manipulators
180 	*************************************************************************/
181 	/*!
182 	\brief
183 		Initialises the Window based object ready for use.
184 
185 	\note
186 		This must be called for every window created.  Normally this is handled automatically by the WindowFactory for each Window type.
187 
188 	\return
189 		Nothing
190 	*/
191 	virtual	void	initialiseComponents(void);
192 
193 
194 	/*!
195 	\brief
196 		set the maximum value for the slider.  Note that the minimum value is fixed at 0.
197 
198 	\param maxVal
199 		float value specifying the maximum value for this slider widget.
200 
201 	\return
202 		Nothing.
203 	*/
204 	void	setMaxValue(float maxVal);
205 
206 
207 	/*!
208 	\brief
209 		set the current slider value.
210 
211 	\param value
212 		float value specifying the new value for this slider widget.
213 
214 	\return
215 		Nothing.
216 	*/
217 	void	setCurrentValue(float value);
218 
219 
220 	/*!
221 	\brief
222 		set the current click step setting for the slider.
223 
224 		The click step size is the amount the slider value will be adjusted when the widget
225 		is clicked wither side of the slider thumb.
226 
227 	\param step
228 		float value representing the click step setting to use.
229 
230 	\return
231 		Nothing.
232 	*/
setClickStep(float step)233 	void	setClickStep(float step)		{d_step = step;}
234 
235 
236 	/*************************************************************************
237 		Construction / Destruction
238 	*************************************************************************/
239 	/*!
240 	\brief
241 		Slider base class constructor
242 	*/
243 	Slider(const String& type, const String& name);
244 
245 
246 	/*!
247 	\brief
248 		Slider base class destructor
249 	*/
250 	virtual ~Slider(void);
251 
252 
253 protected:
254 	/*************************************************************************
255 		Implementation Functions
256 	*************************************************************************/
257 	/*!
258 	\brief
259 		update the size and location of the thumb to properly represent the current state of the slider
260 	*/
261 	virtual void	updateThumb(void);
262 
263 
264 	/*!
265 	\brief
266 		return value that best represents current slider value given the current location of the thumb.
267 
268 	\return
269 		float value that, given the thumb widget position, best represents the current value for the slider.
270 	*/
271 	virtual float	getValueFromThumb(void) const;
272 
273 
274 	/*!
275 	\brief
276 		Given window location \a pt, return a value indicating what change should be
277 		made to the slider.
278 
279 	\param pt
280 		Point object describing a pixel position in window space.
281 
282 	\return
283 		- -1 to indicate slider should be moved to a lower setting.
284 		-  0 to indicate slider should not be moved.
285 		- +1 to indicate slider should be moved to a higher setting.
286 	*/
287 	virtual float	getAdjustDirectionFromPoint(const Vector2f& pt) const;
288 
289 
290     /*!
291     \brief
292         update the size and location of the thumb to properly represent the current state of the slider
293     */
294     //virtual void    updateThumb_impl(void)   = 0;
295 
296 
297     /*!
298     \brief
299         return value that best represents current slider value given the current location of the thumb.
300 
301     \return
302         float value that, given the thumb widget position, best represents the current value for the slider.
303     */
304     //virtual float   getValueFromThumb_impl(void) const   = 0;
305 
306 
307     /*!
308     \brief
309         Given window location \a pt, return a value indicating what change should be
310         made to the slider.
311 
312     \param pt
313         Point object describing a pixel position in window space.
314 
315     \return
316         - -1 to indicate slider should be moved to a lower setting.
317         -  0 to indicate slider should not be moved.
318         - +1 to indicate slider should be moved to a higher setting.
319     */
320     //virtual float   getAdjustDirectionFromPoint_impl(const Point& pt) const  = 0;
321 
322 	/*!
323 	\brief
324 		handler function for when thumb moves.
325 	*/
326 	bool	handleThumbMoved(const EventArgs& e);
327 
328 
329 	/*!
330 	\brief
331 		handler function for when thumb tracking begins
332 	*/
333 	bool	handleThumbTrackStarted(const EventArgs& e);
334 
335 
336 	/*!
337 	\brief
338 		handler function for when thumb tracking begins
339 	*/
340 	bool	handleThumbTrackEnded(const EventArgs& e);
341 
342     // validate window renderer
343 	virtual bool validateWindowRenderer(const WindowRenderer* renderer) const;
344 
345 
346 	/*************************************************************************
347 		New event handlers for slider widget
348 	*************************************************************************/
349 	/*!
350 	\brief
351 		Handler triggered when the slider value changes
352 	*/
353 	virtual void	onValueChanged(WindowEventArgs& e);
354 
355 
356 	/*!
357 	\brief
358 		Handler triggered when the user begins to drag the slider thumb.
359 	*/
360 	virtual void	onThumbTrackStarted(WindowEventArgs& e);
361 
362 
363 	/*!
364 	\brief
365 		Handler triggered when the slider thumb is released
366 	*/
367 	virtual void	onThumbTrackEnded(WindowEventArgs& e);
368 
369 
370 	/*************************************************************************
371 		Overridden event handlers
372 	*************************************************************************/
373 	virtual void	onMouseButtonDown(MouseEventArgs& e);
374 	virtual	void	onMouseWheel(MouseEventArgs& e);
375 
376 
377 	/*************************************************************************
378 		Implementation Data
379 	*************************************************************************/
380 	float	d_value;		//!< current slider value
381 	float	d_maxValue;		//!< slider maximum value (minimum is fixed at 0)
382 	float	d_step;			//!< amount to adjust slider by when clicked (and not dragged).
383 
384 private:
385 
386 	/*************************************************************************
387 		Private methods
388 	*************************************************************************/
389 	void	addSliderProperties(void);
390 };
391 
392 } // End of  CEGUI namespace section
393 
394 #if defined(_MSC_VER)
395 #	pragma warning(pop)
396 #endif
397 
398 #endif	// end of guard _CEGUISlider_h_
399