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