X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/628e155d8c70da0f962289cf1e1dea3699255707..63b37a4e648320827a5b4a3161be13154370b5c3:/interface/calctrl.h diff --git a/interface/calctrl.h b/interface/calctrl.h index d894e1f821..397b4760ef 100644 --- a/interface/calctrl.h +++ b/interface/calctrl.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: calctrl.h -// Purpose: interface of wxCalendarEvent +// Purpose: interface of wxCalendarCtrl // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,8 +10,7 @@ @class wxCalendarEvent @wxheader{calctrl.h} - The wxCalendarEvent class is used together with - wxCalendarCtrl. + The wxCalendarEvent class is used together with wxCalendarCtrl. @library{wxadv} @category{events} @@ -29,20 +28,31 @@ public: wxDateTime::WeekDay GetWeekDay() const; /** - Sets the week day carried by the event, - normally only used by the library internally. + Sets the week day carried by the event, normally only used by the + library internally. */ void SetWeekDay(wxDateTime::WeekDay day); }; +/** + Possible kinds of borders which may be used to decorate a date using + wxCalendarDateAttr. +*/ +enum wxCalendarDateBorder +{ + wxCAL_BORDER_NONE, ///< No Border (Default) + wxCAL_BORDER_SQUARE, ///< Rectangular Border + wxCAL_BORDER_ROUND ///< Round Border +}; + /** @class wxCalendarDateAttr @wxheader{calctrl.h} - wxCalendarDateAttr is a custom attributes for a calendar date. The objects of - this class are used with wxCalendarCtrl. + wxCalendarDateAttr is a custom attributes for a calendar date. The objects + of this class are used with wxCalendarCtrl. @library{wxadv} @category{misc} @@ -52,74 +62,78 @@ public: class wxCalendarDateAttr { public: - //@{ /** - The constructors. + Default constructor. */ wxCalendarDateAttr(); + + /** + Constructor for specifying all wxCalendarDateAttr properties. + */ wxCalendarDateAttr(const wxColour& colText, const wxColour& colBack = wxNullColour, const wxColour& colBorder = wxNullColour, const wxFont& font = wxNullFont, wxCalendarDateBorder border = wxCAL_BORDER_NONE); + + /** + Constructor using default properties except the given border. + */ wxCalendarDateAttr(wxCalendarDateBorder border, const wxColour& colBorder = wxNullColour); - //@} /** - Returns the background colour to use for the item with this attribute. + Returns the background colour set for the calendar date. */ const wxColour GetBackgroundColour() const; /** - Returns the border() to use for the item with this attribute. + Returns the border set for the calendar date. */ wxCalendarDateBorder GetBorder() const; /** - Returns the border colour to use for the item with this attribute. + Returns the border colour set for the calendar date. */ const wxColour GetBorderColour() const; /** - Returns the font to use for the item with this attribute. + Returns the font set for the calendar date. */ const wxFont GetFont() const; /** - Returns the text colour to use for the item with this attribute. + Returns the text colour set for the calendar date. */ const wxColour GetTextColour() const; /** - Returns @true if this attribute specifies a non-default text background - colour. + Returns @true if a non-default text background colour is set. */ bool HasBackgroundColour() const; /** - Returns @true if this attribute specifies a non-default (i.e. any) border. + Returns @true if a non-default (i.e. any) border is set. */ bool HasBorder() const; /** - Returns @true if this attribute specifies a non-default border colour. + Returns @true if a non-default border colour is set. */ bool HasBorderColour() const; /** - Returns @true if this attribute specifies a non-default font. + Returns @true if a non-default font is set. */ bool HasFont() const; /** - Returns @true if this item has a non-default text foreground colour. + Returns @true if a non-default text foreground colour is set. */ bool HasTextColour() const; /** - Returns @true if this attribute specifies that this item should be - displayed as a holiday. + Returns @true if this calendar day is displayed as a holiday. */ bool IsHoliday() const; @@ -129,7 +143,7 @@ public: void SetBackgroundColour(const wxColour& colBack); /** - Sets the @ref overview_wxcalendardateattr "border kind" + Sets the border to use. */ void SetBorder(wxCalendarDateBorder border); @@ -144,7 +158,8 @@ public: void SetFont(const wxFont& font); /** - Display the date with this attribute as a holiday. + If @a holiday is @true, this calendar day will be displayed as a + holiday. */ void SetHoliday(bool holiday); @@ -154,102 +169,118 @@ public: void SetTextColour(const wxColour& colText); /** - Used (internally) by generic wxCalendarCtrl::Mark() + Used (internally) by the generic wxCalendarCtrl::Mark(). */ static const wxCalendarDateAttr& GetMark(); /** - Set the attribute that will be used to Mark() days - on generic wxCalendarCtrl + Set the attributes that will be used to Mark() days on the generic + wxCalendarCtrl. */ static void SetMark(wxCalendarDateAttr const& m); }; +/** + Possible return values from wxCalendarCtrl::HitTest(). +*/ +enum wxCalendarHitTestResult +{ + wxCAL_HITTEST_NOWHERE, ///< Hit outside of anything. + wxCAL_HITTEST_HEADER, ///< Hit on the header (weekdays). + wxCAL_HITTEST_DAY ///< Hit on a day in the calendar. +}; + /** @class wxCalendarCtrl @wxheader{calctrl.h} The calendar control allows the user to pick a date. The user can move the current selection using the keyboard and select the date (generating - @c EVT_CALENDAR event) by pressing @c Return or double clicking it. + @c EVT_CALENDAR event) by pressing @c @ or double clicking it. Generic calendar has advanced possibilities for the customization of its - display, described below. If you want to use these possibilities on - every platform, use wxGenericCalendarCtrl instead of wxCalendarCtrl. + display, described below. If you want to use these possibilities on every + platform, use wxGenericCalendarCtrl instead of wxCalendarCtrl. - All global settings (such as colours and fonts used) can, of course, - be changed. But also, the display style for each day in the month can - be set independently using wxCalendarDateAttr class. + All global settings (such as colours and fonts used) can, of course, be + changed. But also, the display style for each day in the month can be set + independently using wxCalendarDateAttr class. An item without custom attributes is drawn with the default colours and - font and without border, but setting custom attributes with - wxCalendarCtrl::SetAttr allows to modify its appearance. Just - create a custom attribute object and set it for the day you want to be - displayed specially (note that the control will take ownership of - the pointer, i.e. it will delete it itself). + font and without border, but setting custom attributes with SetAttr() + allows to modify its appearance. Just create a custom attribute object and + set it for the day you want to be displayed specially (note that the + control will take ownership of the pointer, i.e. it will delete it itself). A day may be marked as being a holiday, even if it is not recognized as - one by wxDateTime using wxCalendarDateAttr::SetHoliday method. + one by wxDateTime using the wxCalendarDateAttr::SetHoliday() method. - As the attributes are specified for each day, they may change when the month - is changed, so you will often want to update them in + As the attributes are specified for each day, they may change when the + month is changed, so you will often want to update them in @c EVT_CALENDAR_PAGE_CHANGED event handler. @beginStyleTable - @style{wxCAL_SUNDAY_FIRST}: - Show Sunday as the first day in the week (only generic) - @style{wxCAL_MONDAY_FIRST}: - Show Monday as the first day in the week (only generic) - @style{wxCAL_SHOW_HOLIDAYS}: + @style{wxCAL_SUNDAY_FIRST} + Show Sunday as the first day in the week (not in wxGTK) + @style{wxCAL_MONDAY_FIRST} + Show Monday as the first day in the week (not in wxGTK) + @style{wxCAL_SHOW_HOLIDAYS} Highlight holidays in the calendar (only generic) - @style{wxCAL_NO_YEAR_CHANGE}: + @style{wxCAL_NO_YEAR_CHANGE} Disable the year changing (deprecated, only generic) - @style{wxCAL_NO_MONTH_CHANGE}: + @style{wxCAL_NO_MONTH_CHANGE} Disable the month (and, implicitly, the year) changing - @style{wxCAL_SHOW_SURROUNDING_WEEKS}: + @style{wxCAL_SHOW_SURROUNDING_WEEKS} Show the neighbouring weeks in the previous and next months - (only generic) - @style{wxCAL_SEQUENTIAL_MONTH_SELECTION}: + (only generic, always on for the native controls) + @style{wxCAL_SEQUENTIAL_MONTH_SELECTION} Use alternative, more compact, style for the month and year selection controls. (only generic) + @style{wxCAL_SHOW_WEEK_NUMBERS} + Show week numbers on the left side of the calendar. (not in generic) @endStyleTable - @beginEventTable - @event{EVT_CALENDAR(id, func)}: + @beginEventTable{wxCalendarEvent} + @event{EVT_CALENDAR(id, func)} A day was double clicked in the calendar. - @event{EVT_CALENDAR_SEL_CHANGED(id, func)}: + @event{EVT_CALENDAR_SEL_CHANGED(id, func)} The selected date changed. - @event{EVT_CALENDAR_PAGE_CHANGED(id, func)}: + @event{EVT_CALENDAR_PAGE_CHANGED(id, func)} The selected month (and/or year) changed. - @event{EVT_CALENDAR_WEEKDAY_CLICKED(id, func)}: + @event{EVT_CALENDAR_WEEKDAY_CLICKED(id, func)} User clicked on the week day header (only generic). @endEventTable + @note Changing the selected date will trigger an EVT_CALENDAR_DAY, MONTH or + YEAR event as well as an EVT_CALENDAR_SEL_CHANGED event. + @library{wxadv} @category{ctrl} - @appearance{calendarctrl.png} + - @nativeimpl{wxgtk} + @nativeimpl{wxgtk,wxmsw} - @see @ref overview_samplecalendar "Calendar sample", wxCalendarDateAttr, - wxCalendarEvent, wxDatePickerCtrl + @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent, + wxDatePickerCtrl */ class wxCalendarCtrl : public wxControl { public: - //@{ /** - Does the same as Create() method. + Default constructor. */ wxCalendarCtrl(); + + /** + Does the same as Create() method. + */ wxCalendarCtrl(wxWindow* parent, wxWindowID id, const wxDateTime& date = wxDefaultDateTime, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxCAL_SHOW_HOLIDAYS, const wxString& name = wxCalendarNameStr); - //@} /** Destroys the control. @@ -257,8 +288,8 @@ public: ~wxCalendarCtrl(); /** - Creates the control. See @ref wxWindow::ctor wxWindow for the meaning of - the parameters and the control overview for the possible styles. + Creates the control. See wxWindow::wxWindow() for the meaning of the + parameters and the control overview for the possible styles. */ bool Create(wxWindow* parent, wxWindowID id, const wxDateTime& date = wxDefaultDateTime, @@ -269,34 +300,35 @@ public: /** This function should be used instead of changing @c wxCAL_SHOW_HOLIDAYS - style bit directly. It enables or disables the special highlighting of the - holidays. + style bit directly. It enables or disables the special highlighting of + the holidays. */ void EnableHolidayDisplay(bool display = true); /** This function should be used instead of changing @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to - change the month interactively. Note that if the month can not - be changed, the year can not be changed neither. + change the month interactively. Note that if the month can not be + changed, the year can not be changed neither. - @return @true if the value of this option really changed or @false - if it was already set to the requested value. + @return @true if the value of this option really changed or @false if + it was already set to the requested value. */ bool EnableMonthChange(bool enable = true); /** @deprecated - This function should be used instead of changing @c wxCAL_NO_YEAR_CHANGE - style bit directly. It allows or disallows the user to change the year - interactively. Only in generic wxCalendarCtrl. + This function should be used instead of changing + @c wxCAL_NO_YEAR_CHANGE style bit directly. It allows or disallows the + user to change the year interactively. Only in generic wxCalendarCtrl. */ void EnableYearChange(bool enable = true); /** - Returns the attribute for the given date (should be in the range 1...31). - The returned pointer may be @NULL. Only in generic wxCalendarCtrl. + Returns the attribute for the given date (should be in the range + 1...31). The returned pointer may be @NULL. Only in generic + wxCalendarCtrl. */ wxCalendarDateAttr* GetAttr(size_t day) const; @@ -308,13 +340,18 @@ public: /** Gets the background colour of the header part of the calendar window. + This method is currently only implemented in generic wxCalendarCtrl and + always returns @c wxNullColour in the native versions. + @see SetHeaderColours() */ const wxColour GetHeaderColourBg() const; /** Gets the foreground colour of the header part of the calendar window. - Only in generic wxCalendarCtrl. + + This method is currently only implemented in generic wxCalendarCtrl and + always returns @c wxNullColour in the native versions. @see SetHeaderColours() */ @@ -323,6 +360,9 @@ public: /** Gets the background highlight colour. Only in generic wxCalendarCtrl. + This method is currently only implemented in generic wxCalendarCtrl and + always returns @c wxNullColour in the native versions. + @see SetHighlightColours() */ const wxColour GetHighlightColourBg() const; @@ -330,13 +370,19 @@ public: /** Gets the foreground highlight colour. Only in generic wxCalendarCtrl. + This method is currently only implemented in generic wxCalendarCtrl and + always returns @c wxNullColour in the native versions. + @see SetHighlightColours() */ const wxColour GetHighlightColourFg() const; /** Return the background colour currently used for holiday highlighting. - Only in generic wxCalendarCtrl. + + Only useful with generic wxCalendarCtrl as native versions currently + don't support holidays display at all and always return + @c wxNullColour. @see SetHolidayColours() */ @@ -344,17 +390,21 @@ public: /** Return the foreground colour currently used for holiday highlighting. - Only in generic wxCalendarCtrl. + + Only useful with generic wxCalendarCtrl as native versions currently + don't support holidays display at all and always return + @c wxNullColour. @see SetHolidayColours() */ const wxColour GetHolidayColourFg() const; /** - Returns one of @c wxCAL_HITTEST_XXX - constants() and fills either @a date or @a wd pointer with - the corresponding value depending on the hit test code. - Only in generic wxCalendarCtrl. + Returns one of wxCalendarHitTestResult constants and fills either + @a date or @a wd pointer with the corresponding value depending on the + hit test code. + + Not implemented in wxGTK currently. */ wxCalendarHitTestResult HitTest(const wxPoint& pos, wxDateTime* date = NULL, @@ -362,55 +412,118 @@ public: /** Clears any attributes associated with the given day (in the range - 1...31). - Only in generic wxCalendarCtrl. + 1...31). Only in generic wxCalendarCtrl. */ void ResetAttr(size_t day); /** Associates the attribute with the specified date (in the range 1...31). - If the pointer is @NULL, the items attribute is cleared. - Only in generic wxCalendarCtrl. + If the pointer is @NULL, the items attribute is cleared. Only in + generic wxCalendarCtrl. */ void SetAttr(size_t day, wxCalendarDateAttr* attr); /** Sets the current date. + + The @a date parameter must be valid. */ void SetDate(const wxDateTime& date); /** - Set the colours used for painting the weekdays at the top of the control. - Only in generic wxCalendarCtrl. + Set the colours used for painting the weekdays at the top of the + control. + + This method is currently only implemented in generic wxCalendarCtrl and + does nothing in the native versions. */ void SetHeaderColours(const wxColour& colFg, const wxColour& colBg); /** - Set the colours to be used for highlighting the currently selected date. - Only in generic wxCalendarCtrl. + Set the colours to be used for highlighting the currently selected + date. + + This method is currently only implemented in generic wxCalendarCtrl and + does nothing in the native versions. */ void SetHighlightColours(const wxColour& colFg, const wxColour& colBg); /** Marks the specified day as being a holiday in the current month. + + This method is only implemented in the generic version of the control + and does nothing in the native ones. */ void SetHoliday(size_t day); /** - Sets the colours to be used for the holidays highlighting (only used if the - window style includes @c wxCAL_SHOW_HOLIDAYS flag). - Only in generic wxCalendarCtrl. + Sets the colours to be used for the holidays highlighting. + + This method is only implemented in the generic version of the control + and does nothing in the native ones. It should also only be called if + the window style includes @c wxCAL_SHOW_HOLIDAYS flag or + EnableHolidayDisplay() had been called. + */ void SetHolidayColours(const wxColour& colFg, const wxColour& colBg); /** - Mark or unmark the day. - This day of month will be marked in every month. - In generic wxCalendarCtrl, + Mark or unmark the day. This day of month will be marked in every + month. In generic wxCalendarCtrl, */ void Mark(size_t day, bool mark); + + /** + @name Date Range Functions + + The functions in this section are currently implemented in the generic + and MSW versions and do nothing in the native GTK implementation. + */ + //@{ + + /** + Restrict the dates shown by the control to the specified range. + + If either date is set, the corresponding limit will be enforced and + @true returned. If none are set, the existing restrictions are removed + and @false is returned. + + @see GetDateRange() + + @param lowerdate + The low limit for the dates shown by the control or + @c wxDefaultDateTime. + @param highlighting + The high limit for the dates shown by the control or + @c wxDefaultDateTime. + @return + @true if either limit is valid, @false otherwise + */ + virtual bool SetDateRange(const wxDateTime& lowerdate = wxDefaultDateTime, + const wxDateTime& upperdate = wxDefaultDateTime); + + /** + Returns the limits currently being used. + + @see SetDateRange() + + @param lowerdate + If non-@NULL, the value of the low limit for the dates shown by the + control is returned (which may be @c wxDefaultDateTime if no limit + is set). + @param upperdate + If non-@NULL, the value of the upper limit for the dates shown by + the control is returned (which may be @c wxDefaultDateTime if no + limit is set). + @return + @true if either limit is set, @false otherwise + */ + virtual bool GetDateRange(wxDateTime *lowerdate, + wxDateTime *upperdate) const; + + //@} };