]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/calctrl.h
pass ApplyEdit() arguments to EndEdit() too for better backwards compatibility (close...
[wxWidgets.git] / 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{data}
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 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).
190 };
191
192 /**
193 @class wxCalendarCtrl
194
195 The calendar control allows the user to pick a date. The user can move the
196 current selection using the keyboard and select the date (generating
197 @c EVT_CALENDAR event) by pressing @c @<Return@> or double clicking it.
198
199 Generic calendar has advanced possibilities for the customization of its
200 display, described below. If you want to use these possibilities on every
201 platform, use wxGenericCalendarCtrl instead of wxCalendarCtrl.
202
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.
206
207 An item without custom attributes is drawn with the default colours and
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).
212 A day may be marked as being a holiday, even if it is not recognized as
213 one by wxDateTime using the wxCalendarDateAttr::SetHoliday() method.
214
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
217 @c EVT_CALENDAR_PAGE_CHANGED event handler.
218
219 @beginStyleTable
220 @style{wxCAL_SUNDAY_FIRST}
221 Show Sunday as the first day in the week (not in wxGTK)
222 @style{wxCAL_MONDAY_FIRST}
223 Show Monday as the first day in the week (not in wxGTK)
224 @style{wxCAL_SHOW_HOLIDAYS}
225 Highlight holidays in the calendar (only generic)
226 @style{wxCAL_NO_YEAR_CHANGE}
227 Disable the year changing (deprecated, only generic)
228 @style{wxCAL_NO_MONTH_CHANGE}
229 Disable the month (and, implicitly, the year) changing
230 @style{wxCAL_SHOW_SURROUNDING_WEEKS}
231 Show the neighbouring weeks in the previous and next months
232 (only generic, always on for the native controls)
233 @style{wxCAL_SEQUENTIAL_MONTH_SELECTION}
234 Use alternative, more compact, style for the month and year
235 selection controls. (only generic)
236 @style{wxCAL_SHOW_WEEK_NUMBERS}
237 Show week numbers on the left side of the calendar. (not in generic)
238 @endStyleTable
239
240 @beginEventEmissionTable{wxCalendarEvent}
241 @event{EVT_CALENDAR(id, func)}
242 A day was double clicked in the calendar.
243 @event{EVT_CALENDAR_SEL_CHANGED(id, func)}
244 The selected date changed.
245 @event{EVT_CALENDAR_PAGE_CHANGED(id, func)}
246 The selected month (and/or year) changed.
247 @event{EVT_CALENDAR_WEEKDAY_CLICKED(id, func)}
248 User clicked on the week day header (only generic).
249 @event{EVT_CALENDAR_WEEK_CLICKED(id, func)}
250 User clicked on the week of the year number (only generic).
251 @endEventTable
252
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
256 @library{wxadv}
257 @category{ctrl}
258 @appearance{calendarctrl.png}
259
260 @nativeimpl{wxgtk,wxmsw}
261
262 @see @ref page_samples_calendar, wxCalendarDateAttr, wxCalendarEvent,
263 wxDatePickerCtrl
264 */
265 class wxCalendarCtrl : public wxControl
266 {
267 public:
268 /**
269 Default constructor.
270 */
271 wxCalendarCtrl();
272
273 /**
274 Does the same as Create() method.
275 */
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);
282
283 /**
284 Destroys the control.
285 */
286 ~wxCalendarCtrl();
287
288 /**
289 Creates the control. See wxWindow::wxWindow() for the meaning of the
290 parameters and the control overview for the possible styles.
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
301 style bit directly. It enables or disables the special highlighting of
302 the holidays.
303 */
304 virtual void EnableHolidayDisplay(bool display = true);
305
306 /**
307 This function should be used instead of changing
308 @c wxCAL_NO_MONTH_CHANGE style bit. It allows or disallows the user to
309 change the month interactively. Note that if the month can not be
310 changed, the year can not be changed neither.
311
312 @return @true if the value of this option really changed or @false if
313 it was already set to the requested value.
314 */
315 virtual bool EnableMonthChange(bool enable = true);
316
317 /**
318 @deprecated
319
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.
323 */
324 virtual void EnableYearChange(bool enable = true);
325
326 /**
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.
330 */
331 virtual wxCalendarDateAttr* GetAttr(size_t day) const;
332
333 /**
334 Gets the currently selected date.
335 */
336 virtual wxDateTime GetDate() const;
337
338 /**
339 Gets the background colour of the header part of the calendar window.
340
341 This method is currently only implemented in generic wxCalendarCtrl and
342 always returns @c wxNullColour in the native versions.
343
344 @see SetHeaderColours()
345 */
346 virtual const wxColour& GetHeaderColourBg() const;
347
348 /**
349 Gets the foreground colour of the header part of the calendar window.
350
351 This method is currently only implemented in generic wxCalendarCtrl and
352 always returns @c wxNullColour in the native versions.
353
354 @see SetHeaderColours()
355 */
356 virtual const wxColour& GetHeaderColourFg() const;
357
358 /**
359 Gets the background highlight colour. Only in generic wxCalendarCtrl.
360
361 This method is currently only implemented in generic wxCalendarCtrl and
362 always returns @c wxNullColour in the native versions.
363
364 @see SetHighlightColours()
365 */
366 virtual const wxColour& GetHighlightColourBg() const;
367
368 /**
369 Gets the foreground highlight colour. Only in generic wxCalendarCtrl.
370
371 This method is currently only implemented in generic wxCalendarCtrl and
372 always returns @c wxNullColour in the native versions.
373
374 @see SetHighlightColours()
375 */
376 virtual const wxColour& GetHighlightColourFg() const;
377
378 /**
379 Return the background colour currently used for holiday highlighting.
380
381 Only useful with generic wxCalendarCtrl as native versions currently
382 don't support holidays display at all and always return
383 @c wxNullColour.
384
385 @see SetHolidayColours()
386 */
387 virtual const wxColour& GetHolidayColourBg() const;
388
389 /**
390 Return the foreground colour currently used for holiday highlighting.
391
392 Only useful with generic wxCalendarCtrl as native versions currently
393 don't support holidays display at all and always return
394 @c wxNullColour.
395
396 @see SetHolidayColours()
397 */
398 virtual const wxColour& GetHolidayColourFg() const;
399
400 /**
401 Returns one of wxCalendarHitTestResult constants and fills either
402 @a date or @a wd pointer with the corresponding value depending on the
403 hit test code.
404
405 Not implemented in wxGTK currently.
406 */
407 virtual wxCalendarHitTestResult HitTest(const wxPoint& pos,
408 wxDateTime* date = NULL,
409 wxDateTime::WeekDay* wd = NULL);
410
411 /**
412 Clears any attributes associated with the given day (in the range
413 1...31). Only in generic wxCalendarCtrl.
414 */
415 virtual void ResetAttr(size_t day);
416
417 /**
418 Associates the attribute with the specified date (in the range 1...31).
419 If the pointer is @NULL, the items attribute is cleared. Only in
420 generic wxCalendarCtrl.
421 */
422 virtual void SetAttr(size_t day, wxCalendarDateAttr* attr);
423
424 /**
425 Sets the current date.
426
427 The @a date parameter must be valid.
428 */
429 virtual bool SetDate(const wxDateTime& date);
430
431 /**
432 Set the colours used for painting the weekdays at the top of the
433 control.
434
435 This method is currently only implemented in generic wxCalendarCtrl and
436 does nothing in the native versions.
437 */
438 virtual void SetHeaderColours(const wxColour& colFg,
439 const wxColour& colBg);
440
441 /**
442 Set the colours to be used for highlighting the currently selected
443 date.
444
445 This method is currently only implemented in generic wxCalendarCtrl and
446 does nothing in the native versions.
447 */
448 virtual void SetHighlightColours(const wxColour& colFg,
449 const wxColour& colBg);
450
451 /**
452 Marks the specified day as being a holiday in the current month.
453
454 This method is only implemented in the generic version of the control
455 and does nothing in the native ones.
456 */
457 virtual void SetHoliday(size_t day);
458
459 /**
460 Sets the colours to be used for the holidays highlighting.
461
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
467 */
468 virtual void SetHolidayColours(const wxColour& colFg,
469 const wxColour& colBg);
470
471 /**
472 Mark or unmark the day. This day of month will be marked in every
473 month. In generic wxCalendarCtrl,
474 */
475 virtual void Mark(size_t day, bool mark);
476
477 /**
478 @name Date Range Functions
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
492 @see GetDateRange()
493
494 @param lowerdate
495 The low limit for the dates shown by the control or
496 @c wxDefaultDateTime.
497 @param upperdate
498 The high limit for the dates shown by the control or
499 @c wxDefaultDateTime.
500 @return
501 @true if either limit is valid, @false otherwise
502 */
503 virtual bool SetDateRange(const wxDateTime& lowerdate = wxDefaultDateTime,
504 const wxDateTime& upperdate = wxDefaultDateTime);
505
506 /**
507 Returns the limits currently being used.
508
509 @see SetDateRange()
510
511 @param lowerdate
512 If non-@NULL, the value of the low limit for the dates shown by the
513 control is returned (which may be @c wxDefaultDateTime if no limit
514 is set).
515 @param upperdate
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).
519 @return
520 @true if either limit is set, @false otherwise
521 */
522 virtual bool GetDateRange(wxDateTime *lowerdate,
523 wxDateTime *upperdate) const;
524
525 //@}
526 };
527