interface/wx/spinctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        spinctrl.h
   3 // Purpose:     interface of wxSpinCtrl
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxSpinCtrl
  10
  11     wxSpinCtrl combines wxTextCtrl and wxSpinButton in one control.
  12
  13     @beginStyleTable
  14     @style{wxSP_ARROW_KEYS}
  15         The user can use arrow keys to change the value.
  16     @style{wxSP_WRAP}
  17         The value wraps at the minimum and maximum.
  18     @style{wxTE_PROCESS_ENTER}
  19         Indicates that the control should generate @c wxEVT_TEXT_ENTER
  20         events. Using this style will prevent the user from using the Enter key
  21         for dialog navigation (e.g. activating the default button in the
  22         dialog) under MSW.
  23     @style{wxALIGN_LEFT}
  24         Same as wxTE_LEFT for wxTextCtrl: the text is left aligned.
  25     @style{wxALIGN_CENTRE_HORIZONTAL}
  26         Same as wxTE_CENTRE for wxTextCtrl: the text is centered.
  27     @style{wxALIGN_RIGHT}
  28         Same as wxTE_RIGHT for wxTextCtrl: the text is right aligned (this is
  29         the default).
  30     @endStyleTable
  31
  32
  33     @beginEventEmissionTable{wxSpinEvent}
  34     @event{EVT_SPINCTRL(id, func)}
  35         Process a wxEVT_SPINCTRL event, which is generated
  36         whenever the numeric value of the spin control is updated.
  37     @endEventTable
  38
  39     You may also use the wxSpinButton event macros, however the corresponding events
  40     will not be generated under all platforms. Finally, if the user modifies the
  41     text in the edit part of the spin control directly, the EVT_TEXT is generated,
  42     like for the wxTextCtrl. When the use enters text into the text area, the text
  43     is not validated until the control loses focus (e.g. by using the TAB key).
  44     The value is then adjusted to the range and a wxSpinEvent sent then if the value
  45     is different from the last value sent.
  46
  47     @library{wxcore}
  48     @category{ctrl}
  49     @appearance{spinctrl}
  50
  51     @see wxSpinButton, wxSpinCtrlDouble, wxControl
  52 */
  53 class wxSpinCtrl : public wxControl
  54 {
  55 public:
  56     /**
  57        Default constructor.
  58     */
  59     wxSpinCtrl();
  60
  61     /**
  62         Constructor, creating and showing a spin control.
  63
  64         If @a value is non-empty, it will be shown in the text entry part of
  65         the control and if it has numeric value, the initial numeric value of
  66         the control, as returned by GetValue() will also be determined by it
  67         instead of by @a initial. Hence, it only makes sense to specify @a
  68         initial if @a value is an empty string or is not convertible to a
  69         number, otherwise @a initial is simply ignored and the number specified
  70         by @a value is used.
  71
  72         @param parent
  73             Parent window. Must not be @NULL.
  74         @param value
  75             Default value (as text).
  76         @param id
  77             Window identifier. The value wxID_ANY indicates a default value.
  78         @param pos
  79             Window position.
  80             If ::wxDefaultPosition is specified then a default position is chosen.
  81         @param size
  82             Window size.
  83             If ::wxDefaultSize is specified then a default size is chosen.
  84         @param style
  85             Window style. See wxSpinButton.
  86         @param min
  87             Minimal value.
  88         @param max
  89             Maximal value.
  90         @param initial
  91             Initial value.
  92         @param name
  93             Window name.
  94
  95         @see Create()
  96     */
  97     wxSpinCtrl(wxWindow* parent, wxWindowID id = wxID_ANY,
  98                const wxString& value = wxEmptyString,
  99                const wxPoint& pos = wxDefaultPosition,
 100                const wxSize& size = wxDefaultSize,
 101                long style = wxSP_ARROW_KEYS,
 102                int min = 0, int max = 100,
 103                int initial = 0, const wxString& name = "wxSpinCtrl");
 104
 105     /**
 106         Creation function called by the spin control constructor.
 107         See wxSpinCtrl() for details.
 108     */
 109     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 110                 const wxString& value = wxEmptyString,
 111                 const wxPoint& pos = wxDefaultPosition,
 112                 const wxSize& size = wxDefaultSize,
 113                 long style = wxSP_ARROW_KEYS, int min = 0, int max = 100,
 114                 int initial = 0, const wxString& name = "wxSpinCtrl");
 115
 116     /**
 117         Returns the numerical base being currently used, 10 by default.
 118
 119         @see SetBase()
 120
 121         @since 2.9.5
 122      */
 123     int GetBase() const;
 124
 125     /**
 126         Gets maximal allowable value.
 127     */
 128     int GetMax() const;
 129
 130     /**
 131         Gets minimal allowable value.
 132     */
 133     int GetMin() const;
 134
 135     /**
 136         Gets the value of the spin control.
 137     */
 138     int GetValue() const;
 139
 140     /**
 141         Sets the base to use for the numbers in this control.
 142
 143         Currently the only supported values are 10 (which is the default) and
 144         16.
 145
 146         Changing the base allows the user to enter the numbers in the specified
 147         base, e.g. with "0x" prefix for hexadecimal numbers, and also displays
 148         the numbers in the specified base when they are changed using the spin
 149         control arrows.
 150
 151         @param base
 152             Numeric base, currently only 10 and 16 are supported.
 153         @return
 154             @true if the base was successfully changed or @false if it failed,
 155             usually meaning that either the base is not 10 or 16.
 156
 157         @since 2.9.5
 158      */
 159     bool SetBase(int base);
 160
 161     /**
 162         Sets range of allowable values.
 163
 164         Notice that calling this method may change the value of the control if
 165         it's not inside the new valid range, e.g. it will become @a minVal if
 166         it is less than it now. However no @c wxEVT_SPINCTRL
 167         event is generated, even if it the value does change.
 168     */
 169     void SetRange(int minVal, int maxVal);
 170
 171     /**
 172         Select the text in the text part of the control between  positions
 173         @a from (inclusive) and @a to (exclusive).
 174         This is similar to wxTextCtrl::SetSelection().
 175
 176         @note this is currently only implemented for Windows and generic versions
 177               of the control.
 178     */
 179     virtual void SetSelection(long from, long to);
 180
 181     /**
 182         Sets the value of the spin control.
 183
 184         It is recommended to use the overload taking an integer value instead.
 185
 186         Notice that, unlike wxTextCtrl::SetValue(), but like most of the other
 187         setter methods in wxWidgets, calling this method does not generate any
 188         events as events are only generated for the user actions.
 189     */
 190     virtual void SetValue(const wxString& text);
 191
 192     /**
 193         Sets the value of the spin control.
 194
 195         Calling this method doesn't generate any @c wxEVT_SPINCTRL events.
 196     */
 197     void SetValue(int value);
 198 };
 199
 200 /**
 201     @class wxSpinCtrlDouble
 202
 203     wxSpinCtrlDouble combines wxTextCtrl and wxSpinButton in one control and
 204     displays a real number. (wxSpinCtrl displays an integer.)
 205
 206     @beginStyleTable
 207     @style{wxSP_ARROW_KEYS}
 208            The user can use arrow keys to change the value.
 209     @style{wxSP_WRAP}
 210            The value wraps at the minimum and maximum.
 211     @endStyleTable
 212
 213     @beginEventEmissionTable{wxSpinDoubleEvent}
 214     @event{EVT_SPINCTRLDOUBLE(id, func)}
 215         Generated whenever the numeric value of the spin control is changed,
 216         that is, when the up/down spin button is clicked, when ENTER is pressed,
 217         or the control loses focus and the new value is different from the last.
 218         See wxSpinDoubleEvent.
 219     @endEventTable
 220
 221     @library{wxcore}
 222     @category{ctrl}
 223     @appearance{spinctrldouble}
 224
 225     @see wxSpinButton, wxSpinCtrl, wxControl
 226 */
 227 class wxSpinCtrlDouble : public wxControl
 228 {
 229 public:
 230     /**
 231        Default constructor.
 232     */
 233     wxSpinCtrlDouble();
 234
 235     /**
 236         Constructor, creating and showing a spin control.
 237
 238         @param parent
 239             Parent window. Must not be @NULL.
 240         @param value
 241             Default value (as text).
 242         @param id
 243             Window identifier. The value wxID_ANY indicates a default value.
 244         @param pos
 245             Window position.
 246             If ::wxDefaultPosition is specified then a default position is chosen.
 247         @param size
 248             Window size.
 249             If ::wxDefaultSize is specified then a default size is chosen.
 250         @param style
 251             Window style. See wxSpinButton.
 252         @param min
 253             Minimal value.
 254         @param max
 255             Maximal value.
 256         @param initial
 257             Initial value.
 258         @param inc
 259             Increment value.
 260         @param name
 261             Window name.
 262
 263         @see Create()
 264     */
 265     wxSpinCtrlDouble(wxWindow* parent, wxWindowID id = -1,
 266                const wxString& value = wxEmptyString,
 267                const wxPoint& pos = wxDefaultPosition,
 268                const wxSize& size = wxDefaultSize,
 269                long style = wxSP_ARROW_KEYS,
 270                double min = 0, double max = 100,
 271                double initial = 0, double inc = 1,
 272                const wxString& name = wxT("wxSpinCtrlDouble"));
 273
 274     /**
 275         Creation function called by the spin control constructor.
 276         See wxSpinCtrlDouble() for details.
 277     */
 278     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 279                 const wxString& value = wxEmptyString,
 280                 const wxPoint& pos = wxDefaultPosition,
 281                 const wxSize& size = wxDefaultSize,
 282                 long style = wxSP_ARROW_KEYS, double min = 0, double max = 100,
 283                 double initial = 0, double inc = 1,
 284                 const wxString& name = "wxSpinCtrlDouble");
 285
 286     /**
 287         Gets the number of digits in the display.
 288     */
 289     unsigned int GetDigits() const;
 290
 291     /**
 292         Gets the increment value.
 293     */
 294     double GetIncrement() const;
 295
 296     /**
 297         Gets maximal allowable value.
 298     */
 299     double GetMax() const;
 300
 301     /**
 302         Gets minimal allowable value.
 303     */
 304     double GetMin() const;
 305
 306     /**
 307         Gets the value of the spin control.
 308     */
 309     double GetValue() const;
 310
 311     /**
 312         Sets the number of digits in the display.
 313     */
 314     void SetDigits(unsigned int digits);
 315
 316     /**
 317         Sets the increment value.
 318         @note You may also need to increase the number of visible digits
 319         using SetDigits
 320     */
 321     void SetIncrement(double inc);
 322
 323     /**
 324         Sets range of allowable values.
 325     */
 326     void SetRange(double minVal, double maxVal);
 327
 328     /**
 329         Sets the value of the spin control.
 330
 331         It is recommended to use the overload taking a double value instead.
 332
 333         Notice that, unlike wxTextCtrl::SetValue(), but like most of the other
 334         setter methods in wxWidgets, calling this method does not generate any
 335         events as events are only generated for the user actions.
 336     */
 337     virtual void SetValue(const wxString& text);
 338
 339     /**
 340         Sets the value of the spin control.
 341
 342         Calling this method doesn't generate any @c wxEVT_SPINCTRLDOUBLE events.
 343     */
 344     void SetValue(double value);
 345 };
 346
 347 /**
 348     @class wxSpinDoubleEvent
 349
 350     This event class is used for the events generated by wxSpinCtrlDouble.
 351
 352     @beginEventTable{wxSpinDoubleEvent}
 353     @event{EVT_SPINCTRLDOUBLE(id, func)}
 354         Generated whenever the numeric value of the spin control is changed,
 355         that is, when the up/down spin button is clicked, when ENTER is pressed,
 356         or the control loses focus and the new value is different from the last.
 357         See wxSpinDoubleEvent.
 358     @endEventTable
 359
 360     @library{wxcore}
 361     @category{events}
 362
 363     @see wxSpinCtrlDouble
 364 */
 365 class wxSpinDoubleEvent : public wxNotifyEvent
 366 {
 367 public:
 368     /**
 369         The constructor. Not normally used by the user code.
 370     */
 371     wxSpinDoubleEvent(wxEventType commandType = wxEVT_NULL, int winid = 0,
 372                       double value = 0);
 373
 374     /**
 375         The copy constructor.
 376     */
 377     wxSpinDoubleEvent(const wxSpinDoubleEvent& event);
 378
 379     /**
 380         Returns the value associated with this spin control event.
 381     */
 382     double GetValue() const;
 383
 384     /**
 385         Set the value associated with the event.
 386         (Not normally used by user code.)
 387     */
 388     void SetValue(double value);
 389 };
 390
 391 wxEventType wxEVT_SPINCTRL;
 392 wxEventType wxEVT_SPINCTRLDOUBLE;