]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/calctrl.h
say that use of _T() is discouraged in new code, just like wxT() is
[wxWidgets.git] / interface / wx / calctrl.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: calctrl.h
49d37022 3// Purpose: interface of wxCalendarCtrl
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxCalendarEvent
7c913512 11
49d37022 12 The wxCalendarEvent class is used together with wxCalendarCtrl.
7c913512 13
23324ae1
FM
14 @library{wxadv}
15 @category{events}
7c913512 16
e54c96f1 17 @see wxCalendarCtrl
23324ae1
FM
18*/
19class wxCalendarEvent : public wxDateEvent
20{
21public:
22 /**
7c913512 23 Returns the week day on which the user clicked in
23324ae1
FM
24 @c EVT_CALENDAR_WEEKDAY_CLICKED handler. It doesn't make sense to call
25 this function in other handlers.
26 */
328f5751 27 wxDateTime::WeekDay GetWeekDay() const;
23324ae1
FM
28
29 /**
49d37022
BP
30 Sets the week day carried by the event, normally only used by the
31 library internally.
23324ae1 32 */
9d9c1c24 33 void SetWeekDay(const wxDateTime::WeekDay day);
23324ae1
FM
34};
35
36
e54c96f1 37
49d37022
BP
38/**
39 Possible kinds of borders which may be used to decorate a date using
40 wxCalendarDateAttr.
41*/
42enum wxCalendarDateBorder
43{
44 wxCAL_BORDER_NONE, ///< No Border (Default)
45 wxCAL_BORDER_SQUARE, ///< Rectangular Border
46 wxCAL_BORDER_ROUND ///< Round Border
47};
48
23324ae1
FM
49/**
50 @class wxCalendarDateAttr
7c913512 51
49d37022
BP
52 wxCalendarDateAttr is a custom attributes for a calendar date. The objects
53 of this class are used with wxCalendarCtrl.
7c913512 54
23324ae1
FM
55 @library{wxadv}
56 @category{misc}
7c913512 57
e54c96f1 58 @see wxCalendarCtrl
23324ae1 59*/
7c913512 60class wxCalendarDateAttr
23324ae1
FM
61{
62public:
49d37022
BP
63 /**
64 Constructor for specifying all wxCalendarDateAttr properties.
65 */
9d9c1c24 66 wxCalendarDateAttr(const wxColour& colText = wxNullColour,
7c913512
FM
67 const wxColour& colBack = wxNullColour,
68 const wxColour& colBorder = wxNullColour,
69 const wxFont& font = wxNullFont,
70 wxCalendarDateBorder border = wxCAL_BORDER_NONE);
49d37022
BP
71
72 /**
73 Constructor using default properties except the given border.
74 */
7c913512
FM
75 wxCalendarDateAttr(wxCalendarDateBorder border,
76 const wxColour& colBorder = wxNullColour);
23324ae1
FM
77
78 /**
49d37022 79 Returns the background colour set for the calendar date.
23324ae1 80 */
9d9c1c24 81 const wxColour& GetBackgroundColour() const;
23324ae1
FM
82
83 /**
49d37022 84 Returns the border set for the calendar date.
23324ae1 85 */
328f5751 86 wxCalendarDateBorder GetBorder() const;
23324ae1
FM
87
88 /**
49d37022 89 Returns the border colour set for the calendar date.
23324ae1 90 */
9d9c1c24 91 const wxColour& GetBorderColour() const;
23324ae1
FM
92
93 /**
49d37022 94 Returns the font set for the calendar date.
23324ae1 95 */
9d9c1c24 96 const wxFont& GetFont() const;
23324ae1
FM
97
98 /**
49d37022 99 Returns the text colour set for the calendar date.
23324ae1 100 */
9d9c1c24 101 const wxColour& GetTextColour() const;
23324ae1
FM
102
103 /**
49d37022 104 Returns @true if a non-default text background colour is set.
23324ae1 105 */
328f5751 106 bool HasBackgroundColour() const;
23324ae1
FM
107
108 /**
49d37022 109 Returns @true if a non-default (i.e. any) border is set.
23324ae1 110 */
328f5751 111 bool HasBorder() const;
23324ae1
FM
112
113 /**
49d37022 114 Returns @true if a non-default border colour is set.
23324ae1 115 */
328f5751 116 bool HasBorderColour() const;
23324ae1
FM
117
118 /**
49d37022 119 Returns @true if a non-default font is set.
23324ae1 120 */
328f5751 121 bool HasFont() const;
23324ae1
FM
122
123 /**
49d37022 124 Returns @true if a non-default text foreground colour is set.
23324ae1 125 */
328f5751 126 bool HasTextColour() const;
23324ae1
FM
127
128 /**
49d37022 129 Returns @true if this calendar day is displayed as a holiday.
23324ae1 130 */
328f5751 131 bool IsHoliday() const;
23324ae1
FM
132
133 /**
134 Sets the text background colour to use.
135 */
136 void SetBackgroundColour(const wxColour& colBack);
137
138 /**
49d37022 139 Sets the border to use.
23324ae1
FM
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 /**
49d37022
BP
154 If @a holiday is @true, this calendar day will be displayed as a
155 holiday.
23324ae1
FM
156 */
157 void SetHoliday(bool holiday);
158
159 /**
160 Sets the text (foreground) colour to use.
161 */
162 void SetTextColour(const wxColour& colText);
628e155d
VZ
163
164 /**
49d37022 165 Used (internally) by the generic wxCalendarCtrl::Mark().
628e155d
VZ
166 */
167 static const wxCalendarDateAttr& GetMark();
168
169 /**
49d37022
BP
170 Set the attributes that will be used to Mark() days on the generic
171 wxCalendarCtrl.
628e155d
VZ
172 */
173 static void SetMark(wxCalendarDateAttr const& m);
23324ae1
FM
174};
175
176
e54c96f1 177
49d37022
BP
178/**
179 Possible return values from wxCalendarCtrl::HitTest().
180*/
181enum wxCalendarHitTestResult
182{
183 wxCAL_HITTEST_NOWHERE, ///< Hit outside of anything.
184 wxCAL_HITTEST_HEADER, ///< Hit on the header (weekdays).
232b2162
VZ
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).
49d37022
BP
190};
191
23324ae1
FM
192/**
193 @class wxCalendarCtrl
7c913512 194
628e155d 195 The calendar control allows the user to pick a date. The user can move the
7c913512 196 current selection using the keyboard and select the date (generating
49d37022 197 @c EVT_CALENDAR event) by pressing @c @<Return@> or double clicking it.
7c913512 198
628e155d 199 Generic calendar has advanced possibilities for the customization of its
49d37022
BP
200 display, described below. If you want to use these possibilities on every
201 platform, use wxGenericCalendarCtrl instead of wxCalendarCtrl.
628e155d 202
49d37022
BP
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.
7c913512 206
23324ae1 207 An item without custom attributes is drawn with the default colours and
49d37022
BP
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).
628e155d 212 A day may be marked as being a holiday, even if it is not recognized as
49d37022 213 one by wxDateTime using the wxCalendarDateAttr::SetHoliday() method.
7c913512 214
49d37022
BP
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
628e155d 217 @c EVT_CALENDAR_PAGE_CHANGED event handler.
7c913512 218
23324ae1 219 @beginStyleTable
8c6791e4 220 @style{wxCAL_SUNDAY_FIRST}
db0b0942 221 Show Sunday as the first day in the week (not in wxGTK)
8c6791e4 222 @style{wxCAL_MONDAY_FIRST}
db0b0942 223 Show Monday as the first day in the week (not in wxGTK)
8c6791e4 224 @style{wxCAL_SHOW_HOLIDAYS}
628e155d 225 Highlight holidays in the calendar (only generic)
8c6791e4 226 @style{wxCAL_NO_YEAR_CHANGE}
628e155d 227 Disable the year changing (deprecated, only generic)
8c6791e4 228 @style{wxCAL_NO_MONTH_CHANGE}
23324ae1 229 Disable the month (and, implicitly, the year) changing
8c6791e4 230 @style{wxCAL_SHOW_SURROUNDING_WEEKS}
23324ae1 231 Show the neighbouring weeks in the previous and next months
db0b0942 232 (only generic, always on for the native controls)
8c6791e4 233 @style{wxCAL_SEQUENTIAL_MONTH_SELECTION}
23324ae1 234 Use alternative, more compact, style for the month and year
628e155d 235 selection controls. (only generic)
7b0ccb8a
RR
236 @style{wxCAL_SHOW_WEEK_NUMBERS}
237 Show week numbers on the left side of the calendar. (not in generic)
23324ae1 238 @endStyleTable
7c913512 239
1f1d2182 240 @beginEventTable{wxCalendarEvent}
8c6791e4 241 @event{EVT_CALENDAR(id, func)}
628e155d 242 A day was double clicked in the calendar.
8c6791e4 243 @event{EVT_CALENDAR_SEL_CHANGED(id, func)}
628e155d 244 The selected date changed.
8c6791e4 245 @event{EVT_CALENDAR_PAGE_CHANGED(id, func)}
628e155d 246 The selected month (and/or year) changed.
8c6791e4 247 @event{EVT_CALENDAR_WEEKDAY_CLICKED(id, func)}
628e155d 248 User clicked on the week day header (only generic).
232b2162
VZ
249 @event{EVT_CALENDAR_WEEK_CLICKED(id, func)}
250 User clicked on the week of the year number (only generic).
628e155d
VZ
251 @endEventTable
252
49d37022
BP
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
23324ae1
FM
256 @library{wxadv}
257 @category{ctrl}
7e59b885 258 @appearance{calendarctrl.png}
7c913512 259
7b0ccb8a 260 @nativeimpl{wxgtk,wxmsw}
628e155d 261
1f1d2182
FM
262 @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent,
263 wxDatePickerCtrl
23324ae1
FM
264*/
265class wxCalendarCtrl : public wxControl
266{
267public:
23324ae1 268 /**
49d37022 269 Default constructor.
23324ae1
FM
270 */
271 wxCalendarCtrl();
49d37022
BP
272
273 /**
274 Does the same as Create() method.
275 */
7c913512
FM
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);
23324ae1
FM
282
283 /**
284 Destroys the control.
285 */
286 ~wxCalendarCtrl();
287
288 /**
49d37022
BP
289 Creates the control. See wxWindow::wxWindow() for the meaning of the
290 parameters and the control overview for the possible styles.
23324ae1
FM
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
49d37022
BP
301 style bit directly. It enables or disables the special highlighting of
302 the holidays.
23324ae1 303 */
98ccd545 304 virtual void EnableHolidayDisplay(bool display = true);
23324ae1
FM
305
306 /**
7c913512 307 This function should be used instead of changing
23324ae1 308 @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to
49d37022
BP
309 change the month interactively. Note that if the month can not be
310 changed, the year can not be changed neither.
628e155d 311
49d37022
BP
312 @return @true if the value of this option really changed or @false if
313 it was already set to the requested value.
23324ae1 314 */
98ccd545 315 virtual bool EnableMonthChange(bool enable = true);
23324ae1
FM
316
317 /**
628e155d
VZ
318 @deprecated
319
49d37022
BP
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.
23324ae1 323 */
98ccd545 324 virtual void EnableYearChange(bool enable = true);
23324ae1
FM
325
326 /**
49d37022
BP
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.
23324ae1 330 */
98ccd545 331 virtual wxCalendarDateAttr* GetAttr(size_t day) const;
23324ae1
FM
332
333 /**
334 Gets the currently selected date.
335 */
98ccd545 336 virtual wxDateTime GetDate() const;
23324ae1
FM
337
338 /**
339 Gets the background colour of the header part of the calendar window.
3c4f71cc 340
bf956fac
VZ
341 This method is currently only implemented in generic wxCalendarCtrl and
342 always returns @c wxNullColour in the native versions.
343
4cc4bfaf 344 @see SetHeaderColours()
23324ae1 345 */
98ccd545 346 virtual const wxColour& GetHeaderColourBg() const;
23324ae1
FM
347
348 /**
349 Gets the foreground colour of the header part of the calendar window.
bf956fac
VZ
350
351 This method is currently only implemented in generic wxCalendarCtrl and
352 always returns @c wxNullColour in the native versions.
3c4f71cc 353
4cc4bfaf 354 @see SetHeaderColours()
23324ae1 355 */
98ccd545 356 virtual const wxColour& GetHeaderColourFg() const;
23324ae1
FM
357
358 /**
628e155d 359 Gets the background highlight colour. Only in generic wxCalendarCtrl.
3c4f71cc 360
bf956fac
VZ
361 This method is currently only implemented in generic wxCalendarCtrl and
362 always returns @c wxNullColour in the native versions.
363
4cc4bfaf 364 @see SetHighlightColours()
23324ae1 365 */
98ccd545 366 virtual const wxColour& GetHighlightColourBg() const;
23324ae1
FM
367
368 /**
628e155d 369 Gets the foreground highlight colour. Only in generic wxCalendarCtrl.
3c4f71cc 370
bf956fac
VZ
371 This method is currently only implemented in generic wxCalendarCtrl and
372 always returns @c wxNullColour in the native versions.
373
4cc4bfaf 374 @see SetHighlightColours()
23324ae1 375 */
98ccd545 376 virtual const wxColour& GetHighlightColourFg() const;
23324ae1
FM
377
378 /**
379 Return the background colour currently used for holiday highlighting.
bf956fac
VZ
380
381 Only useful with generic wxCalendarCtrl as native versions currently
49d37022
BP
382 don't support holidays display at all and always return
383 @c wxNullColour.
3c4f71cc 384
4cc4bfaf 385 @see SetHolidayColours()
23324ae1 386 */
98ccd545 387 virtual const wxColour& GetHolidayColourBg() const;
23324ae1
FM
388
389 /**
390 Return the foreground colour currently used for holiday highlighting.
bf956fac
VZ
391
392 Only useful with generic wxCalendarCtrl as native versions currently
49d37022
BP
393 don't support holidays display at all and always return
394 @c wxNullColour.
3c4f71cc 395
4cc4bfaf 396 @see SetHolidayColours()
23324ae1 397 */
98ccd545 398 virtual const wxColour& GetHolidayColourFg() const;
23324ae1
FM
399
400 /**
49d37022
BP
401 Returns one of wxCalendarHitTestResult constants and fills either
402 @a date or @a wd pointer with the corresponding value depending on the
db0b0942 403 hit test code.
98ccd545 404
db0b0942 405 Not implemented in wxGTK currently.
23324ae1 406 */
98ccd545
FM
407 virtual wxCalendarHitTestResult HitTest(const wxPoint& pos,
408 wxDateTime* date = NULL,
409 wxDateTime::WeekDay* wd = NULL);
23324ae1
FM
410
411 /**
412 Clears any attributes associated with the given day (in the range
49d37022 413 1...31). Only in generic wxCalendarCtrl.
23324ae1 414 */
98ccd545 415 virtual void ResetAttr(size_t day);
23324ae1
FM
416
417 /**
418 Associates the attribute with the specified date (in the range 1...31).
49d37022
BP
419 If the pointer is @NULL, the items attribute is cleared. Only in
420 generic wxCalendarCtrl.
23324ae1 421 */
98ccd545 422 virtual void SetAttr(size_t day, wxCalendarDateAttr* attr);
23324ae1
FM
423
424 /**
425 Sets the current date.
db0b0942
VZ
426
427 The @a date parameter must be valid.
23324ae1 428 */
9d9c1c24 429 virtual bool SetDate(const wxDateTime& date);
23324ae1
FM
430
431 /**
49d37022
BP
432 Set the colours used for painting the weekdays at the top of the
433 control.
bf956fac
VZ
434
435 This method is currently only implemented in generic wxCalendarCtrl and
436 does nothing in the native versions.
23324ae1 437 */
98ccd545
FM
438 virtual void SetHeaderColours(const wxColour& colFg,
439 const wxColour& colBg);
23324ae1
FM
440
441 /**
49d37022
BP
442 Set the colours to be used for highlighting the currently selected
443 date.
bf956fac
VZ
444
445 This method is currently only implemented in generic wxCalendarCtrl and
446 does nothing in the native versions.
23324ae1 447 */
98ccd545
FM
448 virtual void SetHighlightColours(const wxColour& colFg,
449 const wxColour& colBg);
23324ae1
FM
450
451 /**
452 Marks the specified day as being a holiday in the current month.
bf956fac
VZ
453
454 This method is only implemented in the generic version of the control
455 and does nothing in the native ones.
23324ae1 456 */
98ccd545 457 virtual void SetHoliday(size_t day);
23324ae1
FM
458
459 /**
bf956fac 460 Sets the colours to be used for the holidays highlighting.
98ccd545 461
bf956fac
VZ
462 This method is only implemented in the generic version of the control
463 and does nothing in the native ones. It should also only be called if
464 the window style includes @c wxCAL_SHOW_HOLIDAYS flag or
465 EnableHolidayDisplay() had been called.
466
23324ae1 467 */
98ccd545
FM
468 virtual void SetHolidayColours(const wxColour& colFg,
469 const wxColour& colBg);
628e155d
VZ
470
471 /**
49d37022
BP
472 Mark or unmark the day. This day of month will be marked in every
473 month. In generic wxCalendarCtrl,
628e155d 474 */
98ccd545 475 virtual void Mark(size_t day, bool mark);
51317496 476
51317496 477 /**
49d37022 478 @name Date Range Functions
51317496
VZ
479
480 The functions in this section are currently implemented in the generic
481 and MSW versions and do nothing in the native GTK implementation.
482 */
483 //@{
484
485 /**
486 Restrict the dates shown by the control to the specified 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
49d37022
BP
492 @see GetDateRange()
493
51317496 494 @param lowerdate
49d37022
BP
495 The low limit for the dates shown by the control or
496 @c wxDefaultDateTime.
792255cc 497 @param upperdate
49d37022
BP
498 The high limit for the dates shown by the control or
499 @c wxDefaultDateTime.
51317496
VZ
500 @return
501 @true if either limit is valid, @false otherwise
502 */
503 virtual bool SetDateRange(const wxDateTime& lowerdate = wxDefaultDateTime,
49d37022 504 const wxDateTime& upperdate = wxDefaultDateTime);
51317496
VZ
505
506 /**
507 Returns the limits currently being used.
508
509 @see SetDateRange()
510
511 @param lowerdate
49d37022 512 If non-@NULL, the value of the low limit for the dates shown by the
51317496 513 control is returned (which may be @c wxDefaultDateTime if no limit
49d37022 514 is set).
51317496 515 @param upperdate
49d37022
BP
516 If non-@NULL, the value of the upper limit for the dates shown by
517 the control is returned (which may be @c wxDefaultDateTime if no
518 limit is set).
51317496
VZ
519 @return
520 @true if either limit is set, @false otherwise
521 */
49d37022
BP
522 virtual bool GetDateRange(wxDateTime *lowerdate,
523 wxDateTime *upperdate) const;
51317496
VZ
524
525 //@}
23324ae1 526};
e54c96f1 527