interface/datectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        datectrl.h
   3 // Purpose:     interface of wxDatePickerCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDatePickerCtrl
  11     @wxheader{datectrl.h}
  12
  13     This control allows the user to select a date. Unlike wxCalendarCtrl, which
  14     is a relatively big control, wxDatePickerCtrl is implemented as a small
  15     window showing the currently selected date. The control can be edited using
  16     the keyboard, and can also display a popup window for more user-friendly
  17     date selection, depending on the styles used and the platform, except
  18     PalmOS where date is selected using native dialog.
  19
  20     It is only available if @c wxUSE_DATEPICKCTRL is set to 1.
  21
  22     @beginStyleTable
  23     @style{wxDP_SPIN}
  24            Creates a control without a month calendar drop down but with
  25            spin-control-like arrows to change individual date components. This
  26            style is not supported by the generic version.
  27     @style{wxDP_DROPDOWN}
  28            Creates a control with a month calendar drop-down part from which
  29            the user can select a date.
  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
  33            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.
  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.
  42     @endStyleTable
  43
  44     @beginEventTable{wxDateEvent}
  45     @event{EVT_DATE_CHANGED(id, func)}
  46            This event fires when the user changes the current selection in the
  47            control.
  48     @endEventTable
  49
  50     @library{wxadv}
  51     @category{pickers}
  52     <!-- @appearance{datepickerctrl.png} -->
  53
  54     @see wxCalendarCtrl, wxDateEvent
  55 */
  56 class wxDatePickerCtrl : public wxControl
  57 {
  58 public:
  59     /**
  60         Initializes the object and calls Create() with all the parameters.
  61     */
  62     wxDatePickerCtrl(wxWindow* parent, wxWindowID id,
  63                      const wxDateTime& dt = wxDefaultDateTime,
  64                      const wxPoint& pos = wxDefaultPosition,
  65                      const wxSize& size = wxDefaultSize,
  66                      long style = wxDP_DEFAULT | wxDP_SHOWCENTURY,
  67                      const wxValidator& validator = wxDefaultValidator,
  68                      const wxString& name = "datectrl");
  69
  70     /**
  71         @param parent
  72             Parent window, must not be non-@NULL.
  73         @param id
  74             The identifier for the control.
  75         @param dt
  76             The initial value of the control, if an invalid date (such as the
  77             default value) is used, the control is set to today.
  78         @param pos
  79             Initial position.
  80         @param size
  81             Initial size. If left at default value, the control chooses its own
  82             best size by using the height approximately equal to a text control
  83             and width large enough to show the date string fully.
  84         @param style
  85             The window style, should be left at 0 as there are no special
  86             styles for this control in this version.
  87         @param validator
  88             Validator which can be used for additional date checks.
  89         @param name
  90             Control name.
  91
  92         @return @true if the control was successfully created or @false if
  93                  creation failed.
  94     */
  95     bool Create(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         If the control had been previously limited to a range of dates using
 105         SetRange(), returns the lower and upper bounds of this range. If no
 106         range is set (or only one of the bounds is set), @a dt1 and/or @a dt2
 107         are set to be invalid.
 108
 109         @param dt1
 110             Pointer to the object which receives the lower range limit or
 111             becomes invalid if it is not set. May be @NULL if the caller is not
 112             interested in lower limit.
 113         @param dt2
 114             Same as above but for the upper limit.
 115
 116         @return @false if no range limits are currently set, @true if at least
 117                  one bound is set.
 118     */
 119     bool GetRange(wxDateTime* dt1, wxDateTime dt2) const;
 120
 121     /**
 122         Returns the currently selected. If there is no selection or the
 123         selection is outside of the current range, an invalid object is
 124         returned.
 125     */
 126     wxDateTime GetValue() const;
 127
 128     /**
 129         Sets the display format for the date in the control. See wxDateTime for
 130         the meaning of format strings.
 131
 132         @note This function is only available in the generic version of this
 133               control. The native version always uses the current system locale.
 134
 135         @remarks If the format parameter is invalid, the behaviour is undefined.
 136     */
 137     void SetFormat(const wxChar* format);
 138
 139     /**
 140         Sets the valid range for the date selection. If @a dt1 is valid, it
 141         becomes the earliest date (inclusive) accepted by the control. If
 142         @a dt2 is valid, it becomes the latest possible date.
 143
 144         @remarks If the current value of the control is outside of the newly
 145                  set range bounds, the behaviour is undefined.
 146     */
 147     void SetRange(const wxDateTime& dt1, const wxDateTime& dt2);
 148
 149     /**
 150         Changes the current value of the control. The date should be valid and
 151         included in the currently selected range, if any.
 152
 153         Calling this method does not result in a date change event.
 154     */
 155     void SetValue(const wxDateTime& dt);
 156 };
 157