interface/calctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        calctrl.h
   3 // Purpose:     interface of wxCalendarEvent
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCalendarEvent
  11     @wxheader{calctrl.h}
  12
  13     The wxCalendarEvent class is used together with
  14     wxCalendarCtrl.
  15
  16     @library{wxadv}
  17     @category{events}
  18
  19     @see wxCalendarCtrl
  20 */
  21 class wxCalendarEvent : public wxDateEvent
  22 {
  23 public:
  24     /**
  25         Returns the week day on which the user clicked in
  26         @c EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call
  27         this function in other handlers.
  28     */
  29     wxDateTime::WeekDay GetWeekDay() const;
  30
  31     /**
  32         Sets the week day carried by the event, normally only used by the library
  33         internally.
  34     */
  35     void SetWeekDay(wxDateTime::WeekDay day);
  36 };
  37
  38
  39
  40 /**
  41     @class wxCalendarDateAttr
  42     @wxheader{calctrl.h}
  43
  44     wxCalendarDateAttr is a custom attributes for a calendar date. The objects of
  45     this class are used with wxCalendarCtrl.
  46
  47     @library{wxadv}
  48     @category{misc}
  49
  50     @see wxCalendarCtrl
  51 */
  52 class wxCalendarDateAttr
  53 {
  54 public:
  55     //@{
  56     /**
  57         The constructors.
  58     */
  59     wxCalendarDateAttr();
  60     wxCalendarDateAttr(const wxColour& colText,
  61                        const wxColour& colBack = wxNullColour,
  62                        const wxColour& colBorder = wxNullColour,
  63                        const wxFont& font = wxNullFont,
  64                        wxCalendarDateBorder border = wxCAL_BORDER_NONE);
  65     wxCalendarDateAttr(wxCalendarDateBorder border,
  66                        const wxColour& colBorder = wxNullColour);
  67     //@}
  68
  69     /**
  70         Returns the background colour to use for the item with this attribute.
  71     */
  72     const wxColour GetBackgroundColour() const;
  73
  74     /**
  75         Returns the border() to use for the item with this attribute.
  76     */
  77     wxCalendarDateBorder GetBorder() const;
  78
  79     /**
  80         Returns the border colour to use for the item with this attribute.
  81     */
  82     const wxColour GetBorderColour() const;
  83
  84     /**
  85         Returns the font to use for the item with this attribute.
  86     */
  87     const wxFont GetFont() const;
  88
  89     /**
  90         Returns the text colour to use for the item with this attribute.
  91     */
  92     const wxColour GetTextColour() const;
  93
  94     /**
  95         Returns @true if this attribute specifies a non-default text background
  96         colour.
  97     */
  98     bool HasBackgroundColour() const;
  99
 100     /**
 101         Returns @true if this attribute specifies a non-default (i.e. any) border.
 102     */
 103     bool HasBorder() const;
 104
 105     /**
 106         Returns @true if this attribute specifies a non-default border colour.
 107     */
 108     bool HasBorderColour() const;
 109
 110     /**
 111         Returns @true if this attribute specifies a non-default font.
 112     */
 113     bool HasFont() const;
 114
 115     /**
 116         Returns @true if this item has a non-default text foreground colour.
 117     */
 118     bool HasTextColour() const;
 119
 120     /**
 121         Returns @true if this attribute specifies that this item should be
 122         displayed as a holiday.
 123     */
 124     bool IsHoliday() const;
 125
 126     /**
 127         Sets the text background colour to use.
 128     */
 129     void SetBackgroundColour(const wxColour& colBack);
 130
 131     /**
 132         Sets the @ref overview_wxcalendardateattr "border kind"
 133     */
 134     void SetBorder(wxCalendarDateBorder border);
 135
 136     /**
 137         Sets the border colour to use.
 138     */
 139     void SetBorderColour(const wxColour& col);
 140
 141     /**
 142         Sets the font to use.
 143     */
 144     void SetFont(const wxFont& font);
 145
 146     /**
 147         Display the date with this attribute as a holiday.
 148     */
 149     void SetHoliday(bool holiday);
 150
 151     /**
 152         Sets the text (foreground) colour to use.
 153     */
 154     void SetTextColour(const wxColour& colText);
 155 };
 156
 157
 158
 159 /**
 160     @class wxCalendarCtrl
 161     @wxheader{calctrl.h}
 162
 163     The calendar control allows the user to pick a date. For this,
 164     it displays a window containing several parts: a control at the top to pick the
 165     month
 166     and the year (either or both of them may be disabled), and a month
 167     area below them which shows all the days in the month. The user can move the
 168     current selection using the keyboard and select the date (generating
 169     @c EVT_CALENDAR event) by pressing @c Return or double clicking it.
 170
 171     It has advanced possibilities for the customization of its display. All global
 172     settings (such as colours and fonts used) can, of course, be changed. But
 173     also, the display style for each day in the month can be set independently
 174     using wxCalendarDateAttr class.
 175
 176     An item without custom attributes is drawn with the default colours and
 177     font and without border, but setting custom attributes with
 178     wxCalendarCtrl::SetAttr allows to modify its appearance. Just
 179     create a custom attribute object and set it for the day you want to be
 180     displayed specially (note that the control will take ownership of the pointer,
 181     i.e. it will delete it itself). A day may be marked as being a holiday, even
 182     if it is not recognized as one by wxDateTime using
 183     wxCalendarDateAttr::SetHoliday method.
 184
 185     As the attributes are specified for each day, they may change when the month
 186     is changed, so you will often want to update them in
 187     @c EVT_CALENDAR_MONTH event handler.
 188
 189     @beginStyleTable
 190     @style{wxCAL_SUNDAY_FIRST}:
 191            Show Sunday as the first day in the week
 192     @style{wxCAL_MONDAY_FIRST}:
 193            Show Monday as the first day in the week
 194     @style{wxCAL_SHOW_HOLIDAYS}:
 195            Highlight holidays in the calendar
 196     @style{wxCAL_NO_YEAR_CHANGE}:
 197            Disable the year changing
 198     @style{wxCAL_NO_MONTH_CHANGE}:
 199            Disable the month (and, implicitly, the year) changing
 200     @style{wxCAL_SHOW_SURROUNDING_WEEKS}:
 201            Show the neighbouring weeks in the previous and next months
 202     @style{wxCAL_SEQUENTIAL_MONTH_SELECTION}:
 203            Use alternative, more compact, style for the month and year
 204            selection controls.
 205     @endStyleTable
 206
 207     @library{wxadv}
 208     @category{ctrl}
 209     @appearance{calendarctrl.png}
 210
 211     @see @ref overview_samplecalendar "Calendar sample", wxCalendarDateAttr,
 212     wxCalendarEvent
 213 */
 214 class wxCalendarCtrl : public wxControl
 215 {
 216 public:
 217     //@{
 218     /**
 219         Does the same as Create() method.
 220     */
 221     wxCalendarCtrl();
 222     wxCalendarCtrl(wxWindow* parent, wxWindowID id,
 223                    const wxDateTime& date = wxDefaultDateTime,
 224                    const wxPoint& pos = wxDefaultPosition,
 225                    const wxSize& size = wxDefaultSize,
 226                    long style = wxCAL_SHOW_HOLIDAYS,
 227                    const wxString& name = wxCalendarNameStr);
 228     //@}
 229
 230     /**
 231         Destroys the control.
 232     */
 233     ~wxCalendarCtrl();
 234
 235     /**
 236         Creates the control. See @ref wxWindow::ctor wxWindow for the meaning of
 237         the parameters and the control overview for the possible styles.
 238     */
 239     bool Create(wxWindow* parent, wxWindowID id,
 240                 const wxDateTime& date = wxDefaultDateTime,
 241                 const wxPoint& pos = wxDefaultPosition,
 242                 const wxSize& size = wxDefaultSize,
 243                 long style = wxCAL_SHOW_HOLIDAYS,
 244                 const wxString& name = wxCalendarNameStr);
 245
 246     /**
 247         This function should be used instead of changing @c wxCAL_SHOW_HOLIDAYS
 248         style bit directly. It enables or disables the special highlighting of the
 249         holidays.
 250     */
 251     void EnableHolidayDisplay(bool display = true);
 252
 253     /**
 254         This function should be used instead of changing
 255         @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to
 256         change the month interactively. Note that if the month can not be changed, the
 257         year can not be changed neither.
 258     */
 259     void EnableMonthChange(bool enable = true);
 260
 261     /**
 262         This function should be used instead of changing @c wxCAL_NO_YEAR_CHANGE
 263         style bit directly. It allows or disallows the user to change the year
 264         interactively.
 265     */
 266     void EnableYearChange(bool enable = true);
 267
 268     /**
 269         Returns the attribute for the given date (should be in the range 1...31).
 270         The returned pointer may be @NULL.
 271     */
 272     wxCalendarDateAttr* GetAttr(size_t day) const;
 273
 274     /**
 275         Gets the currently selected date.
 276     */
 277     const wxDateTime GetDate() const;
 278
 279     /**
 280         Gets the background colour of the header part of the calendar window.
 281
 282         @see SetHeaderColours()
 283     */
 284     const wxColour GetHeaderColourBg() const;
 285
 286     /**
 287         Gets the foreground colour of the header part of the calendar window.
 288
 289         @see SetHeaderColours()
 290     */
 291     const wxColour GetHeaderColourFg() const;
 292
 293     /**
 294         Gets the background highlight colour.
 295
 296         @see SetHighlightColours()
 297     */
 298     const wxColour GetHighlightColourBg() const;
 299
 300     /**
 301         Gets the foreground highlight colour.
 302
 303         @see SetHighlightColours()
 304     */
 305     const wxColour GetHighlightColourFg() const;
 306
 307     /**
 308         Return the background colour currently used for holiday highlighting.
 309
 310         @see SetHolidayColours()
 311     */
 312     const wxColour GetHolidayColourBg() const;
 313
 314     /**
 315         Return the foreground colour currently used for holiday highlighting.
 316
 317         @see SetHolidayColours()
 318     */
 319     const wxColour GetHolidayColourFg() const;
 320
 321     /**
 322         Returns one of @c wxCAL_HITTEST_XXX
 323         constants() and fills either @a date or
 324         @a wd pointer with the corresponding value depending on the hit test code.
 325     */
 326     wxCalendarHitTestResult HitTest(const wxPoint& pos,
 327                                     wxDateTime* date = NULL,
 328                                     wxDateTime::WeekDay* wd = NULL);
 329
 330     /**
 331         Clears any attributes associated with the given day (in the range
 332         1...31).
 333     */
 334     void ResetAttr(size_t day);
 335
 336     /**
 337         Associates the attribute with the specified date (in the range 1...31).
 338         If the pointer is @NULL, the items attribute is cleared.
 339     */
 340     void SetAttr(size_t day, wxCalendarDateAttr* attr);
 341
 342     /**
 343         Sets the current date.
 344     */
 345     void SetDate(const wxDateTime& date);
 346
 347     /**
 348         Set the colours used for painting the weekdays at the top of the control.
 349     */
 350     void SetHeaderColours(const wxColour& colFg,
 351                           const wxColour& colBg);
 352
 353     /**
 354         Set the colours to be used for highlighting the currently selected date.
 355     */
 356     void SetHighlightColours(const wxColour& colFg,
 357                              const wxColour& colBg);
 358
 359     /**
 360         Marks the specified day as being a holiday in the current month.
 361     */
 362     void SetHoliday(size_t day);
 363
 364     /**
 365         Sets the colours to be used for the holidays highlighting (only used if the
 366         window style includes @c wxCAL_SHOW_HOLIDAYS flag).
 367     */
 368     void SetHolidayColours(const wxColour& colFg,
 369                            const wxColour& colBg);
 370 };
 371