interface/calctrl.h

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