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