interface/wx/spinctrl.h

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