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