11. Calendar

The Calendar widget is an effective way to display and retrieve monthly date related information. It is a very simple widget to create and work with.

Creating a GtkCalendar widget is a simple as:

GtkWidget *gtk_calendar_new( void );

There might be times where you need to change a lot of information within this widget and the following functions allow you to make multiple change to a Calendar widget without the user seeing multiple on-screen updates.

void gtk_calendar_freeze( GtkCalendar *Calendar );

void gtk_calendar_thaw( GtkCalendar *Calendar );

They work just like the freeze/thaw functions of every other widget.

The Calendar widget has a few options that allow you to change the way the widget both looks and operates by using the function

void gtk_calendar_display_options( GtkCalendar               *calendar,
                                   GtkCalendarDisplayOptions  flags );

The flags argument can be formed by combining either of the following five options using the logical bitwise OR (|) operation:


this option specifies that the month and year should be shown when drawing the calendar.


this option specifies that the three letter descriptions should be displayed for each day (eg Mon,Tue, etc.).


this option states that the user should not and can not change the currently displayed month. This can be good if you only need to display a particular month such as if you are displaying 12 calendar widgets for every month in a particular year.


this option specifies that the number for each week should be displayed down the left side of the calendar. (eg. Jan 1 = Week 1,Dec 31 = Week 52).


this option states that the calander week will start on Monday instead of Sunday which is the default. This only affects the order in which days are displayed from left to right.

The following functions are used to set the the currently displayed date:

gint gtk_calendar_select_month( GtkCalendar *calendar, 
                                guint        month,
                                guint        year );

void gtk_calendar_select_day( GtkCalendar *calendar,
                              guint        day );

The return value from gtk_calendar_select_month() is a boolean value indicating whether the selection was successful.

With gtk_calendar_select_day() the specified day number is selected within the current month, if that is possible. A day value of 0 will deselect any current selection.

In addition to having a day selected, any number of days in the month may be "marked". A marked day is highlighted within the calendar display. The following functions are provided to manipulate marked days:

gint gtk_calendar_mark_day( GtkCalendar *calendar,
                            guint        day);

gint gtk_calendar_unmark_day( GtkCalendar *calendar,
                              guint        day);

void gtk_calendar_clear_marks( GtkCalendar *calendar);

The currently marked days are stored within an array within the GtkCalendar structure. This array is 31 elements long so to test whether a particular day is currently marked, you need to access the corresponding element of the array (don't forget in C that array elements are numbered 0 to n-1). For example:

    GtkCalendar *calendar;
    calendar = gtk_calendar_new ();


    /* Is day 7 marked? */
    if (calendar->marked_date[7-1])
       /* day is marked */

Note that marks are persistent across month and year changes.

The final Calendar widget function is used to retrieve the currently selected date, month and/or year.

void gtk_calendar_get_date( GtkCalendar *calendar, 
                            guint       *year,
                            guint       *month,
                            guint       *day );

This function requires you to pass the addresses of guint variables, into which the result will be placed. Passing NULL as a value will result in the corresponding value not being returned.

The Calendar widget can generate a number of signals indicating date selection and change. The names of these signals are self explanatory, and are:

That just leaves us with the need to put all of this together into example code.

use Glib qw/TRUE FALSE/;
use Gtk2 '-init';