/////////////////////////////////////////////////////////////////////////////
// Name: calctrl.h
-// Purpose: documentation for wxCalendarEvent class
+// Purpose: interface of wxCalendarCtrl
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@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}
-
- @seealso
- wxCalendarCtrl
+
+ @see wxCalendarCtrl
*/
class wxCalendarEvent : public wxDateEvent
{
public:
/**
- Returns the week day on which the user clicked in
+ Returns the week day on which the user clicked in
@c EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call
this function in other handlers.
*/
- wxDateTime::WeekDay GetWeekDay();
+ 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}
-
- @seealso
- wxCalendarCtrl
+
+ @see wxCalendarCtrl
*/
-class wxCalendarDateAttr
+class wxCalendarDateAttr
{
public:
- //@{
/**
- The constructors.
+ Default constructor.
*/
wxCalendarDateAttr();
- wxCalendarDateAttr(const wxColour& colText,
- const wxColour& colBack = wxNullColour,
- const wxColour& colBorder = wxNullColour,
- const wxFont& font = wxNullFont,
- wxCalendarDateBorder border = wxCAL_BORDER_NONE);
- wxCalendarDateAttr(wxCalendarDateBorder border,
- const wxColour& colBorder = wxNullColour);
- //@}
/**
- Returns the background colour to use for the item with this attribute.
+ 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 set for the calendar date.
*/
- const wxColour GetBackgroundColour();
+ 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();
+ 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 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 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 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();
+ 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();
+ 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();
+ bool HasBorderColour() const;
/**
- Returns @true if this attribute specifies a non-default font.
+ Returns @true if a non-default font is set.
*/
- bool HasFont();
+ 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();
+ 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();
+ bool IsHoliday() const;
/**
Sets the text background colour to use.
void SetBackgroundColour(const wxColour& colBack);
/**
- Sets the @ref overview_wxcalendardateattr "border kind"
+ Sets the border to use.
*/
void SetBorder(wxCalendarDateBorder border);
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);
Sets the text (foreground) colour to use.
*/
void SetTextColour(const wxColour& colText);
+
+ /**
+ Used (internally) by the generic wxCalendarCtrl::Mark().
+ */
+ static const wxCalendarDateAttr& GetMark();
+
+ /**
+ 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. For this,
- it displays a window containing several parts: a control at the top to pick the
- month
- and the year (either or both of them may be disabled), and a month
- area below them which shows all the days in the month. 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.
-
- It has advanced possibilities for the customization of its display. 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.
-
+
+ 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.
+
+ 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.
+
+ 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). A day may be marked as being a holiday, even
- if it is not recognized as one by wxDateTime using
- 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
- @c EVT_CALENDAR_MONTH event handler.
-
+ 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 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
+ @c EVT_CALENDAR_PAGE_CHANGED event handler.
+
@beginStyleTable
@style{wxCAL_SUNDAY_FIRST}:
- Show Sunday as the first day in the week
+ 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
+ Show Monday as the first day in the week (not in wxGTK)
@style{wxCAL_SHOW_HOLIDAYS}:
- Highlight holidays in the calendar
+ Highlight holidays in the calendar (only generic)
@style{wxCAL_NO_YEAR_CHANGE}:
- Disable the year changing
+ Disable the year changing (deprecated, only generic)
@style{wxCAL_NO_MONTH_CHANGE}:
Disable the month (and, implicitly, the year) changing
@style{wxCAL_SHOW_SURROUNDING_WEEKS}:
Show the neighbouring weeks in the previous and next months
+ (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.
+ selection controls. (only generic)
@endStyleTable
-
+
+ @beginEventTable{wxCalendarEvent}
+ @event{EVT_CALENDAR(id, func)}:
+ A day was double clicked in the calendar.
+ @event{EVT_CALENDAR_SEL_CHANGED(id, func)}:
+ The selected date changed.
+ @event{EVT_CALENDAR_PAGE_CHANGED(id, func)}:
+ The selected month (and/or year) changed.
+ @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}
-
- @seealso
- @ref overview_samplecalendar "Calendar sample", wxCalendarDateAttr,
- wxCalendarEvent
+ <!-- @appearance{calendarctrl.png} -->
+
+ @nativeimpl{wxgtk}
+
+ @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent,
+ wxDatePickerCtrl
*/
class wxCalendarCtrl : public wxControl
{
public:
- //@{
/**
- Does the same as Create() method.
+ Default constructor.
*/
wxCalendarCtrl();
- 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);
- //@}
+
+ /**
+ 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.
~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,
/**
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);
+ void EnableHolidayDisplay(bool display = true);
/**
- This function should be used instead of changing
+ 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.
*/
- void EnableMonthChange(bool enable = @true);
+ bool EnableMonthChange(bool enable = true);
/**
- 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.
+ @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.
*/
- void EnableYearChange(bool enable = @true);
+ 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.
+ 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);
+ wxCalendarDateAttr* GetAttr(size_t day) const;
/**
Gets the currently selected date.
*/
- const wxDateTime GetDate();
+ const wxDateTime GetDate() const;
/**
Gets the background colour of the header part of the calendar window.
-
- @sa SetHeaderColours()
+
+ This method is currently only implemented in generic wxCalendarCtrl and
+ always returns @c wxNullColour in the native versions.
+
+ @see SetHeaderColours()
*/
- const wxColour GetHeaderColourBg();
+ const wxColour GetHeaderColourBg() const;
/**
Gets the foreground colour of the header part of the calendar window.
-
- @sa SetHeaderColours()
+
+ This method is currently only implemented in generic wxCalendarCtrl and
+ always returns @c wxNullColour in the native versions.
+
+ @see SetHeaderColours()
*/
- const wxColour GetHeaderColourFg();
+ const wxColour GetHeaderColourFg() const;
/**
- Gets the background highlight colour.
-
- @sa SetHighlightColours()
+ 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 wxColour GetHighlightColourBg() const;
/**
- Gets the foreground highlight colour.
-
- @sa SetHighlightColours()
+ 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 wxColour GetHighlightColourFg() const;
/**
Return the background colour currently used for holiday highlighting.
-
- @sa SetHolidayColours()
+
+ 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 GetHolidayColourBg();
+ const wxColour GetHolidayColourBg() const;
/**
Return the foreground colour currently used for holiday highlighting.
-
- @sa SetHolidayColours()
+
+ 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 wxColour GetHolidayColourFg() const;
/**
- Returns one of @c wxCAL_HITTEST_XXX
- constants and fills either @e date or
- @e wd pointer with the corresponding value depending on the hit test code.
+ 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,
- wxDateTime::WeekDay* wd = @NULL);
+ wxDateTime* date = NULL,
+ wxDateTime::WeekDay* wd = NULL);
/**
Clears any attributes associated with the given day (in the range
- 1...31).
+ 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.
+ 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.
+ 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.
+ 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).
+ 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,
+ */
+ 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;
+
+ //@}
};
+
projects / wxWidgets.git / blobdiff