interface/wx/datectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        datectrl.h
   3 // Purpose:     interface of wxDatePickerCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /// wxDatePickerCtrl styles
  10 enum
  11 {
  12     /// default style on this platform, either wxDP_SPIN or wxDP_DROPDOWN
  13     wxDP_DEFAULT = 0,
  14
  15     /// a spin control-like date picker (not supported in generic version)
  16     wxDP_SPIN = 1,
  17
  18     /// a combobox-like date picker (not supported in mac version)
  19     wxDP_DROPDOWN = 2,
  20
  21     /// always show century in the default date display (otherwise it depends on
  22     /// the system date format which may include the century or not)
  23     wxDP_SHOWCENTURY = 4,
  24
  25     /// allow not having any valid date in the control (by default it always has
  26     /// some date, today initially if no valid date specified in ctor)
  27     wxDP_ALLOWNONE = 8
  28 };
  29
  30
  31 /**
  32     @class wxDatePickerCtrl
  33
  34     This control allows the user to select a date. Unlike wxCalendarCtrl, which
  35     is a relatively big control, wxDatePickerCtrl is implemented as a small
  36     window showing the currently selected date. The control can be edited using
  37     the keyboard, and can also display a popup window for more user-friendly
  38     date selection, depending on the styles used and the platform.
  39
  40     It is only available if @c wxUSE_DATEPICKCTRL is set to 1.
  41
  42     @beginStyleTable
  43     @style{wxDP_SPIN}
  44            Creates a control without a month calendar drop down but with
  45            spin-control-like arrows to change individual date components. This
  46            style is not supported by the generic version.
  47     @style{wxDP_DROPDOWN}
  48            Creates a control with a month calendar drop-down part from which
  49            the user can select a date. This style is not supported in OSX/Cocoa
  50            native version.
  51     @style{wxDP_DEFAULT}
  52            Creates a control with the style that is best supported for the
  53            current platform (currently wxDP_SPIN under Windows and OSX/Cocoa
  54            and wxDP_DROPDOWN elsewhere).
  55     @style{wxDP_ALLOWNONE}
  56            With this style, the control allows the user to not enter any valid
  57            date at all. Without it - the default - the control always has some
  58            valid date. This style is not supported in OSX/Cocoa native version.
  59     @style{wxDP_SHOWCENTURY}
  60            Forces display of the century in the default date format. Without
  61            this style the century could be displayed, or not, depending on the
  62            default date representation in the system. This style is not
  63            supported in OSX/Cocoa native version currently.
  64     @endStyleTable
  65
  66     As can be seen from the remarks above, most of the control style are only
  67     supported in the native MSW implementation. In portable code it's
  68     recommended to use @c wxDP_DEFAULT style only, possibly combined with @c
  69     wxDP_SHOWCENTURY (this is also the style used by default if none is
  70     specified).
  71
  72     @beginEventEmissionTable{wxDateEvent}
  73     @event{EVT_DATE_CHANGED(id, func)}
  74            This event fires when the user changes the current selection in the
  75            control.
  76     @endEventTable
  77
  78     @library{wxadv}
  79     @category{pickers}
  80     @appearance{datepickerctrl.png}
  81
  82     @see wxCalendarCtrl, wxDateEvent
  83 */
  84 class wxDatePickerCtrl : public wxControl
  85 {
  86 public:
  87     /**
  88        Default constructor.
  89     */
  90     wxDatePickerCtrl();
  91
  92     /**
  93         Initializes the object and calls Create() with all the parameters.
  94     */
  95     wxDatePickerCtrl(wxWindow* parent, wxWindowID id,
  96                      const wxDateTime& dt = wxDefaultDateTime,
  97                      const wxPoint& pos = wxDefaultPosition,
  98                      const wxSize& size = wxDefaultSize,
  99                      long style = wxDP_DEFAULT | wxDP_SHOWCENTURY,
 100                      const wxValidator& validator = wxDefaultValidator,
 101                      const wxString& name = "datectrl");
 102
 103     /**
 104         Create the control window.
 105
 106         This method should only be used for objects created using default
 107         constructor.
 108
 109         @param parent
 110             Parent window, must not be non-@NULL.
 111         @param id
 112             The identifier for the control.
 113         @param dt
 114             The initial value of the control, if an invalid date (such as the
 115             default value) is used, the control is set to today.
 116         @param pos
 117             Initial position.
 118         @param size
 119             Initial size. If left at default value, the control chooses its own
 120             best size by using the height approximately equal to a text control
 121             and width large enough to show the date string fully.
 122         @param style
 123             The window style, see the description of the styles in the class
 124             documentation.
 125         @param validator
 126             Validator which can be used for additional date checks.
 127         @param name
 128             Control name.
 129
 130         @return @true if the control was successfully created or @false if
 131                  creation failed.
 132     */
 133     bool Create(wxWindow* parent, wxWindowID id,
 134                 const wxDateTime& dt = wxDefaultDateTime,
 135                 const wxPoint& pos = wxDefaultPosition,
 136                 const wxSize& size = wxDefaultSize,
 137                 long style = wxDP_DEFAULT | wxDP_SHOWCENTURY,
 138                 const wxValidator& validator = wxDefaultValidator,
 139                 const wxString& name = "datectrl");
 140
 141     /**
 142         If the control had been previously limited to a range of dates using
 143         SetRange(), returns the lower and upper bounds of this range. If no
 144         range is set (or only one of the bounds is set), @a dt1 and/or @a dt2
 145         are set to be invalid.
 146
 147         Notice that when using a native MSW implementation of this control the
 148         lower range is always set, even if SetRange() hadn't been called
 149         explicitly, as the native control only supports dates later than year
 150         1601.
 151
 152         @param dt1
 153             Pointer to the object which receives the lower range limit or
 154             becomes invalid if it is not set. May be @NULL if the caller is not
 155             interested in lower limit.
 156         @param dt2
 157             Same as above but for the upper limit.
 158
 159         @return @false if no range limits are currently set, @true if at least
 160                  one bound is set.
 161     */
 162     virtual bool GetRange(wxDateTime* dt1, wxDateTime* dt2) const;
 163
 164     /**
 165         Returns the currently entered date.
 166
 167         For a control with @c wxDP_ALLOWNONE style the returned value may be
 168         invalid if no date is entered, otherwise it is always valid.
 169     */
 170     virtual wxDateTime GetValue() const;
 171
 172     /**
 173         Sets the valid range for the date selection. If @a dt1 is valid, it
 174         becomes the earliest date (inclusive) accepted by the control. If
 175         @a dt2 is valid, it becomes the latest possible date.
 176
 177         @remarks If the current value of the control is outside of the newly
 178                  set range bounds, the behaviour is undefined.
 179     */
 180     virtual void SetRange(const wxDateTime& dt1, const wxDateTime& dt2);
 181
 182     /**
 183         Changes the current value of the control.
 184
 185         The date should be valid unless the control was created with @c
 186         wxDP_ALLOWNONE style and included in the currently selected range, if
 187         any.
 188
 189         Calling this method does not result in a date change event.
 190     */
 191     virtual void SetValue(const wxDateTime& dt);
 192 };
 193