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