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