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_COMMAND_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_COMMAND_SPINCTRL_UPDATED 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.png}
  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         Gets maximal allowable value.
 119     */
 120     int GetMax() const;
 121
 122     /**
 123         Gets minimal allowable value.
 124     */
 125     int GetMin() const;
 126
 127     /**
 128         Gets the value of the spin control.
 129     */
 130     int GetValue() const;
 131
 132     /**
 133         Sets range of allowable values.
 134
 135         Notice that calling this method may change the value of the control if
 136         it's not inside the new valid range, e.g. it will become @a minVal if
 137         it is less than it now. However no @c wxEVT_COMMAND_SPINCTRL_UPDATED
 138         event is generated, even if it the value does change.
 139     */
 140     void SetRange(int minVal, int maxVal);
 141
 142     /**
 143         Select the text in the text part of the control between  positions
 144         @a from (inclusive) and @a to (exclusive).
 145         This is similar to wxTextCtrl::SetSelection().
 146
 147         @note this is currently only implemented for Windows and generic versions
 148               of the control.
 149     */
 150     virtual void SetSelection(long from, long to);
 151
 152     /**
 153         Sets the value of the spin control. Use the variant using int instead.
 154     */
 155     virtual void SetValue(const wxString& text);
 156
 157     /**
 158         Sets the value of the spin control.
 159     */
 160     void SetValue(int value);
 161 };
 162
 163 /**
 164     @class wxSpinCtrlDouble
 165
 166     wxSpinCtrlDouble combines wxTextCtrl and wxSpinButton in one control and
 167     displays a real number. (wxSpinCtrl displays an integer.)
 168
 169     @beginStyleTable
 170     @style{wxSP_ARROW_KEYS}
 171            The user can use arrow keys to change the value.
 172     @style{wxSP_WRAP}
 173            The value wraps at the minimum and maximum.
 174     @endStyleTable
 175
 176     @beginEventEmissionTable{wxSpinDoubleEvent}
 177     @event{EVT_SPINCTRLDOUBLE(id, func)}
 178         Generated whenever the numeric value of the spin control is changed,
 179         that is, when the up/down spin button is clicked, when ENTER is pressed,
 180         or the control loses focus and the new value is different from the last.
 181         See wxSpinDoubleEvent.
 182     @endEventTable
 183
 184     @library{wxcore}
 185     @category{ctrl}
 186     @appearance{spinctrldouble.png}
 187
 188     @see wxSpinButton, wxSpinCtrl, wxControl
 189 */
 190 class wxSpinCtrlDouble : public wxControl
 191 {
 192 public:
 193     /**
 194        Default constructor.
 195     */
 196     wxSpinCtrlDouble();
 197
 198     /**
 199         Constructor, creating and showing a spin control.
 200
 201         @param parent
 202             Parent window. Must not be @NULL.
 203         @param value
 204             Default value (as text).
 205         @param id
 206             Window identifier. The value wxID_ANY indicates a default value.
 207         @param pos
 208             Window position.
 209             If ::wxDefaultPosition is specified then a default position is chosen.
 210         @param size
 211             Window size.
 212             If ::wxDefaultSize is specified then a default size is chosen.
 213         @param style
 214             Window style. See wxSpinButton.
 215         @param min
 216             Minimal value.
 217         @param max
 218             Maximal value.
 219         @param initial
 220             Initial value.
 221         @param inc
 222             Increment value.
 223         @param name
 224             Window name.
 225
 226         @see Create()
 227     */
 228     wxSpinCtrlDouble(wxWindow* parent, wxWindowID id = -1,
 229                const wxString& value = wxEmptyString,
 230                const wxPoint& pos = wxDefaultPosition,
 231                const wxSize& size = wxDefaultSize,
 232                long style = wxSP_ARROW_KEYS,
 233                double min = 0, double max = 100,
 234                double initial = 0, double inc = 1,
 235                const wxString& name = wxT("wxSpinCtrlDouble"));
 236
 237     /**
 238         Creation function called by the spin control constructor.
 239         See wxSpinCtrlDouble() for details.
 240     */
 241     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 242                 const wxString& value = wxEmptyString,
 243                 const wxPoint& pos = wxDefaultPosition,
 244                 const wxSize& size = wxDefaultSize,
 245                 long style = wxSP_ARROW_KEYS, double min = 0, double max = 100,
 246                 double initial = 0, double inc = 1,
 247                 const wxString& name = "wxSpinCtrlDouble");
 248
 249     /**
 250         Gets the number of digits in the display.
 251     */
 252     unsigned int GetDigits() const;
 253
 254     /**
 255         Gets the increment value.
 256     */
 257     double GetIncrement() const;
 258
 259     /**
 260         Gets maximal allowable value.
 261     */
 262     double GetMax() const;
 263
 264     /**
 265         Gets minimal allowable value.
 266     */
 267     double GetMin() const;
 268
 269     /**
 270         Gets the value of the spin control.
 271     */
 272     double GetValue() const;
 273
 274     /**
 275         Sets the number of digits in the display.
 276     */
 277     void SetDigits(unsigned int digits);
 278
 279     /**
 280         Sets the increment value.
 281     */
 282     void SetIncrement(double inc);
 283
 284     /**
 285         Sets range of allowable values.
 286     */
 287     void SetRange(double minVal, double maxVal);
 288
 289     /**
 290         Sets the value of the spin control. Use the variant using double instead.
 291     */
 292     virtual void SetValue(const wxString& text);
 293
 294     /**
 295         Sets the value of the spin control.
 296     */
 297     void SetValue(double value);
 298 };
 299
 300 /**
 301     @class wxSpinDoubleEvent
 302
 303     This event class is used for the events generated by wxSpinCtrlDouble.
 304
 305     @beginEventTable{wxSpinDoubleEvent}
 306     @event{EVT_SPINCTRLDOUBLE(id, func)}
 307         Generated whenever the numeric value of the spin control is changed,
 308         that is, when the up/down spin button is clicked, when ENTER is pressed,
 309         or the control loses focus and the new value is different from the last.
 310         See wxSpinDoubleEvent.
 311     @endEventTable
 312
 313     @library{wxcore}
 314     @category{events}
 315
 316     @see wxSpinCtrlDouble
 317 */
 318 class wxSpinDoubleEvent : public wxNotifyEvent
 319 {
 320 public:
 321     /**
 322         The constructor. Not normally used by the user code.
 323     */
 324     wxSpinDoubleEvent(wxEventType commandType = wxEVT_NULL, int winid = 0,
 325                       double value = 0);
 326
 327     /**
 328         The copy constructor.
 329     */
 330     wxSpinDoubleEvent(const wxSpinDoubleEvent& event);
 331
 332     /**
 333         Returns the value associated with this spin control event.
 334     */
 335     double GetValue() const;
 336
 337     /**
 338         Set the value associated with the event.
 339         (Not normally used by user code.)
 340     */
 341     void SetValue(double value);
 342 };
 343
 344 wxEventType wxEVT_COMMAND_SPINCTRL_UPDATED;
 345 wxEventType wxEVT_COMMAND_SPINCTRLDOUBLE_UPDATED;