interface/wx/calctrl.h

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