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