interface/datectrl.h

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