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