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. Use the variant using int instead.
 183     */
 184     virtual void SetValue(const wxString& text);
 185
 186     /**
 187         Sets the value of the spin control.
 188     */
 189     void SetValue(int value);
 190 };
 191
 192 /**
 193     @class wxSpinCtrlDouble
 194
 195     wxSpinCtrlDouble combines wxTextCtrl and wxSpinButton in one control and
 196     displays a real number. (wxSpinCtrl displays an integer.)
 197
 198     @beginStyleTable
 199     @style{wxSP_ARROW_KEYS}
 200            The user can use arrow keys to change the value.
 201     @style{wxSP_WRAP}
 202            The value wraps at the minimum and maximum.
 203     @endStyleTable
 204
 205     @beginEventEmissionTable{wxSpinDoubleEvent}
 206     @event{EVT_SPINCTRLDOUBLE(id, func)}
 207         Generated whenever the numeric value of the spin control is changed,
 208         that is, when the up/down spin button is clicked, when ENTER is pressed,
 209         or the control loses focus and the new value is different from the last.
 210         See wxSpinDoubleEvent.
 211     @endEventTable
 212
 213     @library{wxcore}
 214     @category{ctrl}
 215     @appearance{spinctrldouble}
 216
 217     @see wxSpinButton, wxSpinCtrl, wxControl
 218 */
 219 class wxSpinCtrlDouble : public wxControl
 220 {
 221 public:
 222     /**
 223        Default constructor.
 224     */
 225     wxSpinCtrlDouble();
 226
 227     /**
 228         Constructor, creating and showing a spin control.
 229
 230         @param parent
 231             Parent window. Must not be @NULL.
 232         @param value
 233             Default value (as text).
 234         @param id
 235             Window identifier. The value wxID_ANY indicates a default value.
 236         @param pos
 237             Window position.
 238             If ::wxDefaultPosition is specified then a default position is chosen.
 239         @param size
 240             Window size.
 241             If ::wxDefaultSize is specified then a default size is chosen.
 242         @param style
 243             Window style. See wxSpinButton.
 244         @param min
 245             Minimal value.
 246         @param max
 247             Maximal value.
 248         @param initial
 249             Initial value.
 250         @param inc
 251             Increment value.
 252         @param name
 253             Window name.
 254
 255         @see Create()
 256     */
 257     wxSpinCtrlDouble(wxWindow* parent, wxWindowID id = -1,
 258                const wxString& value = wxEmptyString,
 259                const wxPoint& pos = wxDefaultPosition,
 260                const wxSize& size = wxDefaultSize,
 261                long style = wxSP_ARROW_KEYS,
 262                double min = 0, double max = 100,
 263                double initial = 0, double inc = 1,
 264                const wxString& name = wxT("wxSpinCtrlDouble"));
 265
 266     /**
 267         Creation function called by the spin control constructor.
 268         See wxSpinCtrlDouble() for details.
 269     */
 270     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 271                 const wxString& value = wxEmptyString,
 272                 const wxPoint& pos = wxDefaultPosition,
 273                 const wxSize& size = wxDefaultSize,
 274                 long style = wxSP_ARROW_KEYS, double min = 0, double max = 100,
 275                 double initial = 0, double inc = 1,
 276                 const wxString& name = "wxSpinCtrlDouble");
 277
 278     /**
 279         Gets the number of digits in the display.
 280     */
 281     unsigned int GetDigits() const;
 282
 283     /**
 284         Gets the increment value.
 285     */
 286     double GetIncrement() const;
 287
 288     /**
 289         Gets maximal allowable value.
 290     */
 291     double GetMax() const;
 292
 293     /**
 294         Gets minimal allowable value.
 295     */
 296     double GetMin() const;
 297
 298     /**
 299         Gets the value of the spin control.
 300     */
 301     double GetValue() const;
 302
 303     /**
 304         Sets the number of digits in the display.
 305     */
 306     void SetDigits(unsigned int digits);
 307
 308     /**
 309         Sets the increment value.
 310         @note You may also need to increase the number of visible digits
 311         using SetDigits
 312     */
 313     void SetIncrement(double inc);
 314
 315     /**
 316         Sets range of allowable values.
 317     */
 318     void SetRange(double minVal, double maxVal);
 319
 320     /**
 321         Sets the value of the spin control. Use the variant using double instead.
 322     */
 323     virtual void SetValue(const wxString& text);
 324
 325     /**
 326         Sets the value of the spin control.
 327     */
 328     void SetValue(double value);
 329 };
 330
 331 /**
 332     @class wxSpinDoubleEvent
 333
 334     This event class is used for the events generated by wxSpinCtrlDouble.
 335
 336     @beginEventTable{wxSpinDoubleEvent}
 337     @event{EVT_SPINCTRLDOUBLE(id, func)}
 338         Generated whenever the numeric value of the spin control is changed,
 339         that is, when the up/down spin button is clicked, when ENTER is pressed,
 340         or the control loses focus and the new value is different from the last.
 341         See wxSpinDoubleEvent.
 342     @endEventTable
 343
 344     @library{wxcore}
 345     @category{events}
 346
 347     @see wxSpinCtrlDouble
 348 */
 349 class wxSpinDoubleEvent : public wxNotifyEvent
 350 {
 351 public:
 352     /**
 353         The constructor. Not normally used by the user code.
 354     */
 355     wxSpinDoubleEvent(wxEventType commandType = wxEVT_NULL, int winid = 0,
 356                       double value = 0);
 357
 358     /**
 359         The copy constructor.
 360     */
 361     wxSpinDoubleEvent(const wxSpinDoubleEvent& event);
 362
 363     /**
 364         Returns the value associated with this spin control event.
 365     */
 366     double GetValue() const;
 367
 368     /**
 369         Set the value associated with the event.
 370         (Not normally used by user code.)
 371     */
 372     void SetValue(double value);
 373 };
 374
 375 wxEventType wxEVT_SPINCTRL;
 376 wxEventType wxEVT_SPINCTRLDOUBLE;