interface/calctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        calctrl.h
   3 // Purpose:     interface of wxCalendarCtrl
   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 wxCalendarCtrl.
  14
  15     @library{wxadv}
  16     @category{events}
  17
  18     @see wxCalendarCtrl
  19 */
  20 class wxCalendarEvent : public wxDateEvent
  21 {
  22 public:
  23     /**
  24         Returns the week day on which the user clicked in
  25         @c EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call
  26         this function in other handlers.
  27     */
  28     wxDateTime::WeekDay GetWeekDay() const;
  29
  30     /**
  31         Sets the week day carried by the event, normally only used by the
  32         library internally.
  33     */
  34     void SetWeekDay(wxDateTime::WeekDay day);
  35 };
  36
  37
  38
  39 /**
  40     Possible kinds of borders which may be used to decorate a date using
  41     wxCalendarDateAttr.
  42 */
  43 enum wxCalendarDateBorder
  44 {
  45     wxCAL_BORDER_NONE,      ///< No Border (Default)
  46     wxCAL_BORDER_SQUARE,    ///< Rectangular Border
  47     wxCAL_BORDER_ROUND      ///< Round Border
  48 };
  49
  50 /**
  51     @class wxCalendarDateAttr
  52     @wxheader{calctrl.h}
  53
  54     wxCalendarDateAttr is a custom attributes for a calendar date. The objects
  55     of this class are used with wxCalendarCtrl.
  56
  57     @library{wxadv}
  58     @category{misc}
  59
  60     @see wxCalendarCtrl
  61 */
  62 class wxCalendarDateAttr
  63 {
  64 public:
  65     /**
  66         Default constructor.
  67     */
  68     wxCalendarDateAttr();
  69
  70     /**
  71         Constructor for specifying all wxCalendarDateAttr properties.
  72     */
  73     wxCalendarDateAttr(const wxColour& colText,
  74                        const wxColour& colBack = wxNullColour,
  75                        const wxColour& colBorder = wxNullColour,
  76                        const wxFont& font = wxNullFont,
  77                        wxCalendarDateBorder border = wxCAL_BORDER_NONE);
  78
  79     /**
  80         Constructor using default properties except the given border.
  81     */
  82     wxCalendarDateAttr(wxCalendarDateBorder border,
  83                        const wxColour& colBorder = wxNullColour);
  84
  85     /**
  86         Returns the background colour set for the calendar date.
  87     */
  88     const wxColour GetBackgroundColour() const;
  89
  90     /**
  91         Returns the border set for the calendar date.
  92     */
  93     wxCalendarDateBorder GetBorder() const;
  94
  95     /**
  96         Returns the border colour set for the calendar date.
  97     */
  98     const wxColour GetBorderColour() const;
  99
 100     /**
 101         Returns the font set for the calendar date.
 102     */
 103     const wxFont GetFont() const;
 104
 105     /**
 106         Returns the text colour set for the calendar date.
 107     */
 108     const wxColour GetTextColour() const;
 109
 110     /**
 111         Returns @true if a non-default text background colour is set.
 112     */
 113     bool HasBackgroundColour() const;
 114
 115     /**
 116         Returns @true if a non-default (i.e. any) border is set.
 117     */
 118     bool HasBorder() const;
 119
 120     /**
 121         Returns @true if a non-default border colour is set.
 122     */
 123     bool HasBorderColour() const;
 124
 125     /**
 126         Returns @true if a non-default font is set.
 127     */
 128     bool HasFont() const;
 129
 130     /**
 131         Returns @true if a non-default text foreground colour is set.
 132     */
 133     bool HasTextColour() const;
 134
 135     /**
 136         Returns @true if this calendar day is displayed as a holiday.
 137     */
 138     bool IsHoliday() const;
 139
 140     /**
 141         Sets the text background colour to use.
 142     */
 143     void SetBackgroundColour(const wxColour& colBack);
 144
 145     /**
 146         Sets the border to use.
 147     */
 148     void SetBorder(wxCalendarDateBorder border);
 149
 150     /**
 151         Sets the border colour to use.
 152     */
 153     void SetBorderColour(const wxColour& col);
 154
 155     /**
 156         Sets the font to use.
 157     */
 158     void SetFont(const wxFont& font);
 159
 160     /**
 161         If @a holiday is @true, this calendar day will be displayed as a
 162         holiday.
 163     */
 164     void SetHoliday(bool holiday);
 165
 166     /**
 167         Sets the text (foreground) colour to use.
 168     */
 169     void SetTextColour(const wxColour& colText);
 170
 171     /**
 172         Used (internally) by the generic wxCalendarCtrl::Mark().
 173     */
 174     static const wxCalendarDateAttr& GetMark();
 175
 176     /**
 177         Set the attributes that will be used to Mark() days on the generic
 178         wxCalendarCtrl.
 179     */
 180     static void SetMark(wxCalendarDateAttr const& m);
 181 };
 182
 183
 184
 185 /**
 186     Possible return values from wxCalendarCtrl::HitTest().
 187 */
 188 enum wxCalendarHitTestResult
 189 {
 190     wxCAL_HITTEST_NOWHERE,  ///< Hit outside of anything.
 191     wxCAL_HITTEST_HEADER,   ///< Hit on the header (weekdays).
 192     wxCAL_HITTEST_DAY       ///< Hit on a day in the calendar.
 193 };
 194
 195 /**
 196     @class wxCalendarCtrl
 197     @wxheader{calctrl.h}
 198
 199     The calendar control allows the user to pick a date.  The user can move the
 200     current selection using the keyboard and select the date (generating
 201     @c EVT_CALENDAR event) by pressing @c @<Return@> or double clicking it.
 202
 203     Generic calendar has advanced possibilities for the customization of its
 204     display, described below. If you want to use these possibilities on every
 205     platform, use wxGenericCalendarCtrl instead of wxCalendarCtrl.
 206
 207     All global settings (such as colours and fonts used) can, of course, be
 208     changed. But also, the display style for each day in the month can be set
 209     independently using wxCalendarDateAttr class.
 210
 211     An item without custom attributes is drawn with the default colours and
 212     font and without border, but setting custom attributes with SetAttr()
 213     allows to modify its appearance. Just create a custom attribute object and
 214     set it for the day you want to be displayed specially (note that the
 215     control will take ownership of the pointer, i.e. it will delete it itself).
 216     A day may be marked as being a holiday, even if it is not recognized as
 217     one by wxDateTime using the wxCalendarDateAttr::SetHoliday() method.
 218
 219     As the attributes are specified for each day, they may change when the
 220     month is changed, so you will often want to update them in
 221     @c EVT_CALENDAR_PAGE_CHANGED event handler.
 222
 223     @beginStyleTable
 224     @style{wxCAL_SUNDAY_FIRST}
 225            Show Sunday as the first day in the week (not in wxGTK)
 226     @style{wxCAL_MONDAY_FIRST}
 227            Show Monday as the first day in the week (not in wxGTK)
 228     @style{wxCAL_SHOW_HOLIDAYS}
 229            Highlight holidays in the calendar (only generic)
 230     @style{wxCAL_NO_YEAR_CHANGE}
 231            Disable the year changing (deprecated, only generic)
 232     @style{wxCAL_NO_MONTH_CHANGE}
 233            Disable the month (and, implicitly, the year) changing
 234     @style{wxCAL_SHOW_SURROUNDING_WEEKS}
 235            Show the neighbouring weeks in the previous and next months
 236            (only generic, always on for the native controls)
 237     @style{wxCAL_SEQUENTIAL_MONTH_SELECTION}
 238            Use alternative, more compact, style for the month and year
 239            selection controls. (only generic)
 240     @style{wxCAL_SHOW_WEEK_NUMBERS}
 241            Show week numbers on the left side of the calendar. (not in generic)
 242     @endStyleTable
 243
 244     @beginEventTable{wxCalendarEvent}
 245     @event{EVT_CALENDAR(id, func)}
 246            A day was double clicked in the calendar.
 247     @event{EVT_CALENDAR_SEL_CHANGED(id, func)}
 248            The selected date changed.
 249     @event{EVT_CALENDAR_PAGE_CHANGED(id, func)}
 250            The selected month (and/or year) changed.
 251     @event{EVT_CALENDAR_WEEKDAY_CLICKED(id, func)}
 252            User clicked on the week day header (only generic).
 253     @endEventTable
 254
 255     @note Changing the selected date will trigger an EVT_CALENDAR_DAY, MONTH or
 256           YEAR event as well as an EVT_CALENDAR_SEL_CHANGED event.
 257
 258     @library{wxadv}
 259     @category{ctrl}
 260     <!-- @appearance{calendarctrl.png} -->
 261
 262     @nativeimpl{wxgtk,wxmsw}
 263
 264     @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent,
 265          wxDatePickerCtrl
 266 */
 267 class wxCalendarCtrl : public wxControl
 268 {
 269 public:
 270     /**
 271         Default constructor.
 272     */
 273     wxCalendarCtrl();
 274
 275     /**
 276         Does the same as Create() method.
 277     */
 278     wxCalendarCtrl(wxWindow* parent, wxWindowID id,
 279                    const wxDateTime& date = wxDefaultDateTime,
 280                    const wxPoint& pos = wxDefaultPosition,
 281                    const wxSize& size = wxDefaultSize,
 282                    long style = wxCAL_SHOW_HOLIDAYS,
 283                    const wxString& name = wxCalendarNameStr);
 284
 285     /**
 286         Destroys the control.
 287     */
 288     ~wxCalendarCtrl();
 289
 290     /**
 291         Creates the control. See wxWindow::wxWindow() for the meaning of the
 292         parameters and the control overview for the possible styles.
 293     */
 294     bool Create(wxWindow* parent, wxWindowID id,
 295                 const wxDateTime& date = wxDefaultDateTime,
 296                 const wxPoint& pos = wxDefaultPosition,
 297                 const wxSize& size = wxDefaultSize,
 298                 long style = wxCAL_SHOW_HOLIDAYS,
 299                 const wxString& name = wxCalendarNameStr);
 300
 301     /**
 302         This function should be used instead of changing @c wxCAL_SHOW_HOLIDAYS
 303         style bit directly. It enables or disables the special highlighting of
 304         the holidays.
 305     */
 306     void EnableHolidayDisplay(bool display = true);
 307
 308     /**
 309         This function should be used instead of changing
 310         @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to
 311         change the month interactively. Note that if the month can not be
 312         changed, the year can not be changed neither.
 313
 314         @return @true if the value of this option really changed or @false if
 315                 it was already set to the requested value.
 316     */
 317     bool EnableMonthChange(bool enable = true);
 318
 319     /**
 320         @deprecated
 321
 322         This function should be used instead of changing
 323         @c wxCAL_NO_YEAR_CHANGE style bit directly. It allows or disallows the
 324         user to change the year interactively. Only in generic wxCalendarCtrl.
 325     */
 326     void EnableYearChange(bool enable = true);
 327
 328     /**
 329         Returns the attribute for the given date (should be in the range
 330         1...31). The returned pointer may be @NULL. Only in generic
 331         wxCalendarCtrl.
 332     */
 333     wxCalendarDateAttr* GetAttr(size_t day) const;
 334
 335     /**
 336         Gets the currently selected date.
 337     */
 338     const wxDateTime GetDate() const;
 339
 340     /**
 341         Gets the background colour of the header part of the calendar window.
 342
 343         This method is currently only implemented in generic wxCalendarCtrl and
 344         always returns @c wxNullColour in the native versions.
 345
 346         @see SetHeaderColours()
 347     */
 348     const wxColour GetHeaderColourBg() const;
 349
 350     /**
 351         Gets the foreground colour of the header part of the calendar window.
 352
 353         This method is currently only implemented in generic wxCalendarCtrl and
 354         always returns @c wxNullColour in the native versions.
 355
 356         @see SetHeaderColours()
 357     */
 358     const wxColour GetHeaderColourFg() const;
 359
 360     /**
 361         Gets the background highlight colour. Only in generic wxCalendarCtrl.
 362
 363         This method is currently only implemented in generic wxCalendarCtrl and
 364         always returns @c wxNullColour in the native versions.
 365
 366         @see SetHighlightColours()
 367     */
 368     const wxColour GetHighlightColourBg() const;
 369
 370     /**
 371         Gets the foreground highlight colour. Only in generic wxCalendarCtrl.
 372
 373         This method is currently only implemented in generic wxCalendarCtrl and
 374         always returns @c wxNullColour in the native versions.
 375
 376         @see SetHighlightColours()
 377     */
 378     const wxColour GetHighlightColourFg() const;
 379
 380     /**
 381         Return the background colour currently used for holiday highlighting.
 382
 383         Only useful with generic wxCalendarCtrl as native versions currently
 384         don't support holidays display at all and always return
 385         @c wxNullColour.
 386
 387         @see SetHolidayColours()
 388     */
 389     const wxColour GetHolidayColourBg() const;
 390
 391     /**
 392         Return the foreground colour currently used for holiday highlighting.
 393
 394         Only useful with generic wxCalendarCtrl as native versions currently
 395         don't support holidays display at all and always return
 396         @c wxNullColour.
 397
 398         @see SetHolidayColours()
 399     */
 400     const wxColour GetHolidayColourFg() const;
 401
 402     /**
 403         Returns one of wxCalendarHitTestResult constants and fills either
 404         @a date or @a wd pointer with the corresponding value depending on the
 405         hit test code.
 406
 407         Not implemented in wxGTK currently.
 408     */
 409     wxCalendarHitTestResult HitTest(const wxPoint& pos,
 410                                     wxDateTime* date = NULL,
 411                                     wxDateTime::WeekDay* wd = NULL);
 412
 413     /**
 414         Clears any attributes associated with the given day (in the range
 415         1...31). Only in generic wxCalendarCtrl.
 416     */
 417     void ResetAttr(size_t day);
 418
 419     /**
 420         Associates the attribute with the specified date (in the range 1...31).
 421         If the pointer is @NULL, the items attribute is cleared. Only in
 422         generic wxCalendarCtrl.
 423     */
 424     void SetAttr(size_t day, wxCalendarDateAttr* attr);
 425
 426     /**
 427         Sets the current date.
 428
 429         The @a date parameter must be valid.
 430     */
 431     void SetDate(const wxDateTime& date);
 432
 433     /**
 434         Set the colours used for painting the weekdays at the top of the
 435         control.
 436
 437         This method is currently only implemented in generic wxCalendarCtrl and
 438         does nothing in the native versions.
 439     */
 440     void SetHeaderColours(const wxColour& colFg,
 441                           const wxColour& colBg);
 442
 443     /**
 444         Set the colours to be used for highlighting the currently selected
 445         date.
 446
 447         This method is currently only implemented in generic wxCalendarCtrl and
 448         does nothing in the native versions.
 449     */
 450     void SetHighlightColours(const wxColour& colFg,
 451                              const wxColour& colBg);
 452
 453     /**
 454         Marks the specified day as being a holiday in the current month.
 455
 456         This method is only implemented in the generic version of the control
 457         and does nothing in the native ones.
 458     */
 459     void SetHoliday(size_t day);
 460
 461     /**
 462         Sets the colours to be used for the holidays highlighting.
 463
 464         This method is only implemented in the generic version of the control
 465         and does nothing in the native ones. It should also only be called if
 466         the window style includes @c wxCAL_SHOW_HOLIDAYS flag or
 467         EnableHolidayDisplay() had been called.
 468
 469     */
 470     void SetHolidayColours(const wxColour& colFg,
 471                            const wxColour& colBg);
 472
 473     /**
 474         Mark or unmark the day. This day of month will be marked in every
 475         month. In generic wxCalendarCtrl,
 476     */
 477     void Mark(size_t day, bool mark);
 478
 479     /**
 480         @name Date Range Functions
 481
 482         The functions in this section are currently implemented in the generic
 483         and MSW versions and do nothing in the native GTK implementation.
 484      */
 485     //@{
 486
 487     /**
 488         Restrict the dates shown by the control to the specified range.
 489
 490         If either date is set, the corresponding limit will be enforced and
 491         @true returned. If none are set, the existing restrictions are removed
 492         and @false is returned.
 493
 494         @see GetDateRange()
 495
 496         @param lowerdate
 497             The low limit for the dates shown by the control or
 498             @c wxDefaultDateTime.
 499         @param highlighting
 500             The high limit for the dates shown by the control or
 501             @c wxDefaultDateTime.
 502         @return
 503             @true if either limit is valid, @false otherwise
 504      */
 505     virtual bool SetDateRange(const wxDateTime& lowerdate = wxDefaultDateTime,
 506                                 const wxDateTime& upperdate = wxDefaultDateTime);
 507
 508     /**
 509         Returns the limits currently being used.
 510
 511         @see SetDateRange()
 512
 513         @param lowerdate
 514             If non-@NULL, the value of the low limit for the dates shown by the
 515             control is returned (which may be @c wxDefaultDateTime if no limit
 516             is set).
 517         @param upperdate
 518             If non-@NULL, the value of the upper limit for the dates shown by
 519             the control is returned (which may be @c wxDefaultDateTime if no
 520             limit is set).
 521         @return
 522             @true if either limit is set, @false otherwise
 523      */
 524     virtual bool GetDateRange(wxDateTime *lowerdate,
 525                                 wxDateTime *upperdate) const;
 526
 527     //@}
 528 };
 529