X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b91c4601f2cc8fab375dc49a0a1222d58065cfdb..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/datectrl.h diff --git a/interface/wx/datectrl.h b/interface/wx/datectrl.h index ea378b9f0a..c817154997 100644 --- a/interface/wx/datectrl.h +++ b/interface/wx/datectrl.h @@ -2,10 +2,31 @@ // Name: datectrl.h // Purpose: interface of wxDatePickerCtrl // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/// wxDatePickerCtrl styles +enum +{ + /// default style on this platform, either wxDP_SPIN or wxDP_DROPDOWN + wxDP_DEFAULT = 0, + + /// a spin control-like date picker (not supported in generic version) + wxDP_SPIN = 1, + + /// a combobox-like date picker (not supported in mac version) + wxDP_DROPDOWN = 2, + + /// always show century in the default date display (otherwise it depends on + /// the system date format which may include the century or not) + wxDP_SHOWCENTURY = 4, + + /// allow not having any valid date in the control (by default it always has + /// some date, today initially if no valid date specified in ctor) + wxDP_ALLOWNONE = 8 +}; + + /** @class wxDatePickerCtrl @@ -13,8 +34,7 @@ is a relatively big control, wxDatePickerCtrl is implemented as a small window showing the currently selected date. The control can be edited using the keyboard, and can also display a popup window for more user-friendly - date selection, depending on the styles used and the platform, except - PalmOS where date is selected using native dialog. + date selection, depending on the styles used and the platform. It is only available if @c wxUSE_DATEPICKCTRL is set to 1. @@ -25,22 +45,30 @@ style is not supported by the generic version. @style{wxDP_DROPDOWN} Creates a control with a month calendar drop-down part from which - the user can select a date. + the user can select a date. This style is not supported in OSX/Cocoa + native version. @style{wxDP_DEFAULT} Creates a control with the style that is best supported for the - current platform (currently wxDP_SPIN under Windows and - wxDP_DROPDOWN elsewhere). + current platform (currently wxDP_SPIN under Windows and OSX/Cocoa + and wxDP_DROPDOWN elsewhere). @style{wxDP_ALLOWNONE} With this style, the control allows the user to not enter any valid date at all. Without it - the default - the control always has some - valid date. + valid date. This style is not supported in OSX/Cocoa native version. @style{wxDP_SHOWCENTURY} Forces display of the century in the default date format. Without this style the century could be displayed, or not, depending on the - default date representation in the system. + default date representation in the system. This style is not + supported in OSX/Cocoa native version currently. @endStyleTable - @beginEventTable{wxDateEvent} + As can be seen from the remarks above, most of the control style are only + supported in the native MSW implementation. In portable code it's + recommended to use @c wxDP_DEFAULT style only, possibly combined with @c + wxDP_SHOWCENTURY (this is also the style used by default if none is + specified). + + @beginEventEmissionTable{wxDateEvent} @event{EVT_DATE_CHANGED(id, func)} This event fires when the user changes the current selection in the control. @@ -48,13 +76,18 @@ @library{wxadv} @category{pickers} - + @appearance{datepickerctrl} @see wxCalendarCtrl, wxDateEvent */ class wxDatePickerCtrl : public wxControl { public: + /** + Default constructor. + */ + wxDatePickerCtrl(); + /** Initializes the object and calls Create() with all the parameters. */ @@ -67,6 +100,11 @@ public: const wxString& name = "datectrl"); /** + Create the control window. + + This method should only be used for objects created using default + constructor. + @param parent Parent window, must not be non-@NULL. @param id @@ -81,8 +119,8 @@ public: best size by using the height approximately equal to a text control and width large enough to show the date string fully. @param style - The window style, should be left at 0 as there are no special - styles for this control in this version. + The window style, see the description of the styles in the class + documentation. @param validator Validator which can be used for additional date checks. @param name @@ -105,6 +143,11 @@ public: range is set (or only one of the bounds is set), @a dt1 and/or @a dt2 are set to be invalid. + Notice that when using a native MSW implementation of this control the + lower range is always set, even if SetRange() hadn't been called + explicitly, as the native control only supports dates later than year + 1601. + @param dt1 Pointer to the object which receives the lower range limit or becomes invalid if it is not set. May be @NULL if the caller is not @@ -115,25 +158,15 @@ public: @return @false if no range limits are currently set, @true if at least one bound is set. */ - virtual bool GetRange(wxDateTime* dt1, wxDateTime* dt2) const = 0; + virtual bool GetRange(wxDateTime* dt1, wxDateTime* dt2) const; /** - Returns the currently selected. If there is no selection or the - selection is outside of the current range, an invalid object is - returned. - */ - virtual wxDateTime GetValue() const = 0; + Returns the currently entered date. - /** - Sets the display format for the date in the control. See wxDateTime for - the meaning of format strings. - - @note This function is only available in the generic version of this - control. The native version always uses the current system locale. - - @remarks If the format parameter is invalid, the behaviour is undefined. + For a control with @c wxDP_ALLOWNONE style the returned value may be + invalid if no date is entered, otherwise it is always valid. */ - void SetFormat(const wxChar* format); + virtual wxDateTime GetValue() const; /** Sets the valid range for the date selection. If @a dt1 is valid, it @@ -143,14 +176,17 @@ public: @remarks If the current value of the control is outside of the newly set range bounds, the behaviour is undefined. */ - virtual void SetRange(const wxDateTime& dt1, const wxDateTime& dt2) = 0; + virtual void SetRange(const wxDateTime& dt1, const wxDateTime& dt2); /** - Changes the current value of the control. The date should be valid and - included in the currently selected range, if any. + Changes the current value of the control. + + The date should be valid unless the control was created with @c + wxDP_ALLOWNONE style and included in the currently selected range, if + any. Calling this method does not result in a date change event. */ - virtual void SetValue(const wxDateTime& dt) = 0; + virtual void SetValue(const wxDateTime& dt); };