1 /*********************************************************************** 2 created: 25/4/2004 3 author: Paul D Turner 4 5 purpose: Interface for a 'Thumb' widget. Intended to be used as 6 part of other widgets such as scrollers and sliders. 7 *************************************************************************/ 8 /*************************************************************************** 9 * Copyright (C) 2004 - 2006 Paul D Turner & The CEGUI Development Team 10 * 11 * Permission is hereby granted, free of charge, to any person obtaining 12 * a copy of this software and associated documentation files (the 13 * "Software"), to deal in the Software without restriction, including 14 * without limitation the rights to use, copy, modify, merge, publish, 15 * distribute, sublicense, and/or sell copies of the Software, and to 16 * permit persons to whom the Software is furnished to do so, subject to 17 * the following conditions: 18 * 19 * The above copyright notice and this permission notice shall be 20 * included in all copies or substantial portions of the Software. 21 * 22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 23 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 24 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 25 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 26 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 27 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 28 * OTHER DEALINGS IN THE SOFTWARE. 29 ***************************************************************************/ 30 #ifndef _CEGUIThumb_h_ 31 #define _CEGUIThumb_h_ 32 33 #include "./PushButton.h" 34 #include <utility> 35 36 37 #if defined(_MSC_VER) 38 # pragma warning(push) 39 # pragma warning(disable : 4251) 40 # pragma warning(disable : 4996) 41 #endif 42 43 44 // Start of CEGUI namespace section 45 namespace CEGUI 46 { 47 48 /*! 49 \brief 50 Base class for Thumb widget. 51 52 The thumb widget is used to compose other widgets (like sliders and scroll bars). You would 53 not normally need to use this widget directly unless you are making a new widget of some type. 54 */ 55 class CEGUIEXPORT Thumb : public PushButton 56 { 57 public: 58 static const String EventNamespace; //!< Namespace for global events 59 static const String WidgetTypeName; //!< Window factory name 60 61 /************************************************************************* 62 Event name constants 63 *************************************************************************/ 64 // generated internally by Window 65 /** Event fired when the position of the thumb widget has changed (this 66 * event is only fired when hot tracking is enabled). 67 * Handlers are passed a const WindowEventArgs reference with 68 * WindowEventArgs::window set to the Thumb whose position has changed. 69 */ 70 static const String EventThumbPositionChanged; 71 /** Event fired when the user begins dragging the thumb. 72 * Handlers are passed a const WindowEventArgs reference with 73 * WindowEventArgs::window set to the Thumb that has started to be dragged 74 * by the user. 75 */ 76 static const String EventThumbTrackStarted; 77 /** Event fired when the user releases the thumb. 78 * Handlers are passed a const WindowEventArgs reference with 79 * WindowEventArgs::window set to the Thumb that has been released. 80 */ 81 static const String EventThumbTrackEnded; 82 83 84 /************************************************************************* 85 Accessor Functions 86 *************************************************************************/ 87 /*! 88 \brief 89 return whether hot-tracking is enabled or not. 90 91 \return 92 true if hot-tracking is enabled. false if hot-tracking is disabled. 93 */ isHotTracked(void)94 bool isHotTracked(void) const {return d_hotTrack;} 95 96 /*! 97 \brief 98 return whether the thumb is movable on the vertical axis. 99 100 \return 101 true if the thumb is movable along the vertical axis. 102 false if the thumb is fixed on the vertical axis. 103 */ isVertFree(void)104 bool isVertFree(void) const {return d_vertFree;} 105 106 /*! 107 \brief 108 return whether the thumb is movable on the horizontal axis. 109 110 \return 111 true if the thumb is movable along the horizontal axis. 112 false if the thumb is fixed on the horizontal axis. 113 */ isHorzFree(void)114 bool isHorzFree(void) const {return d_horzFree;} 115 116 117 /*! 118 \brief 119 Return a std::pair that describes the current range set for the vertical movement. 120 121 \return 122 a std::pair describing the current vertical range. The first element is the minimum value, 123 the second element is the maximum value. 124 */ 125 std::pair<float, float> getVertRange(void) const; 126 127 128 /*! 129 \brief 130 Return a std::pair that describes the current range set for the horizontal movement. 131 132 \return 133 a std::pair describing the current horizontal range. The first element is the minimum value, 134 the second element is the maximum value. 135 */ 136 std::pair<float, float> getHorzRange(void) const; 137 138 139 /************************************************************************* 140 Manipulator Functions 141 *************************************************************************/ 142 /*! 143 \brief 144 set whether the thumb uses hot-tracking. 145 146 \param setting 147 true to enable hot-tracking. false to disable hot-tracking. 148 149 \return 150 Nothing. 151 */ setHotTracked(bool setting)152 void setHotTracked(bool setting) {d_hotTrack = setting;} 153 154 155 /*! 156 \brief 157 set whether thumb is movable on the vertical axis. 158 159 \param setting 160 true to allow movement of thumb along the vertical axis. false to fix thumb on the vertical axis. 161 162 \return 163 nothing. 164 */ setVertFree(bool setting)165 void setVertFree(bool setting) {d_vertFree = setting;} 166 167 168 /*! 169 \brief 170 set whether thumb is movable on the horizontal axis. 171 172 \param setting 173 true to allow movement of thumb along the horizontal axis. false to fix thumb on the horizontal axis. 174 175 \return 176 nothing. 177 */ setHorzFree(bool setting)178 void setHorzFree(bool setting) {d_horzFree = setting;} 179 180 181 /*! 182 \brief 183 set the movement range of the thumb for the vertical axis. 184 185 The values specified here are relative to the parent window for the thumb, and are specified in whichever 186 metrics mode is active for the widget. 187 188 \param min 189 the minimum setting for the thumb on the vertical axis. 190 191 \param max 192 the maximum setting for the thumb on the vertical axis. 193 194 \return 195 Nothing. 196 */ 197 void setVertRange(float min, float max); 198 199 /*! 200 \brief 201 set the movement range of the thumb for the vertical axis. 202 203 The values specified here are relative to the parent window for the thumb, and are specified in whichever 204 metrics mode is active for the widget. 205 206 \param range 207 the setting for the thumb on the vertical axis. 208 209 \return 210 Nothing. 211 */ 212 void setVertRange(const std::pair<float, float> &range); 213 214 215 /*! 216 \brief 217 set the movement range of the thumb for the horizontal axis. 218 219 The values specified here are relative to the parent window for the thumb, and are specified in whichever 220 metrics mode is active for the widget. 221 222 \param min 223 the minimum setting for the thumb on the horizontal axis. 224 225 \param max 226 the maximum setting for the thumb on the horizontal axis. 227 228 \return 229 Nothing. 230 */ 231 void setHorzRange(float min, float max); 232 /*! 233 \brief 234 set the movement range of the thumb for the horizontal axis. 235 236 The values specified here are relative to the parent window for the thumb, and are specified in whichever 237 metrics mode is active for the widget. 238 239 \param range 240 the setting for the thumb on the horizontal axis. 241 242 \return 243 Nothing. 244 */ 245 void setHorzRange(const std::pair<float, float> &range); 246 247 248 /************************************************************************* 249 Construction / Destruction 250 *************************************************************************/ 251 /*! 252 \brief 253 Constructor for Thumb objects 254 */ 255 Thumb(const String& type, const String& name); 256 257 258 /*! 259 \brief 260 Destructor for Thumb objects 261 */ 262 virtual ~Thumb(void); 263 264 265 protected: 266 // overridden from base class 267 void banPropertiesForAutoWindow(); 268 269 /************************************************************************* 270 New Thumb Events 271 *************************************************************************/ 272 /*! 273 \brief 274 event triggered internally when the position of the thumb 275 */ 276 virtual void onThumbPositionChanged(WindowEventArgs& e); 277 278 279 /*! 280 \brief 281 Handler triggered when the user begins to drag the thumb. 282 */ 283 virtual void onThumbTrackStarted(WindowEventArgs& e); 284 285 286 /*! 287 \brief 288 Handler triggered when the thumb is released 289 */ 290 virtual void onThumbTrackEnded(WindowEventArgs& e); 291 292 293 294 /************************************************************************* 295 Overridden event handling routines 296 *************************************************************************/ 297 virtual void onMouseMove(MouseEventArgs& e); 298 virtual void onMouseButtonDown(MouseEventArgs& e); 299 virtual void onCaptureLost(WindowEventArgs& e); 300 301 302 /************************************************************************* 303 Implementation Data 304 *************************************************************************/ 305 // general settings 306 bool d_hotTrack; //!< true if events are to be sent real-time, else just when thumb is released 307 bool d_vertFree; //!< true if thumb is movable vertically 308 bool d_horzFree; //!< true if thumb is movable horizontally 309 310 // operational limits 311 float d_vertMin, d_vertMax; //!< vertical range 312 float d_horzMin, d_horzMax; //!< horizontal range 313 314 // internal state 315 bool d_beingDragged; //!< true if thumb is being dragged 316 Vector2f d_dragPoint; //!< point where we are being dragged at. 317 318 319 private: 320 /************************************************************************* 321 Private methods 322 *************************************************************************/ 323 void addThumbProperties(void); 324 }; 325 326 /* 327 TODO: This is horrible, PropertyHelper for std::pair<float, float> would be fine but enforcing min: %f max: %f is just horrible 328 */ 329 template<> 330 class PropertyHelper<std::pair<float,float> > 331 { 332 public: 333 typedef std::pair<float,float> return_type; 334 typedef return_type safe_method_return_type; 335 typedef const std::pair<float,float>& pass_type; 336 typedef String string_return_type; 337 getDataTypeName()338 static const String& getDataTypeName() 339 { 340 static String type("std::pair<float,float>"); 341 342 return type; 343 } 344 fromString(const String & str)345 static return_type fromString(const String& str) 346 { 347 float rangeMin = 0, rangeMax = 0; 348 sscanf(str.c_str(), " min:%f max:%f", &rangeMin, &rangeMax); 349 return std::pair<float,float>(rangeMin,rangeMax); 350 } 351 toString(pass_type val)352 static string_return_type toString(pass_type val) 353 { 354 char buff[64]; 355 sprintf(buff, "min:%f max:%f", val.first, val.second); 356 return buff; 357 } 358 }; 359 360 } // End of CEGUI namespace section 361 362 #if defined(_MSC_VER) 363 # pragma warning(pop) 364 #endif 365 366 #endif // end of guard _CEGUIThumb_h_ 367