]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/calctrl.h
add handling of wxWrapSizer flags (part of ticket 9468)
[wxWidgets.git] / interface / calctrl.h
index d894e1f82136739e62984d83fe0348232604cfce..397b4760ef73627783d755036866614a4b5cbe03 100644 (file)
@@ -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 @<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.
+    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}
+    <!-- @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;
+
+    //@}
 };