interface/calctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        calctrl.h
   3 // Purpose:     documentation for wxCalendarEvent class
   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     @seealso
  20     wxCalendarCtrl
  21 */
  22 class wxCalendarEvent : public wxDateEvent
  23 {
  24 public:
  25     /**
  26         Returns the week day on which the user clicked in
  27         @c EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call
  28         this function in other handlers.
  29     */
  30     wxDateTime::WeekDay GetWeekDay();
  31
  32     /**
  33         Sets the week day carried by the event, normally only used by the library
  34         internally.
  35     */
  36     void SetWeekDay(wxDateTime::WeekDay day);
  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     @seealso
  51     wxCalendarCtrl
  52 */
  53 class wxCalendarDateAttr
  54 {
  55 public:
  56     //@{
  57     /**
  58         The constructors.
  59     */
  60     wxCalendarDateAttr();
  61     wxCalendarDateAttr(const wxColour& colText,
  62                        const wxColour& colBack = wxNullColour,
  63                        const wxColour& colBorder = wxNullColour,
  64                        const wxFont& font = wxNullFont,
  65                        wxCalendarDateBorder border = wxCAL_BORDER_NONE);
  66     wxCalendarDateAttr(wxCalendarDateBorder border,
  67                        const wxColour& colBorder = wxNullColour);
  68     //@}
  69
  70     /**
  71         Returns the background colour to use for the item with this attribute.
  72     */
  73     const wxColour GetBackgroundColour();
  74
  75     /**
  76         Returns the border to use for the item with this attribute.
  77     */
  78     wxCalendarDateBorder GetBorder();
  79
  80     /**
  81         Returns the border colour to use for the item with this attribute.
  82     */
  83     const wxColour GetBorderColour();
  84
  85     /**
  86         Returns the font to use for the item with this attribute.
  87     */
  88     const wxFont GetFont();
  89
  90     /**
  91         Returns the text colour to use for the item with this attribute.
  92     */
  93     const wxColour GetTextColour();
  94
  95     /**
  96         Returns @true if this attribute specifies a non-default text background
  97         colour.
  98     */
  99     bool HasBackgroundColour();
 100
 101     /**
 102         Returns @true if this attribute specifies a non-default (i.e. any) border.
 103     */
 104     bool HasBorder();
 105
 106     /**
 107         Returns @true if this attribute specifies a non-default border colour.
 108     */
 109     bool HasBorderColour();
 110
 111     /**
 112         Returns @true if this attribute specifies a non-default font.
 113     */
 114     bool HasFont();
 115
 116     /**
 117         Returns @true if this item has a non-default text foreground colour.
 118     */
 119     bool HasTextColour();
 120
 121     /**
 122         Returns @true if this attribute specifies that this item should be
 123         displayed as a holiday.
 124     */
 125     bool IsHoliday();
 126
 127     /**
 128         Sets the text background colour to use.
 129     */
 130     void SetBackgroundColour(const wxColour& colBack);
 131
 132     /**
 133         Sets the @ref overview_wxcalendardateattr "border kind"
 134     */
 135     void SetBorder(wxCalendarDateBorder border);
 136
 137     /**
 138         Sets the border colour to use.
 139     */
 140     void SetBorderColour(const wxColour& col);
 141
 142     /**
 143         Sets the font to use.
 144     */
 145     void SetFont(const wxFont& font);
 146
 147     /**
 148         Display the date with this attribute as a holiday.
 149     */
 150     void SetHoliday(bool holiday);
 151
 152     /**
 153         Sets the text (foreground) colour to use.
 154     */
 155     void SetTextColour(const wxColour& colText);
 156 };
 157
 158
 159 /**
 160     @class wxCalendarCtrl
 161     @wxheader{calctrl.h}
 162
 163     The calendar control allows the user to pick a date. For this,
 164     it displays a window containing several parts: a control at the top to pick the
 165     month
 166     and the year (either or both of them may be disabled), and a month
 167     area below them which shows all the days in the month. The user can move the
 168     current selection using the keyboard and select the date (generating
 169     @c EVT_CALENDAR event) by pressing @c Return or double clicking it.
 170
 171     It has advanced possibilities for the customization of its display. All global
 172     settings (such as colours and fonts used) can, of course, be changed. But
 173     also, the display style for each day in the month can be set independently
 174     using wxCalendarDateAttr class.
 175
 176     An item without custom attributes is drawn with the default colours and
 177     font and without border, but setting custom attributes with
 178     wxCalendarCtrl::SetAttr allows to modify its appearance. Just
 179     create a custom attribute object and set it for the day you want to be
 180     displayed specially (note that the control will take ownership of the pointer,
 181     i.e. it will delete it itself). A day may be marked as being a holiday, even
 182     if it is not recognized as one by wxDateTime using
 183     wxCalendarDateAttr::SetHoliday method.
 184
 185     As the attributes are specified for each day, they may change when the month
 186     is changed, so you will often want to update them in
 187     @c EVT_CALENDAR_MONTH event handler.
 188
 189     @beginStyleTable
 190     @style{wxCAL_SUNDAY_FIRST}:
 191            Show Sunday as the first day in the week
 192     @style{wxCAL_MONDAY_FIRST}:
 193            Show Monday as the first day in the week
 194     @style{wxCAL_SHOW_HOLIDAYS}:
 195            Highlight holidays in the calendar
 196     @style{wxCAL_NO_YEAR_CHANGE}:
 197            Disable the year changing
 198     @style{wxCAL_NO_MONTH_CHANGE}:
 199            Disable the month (and, implicitly, the year) changing
 200     @style{wxCAL_SHOW_SURROUNDING_WEEKS}:
 201            Show the neighbouring weeks in the previous and next months
 202     @style{wxCAL_SEQUENTIAL_MONTH_SELECTION}:
 203            Use alternative, more compact, style for the month and year
 204            selection controls.
 205     @endStyleTable
 206
 207     @library{wxadv}
 208     @category{ctrl}
 209     @appearance{calendarctrl.png}
 210
 211     @seealso
 212     @ref overview_samplecalendar "Calendar sample", wxCalendarDateAttr,
 213     wxCalendarEvent
 214 */
 215 class wxCalendarCtrl : public wxControl
 216 {
 217 public:
 218     //@{
 219     /**
 220         Does the same as Create() method.
 221     */
 222     wxCalendarCtrl();
 223     wxCalendarCtrl(wxWindow* parent, wxWindowID id,
 224                    const wxDateTime& date = wxDefaultDateTime,
 225                    const wxPoint& pos = wxDefaultPosition,
 226                    const wxSize& size = wxDefaultSize,
 227                    long style = wxCAL_SHOW_HOLIDAYS,
 228                    const wxString& name = wxCalendarNameStr);
 229     //@}
 230
 231     /**
 232         Destroys the control.
 233     */
 234     ~wxCalendarCtrl();
 235
 236     /**
 237         Creates the control. See @ref wxWindow::ctor wxWindow for the meaning of
 238         the parameters and the control overview for the possible styles.
 239     */
 240     bool Create(wxWindow* parent, wxWindowID id,
 241                 const wxDateTime& date = wxDefaultDateTime,
 242                 const wxPoint& pos = wxDefaultPosition,
 243                 const wxSize& size = wxDefaultSize,
 244                 long style = wxCAL_SHOW_HOLIDAYS,
 245                 const wxString& name = wxCalendarNameStr);
 246
 247     /**
 248         This function should be used instead of changing @c wxCAL_SHOW_HOLIDAYS
 249         style bit directly. It enables or disables the special highlighting of the
 250         holidays.
 251     */
 252     void EnableHolidayDisplay(bool display = @true);
 253
 254     /**
 255         This function should be used instead of changing
 256         @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to
 257         change the month interactively. Note that if the month can not be changed, the
 258         year can not be changed neither.
 259     */
 260     void EnableMonthChange(bool enable = @true);
 261
 262     /**
 263         This function should be used instead of changing @c wxCAL_NO_YEAR_CHANGE
 264         style bit directly. It allows or disallows the user to change the year
 265         interactively.
 266     */
 267     void EnableYearChange(bool enable = @true);
 268
 269     /**
 270         Returns the attribute for the given date (should be in the range 1...31).
 271
 272         The returned pointer may be @NULL.
 273     */
 274     wxCalendarDateAttr * GetAttr(size_t day);
 275
 276     /**
 277         Gets the currently selected date.
 278     */
 279     const wxDateTime GetDate();
 280
 281     /**
 282         Gets the background colour of the header part of the calendar window.
 283
 284         @sa SetHeaderColours()
 285     */
 286     const wxColour GetHeaderColourBg();
 287
 288     /**
 289         Gets the foreground colour of the header part of the calendar window.
 290
 291         @sa SetHeaderColours()
 292     */
 293     const wxColour GetHeaderColourFg();
 294
 295     /**
 296         Gets the background highlight colour.
 297
 298         @sa SetHighlightColours()
 299     */
 300     const wxColour GetHighlightColourBg();
 301
 302     /**
 303         Gets the foreground highlight colour.
 304
 305         @sa SetHighlightColours()
 306     */
 307     const wxColour GetHighlightColourFg();
 308
 309     /**
 310         Return the background colour currently used for holiday highlighting.
 311
 312         @sa SetHolidayColours()
 313     */
 314     const wxColour GetHolidayColourBg();
 315
 316     /**
 317         Return the foreground colour currently used for holiday highlighting.
 318
 319         @sa SetHolidayColours()
 320     */
 321     const wxColour GetHolidayColourFg();
 322
 323     /**
 324         Returns one of @c wxCAL_HITTEST_XXX
 325         constants and fills either @e date or
 326         @e wd pointer with the corresponding value depending on the hit test code.
 327     */
 328     wxCalendarHitTestResult HitTest(const wxPoint& pos,
 329                                     wxDateTime* date = @NULL,
 330                                     wxDateTime::WeekDay* wd = @NULL);
 331
 332     /**
 333         Clears any attributes associated with the given day (in the range
 334         1...31).
 335     */
 336     void ResetAttr(size_t day);
 337
 338     /**
 339         Associates the attribute with the specified date (in the range 1...31).
 340
 341         If the pointer is @NULL, the items attribute is cleared.
 342     */
 343     void SetAttr(size_t day, wxCalendarDateAttr* attr);
 344
 345     /**
 346         Sets the current date.
 347     */
 348     void SetDate(const wxDateTime& date);
 349
 350     /**
 351         Set the colours used for painting the weekdays at the top of the control.
 352     */
 353     void SetHeaderColours(const wxColour& colFg,
 354                           const wxColour& colBg);
 355
 356     /**
 357         Set the colours to be used for highlighting the currently selected date.
 358     */
 359     void SetHighlightColours(const wxColour& colFg,
 360                              const wxColour& colBg);
 361
 362     /**
 363         Marks the specified day as being a holiday in the current month.
 364     */
 365     void SetHoliday(size_t day);
 366
 367     /**
 368         Sets the colours to be used for the holidays highlighting (only used if the
 369         window style includes @c wxCAL_SHOW_HOLIDAYS flag).
 370     */
 371     void SetHolidayColours(const wxColour& colFg,
 372                            const wxColour& colBg);
 373 };