gtk.Calendar
Prev | The gtk Class Reference | Next

## gtk.Calendar

gtk.Calendar — a widget that displays a calendar and allows the user to select a date.

## Synopsis

    class gtk.Calendar(gtk.Widget):
        gtk.Calendar()
        def select_month(month, year)
        def select_day(day)
        def mark_day(day)
        def unmark_day(day)
        def clear_marks()
        def get_display_options()
        def set_display_options(flags)
        def get_detail_height_rows()
        def set_detail_height_rows(rows)
        def get_detail_width_chars()
        def set_detail_width_chars(chars)
        def display_options(flags)
        def get_date()
        def freeze()
        def thaw()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.Widget
          +-- gtk.Calendar

## Implemented Interfaces

`gtk.Calendar` implements `gtk.Buildable`

## gtk.Calendar Properties

gtk.Object Properties

gtk.Widget Properties

### Note

These properties are available in GTK+ 2.4 and above.

"day" | Read-Write | The selected day (as a number between 1 and 31, or 0 to unselect the currently selected day).
"detail-height-rows" | Read-Write | Height of a detail cell, in rows. A value of 0 allows any width. See gtk_calendar_set_detail_func(). Allowed values: [0,127]. Default value: 0 .This property is available in GTK+ 2.14 and above.
"detail-width-chars" | Read-Write | Width of a detail cell, in characters. A value of 0 allows any width. See gtk_calendar_set_detail_func(). Allowed values: [0,127] Default value: 0. This property is available in GTK+ 2.14 and above.
"month" | Read-Write | The selected month (as a number between 0 and 11).
"no-month-change" | Read-Write | If `True` the selected month cannot be changed.
"show-day-names" | Read-Write | If `True`, day names are displayed.
"show-details" | Read-Write | Determines whether details are shown directly in the widget, or if they are available only as tooltip. When this property is set days with details are marked. Default value: `True`. This property is available in GTK+ 2.14 and above.
"show-heading" | Read-Write | If `True`, a heading is displayed.
"show-week-numbers" | Read-Write | If `True`, week numbers are displayed.
"year" | Read-Write | The selected year.

## gtk.Calendar Style Properties

gtk.Widget Style Properties

"horizontal-separation" | Read | Separation between week headers and main area. Allowed values: >=0. Default value: 4.
"inner-border" | Read | The spacing around the day/week headers and main area. Allowed values: >=0. Default value: 2.
"vertical-separation" | Read | Space between day headers and main area. Allowed values: >=0. Default value: 2.

## gtk.Calendar Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

gtk.Widget Signal Prototypes

"day-selected" | `def callback(`calendar`, `user_param1`, `...`)`
"day-selected-double-click" | `def callback(`calendar`, `user_param1`, `...`)`
"month-changed" | `def callback(`calendar`, `user_param1`, `...`)`
"next-month" | `def callback(`calendar`, `user_param1`, `...`)`
"next-year" | `def callback(`calendar`, `user_param1`, `...`)`
"prev-month" | `def callback(`calendar`, `user_param1`, `...`)`
"prev-year" | `def callback(`calendar`, `user_param1`, `...`)`

## Description

The `gtk.Calendar` is a widget that displays a simple calendar, one month at a time. In addition, the calendar can display the days of the week and navigation controls that allow a user to change the month and year displayed by calling the `display_options`() (`set_display_options`() in PyGTK 2.4 and above) method. The possible display options are:

`gtk.CALENDAR_SHOW_HEADING` | Specifies that the month and year should be displayed.
`gtk.CALENDAR_SHOW_DAY_NAMES` | Specifies that three letter day descriptions should be present.
`gtk.CALENDAR_NO_MONTH_CHANGE` | Prevents the user from switching months with the calendar.
`gtk.CALENDAR_SHOW_WEEK_NUMBERS` | Displays each week numbers of the current year, down the left side of the calendar.
`gtk.CALENDAR_WEEK_START_MONDAY` | Starts the calendar week on Monday, instead of the default Sunday.

The month and year currently displayed are programatically changed by calling the `select_month`() method. The exact day is selected from the displayed month using the `select_day`() method.

To place a visual marker on a particular day, use the `mark_day`() method and to remove the marker, the `unmark_day`() method. All marks are cleared by calling the `clear_marks`() method.

The selected date can be retrieved from a `gtk.Calendar` using the `get_date`() method. If performing many 'mark' operations, the calendar can be frozen to prevent flicker, using the `freeze`() method, and 'thawed' again using the `thaw`() method.

### Note

Note that month is zero-based (i.e it allowed values are 0-11) while selected_day is one-based (i.e. allowed values are 1-31).

## Constructor

        gtk.Calendar()

Returns : | a calendar object

Creates a calendar object that displays the current month and year with the current day selected. The default calendar display style is: gtk.CALENDAR_SHOW_HEADING | gtk.CALENDAR_SHOW_DAY_NAMES that shows the days of the week and the month and year heading with navigation controls.

## Methods

### gtk.Calendar.select_month

        def select_month(month, year)

`month` : | the new month number between 0 and 11
`year` : | the new year number
Returns : | True if the month is set

The `select_month`() method changes the calendar display to the specified `month` and `year`.

### gtk.Calendar.select_day

        def select_day(day)

`day` : | the new day number between 1 and 31 - 0 removes the current selection

The `select_day`() method selects the specified `day` on the calendar when `day` has a value between 1 and 31. If `day` is 0 then the current day selection is removed.

### gtk.Calendar.mark_day

        def mark_day(day)

`day` : | the number of the day to be marked
Returns : | True

The `mark_day`() method marks the specified month `day` with a visual marker (typically by making the number bold). If the calendar month and year are changed the marked days remain marked.

### gtk.Calendar.unmark_day

        def unmark_day(day)

`day` : | the number of the day to be unmarked
Returns : | True

The `unmark_day`() method unmarks the specified month `day`.

### gtk.Calendar.clear_marks

        def clear_marks()

The `clear_marks`() method clears all marked days.

### gtk.Calendar.get_display_options

        def get_display_options()

Returns : | the calendar display options

### Note

This method is available in PyGTK 2.4 and above.

The `get_display_options`() method returns the current calendar display options. See the `set_display_options`() method for more information.

### gtk.Calendar.set_display_options

        def set_display_options(flags)

`flags` : | the new calendar display options

### Note

This method is available in PyGTK 2.4 and above.

The `set_display_options`() method sets the calendar display options to the value specified by `flags`. The possible display options are a combination of:

`gtk.CALENDAR_SHOW_HEADING` | Specifies that the month and year should be displayed.
`gtk.CALENDAR_SHOW_DAY_NAMES` | Specifies that three letter day descriptions should be present.
`gtk.CALENDAR_NO_MONTH_CHANGE` | Prevents the user from switching months with the calendar.
`gtk.CALENDAR_SHOW_WEEK_NUMBERS` | Displays each week numbers of the current year, down the left side of the calendar.
`gtk.CALENDAR_WEEK_START_MONDAY` | Starts the calendar week on Monday, instead of the default Sunday.

The display options can be removed by passing 0 as the value of `flags`.

### gtk.Calendar.get_detail_height_rows

        def get_detail_height_rows()

Returns : | The height of detail cells, in rows.

### Note

This method is available in PyGTK 2.14 and above.

The `get_detail_height_rows`() method queries the height of detail cells, in rows. See the "detail-width-chars" property.

### gtk.Calendar.set_detail_height_rows

        def set_detail_height_rows(rows)

`rows` : | detail height in rows.

### Note

This method is available in PyGTK 2.14 and above.

The `set_detail_height_rows`() method updates the height of detail cells. See the "detail-height-rows" property.

### gtk.Calendar.get_detail_width_chars

        def get_detail_width_chars()

Returns : | The width of detail cells, in characters.

### Note

This method is available in PyGTK 2.14 and above.

The `get_detail_width_chars`() method queries the width of detail cells, in characters. See the "detail-width-chars" property.

### gtk.Calendar.set_detail_width_chars

        def set_detail_width_chars(chars)

`chars` : | detail width in characters.

### Note

This method is available in PyGTK 2.14 and above.

The `set_detail_width_chars`() method updates the width of detail cells. See the "detail-width-chars" property.

### gtk.Calendar.display_options

        def display_options(flags)

`flags` : | the new calendar display options

### Warning

This method is deprecated in PyGTK 2.4 and should be replaced by the `set_display_options`() method.

The `display_options`() method sets the calendar display options to the value specified by `flags`. The possible display options are a combination of:

`gtk.CALENDAR_SHOW_HEADING` | Specifies that the month and year should be displayed.
`gtk.CALENDAR_SHOW_DAY_NAMES` | Specifies that three letter day descriptions should be present.
`gtk.CALENDAR_NO_MONTH_CHANGE` | Prevents the user from switching months with the calendar.
`gtk.CALENDAR_SHOW_WEEK_NUMBERS` | Displays each week numbers of the current year, down the left side of the calendar.
`gtk.CALENDAR_WEEK_START_MONDAY` | Starts the calendar week on Monday, instead of the default Sunday.

The display options can be removed by passing 0 as the value of `flags`.

### gtk.Calendar.get_date

        def get_date()

Returns : | a tuple containing the year, month and day

The `get_date`() method retrieves the calendar's current year, month and selected day numbers as a tuple (year, month, day).

### Note

Note that month is zero-based (i.e it allowed values are 0-11) while selected_day is one-based (i.e. allowed values are 1-31).

### gtk.Calendar.freeze

        def freeze()

### Warning

This method is deprecated since PyGTK 2.8 and should not be used in newly-written code.

The `freeze`() method stops the update of the calendar display until the `thaw`() method is called. This method is used to reduce calendar flicker when doing a large number of updates to the calendar.

### gtk.Calendar.thaw

        def thaw()

### Warning

This method is deprecated since PyGTK 2.8 and should not be used in newly-written code.

The `thaw`() method reenables the update of the calendar after a `freeze`() method is called. All changes made since the last `freeze`() are displayed

## Signals

### The "day-selected" gtk.Calendar Signal

        def callback(calendar, user_param1, ...)

`calendar` : | the calendar that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "day-selected" signal is emitted when a day is selected either by the user or programatically.

### The "day-selected-double-click" gtk.Calendar Signal

        def callback(calendar, user_param1, ...)

`calendar` : | the calendar that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "day-selected-double-click" signal is emitted when a calendar day is doubled-clicked by the user.

### The "month-changed" gtk.Calendar Signal

        def callback(calendar, user_param1, ...)

`calendar` : | the calendar that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "month-changed" signal is emitted when the calendar month is changed programatically or by the user.

### The "next-month" gtk.Calendar Signal

        def callback(calendar, user_param1, ...)

`calendar` : | the calendar that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "next-month" signal is emitted when the user clicks the "next-month" navigation control in the calendar header.

### The "next-year" gtk.Calendar Signal

        def callback(calendar, user_param1, ...)

`calendar` : | the calendar that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "next-year" signal is emitted when the user clicks the "next-year" navigation control in the calendar header.

### The "prev-month" gtk.Calendar Signal

        def callback(calendar, user_param1, ...)

`calendar` : | the calendar that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "prev-month" signal is emitted when the user clicks the "prev-month" navigation control in the calendar header.

### The "prev-year" gtk.Calendar Signal

        def callback(calendar, user_param1, ...)

`calendar` : | the calendar that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "prev-year" signal is emitted when the user clicks the "prev-year" navigation control in the calendar header.

Prev | Up | Next
gtk.ButtonBox | Home | gtk.CellEditable