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:

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';

Gtk2->main;

0;