interface/wx/calctrl.h

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