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