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 license
   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{misc}
  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 };
 187
 188 /**
 189     @class wxCalendarCtrl
 190
 191     The calendar control allows the user to pick a date.  The user can move the
 192     current selection using the keyboard and select the date (generating
 193     @c EVT_CALENDAR event) by pressing @c @<Return@> or double clicking it.
 194
 195     Generic calendar has advanced possibilities for the customization of its
 196     display, described below. If you want to use these possibilities on every
 197     platform, use wxGenericCalendarCtrl instead of wxCalendarCtrl.
 198
 199     All global settings (such as colours and fonts used) can, of course, be
 200     changed. But also, the display style for each day in the month can be set
 201     independently using wxCalendarDateAttr class.
 202
 203     An item without custom attributes is drawn with the default colours and
 204     font and without border, but setting custom attributes with SetAttr()
 205     allows to modify its appearance. Just create a custom attribute object and
 206     set it for the day you want to be displayed specially (note that the
 207     control will take ownership of the pointer, i.e. it will delete it itself).
 208     A day may be marked as being a holiday, even if it is not recognized as
 209     one by wxDateTime using the wxCalendarDateAttr::SetHoliday() method.
 210
 211     As the attributes are specified for each day, they may change when the
 212     month is changed, so you will often want to update them in
 213     @c EVT_CALENDAR_PAGE_CHANGED event handler.
 214
 215     @beginStyleTable
 216     @style{wxCAL_SUNDAY_FIRST}
 217            Show Sunday as the first day in the week (not in wxGTK)
 218     @style{wxCAL_MONDAY_FIRST}
 219            Show Monday as the first day in the week (not in wxGTK)
 220     @style{wxCAL_SHOW_HOLIDAYS}
 221            Highlight holidays in the calendar (only generic)
 222     @style{wxCAL_NO_YEAR_CHANGE}
 223            Disable the year changing (deprecated, only generic)
 224     @style{wxCAL_NO_MONTH_CHANGE}
 225            Disable the month (and, implicitly, the year) changing
 226     @style{wxCAL_SHOW_SURROUNDING_WEEKS}
 227            Show the neighbouring weeks in the previous and next months
 228            (only generic, always on for the native controls)
 229     @style{wxCAL_SEQUENTIAL_MONTH_SELECTION}
 230            Use alternative, more compact, style for the month and year
 231            selection controls. (only generic)
 232     @style{wxCAL_SHOW_WEEK_NUMBERS}
 233            Show week numbers on the left side of the calendar. (not in generic)
 234     @endStyleTable
 235
 236     @beginEventTable{wxCalendarEvent}
 237     @event{EVT_CALENDAR(id, func)}
 238            A day was double clicked in the calendar.
 239     @event{EVT_CALENDAR_SEL_CHANGED(id, func)}
 240            The selected date changed.
 241     @event{EVT_CALENDAR_PAGE_CHANGED(id, func)}
 242            The selected month (and/or year) changed.
 243     @event{EVT_CALENDAR_WEEKDAY_CLICKED(id, func)}
 244            User clicked on the week day header (only generic).
 245     @endEventTable
 246
 247     @note Changing the selected date will trigger an EVT_CALENDAR_DAY, MONTH or
 248           YEAR event as well as an EVT_CALENDAR_SEL_CHANGED event.
 249
 250     @library{wxadv}
 251     @category{ctrl}
 252     @appearance{calendarctrl.png}
 253
 254     @nativeimpl{wxgtk,wxmsw}
 255
 256     @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent,
 257          wxDatePickerCtrl
 258 */
 259 class wxCalendarCtrl : public wxControl
 260 {
 261 public:
 262     /**
 263         Default constructor.
 264     */
 265     wxCalendarCtrl();
 266
 267     /**
 268         Does the same as Create() method.
 269     */
 270     wxCalendarCtrl(wxWindow* parent, wxWindowID id,
 271                    const wxDateTime& date = wxDefaultDateTime,
 272                    const wxPoint& pos = wxDefaultPosition,
 273                    const wxSize& size = wxDefaultSize,
 274                    long style = wxCAL_SHOW_HOLIDAYS,
 275                    const wxString& name = wxCalendarNameStr);
 276
 277     /**
 278         Destroys the control.
 279     */
 280     ~wxCalendarCtrl();
 281
 282     /**
 283         Creates the control. See wxWindow::wxWindow() for the meaning of the
 284         parameters and the control overview for the possible styles.
 285     */
 286     bool Create(wxWindow* parent, wxWindowID id,
 287                 const wxDateTime& date = wxDefaultDateTime,
 288                 const wxPoint& pos = wxDefaultPosition,
 289                 const wxSize& size = wxDefaultSize,
 290                 long style = wxCAL_SHOW_HOLIDAYS,
 291                 const wxString& name = wxCalendarNameStr);
 292
 293     /**
 294         This function should be used instead of changing @c wxCAL_SHOW_HOLIDAYS
 295         style bit directly. It enables or disables the special highlighting of
 296         the holidays.
 297     */
 298     virtual void EnableHolidayDisplay(bool display = true);
 299
 300     /**
 301         This function should be used instead of changing
 302         @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to
 303         change the month interactively. Note that if the month can not be
 304         changed, the year can not be changed neither.
 305
 306         @return @true if the value of this option really changed or @false if
 307                 it was already set to the requested value.
 308     */
 309     virtual bool EnableMonthChange(bool enable = true);
 310
 311     /**
 312         @deprecated
 313
 314         This function should be used instead of changing
 315         @c wxCAL_NO_YEAR_CHANGE style bit directly. It allows or disallows the
 316         user to change the year interactively. Only in generic wxCalendarCtrl.
 317     */
 318     virtual void EnableYearChange(bool enable = true);
 319
 320     /**
 321         Returns the attribute for the given date (should be in the range
 322         1...31). The returned pointer may be @NULL. Only in generic
 323         wxCalendarCtrl.
 324     */
 325     virtual wxCalendarDateAttr* GetAttr(size_t day) const;
 326
 327     /**
 328         Gets the currently selected date.
 329     */
 330     virtual wxDateTime GetDate() const;
 331
 332     /**
 333         Gets the background colour of the header part of the calendar window.
 334
 335         This method is currently only implemented in generic wxCalendarCtrl and
 336         always returns @c wxNullColour in the native versions.
 337
 338         @see SetHeaderColours()
 339     */
 340     virtual const wxColour& GetHeaderColourBg() const;
 341
 342     /**
 343         Gets the foreground colour of the header part of the calendar window.
 344
 345         This method is currently only implemented in generic wxCalendarCtrl and
 346         always returns @c wxNullColour in the native versions.
 347
 348         @see SetHeaderColours()
 349     */
 350     virtual const wxColour& GetHeaderColourFg() const;
 351
 352     /**
 353         Gets the background highlight colour. Only in generic wxCalendarCtrl.
 354
 355         This method is currently only implemented in generic wxCalendarCtrl and
 356         always returns @c wxNullColour in the native versions.
 357
 358         @see SetHighlightColours()
 359     */
 360     virtual const wxColour& GetHighlightColourBg() const;
 361
 362     /**
 363         Gets the foreground highlight colour. Only in generic wxCalendarCtrl.
 364
 365         This method is currently only implemented in generic wxCalendarCtrl and
 366         always returns @c wxNullColour in the native versions.
 367
 368         @see SetHighlightColours()
 369     */
 370     virtual const wxColour& GetHighlightColourFg() const;
 371
 372     /**
 373         Return the background colour currently used for holiday highlighting.
 374
 375         Only useful with generic wxCalendarCtrl as native versions currently
 376         don't support holidays display at all and always return
 377         @c wxNullColour.
 378
 379         @see SetHolidayColours()
 380     */
 381     virtual const wxColour& GetHolidayColourBg() const;
 382
 383     /**
 384         Return the foreground colour currently used for holiday highlighting.
 385
 386         Only useful with generic wxCalendarCtrl as native versions currently
 387         don't support holidays display at all and always return
 388         @c wxNullColour.
 389
 390         @see SetHolidayColours()
 391     */
 392     virtual const wxColour& GetHolidayColourFg() const;
 393
 394     /**
 395         Returns one of wxCalendarHitTestResult constants and fills either
 396         @a date or @a wd pointer with the corresponding value depending on the
 397         hit test code.
 398
 399         Not implemented in wxGTK currently.
 400     */
 401     virtual wxCalendarHitTestResult HitTest(const wxPoint& pos,
 402                                             wxDateTime* date = NULL,
 403                                             wxDateTime::WeekDay* wd = NULL);
 404
 405     /**
 406         Clears any attributes associated with the given day (in the range
 407         1...31). Only in generic wxCalendarCtrl.
 408     */
 409     virtual void ResetAttr(size_t day);
 410
 411     /**
 412         Associates the attribute with the specified date (in the range 1...31).
 413         If the pointer is @NULL, the items attribute is cleared. Only in
 414         generic wxCalendarCtrl.
 415     */
 416     virtual void SetAttr(size_t day, wxCalendarDateAttr* attr);
 417
 418     /**
 419         Sets the current date.
 420
 421         The @a date parameter must be valid.
 422     */
 423     virtual bool SetDate(const wxDateTime& date);
 424
 425     /**
 426         Set the colours used for painting the weekdays at the top of the
 427         control.
 428
 429         This method is currently only implemented in generic wxCalendarCtrl and
 430         does nothing in the native versions.
 431     */
 432     virtual void SetHeaderColours(const wxColour& colFg,
 433                                   const wxColour& colBg);
 434
 435     /**
 436         Set the colours to be used for highlighting the currently selected
 437         date.
 438
 439         This method is currently only implemented in generic wxCalendarCtrl and
 440         does nothing in the native versions.
 441     */
 442     virtual void SetHighlightColours(const wxColour& colFg,
 443                                      const wxColour& colBg);
 444
 445     /**
 446         Marks the specified day as being a holiday in the current month.
 447
 448         This method is only implemented in the generic version of the control
 449         and does nothing in the native ones.
 450     */
 451     virtual void SetHoliday(size_t day);
 452
 453     /**
 454         Sets the colours to be used for the holidays highlighting.
 455
 456         This method is only implemented in the generic version of the control
 457         and does nothing in the native ones. It should also only be called if
 458         the window style includes @c wxCAL_SHOW_HOLIDAYS flag or
 459         EnableHolidayDisplay() had been called.
 460
 461     */
 462     virtual void SetHolidayColours(const wxColour& colFg,
 463                                    const wxColour& colBg);
 464
 465     /**
 466         Mark or unmark the day. This day of month will be marked in every
 467         month. In generic wxCalendarCtrl,
 468     */
 469     virtual void Mark(size_t day, bool mark);
 470
 471     /**
 472         @name Date Range Functions
 473
 474         The functions in this section are currently implemented in the generic
 475         and MSW versions and do nothing in the native GTK implementation.
 476      */
 477     //@{
 478
 479     /**
 480         Restrict the dates shown by the control to the specified range.
 481
 482         If either date is set, the corresponding limit will be enforced and
 483         @true returned. If none are set, the existing restrictions are removed
 484         and @false is returned.
 485
 486         @see GetDateRange()
 487
 488         @param lowerdate
 489             The low limit for the dates shown by the control or
 490             @c wxDefaultDateTime.
 491         @param upperdate
 492             The high limit for the dates shown by the control or
 493             @c wxDefaultDateTime.
 494         @return
 495             @true if either limit is valid, @false otherwise
 496      */
 497     virtual bool SetDateRange(const wxDateTime& lowerdate = wxDefaultDateTime,
 498                                 const wxDateTime& upperdate = wxDefaultDateTime);
 499
 500     /**
 501         Returns the limits currently being used.
 502
 503         @see SetDateRange()
 504
 505         @param lowerdate
 506             If non-@NULL, the value of the low limit for the dates shown by the
 507             control is returned (which may be @c wxDefaultDateTime if no limit
 508             is set).
 509         @param upperdate
 510             If non-@NULL, the value of the upper limit for the dates shown by
 511             the control is returned (which may be @c wxDefaultDateTime if no
 512             limit is set).
 513         @return
 514             @true if either limit is set, @false otherwise
 515      */
 516     virtual bool GetDateRange(wxDateTime *lowerdate,
 517                                 wxDateTime *upperdate) const;
 518
 519     //@}
 520 };
 521