.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 by Total Control Software
License: wxWindows License
.. include:: headings.inc
.. _wx.adv.CalendarCtrl:
==========================================================================================================================================
|phoenix_title| **wx.adv.CalendarCtrl**
==========================================================================================================================================
The calendar control allows the user to pick a date.
The user can move the current selection using the keyboard and select the date (generating ``EVT_CALENDAR`` event) by pressing ``<Return>`` or double clicking it.
Generic calendar has advanced possibilities for the customization of its display, described below. If you want to use these possibilities on every platform, use GenericCalendarCtrl instead of :ref:`wx.adv.CalendarCtrl`.
All global settings (such as colours and fonts used) can, of course, be changed. But also, the display style for each day in the month can be set independently using :ref:`wx.adv.CalendarDateAttr` class.
An item without custom attributes is drawn with the default colours and font and without border, but setting custom attributes with :meth:`~wx.adv.CalendarCtrl.SetAttr` allows modifying its appearance. Just create a custom attribute object and set it for the day you want to be displayed specially (note that the control will take ownership of the pointer, i.e. it will delete it itself). A day may be marked as being a holiday, even if it is not recognized as one by :ref:`wx.DateTime` using the :meth:`wx.adv.CalendarDateAttr.SetHoliday` method.
As the attributes are specified for each day, they may change when the month is changed, so you will often want to update them in ``EVT_CALENDAR_PAGE_CHANGED`` event handler.
.. _CalendarCtrl-styles:
|styles| Window Styles
================================
This class supports the following styles:
- ``wx.adv.CAL_SUNDAY_FIRST``: Show Sunday as the first day in the week (not in wxGTK)
- ``wx.adv.CAL_MONDAY_FIRST``: Show Monday as the first day in the week (not in wxGTK)
- ``wx.adv.CAL_SHOW_HOLIDAYS``: Highlight holidays in the calendar (only generic)
- ``wx.adv.CAL_NO_YEAR_CHANGE``: Disable the year changing (deprecated, only generic)
- ``wx.adv.CAL_NO_MONTH_CHANGE``: Disable the month (and, implicitly, the year) changing
- ``wx.adv.CAL_SHOW_SURROUNDING_WEEKS``: Show the neighbouring weeks in the previous and next months (only generic, always on for the native controls)
- ``wx.adv.CAL_SEQUENTIAL_MONTH_SELECTION``: Use alternative, more compact, style for the month and year selection controls. (only generic)
- ``wx.adv.CAL_SHOW_WEEK_NUMBERS``: Show week numbers on the left side of the calendar. (not in generic)
.. _CalendarCtrl-events:
|events| Events Emitted by this Class
=====================================
Handlers bound for the following event types will receive a :ref:`wx.adv.CalendarEvent` parameter.
- EVT_CALENDAR: A day was double clicked in the calendar.
- EVT_CALENDAR_SEL_CHANGED: The selected date changed.
- EVT_CALENDAR_PAGE_CHANGED: The selected month (and/or year) changed.
- EVT_CALENDAR_WEEKDAY_CLICKED: User clicked on the week day header (only generic).
- EVT_CALENDAR_WEEK_CLICKED: User clicked on the week of the year number (only generic).
Implementations:GTK, MSW ports; a generic implementation is used elsewhere.
.. note::
Changing the selected date will trigger an ``EVT_CALENDAR_DAY``, ``MONTH`` or ``YEAR`` event as well as an ``EVT_CALENDAR_SEL_CHANGED`` event.
.. seealso:: :ref:`Calendar Sample <calendar sample>`, :ref:`wx.adv.CalendarDateAttr`, :ref:`wx.adv.CalendarEvent`, :ref:`wx.adv.DatePickerCtrl`
|
|class_hierarchy| Class Hierarchy
=================================
.. raw:: html
<div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
<img id="toggleBlock-trigger" src="_static/images/closed.png"/>
Inheritance diagram for class <strong>CalendarCtrl</strong>:
</div>
<div id="toggleBlock-summary" style="display:block;"></div>
<div id="toggleBlock-content" style="display:none;">
<p class="graphviz">
<center><img src="_static/images/inheritance/wx.adv.CalendarCtrl_inheritance.png" alt="Inheritance diagram of CalendarCtrl" usemap="#dummy" class="inheritance"/></center>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.adv.CalendarCtrl.html" title="The calendar control allows the user to pick a date." alt="" coords="32,315,189,344"/> <area shape="rect" id="node2" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="64,237,157,267"/> <area shape="rect" id="node3" href="wx.Window.html" title="wx.Window is the base class for all windows and represents any visible object on screen." alt="" coords="62,160,159,189"/> <area shape="rect" id="node4" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="51,83,170,112"/> <area shape="rect" id="node5" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="5,5,93,35"/> <area shape="rect" id="node6" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="118,5,229,35"/> </map>
</p>
</div>
|
|appearance| Control Appearance
===============================
|
.. figure:: _static/images/widgets/fullsize/wxmsw/wx.adv.calendarctrl.png
:alt: wxMSW
:figclass: floatleft
**wxMSW**
.. figure:: _static/images/widgets/fullsize/wxmac/wx.adv.calendarctrl.png
:alt: wxMAC
:figclass: floatright
**wxMAC**
.. figure:: _static/images/widgets/fullsize/wxgtk/wx.adv.calendarctrl.png
:alt: wxGTK
:figclass: floatcenter
**wxGTK**
|
|method_summary| Methods Summary
================================
================================================================================ ================================================================================
:meth:`~wx.adv.CalendarCtrl.__init__` Default constructor.
:meth:`~wx.adv.CalendarCtrl.Create` Creates the control.
:meth:`~wx.adv.CalendarCtrl.EnableHolidayDisplay` This function should be used instead of changing ``CAL_SHOW_HOLIDAYS`` style bit directly.
:meth:`~wx.adv.CalendarCtrl.EnableMonthChange` This function should be used instead of changing ``CAL_NO_MONTH_CHANGE`` style bit.
:meth:`~wx.adv.CalendarCtrl.GetAttr` Returns the attribute for the given date (should be in the range 1...31).
:meth:`~wx.adv.CalendarCtrl.GetClassDefaultAttributes`
:meth:`~wx.adv.CalendarCtrl.GetDate` Gets the currently selected date.
:meth:`~wx.adv.CalendarCtrl.GetDateRange` Returns the limits currently being used.
:meth:`~wx.adv.CalendarCtrl.GetHeaderColourBg` Gets the background colour of the header part of the calendar window.
:meth:`~wx.adv.CalendarCtrl.GetHeaderColourFg` Gets the foreground colour of the header part of the calendar window.
:meth:`~wx.adv.CalendarCtrl.GetHighlightColourBg` Gets the background highlight colour.
:meth:`~wx.adv.CalendarCtrl.GetHighlightColourFg` Gets the foreground highlight colour.
:meth:`~wx.adv.CalendarCtrl.GetHolidayColourBg` Return the background colour currently used for holiday highlighting.
:meth:`~wx.adv.CalendarCtrl.GetHolidayColourFg` Return the foreground colour currently used for holiday highlighting.
:meth:`~wx.adv.CalendarCtrl.HitTest` Returns one of CalendarHitTestResult constants and fills either `date` or `wd` pointer with the corresponding value depending on the hit test code.
:meth:`~wx.adv.CalendarCtrl.Mark` Mark or unmark the day.
:meth:`~wx.adv.CalendarCtrl.PyGetDate` Return the date as a Python datetime.date object.
:meth:`~wx.adv.CalendarCtrl.ResetAttr` Clears any attributes associated with the given day (in the range 1...31).
:meth:`~wx.adv.CalendarCtrl.SetAttr` Associates the attribute with the specified date (in the range 1...31).
:meth:`~wx.adv.CalendarCtrl.SetDate` Sets the current date.
:meth:`~wx.adv.CalendarCtrl.SetDateRange` Restrict the dates that can be selected in the control to the specified range.
:meth:`~wx.adv.CalendarCtrl.SetHeaderColours` Set the colours used for painting the weekdays at the top of the control.
:meth:`~wx.adv.CalendarCtrl.SetHighlightColours` Set the colours to be used for highlighting the currently selected date.
:meth:`~wx.adv.CalendarCtrl.SetHoliday` Marks the specified day as being a holiday in the current month.
:meth:`~wx.adv.CalendarCtrl.SetHolidayColours` Sets the colours to be used for the holidays highlighting.
================================================================================ ================================================================================
|
|property_summary| Properties Summary
=====================================
================================================================================ ================================================================================
:attr:`~wx.adv.CalendarCtrl.Date` See :meth:`~wx.adv.CalendarCtrl.GetDate` and :meth:`~wx.adv.CalendarCtrl.SetDate`
:attr:`~wx.adv.CalendarCtrl.DateRange` See :meth:`~wx.adv.CalendarCtrl.GetDateRange` and :meth:`~wx.adv.CalendarCtrl.SetDateRange`
:attr:`~wx.adv.CalendarCtrl.HeaderColourBg` See :meth:`~wx.adv.CalendarCtrl.GetHeaderColourBg`
:attr:`~wx.adv.CalendarCtrl.HeaderColourFg` See :meth:`~wx.adv.CalendarCtrl.GetHeaderColourFg`
:attr:`~wx.adv.CalendarCtrl.HighlightColourBg` See :meth:`~wx.adv.CalendarCtrl.GetHighlightColourBg`
:attr:`~wx.adv.CalendarCtrl.HighlightColourFg` See :meth:`~wx.adv.CalendarCtrl.GetHighlightColourFg`
:attr:`~wx.adv.CalendarCtrl.HolidayColourBg` See :meth:`~wx.adv.CalendarCtrl.GetHolidayColourBg`
:attr:`~wx.adv.CalendarCtrl.HolidayColourFg` See :meth:`~wx.adv.CalendarCtrl.GetHolidayColourFg`
================================================================================ ================================================================================
|
|api| Class API
===============
.. class:: wx.adv.CalendarCtrl(Control)
**Possible constructors**::
CalendarCtrl()
CalendarCtrl(parent, id=ID_ANY, date=DefaultDateTime,
pos=DefaultPosition, size=DefaultSize, style=CAL_SHOW_HOLIDAYS,
name=CalendarNameStr)
The calendar control allows the user to pick a date.
.. method:: __init__(self, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self)`
Default constructor.
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, parent, id=ID_ANY, date=DefaultDateTime, pos=DefaultPosition, size=DefaultSize, style=CAL_SHOW_HOLIDAYS, name=CalendarNameStr)`
Does the same as :meth:`Create` method.
:param `parent`:
:type `parent`: wx.Window
:param `id`:
:type `id`: wx.WindowID
:param `date`:
:type `date`: wx.DateTime
:param `pos`:
:type `pos`: wx.Point
:param `size`:
:type `size`: wx.Size
:param `style`:
:type `style`: long
:param `name`:
:type `name`: string
:html:`<hr class="overloadsep" /><br />`
.. method:: Create(self, parent, id=ID_ANY, date=DefaultDateTime, pos=DefaultPosition, size=DefaultSize, style=CAL_SHOW_HOLIDAYS, name=CalendarNameStr)
Creates the control.
See :meth:`Window.__init__` for the meaning of the parameters and the control overview for the possible styles.
:param `parent`:
:type `parent`: wx.Window
:param `id`:
:type `id`: wx.WindowID
:param `date`:
:type `date`: wx.DateTime
:param `pos`:
:type `pos`: wx.Point
:param `size`:
:type `size`: wx.Size
:param `style`:
:type `style`: long
:param `name`:
:type `name`: string
:rtype: `bool`
.. method:: EnableHolidayDisplay(self, display=True)
This function should be used instead of changing ``CAL_SHOW_HOLIDAYS`` style bit directly.
It enables or disables the special highlighting of the holidays.
:param `display`:
:type `display`: bool
.. method:: EnableMonthChange(self, enable=True)
This function should be used instead of changing ``CAL_NO_MONTH_CHANGE`` style bit.
It allows or disallows the user to change the month interactively. Note that if the month cannot be changed, the year cannot be changed neither.
:param `enable`:
:type `enable`: bool
:rtype: `bool`
:returns:
``True`` if the value of this option really changed or ``False`` if it was already set to the requested value.
.. method:: GetAttr(self, day)
Returns the attribute for the given date (should be in the range 1...31).
The returned pointer may be ``None``. Only in generic :ref:`wx.adv.CalendarCtrl`.
:param `day`:
:type `day`: int
:rtype: :ref:`wx.adv.CalendarDateAttr`
.. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
:param `variant`:
:type `variant`: wx.WindowVariant
:rtype: `VisualAttributes`
.. method:: GetDate(self)
Gets the currently selected date.
:rtype: `DateTime`
.. method:: GetDateRange(self)
Returns the limits currently being used.
:rtype: `tuple`
:returns:
( `bool`, `lowerdate`, `upperdate` )
.. seealso:: :meth:`SetDateRange`
.. method:: GetHeaderColourBg(self)
Gets the background colour of the header part of the calendar window.
This method is currently only implemented in generic :ref:`wx.adv.CalendarCtrl` and always returns ``NullColour`` in the native versions.
:rtype: `Colour`
.. seealso:: :meth:`SetHeaderColours`
.. method:: GetHeaderColourFg(self)
Gets the foreground colour of the header part of the calendar window.
This method is currently only implemented in generic :ref:`wx.adv.CalendarCtrl` and always returns ``NullColour`` in the native versions.
:rtype: `Colour`
.. seealso:: :meth:`SetHeaderColours`
.. method:: GetHighlightColourBg(self)
Gets the background highlight colour.
Only in generic :ref:`wx.adv.CalendarCtrl`.
This method is currently only implemented in generic :ref:`wx.adv.CalendarCtrl` and always returns ``NullColour`` in the native versions.
:rtype: `Colour`
.. seealso:: :meth:`SetHighlightColours`
.. method:: GetHighlightColourFg(self)
Gets the foreground highlight colour.
Only in generic :ref:`wx.adv.CalendarCtrl`.
This method is currently only implemented in generic :ref:`wx.adv.CalendarCtrl` and always returns ``NullColour`` in the native versions.
:rtype: `Colour`
.. seealso:: :meth:`SetHighlightColours`
.. method:: GetHolidayColourBg(self)
Return the background colour currently used for holiday highlighting.
Only useful with generic :ref:`wx.adv.CalendarCtrl` as native versions currently don't support holidays display at all and always return ``NullColour`` .
:rtype: `Colour`
.. seealso:: :meth:`SetHolidayColours`
.. method:: GetHolidayColourFg(self)
Return the foreground colour currently used for holiday highlighting.
Only useful with generic :ref:`wx.adv.CalendarCtrl` as native versions currently don't support holidays display at all and always return ``NullColour`` .
:rtype: `Colour`
.. seealso:: :meth:`SetHolidayColours`
.. method:: HitTest(self, pos)
Returns one of CalendarHitTestResult constants and fills either `date` or `wd` pointer with the corresponding value depending on the hit test code.
Not implemented in wxGTK currently.
:param `pos`:
:type `pos`: wx.Point
:rtype: `tuple`
:returns:
( :ref:`wx.adv.CalendarHitTestResult`, `date`, `wd` )
.. method:: Mark(self, day, mark)
Mark or unmark the day.
This day of month will be marked in every month. In generic :ref:`wx.adv.CalendarCtrl`,
:param `day`:
:type `day`: int
:param `mark`:
:type `mark`: bool
.. method:: PyGetDate(self)
Return the date as a Python datetime.date object.
.. method:: ResetAttr(self, day)
Clears any attributes associated with the given day (in the range 1...31).
Only in generic :ref:`wx.adv.CalendarCtrl`.
:param `day`:
:type `day`: int
.. method:: SetAttr(self, day, attr)
Associates the attribute with the specified date (in the range 1...31).
If the pointer is ``None``, the items attribute is cleared. Only in generic :ref:`wx.adv.CalendarCtrl`.
:param `day`:
:type `day`: int
:param `attr`:
:type `attr`: wx.adv.CalendarDateAttr
.. method:: SetDate(self, date)
Sets the current date.
The `date` parameter must be valid and in the currently valid range as set by :meth:`SetDateRange` , otherwise the current date is not changed and the function returns ``False``.
:param `date`:
:type `date`: wx.DateTime
:rtype: `bool`
.. method:: SetDateRange(self, lowerdate=DefaultDateTime, upperdate=DefaultDateTime)
Restrict the dates that can be selected in the control to the specified range.
If either date is set, the corresponding limit will be enforced and ``True`` returned. If none are set, the existing restrictions are removed and ``False`` is returned.
:param `lowerdate`: The low limit for the dates shown by the control or `wx.DefaultDateTime` .
:type `lowerdate`: wx.DateTime
:param `upperdate`: The high limit for the dates shown by the control or `wx.DefaultDateTime` .
:type `upperdate`: wx.DateTime
:rtype: `bool`
:returns:
``True`` if either limit is valid, ``False`` otherwise
.. seealso:: :meth:`GetDateRange`
.. method:: SetHeaderColours(self, colFg, colBg)
Set the colours used for painting the weekdays at the top of the control.
This method is currently only implemented in generic :ref:`wx.adv.CalendarCtrl` and does nothing in the native versions.
:param `colFg`:
:type `colFg`: wx.Colour
:param `colBg`:
:type `colBg`: wx.Colour
.. method:: SetHighlightColours(self, colFg, colBg)
Set the colours to be used for highlighting the currently selected date.
This method is currently only implemented in generic :ref:`wx.adv.CalendarCtrl` and does nothing in the native versions.
:param `colFg`:
:type `colFg`: wx.Colour
:param `colBg`:
:type `colBg`: wx.Colour
.. method:: SetHoliday(self, day)
Marks the specified day as being a holiday in the current month.
This method is only implemented in the generic version of the control and does nothing in the native ones.
:param `day`:
:type `day`: int
.. method:: SetHolidayColours(self, colFg, colBg)
Sets the colours to be used for the holidays highlighting.
This method is only implemented in the generic version of the control and does nothing in the native ones. It should also only be called if the window style includes ``CAL_SHOW_HOLIDAYS`` flag or :meth:`EnableHolidayDisplay` had been called.
:param `colFg`:
:type `colFg`: wx.Colour
:param `colBg`:
:type `colBg`: wx.Colour
.. attribute:: Date
See :meth:`~wx.adv.CalendarCtrl.GetDate` and :meth:`~wx.adv.CalendarCtrl.SetDate`
.. attribute:: DateRange
See :meth:`~wx.adv.CalendarCtrl.GetDateRange` and :meth:`~wx.adv.CalendarCtrl.SetDateRange`
.. attribute:: HeaderColourBg
See :meth:`~wx.adv.CalendarCtrl.GetHeaderColourBg`
.. attribute:: HeaderColourFg
See :meth:`~wx.adv.CalendarCtrl.GetHeaderColourFg`
.. attribute:: HighlightColourBg
See :meth:`~wx.adv.CalendarCtrl.GetHighlightColourBg`
.. attribute:: HighlightColourFg
See :meth:`~wx.adv.CalendarCtrl.GetHighlightColourFg`
.. attribute:: HolidayColourBg
See :meth:`~wx.adv.CalendarCtrl.GetHolidayColourBg`
.. attribute:: HolidayColourFg
See :meth:`~wx.adv.CalendarCtrl.GetHolidayColourFg`