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