docs/latex/wx/calctrl.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        calctrl.tex
   3 %% Purpose:     wxCalendarCtrl documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     03.01.00
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% License:     wxWidgets license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxCalendarCtrl}}\label{wxcalendarctrl}
  13
  14 The calendar control allows the user to pick a date interactively. For this,
  15 it displays a window containing several parts: the control to pick the month
  16 and the year at the top (either or both of them may be disabled) and a month
  17 area below them which shows all the days in the month. The user can move the
  18 current selection using the keyboard and select the date (generating
  19 {\tt EVT\_CALENDAR} event) by pressing {\tt <Return>} or double clicking it.
  20
  21 It has advanced possibilities for the customization of its display. All global
  22 settings (such as colours and fonts used) can, of course, be changed. But
  23 also, the display style for each day in the month can be set independently
  24 using \helpref{wxCalendarDateAttr}{wxcalendardateattr} class.
  25
  26 An item without custom attributes is drawn with the default colours and
  27 font and without border, but setting custom attributes with
  28 \helpref{SetAttr}{wxcalendarctrlsetattr} allows to modify its appearance. Just
  29 create a custom attribute object and set it for the day you want to be
  30 displayed specially (note that the control will take ownership of the pointer,
  31 i.e. it will delete it itself). A day may be marked as being a holiday, even
  32 if it is not recognized as one by \helpref{wxDateTime}{tdateholidays} using
  33 \helpref{SetHoliday}{wxcalendardateattrsetholiday} method.
  34
  35 As the attributes are specified for each day, they may change when the month
  36 is changed, so you will often want to update them in
  37 {\tt EVT\_CALENDAR\_MONTH} event handler.
  38
  39 \wxheading{Derived from}
  40
  41 \helpref{wxControl}{wxcontrol}\\
  42 \helpref{wxWindow}{wxwindow}\\
  43 \helpref{wxEvtHandler}{wxevthandler}\\
  44 \helpref{wxObject}{wxobject}
  45
  46 \wxheading{Include files}
  47
  48 <wx/calctrl.h>
  49
  50 \wxheading{Window styles}
  51
  52 \twocolwidtha{5cm}
  53 \begin{twocollist}\itemsep=4pt
  54 \twocolitem{\windowstyle{wxCAL\_SUNDAY\_FIRST}}{Show Sunday as the first day in the week}
  55 \twocolitem{\windowstyle{wxCAL\_MONDAY\_FIRST}}{Show Monday as the first day in the week}
  56 \twocolitem{\windowstyle{wxCAL\_SHOW\_HOLIDAYS}}{Highlight holidays in the calendar}
  57 \twocolitem{\windowstyle{wxCAL\_NO\_YEAR\_CHANGE}}{Disable the year changing}
  58 \twocolitem{\windowstyle{wxCAL\_NO\_MONTH\_CHANGE}}{Disable the month (and, implicitly, the year) changing}
  59 \twocolitem{\windowstyle{wxCAL\_SHOW\_SURROUNDING\_WEEKS}}{Show the neighbouring weeks in the previous and next months}
  60 \twocolitem{\windowstyle{wxCAL\_SEQUENTIAL\_MONTH\_SELECTION}}{Use alternative, more compact, style for the month and year selection controls.}
  61 \end{twocollist}
  62
  63 The default calendar style is {\tt wxCAL\_SHOW\_HOLIDAYS}.
  64
  65 \wxheading{Event table macros}
  66
  67 To process input from a calendar control, use these event handler macros to
  68 direct input to member functions that take a
  69 \helpref{wxCalendarEvent}{wxcalendarevent} argument.
  70
  71 \twocolwidtha{7cm}
  72 \begin{twocollist}\itemsep=7pt
  73 \twocolitem{{\bf EVT\_CALENDAR(id, func)}}{A day was double clicked in the calendar.}
  74 \twocolitem{{\bf EVT\_CALENDAR\_SEL\_CHANGED(id, func)}}{The selected date changed.}
  75 \twocolitem{{\bf EVT\_CALENDAR\_DAY(id, func)}}{The selected day changed.}
  76 \twocolitem{{\bf EVT\_CALENDAR\_MONTH(id, func)}}{The selected month changed.}
  77 \twocolitem{{\bf EVT\_CALENDAR\_YEAR(id, func)}}{The selected year changed.}
  78 \twocolitem{{\bf EVT\_CALENDAR\_WEEKDAY\_CLICKED(id, func)}}{User clicked on the week day header}
  79 \end{twocollist}%
  80
  81 Note that changing the selected date will result in either of
  82 {\tt EVT\_CALENDAR\_DAY}, {\tt MONTH} or {\tt YEAR} events and
  83 {\tt EVT\_CALENDAR\_SEL\_CHANGED} one.
  84
  85 \wxheading{Constants}
  86
  87 The following are the possible return values for
  88 \helpref{HitTest}{wxcalendarctrlhittest} method:
  89
  90 {\small
  91 \begin{verbatim}
  92 enum wxCalendarHitTestResult
  93 {
  94     wxCAL_HITTEST_NOWHERE,      // outside of anything
  95     wxCAL_HITTEST_HEADER,       // on the header (weekdays)
  96     wxCAL_HITTEST_DAY           // on a day in the calendar
  97 }
  98 \end{verbatim}
  99 }
 100
 101 \wxheading{See also}
 102
 103 \helpref{Calendar sample}{samplecalendar}\\
 104 \helpref{wxCalendarDateAttr}{wxcalendardateattr}\\
 105 \helpref{wxCalendarEvent}{wxcalendarevent}
 106
 107 \latexignore{\rtfignore{\wxheading{Members}}}
 108
 109 \membersection{wxCalendarCtrl::wxCalendarCtrl}\label{wxcalendarctrlwxcalendarctrldef}
 110
 111 \func{}{wxCalendarCtrl}{\void}
 112
 113 Default constructor, use \helpref{Create}{wxcalendarctrlcreate} after it.
 114
 115 \membersection{wxCalendarCtrl::wxCalendarCtrl}\label{wxcalendarctrlwxcalendarctrl}
 116
 117 \func{}{wxCalendarCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID }{id}, \param{const wxDateTime\& }{date = wxDefaultDateTime}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxCAL\_SHOW\_HOLIDAYS}, \param{const wxString\& }{name = wxCalendarNameStr}}
 118
 119 Does the same as \helpref{Create}{wxcalendarctrlcreate} method.
 120
 121 \membersection{wxCalendarCtrl::Create}\label{wxcalendarctrlcreate}
 122
 123 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id}, \param{const wxDateTime\& }{date = wxDefaultDateTime}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = wxCAL\_SHOW\_HOLIDAYS}, \param{const wxString\& }{name = wxCalendarNameStr}}
 124
 125 Creates the control. See \helpref{wxWindow}{wxwindowctor} for the meaning of
 126 the parameters and the control overview for the possible styles.
 127
 128 \membersection{wxCalendarCtrl::\destruct{wxCalendarCtrl}}\label{wxcalendarctrldtor}
 129
 130 \func{}{\destruct{wxCalendarCtrl}}{\void}
 131
 132 Destroys the control.
 133
 134 \membersection{wxCalendarCtrl::SetDate}\label{wxcalendarctrlsetdate}
 135
 136 \func{void}{SetDate}{\param{const wxDateTime\& }{date}}
 137
 138 Sets the current date.
 139
 140 \membersection{wxCalendarCtrl::GetDate}\label{wxcalendarctrlgetdate}
 141
 142 \constfunc{const wxDateTime\&}{GetDate}{\void}
 143
 144 Gets the currently selected date.
 145
 146 \membersection{wxCalendarCtrl::EnableYearChange}\label{wxcalendarctrlenableyearchange}
 147
 148 \func{void}{EnableYearChange}{\param{bool }{enable = true}}
 149
 150 This function should be used instead of changing {\tt wxCAL\_NO\_YEAR\_CHANGE}
 151 style bit directly. It allows or disallows the user to change the year
 152 interactively.
 153
 154 \membersection{wxCalendarCtrl::EnableMonthChange}\label{wxcalendarctrlenablemonthchange}
 155
 156 \func{void}{EnableMonthChange}{\param{bool }{enable = true}}
 157
 158 This function should be used instead of changing
 159 {\tt wxCAL\_NO\_MONTH\_CHANGE} style bit. It allows or disallows the user to
 160 change the month interactively. Note that if the month can not be changed, the
 161 year can not be changed neither.
 162
 163 \membersection{wxCalendarCtrl::EnableHolidayDisplay}\label{wxcalendarctrlenableholidaydisplay}
 164
 165 \func{void}{EnableHolidayDisplay}{\param{bool }{display = true}}
 166
 167 This function should be used instead of changing {\tt wxCAL\_SHOW\_HOLIDAYS}
 168 style bit directly. It enables or disables the special highlighting of the
 169 holidays.
 170
 171 \membersection{wxCalendarCtrl::SetHeaderColours}\label{wxcalendarctrlsetheadercolours}
 172
 173 \func{void}{SetHeaderColours}{\param{const wxColour\& }{colFg}, \param{const wxColour\& }{colBg}}
 174
 175 Set the colours used for painting the weekdays at the top of the control.
 176
 177 \membersection{wxCalendarCtrl::GetHeaderColourFg}\label{wxcalendarctrlgetheadercolourfg}
 178
 179 \constfunc{const wxColour\&}{GetHeaderColourFg}{\void}
 180
 181 Gets the foreground colour of the header part of the calendar window.
 182
 183 \wxheading{See also}
 184
 185 \helpref{SetHeaderColours}{wxcalendarctrlsetheadercolours}
 186
 187 \membersection{wxCalendarCtrl::GetHeaderColourBg}\label{wxcalendarctrlgetheadercolourbg}
 188
 189 \constfunc{const wxColour\&}{GetHeaderColourBg}{\void}
 190
 191 Gets the background colour of the header part of the calendar window.
 192
 193 \wxheading{See also}
 194
 195 \helpref{SetHeaderColours}{wxcalendarctrlsetheadercolours}
 196
 197 \membersection{wxCalendarCtrl::SetHighlightColours}\label{wxcalendarctrlsethighlightcolours}
 198
 199 \func{void}{SetHighlightColours}{\param{const wxColour\& }{colFg}, \param{const wxColour\& }{colBg}}
 200
 201 Set the colours to be used for highlighting the currently selected date.
 202
 203 \membersection{wxCalendarCtrl::GetHighlightColourFg}\label{wxcalendarctrlgethighlightcolourfg}
 204
 205 \constfunc{const wxColour\&}{GetHighlightColourFg}{\void}
 206
 207 Gets the foreground highlight colour.
 208
 209 \wxheading{See also}
 210
 211 \helpref{SetHighlightColours}{wxcalendarctrlsethighlightcolours}
 212
 213 \membersection{wxCalendarCtrl::GetHighlightColourBg}\label{wxcalendarctrlgethighlightcolourbg}
 214
 215 \constfunc{const wxColour\&}{GetHighlightColourBg}{\void}
 216
 217 Gets the background highlight colour.
 218
 219 \wxheading{See also}
 220
 221 \helpref{SetHighlightColours}{wxcalendarctrlsethighlightcolours}
 222
 223 \membersection{wxCalendarCtrl::SetHolidayColours}\label{wxcalendarctrlsetholidaycolours}
 224
 225 \func{void}{SetHolidayColours}{\param{const wxColour\& }{colFg}, \param{const wxColour\& }{colBg}}
 226
 227 Sets the colours to be used for the holidays highlighting (only used if the
 228 window style includes {\tt wxCAL\_SHOW\_HOLIDAYS} flag).
 229
 230 \membersection{wxCalendarCtrl::GetHolidayColourFg}\label{wxcalendarctrlgetholidaycolourfg}
 231
 232 \constfunc{const wxColour\&}{GetHolidayColourFg}{\void}
 233
 234 Return the foreground colour currently used for holiday highlighting.
 235
 236 \wxheading{See also}
 237
 238 \helpref{SetHolidayColours}{wxcalendarctrlsetholidaycolours}
 239
 240 \membersection{wxCalendarCtrl::GetHolidayColourBg}\label{wxcalendarctrlgetholidaycolourbg}
 241
 242 \constfunc{const wxColour\&}{GetHolidayColourBg}{\void}
 243
 244 Return the background colour currently used for holiday highlighting.
 245
 246 \wxheading{See also}
 247
 248 \helpref{SetHolidayColours}{wxcalendarctrlsetholidaycolours}
 249
 250 \membersection{wxCalendarCtrl::GetAttr}\label{wxcalendarctrlgetattr}
 251
 252 \constfunc{wxCalendarDateAttr *}{GetAttr}{\param{size\_t }{day}}
 253
 254 Returns the attribute for the given date (should be in the range $1\ldots31$).
 255
 256 The returned pointer may be {\tt NULL}.
 257
 258 \membersection{wxCalendarCtrl::SetAttr}\label{wxcalendarctrlsetattr}
 259
 260 \func{void}{SetAttr}{\param{size\_t }{day}, \param{wxCalendarDateAttr* }{attr}}
 261
 262 Associates the attribute with the specified date (in the range $1\ldots31$).
 263
 264 If the pointer is {\tt NULL}, the items attribute is cleared.
 265
 266 \membersection{wxCalendarCtrl::SetHoliday}\label{wxcalendarctrlsetholiday}
 267
 268 \func{void}{SetHoliday}{\param{size\_t }{day}}
 269
 270 Marks the specified day as being a holiday in the current month.
 271
 272 \membersection{wxCalendarCtrl::ResetAttr}\label{wxcalendarctrlresetattr}
 273
 274 \func{void}{ResetAttr}{\param{size\_t }{day}}
 275
 276 Clears any attributes associated with the given day (in the range
 277 $1\ldots31$).
 278
 279 \membersection{wxCalendarCtrl::HitTest}\label{wxcalendarctrlhittest}
 280
 281 \func{wxCalendarHitTestResult}{HitTest}{\param{const wxPoint\& }{pos}, \param{wxDateTime* }{date = NULL}, \param{wxDateTime::WeekDay* }{wd = NULL}}
 282
 283 Returns one of {\tt wxCAL\_HITTEST\_XXX}
 284 \helpref{constants}{wxcalendarctrl} and fills either {\it date} or
 285 {\it wd} pointer with the corresponding value depending on the hit test code.
 286
 287 \section{\class{wxCalendarDateAttr}}\label{wxcalendardateattr}
 288
 289 wxCalendarDateAttr is a custom attributes for a calendar date. The objects of
 290 this class are used with \helpref{wxCalendarCtrl}{wxcalendarctrl}.
 291
 292 \wxheading{Derived from}
 293
 294 No base class
 295
 296 \wxheading{Constants}
 297
 298 Here are the possible kinds of borders which may be used to decorate a date:
 299
 300 \begin{verbatim}
 301 enum wxCalendarDateBorder
 302 {
 303     wxCAL_BORDER_NONE,          // no border (default)
 304     wxCAL_BORDER_SQUARE,        // a rectangular border
 305     wxCAL_BORDER_ROUND          // a round border
 306 }
 307 \end{verbatim}
 308
 309 \wxheading{See also}
 310
 311 \helpref{wxCalendarCtrl}{wxcalendarctrl}
 312
 313 \latexignore{\rtfignore{\wxheading{Members}}}
 314
 315 \membersection{wxCalendarDateAttr::wxCalendarDateAttr}\label{wxcalendardateattrwxcalendardateattr}
 316
 317 \func{}{wxCalendarDateAttr}{\void}
 318
 319 \func{}{wxCalendarDateAttr}{\param{const wxColour\& }{colText}, \param{const wxColour\& }{colBack = wxNullColour}, \param{const wxColour\& }{colBorder = wxNullColour}, \param{const wxFont\& }{font = wxNullFont}, \param{wxCalendarDateBorder }{border = wxCAL\_BORDER\_NONE}}
 320
 321 \func{}{wxCalendarDateAttr}{\param{wxCalendarDateBorder }{border}, \param{const wxColour\& }{colBorder = wxNullColour}}
 322
 323 The constructors.
 324
 325 \membersection{wxCalendarDateAttr::SetTextColour}\label{wxcalendardateattrsettextcolour}
 326
 327 \func{void}{SetTextColour}{\param{const wxColour\& }{colText}}
 328
 329 Sets the text (foreground) colour to use.
 330
 331 \membersection{wxCalendarDateAttr::SetBackgroundColour}\label{wxcalendardateattrsetbackgroundcolour}
 332
 333 \func{void}{SetBackgroundColour}{\param{const wxColour\& }{colBack}}
 334
 335 Sets the text background colour to use.
 336
 337 \membersection{wxCalendarDateAttr::SetBorderColour}\label{wxcalendardateattrsetbordercolour}
 338
 339 \func{void}{SetBorderColour}{\param{const wxColour\& }{col}}
 340
 341 Sets the border colour to use.
 342
 343 \membersection{wxCalendarDateAttr::SetFont}\label{wxcalendardateattrsetfont}
 344
 345 \func{void}{SetFont}{\param{const wxFont\& }{font}}
 346
 347 Sets the font to use.
 348
 349 \membersection{wxCalendarDateAttr::SetBorder}\label{wxcalendardateattrsetborder}
 350
 351 \func{void}{SetBorder}{\param{wxCalendarDateBorder }{border}}
 352
 353 Sets the \helpref{border kind}{wxcalendardateattr}
 354
 355 \membersection{wxCalendarDateAttr::SetHoliday}\label{wxcalendardateattrsetholiday}
 356
 357 \func{void}{SetHoliday}{\param{bool }{holiday}}
 358
 359 Display the date with this attribute as a holiday.
 360
 361 \membersection{wxCalendarDateAttr::HasTextColour}\label{wxcalendardateattrhastextcolour}
 362
 363 \constfunc{bool}{HasTextColour}{\void}
 364
 365 Returns {\tt true} if this item has a non default text foreground colour.
 366
 367 \membersection{wxCalendarDateAttr::HasBackgroundColour}\label{wxcalendardateattrhasbackgroundcolour}
 368
 369 \constfunc{bool}{HasBackgroundColour}{\void}
 370
 371 Returns {\tt true} if this attribute specifies a non default text background colour.
 372
 373 \membersection{wxCalendarDateAttr::HasBorderColour}\label{wxcalendardateattrhasbordercolour}
 374
 375 \constfunc{bool}{HasBorderColour}{\void}
 376
 377 Returns {\tt true} if this attribute specifies a non default border colour.
 378
 379 \membersection{wxCalendarDateAttr::HasFont}\label{wxcalendardateattrhasfont}
 380
 381 \constfunc{bool}{HasFont}{\void}
 382
 383 Returns {\tt true} if this attribute specifies a non default font.
 384
 385 \membersection{wxCalendarDateAttr::HasBorder}\label{wxcalendardateattrhasborder}
 386
 387 \constfunc{bool}{HasBorder}{\void}
 388
 389 Returns {\tt true} if this attribute specifies a non default (i.e. any) border.
 390
 391 \membersection{wxCalendarDateAttr::IsHoliday}\label{wxcalendardateattrisholiday}
 392
 393 \constfunc{bool}{IsHoliday}{\void}
 394
 395 Returns {\tt true} if this attribute specifies that this item should be
 396 displayed as a holiday.
 397
 398 \membersection{wxCalendarDateAttr::GetTextColour}\label{wxcalendardateattrgettextcolour}
 399
 400 \constfunc{const wxColour\&}{GetTextColour}{\void}
 401
 402 Returns the text colour to use for the item with this attribute.
 403
 404 \membersection{wxCalendarDateAttr::GetBackgroundColour}\label{wxcalendardateattrgetbackgroundcolour}
 405
 406 \constfunc{const wxColour\&}{GetBackgroundColour}{\void}
 407
 408 Returns the background colour to use for the item with this attribute.
 409
 410 \membersection{wxCalendarDateAttr::GetBorderColour}\label{wxcalendardateattrgetbordercolour}
 411
 412 \constfunc{const wxColour\&}{GetBorderColour}{\void}
 413
 414 Returns the border colour to use for the item with this attribute.
 415
 416 \membersection{wxCalendarDateAttr::GetFont}\label{wxcalendardateattrgetfont}
 417
 418 \constfunc{const wxFont\&}{GetFont}{\void}
 419
 420 Returns the font to use for the item with this attribute.
 421
 422 \membersection{wxCalendarDateAttr::GetBorder}\label{wxcalendardateattrgetborder}
 423
 424 \constfunc{wxCalendarDateBorder}{GetBorder}{\void}
 425
 426 Returns the \helpref{border}{wxcalendardateattr} to use for the item with this attribute.
 427
 428 \section{\class{wxCalendarEvent}}\label{wxcalendarevent}
 429
 430 The wxCalendarEvent class is used together with
 431 \helpref{wxCalendarCtrl}{wxcalendarctrl}.
 432
 433 \wxheading{See also}
 434
 435 \helpref{wxCalendarCtrl}{wxcalendarctrl}
 436
 437 \latexignore{\rtfignore{\wxheading{Members}}}
 438
 439 \membersection{wxCalendarEvent::GetDate}\label{wxcalendareventgetdate}
 440
 441 \constfunc{const wxDateTime\&}{GetDate}{\void}
 442
 443 Returns the date. This function may be called for all event types except
 444 {\tt EVT\_CALENDAR\_WEEKDAY\_CLICKED} one for which it doesn't make sense.
 445
 446 \membersection{wxCalendarEvent::GetWeekDay}\label{wxcalendareventgetweekday}
 447
 448 \constfunc{wxDateTime::WeekDay}{GetWeekDay}{\void}
 449
 450 Returns the week day on which the user clicked in
 451 {\tt EVT\_CALENDAR\_WEEKDAY\_CLICKED} handler. It doesn't make sense to call
 452 this function in other handlers.
 453
 454 \membersection{wxCalendarEvent::SetDate}\label{wxcalendareventsetdate}
 455
 456 \func{void}{SetDate}{\param{const wxDateTime\&}{ date}}
 457
 458 Sets the date.
 459
 460 \membersection{wxCalendarEvent::SetWeekDay}\label{wxcalendareventsetweekday}
 461
 462 \func{void}{SetWeekDay}{\param{wxDateTime::WeekDay}{ day}}
 463
 464 Sets the week day.
 465