A Calendar widget allows for displaying and retrival of date information. It can be configured in many ways and is a relatively powerful widget.


The Calendar can be constructed using the following:

calendar = Gtk.Calendar()


The date can be retrieved from the Calendar using:


The date will be returned in comma-seperated format. The day value will be between 1 and 31, the month will be between 0 and 11 and the date will be in four-digit number format.

To select a specific day on the Calendar call:


Alternatively, to set a month and year call:

calendar.select_month(month, year)

To configure the view of the Calendar, the following method can be used:


The flags parameter can take the following parameters; Gtk.CalendarDisplayOptions.SHOW_HEADING configures whether the month and year should be displayed, Gtk.CalendarDisplayOptions.SHOW_DAY_NAMES specifies whether the three letter day description should be present, Gtk.CalendarDisplayOptions.NO_MONTH_CHANGE prevents the user from changing the month. Gtk.CalendarDisplayOptions.SHOW_WEEK_NUMBERS sets the calendar to display the week number down the left-side of the Calendar and Gtk.CalendarDisplayOptions.SHOW_DETAILS sets the calendar to show an indicator as opposed to the full details text. When multiple flags are required, they should be a seperated by a ‘|’ character.

The defined display options can be retrieved from the Calendar using:


A day can be marked or unmarked by specifying the day integer:


To check whether a day is marked, use:


All day marks can be cleared from the Calendar via the method:


Extra information can be displayed on the Calendar, such as appointments, birthdays, holidays, etc. This is done by specifying a function which handles the detail values. This is specified with:

calendar.set_detail_func(function, data, destroy)

Detail information is only shown on the Calendar when the Gtk.CalendarDisplayOptions.SHOW_DETAILS parameter is set.

Sizing values can be set with the methods:


The width value defines the number of pixels permitted for displaying of detail information. The height integer sets the number of rows of information to show.


The commonly used signals of a Calendar are:

"day-selected" (calendar)
"day-selected-double-click" (calendar)
"month-changed" (calendar)
"next-month" (calendar)
"next-year" (calendar)
"prev-month" (calendar)
"prev-year" (calendar)

The "day-selected" and "day-selected-double-click" signals emit from the Calendar when the user clicks or double clicks on a date. A "month-changed" signal is emitted when the user changes months and year. The signals "next-month", "next-year", "prev-month", and "prev-year" emit whenever the users moves back or forward on a month or year basis.


Below is an example of a Calendar:

#!/usr/bin/env python3

from gi.repository import Gtk

class Calendar(Gtk.Window):
    def __init__(self):
        self.connect("destroy", Gtk.main_quit)

        hbox = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=2)

        self.calendar = Gtk.Calendar()
        self.calendar.connect("day-selected-double-click", self.on_date_selected)
        hbox.pack_start(self.calendar, True, True, 0)

        vbox = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=2)
        hbox.pack_start(vbox, False, False, 0)

        checkbuttonHeading = Gtk.CheckButton(label="Show Heading")
        checkbuttonHeading.connect("toggled", self.on_show_heading_change)
        vbox.pack_start(checkbuttonHeading, False, False, 0)

        checkbuttonDayNames = Gtk.CheckButton(label="Show Day Names")
        checkbuttonDayNames.connect("toggled", self.on_show_days_change)
        vbox.pack_start(checkbuttonDayNames, False, False, 0)

        checkbuttonPreventChange = Gtk.CheckButton(label="Prevent Month/Year Change")
        checkbuttonPreventChange.connect("toggled", self.on_prevent_month_change)
        vbox.pack_start(checkbuttonPreventChange, False, False, 0)

        checkbuttonShowWeeks = Gtk.CheckButton(label="Show Week Numbers")
        checkbuttonShowWeeks.connect("toggled", self.on_show_weeks_change)
        vbox.pack_start(checkbuttonShowWeeks, False, False, 0)

    def on_date_selected(self, calendar):
        year, month, day = self.calendar.get_date()
        month += 1

        print("Date selected: %i/%i/%i" % (year, month, day))

    def on_show_heading_change(self, checkbutton):
        self.calendar.set_property("show-heading", checkbutton.get_active())

    def on_show_days_change(self, checkbutton):
        self.calendar.set_property("show-day-names", checkbutton.get_active())

    def on_prevent_month_change(self, checkbutton):
        self.calendar.set_property("no-month-change", checkbutton.get_active())

    def on_show_weeks_change(self, checkbutton):
        self.calendar.set_property("show-week-numbers", checkbutton.get_active())

window = Calendar()


Download: Calendar