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