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