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
 110 \membersection{wxCalendarCtrl::wxCalendarCtrl}\label{wxcalendarctrlwxcalendarctrldef}
 111
 112 \func{}{wxCalendarCtrl}{\void}
 113
 114 Default constructor, use \helpref{Create}{wxcalendarctrlcreate} after it.
 115
 116
 117 \membersection{wxCalendarCtrl::wxCalendarCtrl}\label{wxcalendarctrlwxcalendarctrl}
 118
 119 \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}}
 120
 121 Does the same as \helpref{Create}{wxcalendarctrlcreate} method.
 122
 123
 124 \membersection{wxCalendarCtrl::Create}\label{wxcalendarctrlcreate}
 125
 126 \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}}
 127
 128 Creates the control. See \helpref{wxWindow}{wxwindowctor} for the meaning of
 129 the parameters and the control overview for the possible styles.
 130
 131
 132 \membersection{wxCalendarCtrl::\destruct{wxCalendarCtrl}}\label{wxcalendarctrldtor}
 133
 134 \func{}{\destruct{wxCalendarCtrl}}{\void}
 135
 136 Destroys the control.
 137
 138
 139 \membersection{wxCalendarCtrl::SetDate}\label{wxcalendarctrlsetdate}
 140
 141 \func{void}{SetDate}{\param{const wxDateTime\& }{date}}
 142
 143 Sets the current date.
 144
 145
 146 \membersection{wxCalendarCtrl::GetDate}\label{wxcalendarctrlgetdate}
 147
 148 \constfunc{const wxDateTime\&}{GetDate}{\void}
 149
 150 Gets the currently selected date.
 151
 152
 153 \membersection{wxCalendarCtrl::EnableYearChange}\label{wxcalendarctrlenableyearchange}
 154
 155 \func{void}{EnableYearChange}{\param{bool }{enable = true}}
 156
 157 This function should be used instead of changing {\tt wxCAL\_NO\_YEAR\_CHANGE}
 158 style bit directly. It allows or disallows the user to change the year
 159 interactively.
 160
 161
 162 \membersection{wxCalendarCtrl::EnableMonthChange}\label{wxcalendarctrlenablemonthchange}
 163
 164 \func{void}{EnableMonthChange}{\param{bool }{enable = true}}
 165
 166 This function should be used instead of changing
 167 {\tt wxCAL\_NO\_MONTH\_CHANGE} style bit. It allows or disallows the user to
 168 change the month interactively. Note that if the month can not be changed, the
 169 year can not be changed neither.
 170
 171
 172 \membersection{wxCalendarCtrl::EnableHolidayDisplay}\label{wxcalendarctrlenableholidaydisplay}
 173
 174 \func{void}{EnableHolidayDisplay}{\param{bool }{display = true}}
 175
 176 This function should be used instead of changing {\tt wxCAL\_SHOW\_HOLIDAYS}
 177 style bit directly. It enables or disables the special highlighting of the
 178 holidays.
 179
 180
 181 \membersection{wxCalendarCtrl::SetHeaderColours}\label{wxcalendarctrlsetheadercolours}
 182
 183 \func{void}{SetHeaderColours}{\param{const wxColour\& }{colFg}, \param{const wxColour\& }{colBg}}
 184
 185 Set the colours used for painting the weekdays at the top of the control.
 186
 187
 188 \membersection{wxCalendarCtrl::GetHeaderColourFg}\label{wxcalendarctrlgetheadercolourfg}
 189
 190 \constfunc{const wxColour\&}{GetHeaderColourFg}{\void}
 191
 192 Gets the foreground colour of the header part of the calendar window.
 193
 194 \wxheading{See also}
 195
 196 \helpref{SetHeaderColours}{wxcalendarctrlsetheadercolours}
 197
 198
 199 \membersection{wxCalendarCtrl::GetHeaderColourBg}\label{wxcalendarctrlgetheadercolourbg}
 200
 201 \constfunc{const wxColour\&}{GetHeaderColourBg}{\void}
 202
 203 Gets the background colour of the header part of the calendar window.
 204
 205 \wxheading{See also}
 206
 207 \helpref{SetHeaderColours}{wxcalendarctrlsetheadercolours}
 208
 209
 210 \membersection{wxCalendarCtrl::SetHighlightColours}\label{wxcalendarctrlsethighlightcolours}
 211
 212 \func{void}{SetHighlightColours}{\param{const wxColour\& }{colFg}, \param{const wxColour\& }{colBg}}
 213
 214 Set the colours to be used for highlighting the currently selected date.
 215
 216
 217 \membersection{wxCalendarCtrl::GetHighlightColourFg}\label{wxcalendarctrlgethighlightcolourfg}
 218
 219 \constfunc{const wxColour\&}{GetHighlightColourFg}{\void}
 220
 221 Gets the foreground highlight colour.
 222
 223 \wxheading{See also}
 224
 225 \helpref{SetHighlightColours}{wxcalendarctrlsethighlightcolours}
 226
 227
 228 \membersection{wxCalendarCtrl::GetHighlightColourBg}\label{wxcalendarctrlgethighlightcolourbg}
 229
 230 \constfunc{const wxColour\&}{GetHighlightColourBg}{\void}
 231
 232 Gets the background highlight colour.
 233
 234 \wxheading{See also}
 235
 236 \helpref{SetHighlightColours}{wxcalendarctrlsethighlightcolours}
 237
 238
 239 \membersection{wxCalendarCtrl::SetHolidayColours}\label{wxcalendarctrlsetholidaycolours}
 240
 241 \func{void}{SetHolidayColours}{\param{const wxColour\& }{colFg}, \param{const wxColour\& }{colBg}}
 242
 243 Sets the colours to be used for the holidays highlighting (only used if the
 244 window style includes {\tt wxCAL\_SHOW\_HOLIDAYS} flag).
 245
 246
 247 \membersection{wxCalendarCtrl::GetHolidayColourFg}\label{wxcalendarctrlgetholidaycolourfg}
 248
 249 \constfunc{const wxColour\&}{GetHolidayColourFg}{\void}
 250
 251 Return the foreground colour currently used for holiday highlighting.
 252
 253 \wxheading{See also}
 254
 255 \helpref{SetHolidayColours}{wxcalendarctrlsetholidaycolours}
 256
 257
 258 \membersection{wxCalendarCtrl::GetHolidayColourBg}\label{wxcalendarctrlgetholidaycolourbg}
 259
 260 \constfunc{const wxColour\&}{GetHolidayColourBg}{\void}
 261
 262 Return the background colour currently used for holiday highlighting.
 263
 264 \wxheading{See also}
 265
 266 \helpref{SetHolidayColours}{wxcalendarctrlsetholidaycolours}
 267
 268
 269 \membersection{wxCalendarCtrl::GetAttr}\label{wxcalendarctrlgetattr}
 270
 271 \constfunc{wxCalendarDateAttr *}{GetAttr}{\param{size\_t }{day}}
 272
 273 Returns the attribute for the given date (should be in the range $1\ldots31$).
 274
 275 The returned pointer may be {\tt NULL}.
 276
 277
 278 \membersection{wxCalendarCtrl::SetAttr}\label{wxcalendarctrlsetattr}
 279
 280 \func{void}{SetAttr}{\param{size\_t }{day}, \param{wxCalendarDateAttr* }{attr}}
 281
 282 Associates the attribute with the specified date (in the range $1\ldots31$).
 283
 284 If the pointer is {\tt NULL}, the items attribute is cleared.
 285
 286
 287 \membersection{wxCalendarCtrl::SetHoliday}\label{wxcalendarctrlsetholiday}
 288
 289 \func{void}{SetHoliday}{\param{size\_t }{day}}
 290
 291 Marks the specified day as being a holiday in the current month.
 292
 293
 294 \membersection{wxCalendarCtrl::ResetAttr}\label{wxcalendarctrlresetattr}
 295
 296 \func{void}{ResetAttr}{\param{size\_t }{day}}
 297
 298 Clears any attributes associated with the given day (in the range
 299 $1\ldots31$).
 300
 301
 302 \membersection{wxCalendarCtrl::HitTest}\label{wxcalendarctrlhittest}
 303
 304 \func{wxCalendarHitTestResult}{HitTest}{\param{const wxPoint\& }{pos}, \param{wxDateTime* }{date = NULL}, \param{wxDateTime::WeekDay* }{wd = NULL}}
 305
 306 Returns one of {\tt wxCAL\_HITTEST\_XXX}
 307 \helpref{constants}{wxcalendarctrl} and fills either {\it date} or
 308 {\it wd} pointer with the corresponding value depending on the hit test code.
 309
 310 \section{\class{wxCalendarDateAttr}}\label{wxcalendardateattr}
 311
 312 wxCalendarDateAttr is a custom attributes for a calendar date. The objects of
 313 this class are used with \helpref{wxCalendarCtrl}{wxcalendarctrl}.
 314
 315 \wxheading{Derived from}
 316
 317 No base class
 318
 319 \wxheading{Constants}
 320
 321 Here are the possible kinds of borders which may be used to decorate a date:
 322
 323 \begin{verbatim}
 324 enum wxCalendarDateBorder
 325 {
 326     wxCAL_BORDER_NONE,          // no border (default)
 327     wxCAL_BORDER_SQUARE,        // a rectangular border
 328     wxCAL_BORDER_ROUND          // a round border
 329 }
 330 \end{verbatim}
 331
 332 \wxheading{See also}
 333
 334 \helpref{wxCalendarCtrl}{wxcalendarctrl}
 335
 336 \latexignore{\rtfignore{\wxheading{Members}}}
 337
 338
 339 \membersection{wxCalendarDateAttr::wxCalendarDateAttr}\label{wxcalendardateattrwxcalendardateattr}
 340
 341 \func{}{wxCalendarDateAttr}{\void}
 342
 343 \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}}
 344
 345 \func{}{wxCalendarDateAttr}{\param{wxCalendarDateBorder }{border}, \param{const wxColour\& }{colBorder = wxNullColour}}
 346
 347 The constructors.
 348
 349
 350 \membersection{wxCalendarDateAttr::SetTextColour}\label{wxcalendardateattrsettextcolour}
 351
 352 \func{void}{SetTextColour}{\param{const wxColour\& }{colText}}
 353
 354 Sets the text (foreground) colour to use.
 355
 356
 357 \membersection{wxCalendarDateAttr::SetBackgroundColour}\label{wxcalendardateattrsetbackgroundcolour}
 358
 359 \func{void}{SetBackgroundColour}{\param{const wxColour\& }{colBack}}
 360
 361 Sets the text background colour to use.
 362
 363
 364 \membersection{wxCalendarDateAttr::SetBorderColour}\label{wxcalendardateattrsetbordercolour}
 365
 366 \func{void}{SetBorderColour}{\param{const wxColour\& }{col}}
 367
 368 Sets the border colour to use.
 369
 370
 371 \membersection{wxCalendarDateAttr::SetFont}\label{wxcalendardateattrsetfont}
 372
 373 \func{void}{SetFont}{\param{const wxFont\& }{font}}
 374
 375 Sets the font to use.
 376
 377
 378 \membersection{wxCalendarDateAttr::SetBorder}\label{wxcalendardateattrsetborder}
 379
 380 \func{void}{SetBorder}{\param{wxCalendarDateBorder }{border}}
 381
 382 Sets the \helpref{border kind}{wxcalendardateattr}
 383
 384
 385 \membersection{wxCalendarDateAttr::SetHoliday}\label{wxcalendardateattrsetholiday}
 386
 387 \func{void}{SetHoliday}{\param{bool }{holiday}}
 388
 389 Display the date with this attribute as a holiday.
 390
 391
 392 \membersection{wxCalendarDateAttr::HasTextColour}\label{wxcalendardateattrhastextcolour}
 393
 394 \constfunc{bool}{HasTextColour}{\void}
 395
 396 Returns {\tt true} if this item has a non default text foreground colour.
 397
 398
 399 \membersection{wxCalendarDateAttr::HasBackgroundColour}\label{wxcalendardateattrhasbackgroundcolour}
 400
 401 \constfunc{bool}{HasBackgroundColour}{\void}
 402
 403 Returns {\tt true} if this attribute specifies a non default text background colour.
 404
 405
 406 \membersection{wxCalendarDateAttr::HasBorderColour}\label{wxcalendardateattrhasbordercolour}
 407
 408 \constfunc{bool}{HasBorderColour}{\void}
 409
 410 Returns {\tt true} if this attribute specifies a non default border colour.
 411
 412
 413 \membersection{wxCalendarDateAttr::HasFont}\label{wxcalendardateattrhasfont}
 414
 415 \constfunc{bool}{HasFont}{\void}
 416
 417 Returns {\tt true} if this attribute specifies a non default font.
 418
 419
 420 \membersection{wxCalendarDateAttr::HasBorder}\label{wxcalendardateattrhasborder}
 421
 422 \constfunc{bool}{HasBorder}{\void}
 423
 424 Returns {\tt true} if this attribute specifies a non default (i.e. any) border.
 425
 426
 427 \membersection{wxCalendarDateAttr::IsHoliday}\label{wxcalendardateattrisholiday}
 428
 429 \constfunc{bool}{IsHoliday}{\void}
 430
 431 Returns {\tt true} if this attribute specifies that this item should be
 432 displayed as a holiday.
 433
 434
 435 \membersection{wxCalendarDateAttr::GetTextColour}\label{wxcalendardateattrgettextcolour}
 436
 437 \constfunc{const wxColour\&}{GetTextColour}{\void}
 438
 439 Returns the text colour to use for the item with this attribute.
 440
 441
 442 \membersection{wxCalendarDateAttr::GetBackgroundColour}\label{wxcalendardateattrgetbackgroundcolour}
 443
 444 \constfunc{const wxColour\&}{GetBackgroundColour}{\void}
 445
 446 Returns the background colour to use for the item with this attribute.
 447
 448
 449 \membersection{wxCalendarDateAttr::GetBorderColour}\label{wxcalendardateattrgetbordercolour}
 450
 451 \constfunc{const wxColour\&}{GetBorderColour}{\void}
 452
 453 Returns the border colour to use for the item with this attribute.
 454
 455
 456 \membersection{wxCalendarDateAttr::GetFont}\label{wxcalendardateattrgetfont}
 457
 458 \constfunc{const wxFont\&}{GetFont}{\void}
 459
 460 Returns the font to use for the item with this attribute.
 461
 462
 463 \membersection{wxCalendarDateAttr::GetBorder}\label{wxcalendardateattrgetborder}
 464
 465 \constfunc{wxCalendarDateBorder}{GetBorder}{\void}
 466
 467 Returns the \helpref{border}{wxcalendardateattr} to use for the item with this attribute.
 468
 469
 470 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 471
 472 \section{\class{wxCalendarEvent}}\label{wxcalendarevent}
 473
 474 The wxCalendarEvent class is used together with
 475 \helpref{wxCalendarCtrl}{wxcalendarctrl}.
 476
 477 \wxheading{Derived from}
 478
 479 \helpref{wxDateEvent}{wxdateevent}\\
 480 \helpref{wxCommandEvent}{wxcommandevent}\\
 481 \helpref{wxEvent}{wxevent}\\
 482 \helpref{wxObject}{wxobject}
 483
 484 \wxheading{Include files}
 485
 486 <wx/calctrl.h>
 487
 488 \wxheading{See also}
 489
 490 \helpref{wxCalendarCtrl}{wxcalendarctrl}
 491
 492 \latexignore{\rtfignore{\wxheading{Members}}}
 493
 494
 495 \membersection{wxCalendarEvent::GetWeekDay}\label{wxcalendareventgetweekday}
 496
 497 \constfunc{wxDateTime::WeekDay}{GetWeekDay}{\void}
 498
 499 Returns the week day on which the user clicked in
 500 {\tt EVT\_CALENDAR\_WEEKDAY\_CLICKED} handler. It doesn't make sense to call
 501 this function in other handlers.
 502
 503
 504 \membersection{wxCalendarEvent::SetWeekDay}\label{wxcalendareventsetweekday}
 505
 506 \func{void}{SetWeekDay}{\param{wxDateTime::WeekDay}{ day}}
 507
 508 Sets the week day carried by the event, normally only used by the library
 509 internally.
 510