<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id="class-gtkcalendar">
  <refnamediv>
    <refname>gtk.Calendar</refname>
    <refpurpose>a widget that displays a calendar and allows the user to
select a date.</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.Calendar</classname></ooclass>
      <ooclass><classname><link
linkend="class-gtkwidget">gtk.Widget</link></classname></ooclass>
      <constructorsynopsis language="python">
	<methodname><link
linkend="constructor-gtkcalendar">gtk.Calendar</link></methodname>
	<methodparam></methodparam>  </constructorsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--select-month">select_month</link></methodname>
	<methodparam><parameter
		       role="keyword">month</parameter></methodparam>
	<methodparam><parameter
		       role="keyword">year</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--select-day">select_day</link></methodname>
	<methodparam><parameter role="keyword">day</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--mark-day">mark_day</link></methodname>
	<methodparam><parameter role="keyword">day</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--unmark-day">unmark_day</link></methodname>
	<methodparam><parameter role="keyword">day</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--clear-marks">clear_marks</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--get-display-options">get_display_options</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--set-display-options">set_display_options</link></methodname>
	<methodparam><parameter
		       role="keyword">flags</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--get-detail-height-rows">get_detail_height_rows</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--set-detail-height-rows">set_detail_height_rows</link></methodname>
	<methodparam><parameter
		       role="keyword">rows</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--get-detail-width-chars">get_detail_width_chars</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--set-detail-width-chars">set_detail_width_chars</link></methodname>
	<methodparam><parameter
		       role="keyword">chars</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--display-options">display_options</link></methodname>
	<methodparam><parameter
		       role="keyword">flags</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--get-date">get_date</link></methodname>
	<methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--freeze">freeze</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
      <methodsynopsis language="python">
	<methodname><link
linkend="method-gtkcalendar--thaw">thaw</link></methodname>
	<methodparam></methodparam>  </methodsynopsis>
    </classsynopsis>

  </refsect1>

  <refsect1>
    <title>Ancestry</title>

<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
  +-- <link linkend="class-gtkobject">gtk.Object</link>
    +-- <link linkend="class-gtkwidget">gtk.Widget</link>
      +-- <link linkend="class-gtkcalendar">gtk.Calendar</link>
</synopsis>
  
  </refsect1>
  
  <refsect1>
		<title>Implemented Interfaces</title>
		<para>
			<link linkend="class-gtkcalendar"><classname>gtk.Calendar</classname></link>
			implements 
			<link linkend="class-gtkbuildable"><classname>gtk.Buildable</classname></link>
		</para>
	</refsect1>
  
  
  <refsect1 id="properties-gtkcalendar">
    <title>gtk.Calendar Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>
    <para><link linkend="properties-gtkwidget">gtk.Widget Properties</link></para>

    <note>
      <para>These properties are available in GTK+ 2.4 and above.</para>
    </note>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="4in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"day"</entry>
	      <entry>Read-Write</entry>
	      <entry>The selected day (as a number between 1 and 31, or 0 to
unselect the currently selected day).</entry>
	    </row>

	    <row valign="top">
	      <entry>"detail-height-rows"</entry>
	      <entry>Read-Write</entry>
	      <entry>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.</entry>
	    </row>
	    
	    <row valign="top">
	      <entry>"detail-width-chars"</entry>
	      <entry>Read-Write</entry>
	      <entry>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.</entry>
	    </row>

	    <row valign="top">
	      <entry>"month"</entry>
	      <entry>Read-Write</entry>
	      <entry>The selected month (as a number between 0 and 11).</entry>
	    </row>

	    <row valign="top">
	      <entry>"no-month-change"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal> the selected month cannot be
changed.</entry>
	    </row>

	    <row valign="top">
	      <entry>"show-day-names"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, day names are
displayed.</entry>
	    </row>

	    <row valign="top">
	      <entry>"show-details"</entry>
	      <entry>Read-Write</entry>
	      <entry>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: <literal>True</literal>.
              This property is available in GTK+ 2.14 and above.</entry>
	    </row>

	    <row valign="top">
	      <entry>"show-heading"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, a heading is
displayed.</entry>
	    </row>

	    <row valign="top">
	      <entry>"show-week-numbers"</entry>
	      <entry>Read-Write</entry>
	      <entry>If <literal>True</literal>, week numbers are
displayed.</entry>
	    </row>

	    <row valign="top">
	      <entry>"year"</entry>
	      <entry>Read-Write</entry>
	      <entry>The selected year.</entry>
	    </row>

	  </tbody>
	</tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="style-properties-gtkcalendar">
    <title>gtk.Calendar Style Properties</title>

    <para><link linkend="style-properties-gtkwidget">gtk.Widget Style Properties</link></para>

    <blockquote role="properties">
      <informaltable pgwide="1" frame="none">
	<tgroup cols="3">
	  <colspec column="1" colwidth="1in"/>
	  <colspec column="2" colwidth="1in"/>
	  <colspec column="3" colwidth="3.5in"/>
	  <tbody>

	    <row valign="top">
	      <entry>"horizontal-separation"</entry>
	      <entry>Read</entry>
	      <entry>Separation between week headers and main area. Allowed values: &#62;=0. Default value: 4.</entry>
	    </row>

	    <row valign="top">
	      <entry>"inner-border"</entry>
	      <entry>Read</entry>
	      <entry>The spacing around the day/week headers and main area. Allowed values: &#62;=0. Default value: 2.</entry>
	    </row>

	    <row valign="top">
	      <entry>"vertical-separation"</entry>
	      <entry>Read</entry>
	      <entry>Space between day headers and main area. Allowed values: &#62;=0. Default value: 2.</entry>
	    </row>

	</tbody>
      </tgroup>
      </informaltable>
    </blockquote>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkcalendar">
    <title>gtk.Calendar Signal Prototypes</title>

    <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para>
    <para><link linkend="signal-prototypes-gtkwidget">gtk.Widget Signal Prototypes</link></para>

    <variablelist>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcalendar--day-selected">day-selected</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>calendar</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcalendar--day-selected-double-click">day-selected-double-click</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>calendar</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcalendar--month-changed">month-changed</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>calendar</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcalendar--next-month">next-month</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>calendar</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcalendar--next-year">next-year</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>calendar</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcalendar--prev-month">prev-month</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>calendar</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>"<link
linkend="signal-gtkcalendar--prev-year">prev-year</link>"</term>
        <listitem>
          <methodsynopsis
	    language="python"><methodname>callback</methodname>
            <methodparam><parameter>calendar</parameter>
            </methodparam>
            <methodparam><parameter>user_param1</parameter>
            </methodparam>
            <methodparam><parameter>...</parameter>
            </methodparam>
          </methodsynopsis>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>The <link
linkend="class-gtkcalendar"><classname>gtk.Calendar</classname></link> 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 <link
linkend="method-gtkcalendar--display-options"><methodname>display_options</methodname>()</link>
(<link
linkend="method-gtkcalendar--set-display-options"><methodname>set_display_options</methodname>()</link>
in PyGTK 2.4 and above) method. The possible display options are:</para>

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

    <para>The month and year currently displayed are programatically
changed by calling the <link
linkend="method-gtkcalendar--select-month"><methodname>select_month</methodname>()</link> 
method. The exact day is selected from the displayed month using the <link
linkend="method-gtkcalendar--select-day"><methodname>select_day</methodname>()</link> 
method.</para>

    <para>To place a visual marker on a particular day, use the <link
linkend="method-gtkcalendar--mark-day"><methodname>mark_day</methodname>()</link> 
method and to remove the marker, the <link
linkend="method-gtkcalendar--unmark-day"><methodname>unmark_day</methodname>()</link> 
method. All marks are cleared by calling the <link
linkend="method-gtkcalendar--clear-marks"><methodname>clear_marks</methodname>()</link> 
method.</para>

    <para>The selected date can be retrieved from a <link
linkend="class-gtkcalendar"><classname>gtk.Calendar</classname></link> using
the <link
linkend="method-gtkcalendar--get-date"><methodname>get_date</methodname>()</link> 
method. If performing many 'mark' operations, the calendar can be frozen to
prevent flicker, using the <link
linkend="method-gtkcalendar--freeze"><methodname>freeze</methodname>()</link> 
method, and 'thawed' again using the <link
linkend="method-gtkcalendar--freeze"><methodname>thaw</methodname>()</link>
method.</para>
    
    <note>
      <para>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).</para>
    </note>
    
  </refsect1>

  <refsect1 id="constructor-gtkcalendar">
    <title>Constructor</title>

    <programlisting><constructorsynopsis language="python">
	<methodname>gtk.Calendar</methodname>
	<methodparam></methodparam>  </constructorsynopsis></programlisting>
    <variablelist>
      <varlistentry>
	<term><emphasis>Returns</emphasis>&nbsp;:</term>
	<listitem><simpara>a calendar object</simpara></listitem>
      </varlistentry>
    </variablelist>

    <para>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.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkcalendar--select-month">
      <title>gtk.Calendar.select_month</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>select_month</methodname>
	  <methodparam
	    role="keyword"><parameter>month</parameter></methodparam>
	  <methodparam
	    role="keyword"><parameter>year</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">month</parameter>&nbsp;:</term>
	  <listitem><simpara>the new month number between 0 and
11</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter role="keyword">year</parameter>&nbsp;:</term>
	  <listitem><simpara>the new year number</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>True if the month is set</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>select_month</methodname>() method changes the
calendar display to the specified <parameter>month</parameter> and
<parameter>year</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--select-day">
      <title>gtk.Calendar.select_day</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>select_day</methodname>
	  <methodparam><parameter
			 role="keyword">day</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">day</parameter>&nbsp;:</term>
	  <listitem><simpara>the new day number between 1 and 31 - 0 removes
the current selection</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>select_day</methodname>() method selects the
specified <parameter>day</parameter> on the calendar when
<parameter>day</parameter> has a value between 1 and 31. If
<parameter>day</parameter> is 0 then the current day selection is
removed.</para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--mark-day">
      <title>gtk.Calendar.mark_day</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>mark_day</methodname>
	  <methodparam><parameter
			 role="keyword">day</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">day</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of the day to be
marked</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>True</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="method-gtkcalendar--unmark-day">
      <title>gtk.Calendar.unmark_day</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>unmark_day</methodname>
	  <methodparam><parameter
			 role="keyword">day</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">day</parameter>&nbsp;:</term>
	  <listitem><simpara>the number of the day to be
unmarked</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>True</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>unmark_day</methodname>() method unmarks the
specified month <parameter>day</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--clear-marks">
      <title>gtk.Calendar.clear_marks</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>clear_marks</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <para>The <methodname>clear_marks</methodname>() method clears all
marked days.</para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--get-display-options">
      <title>gtk.Calendar.get_display_options</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_display_options</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>the calendar display options</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>get_display_options</methodname>() method
returns the current calendar display options. See the <link
linkend="method-gtkcalendar--set-display-options"><methodname>set_display_options</methodname>()</link>
method for more information.</para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--set-display-options">
      <title>gtk.Calendar.set_display_options</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_display_options</methodname>
	  <methodparam><parameter
			 role="keyword">flags</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
	  <listitem><simpara>the new calendar display
options</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.4 and above.</para>
      </note>

      <para>The <methodname>set_display_options</methodname>() method sets the
calendar display options to the value specified by
<parameter>flags</parameter>. The possible display options are a combination
of:</para>

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

      <para>The display options can be removed by passing 0 as the value of
<parameter>flags</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--get-detail-height-rows">
      <title>gtk.Calendar.get_detail_height_rows</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_detail_height_rows</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The height of detail cells, in rows.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
        The <methodname>get_detail_height_rows</methodname>() method
        queries the height of detail cells, in rows. See the "detail-width-chars" property.
      </para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--set-detail-height-rows">
      <title>gtk.Calendar.set_detail_height_rows</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_detail_height_rows</methodname>
	  <methodparam><parameter
			 role="keyword">rows</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">rows</parameter>&nbsp;:</term>
	  <listitem><simpara>detail height in rows.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
        The <methodname>set_detail_height_rows</methodname>() method
        updates the height of detail cells. See the "detail-height-rows" property.
      </para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--get-detail-width-chars">
      <title>gtk.Calendar.get_detail_width_chars</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_detail_width_chars</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>The width of detail cells, in characters.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
        The <methodname>get_detail_width_chars</methodname>() method
        queries the width of detail cells, in characters. See the "detail-width-chars" property.
      </para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--set-detail-width-chars">
      <title>gtk.Calendar.set_detail_width_chars</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>set_detail_width_chars</methodname>
	  <methodparam><parameter
			 role="keyword">chars</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">chars</parameter>&nbsp;:</term>
	  <listitem><simpara>detail width in characters.</simpara></listitem>
	</varlistentry>
      </variablelist>

      <note>
	<para>This method is available in PyGTK 2.14 and above.</para>
      </note>

      <para>
        The <methodname>set_detail_width_chars</methodname>() method
        updates the width of detail cells. See the "detail-width-chars" property.
      </para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--display-options">
      <title>gtk.Calendar.display_options</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>display_options</methodname>
	  <methodparam><parameter
			 role="keyword">flags</parameter></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><parameter role="keyword">flags</parameter>&nbsp;:</term>
	  <listitem><simpara>the new calendar display
options</simpara></listitem>
	</varlistentry>
      </variablelist>

      <warning>
	<para>This method is deprecated in PyGTK 2.4 and should be replaced
	by the <link
	linkend="method-gtkcalendar--set-display-options"><methodname>set_display_options</methodname>()</link>
	method.</para>
      </warning>

      <para>The <methodname>display_options</methodname>() method sets the
calendar display options to the value specified by
<parameter>flags</parameter>. The possible display options are a combination
of:</para>

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

      <para>The display options can be removed by passing 0 as the value of
<parameter>flags</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--get-date">
      <title>gtk.Calendar.get_date</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>get_date</methodname>
	  <methodparam></methodparam>
	</methodsynopsis></programlisting>
      <variablelist>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</term>
	  <listitem><simpara>a tuple containing the year, month and
day</simpara></listitem>
	</varlistentry>
      </variablelist>

      <para>The <methodname>get_date</methodname>() method retrieves the
calendar's current year, month and selected day numbers as a tuple (year,
month, day).</para>
    
    <note>
      <para>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).</para>
    </note>

    </refsect2>

    <refsect2 id="method-gtkcalendar--freeze">
      <title>gtk.Calendar.freeze</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>freeze</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <warning>
        <para>This method is deprecated since PyGTK 2.8 and should not be used in newly-written code.</para>
      </warning>

      <para>The <methodname>freeze</methodname>() method stops the update of
the calendar display until the <link
linkend="method-gtkcalendar--thaw"><methodname>thaw</methodname>()</link>
method is called. This method is used to reduce calendar flicker when doing
a large number of updates to the calendar.</para>

    </refsect2>

    <refsect2 id="method-gtkcalendar--thaw">
      <title>gtk.Calendar.thaw</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>thaw</methodname>
	  <methodparam></methodparam>  </methodsynopsis></programlisting>

      <warning>
        <para>This method is deprecated since PyGTK 2.8 and should not be used in newly-written code.</para>
      </warning>

      <para>The <methodname>thaw</methodname>() method reenables the update
of the calendar after a <link
linkend="method-gtkcalendar--freeze"><methodname>freeze</methodname>()</link> 
method is called. All changes made since the last <link
linkend="method-gtkcalendar--freeze"><methodname>freeze</methodname>()</link> 
are displayed</para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Signals</title>

    <refsect2 id="signal-gtkcalendar--day-selected">
      <title>The "day-selected" gtk.Calendar Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>calendar</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>calendar</parameter>&nbsp;:</term>
	  <listitem><simpara>the calendar that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="signal-gtkcalendar--day-selected-double-click">
      <title>The "day-selected-double-click" gtk.Calendar Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>calendar</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>calendar</parameter>&nbsp;:</term>
	  <listitem><simpara>the calendar that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="signal-gtkcalendar--month-changed">
      <title>The "month-changed" gtk.Calendar Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>calendar</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>calendar</parameter>&nbsp;:</term>
	  <listitem><simpara>the calendar that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="signal-gtkcalendar--next-month">
      <title>The "next-month" gtk.Calendar Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>calendar</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>calendar</parameter>&nbsp;:</term>
	  <listitem><simpara>the calendar that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="signal-gtkcalendar--next-year">
      <title>The "next-year" gtk.Calendar Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>calendar</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>calendar</parameter>&nbsp;:</term>
	  <listitem><simpara>the calendar that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="signal-gtkcalendar--prev-month">
      <title>The "prev-month" gtk.Calendar Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>calendar</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>calendar</parameter>&nbsp;:</term>
	  <listitem><simpara>the calendar that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

    <refsect2 id="signal-gtkcalendar--prev-year">
      <title>The "prev-year" gtk.Calendar Signal</title>

      <programlisting><methodsynopsis language="python">
	  <methodname>callback</methodname>
	  <methodparam><parameter>calendar</parameter></methodparam>
	  <methodparam><parameter>user_param1</parameter></methodparam>
	  <methodparam><parameter>...</parameter></methodparam>
	</methodsynopsis></programlisting>

      <variablelist>
	<varlistentry>
	  <term><parameter>calendar</parameter>&nbsp;:</term>
	  <listitem><simpara>the calendar that received the
signal</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>user_param1</parameter>&nbsp;:</term>
          <listitem><simpara>the first user parameter (if any) specified
with the <link
linkend="method-gobject--connect"><methodname>connect</methodname>()</link>
method</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>...</parameter>&nbsp;:</term>
	  <listitem><simpara>additional user parameters (if
any)</simpara></listitem>
	</varlistentry>
      </variablelist>

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

    </refsect2>

  </refsect1>

</refentry>
