Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkcalendar.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkCalendar
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 display a calendar and/or allow the user to select a date.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 #GtkCalendar is a widget that displays a calendar, one month at a time.
  10 It can be created with gtk_calendar_new().
  11 </para>
  12 <para>
  13 The month and year currently displayed can be altered with
  14 gtk_calendar_select_month(). The exact day can be selected from the displayed
  15 month using gtk_calendar_select_day().
  16 </para>
  17 <para>
  18 To place a visual marker on a particular day, use gtk_calendar_mark_day()
  19 and to remove the marker, gtk_calendar_unmark_day().
  20 Alternative, all marks can be cleared with gtk_calendar_clear_marks().
  21 </para>
  22 <para>
  23 The way in which the calendar itself is displayed can be altered using
  24 gtk_calendar_display_options().
  25 </para>
  26 <para>
  27 The selected date can be retrieved from a #GtkCalendar using
  28 gtk_calendar_get_date().
  29 </para>
  30 <para>
  31 If performing many 'mark' operations, the calendar can be frozen to prevent
  32 flicker, using gtk_calendar_freeze(), and 'thawed' again using
  33 gtk_calendar_thaw().
  34 </para>
  35
  36 <!-- ##### SECTION See_Also ##### -->
  37 <para>
  38
  39 </para>
  40
  41 <!-- ##### STRUCT GtkCalendar ##### -->
  42 <para>
  43 <structfield>num_marked_dates</structfield> is an integer containing the
  44 number of days that have a mark over them.
  45 </para>
  46 <para>
  47 <structfield>marked_date</structfield> is an array containing the day numbers
  48 that currently have a mark over them.
  49 </para>
  50 <para>
  51 <structfield>month</structfield>, <structfield>year</structfield>, and
  52 <structfield>selected_day</structfield> contain the currently visible month,
  53 year, and selected day respectively.
  54 </para>
  55 <para>
  56 All of these fields should be considered read only, and everything in this
  57 struct should only be modified using the functions provided below.
  58 </para>
  59
  60
  61 <!-- ##### ENUM GtkCalendarDisplayOptions ##### -->
  62 <para>
  63 <informaltable pgwide=1 frame="none" role="enum">
  64 <tgroup cols="2"><colspec colwidth="*"><colspec colwidth="8*">
  65 <tbody>
  66
  67 <row>
  68 <entry>GTK_CALENDAR_SHOW_HEADING</entry>
  69 <entry>Specifies that the month and year should be displayed.</entry>
  70 </row>
  71 <row>
  72 <entry>GTK_CALENDAR_SHOW_DAY_NAMES</entry>
  73 <entry>Specifies that three letter day descriptions should be present.</entry>
  74 </row>
  75 <row>
  76 <entry>GTK_CALENDAR_NO_MONTH_CHANGE</entry>
  77 <entry>Prevents the user from switching months with the calendar.</entry>
  78 </row>
  79 <row>
  80 <entry>GTK_CALENDAR_SHOW_WEEK_NUMBERS</entry>
  81 <entry>Displays each week numbers of the current year, down the left side of
  82 the calendar.</entry>
  83 </row>
  84 <row>
  85 <entry>GTK_CALENDAR_WEEK_START_MONDAY</entry>
  86 <entry>Starts the calendar week on Monday, instead of the default Sunday.</entry>
  87 </row>
  88
  89 </tbody></tgroup></informaltable>
  90 </para>
  91
  92 @GTK_CALENDAR_SHOW_HEADING:
  93 @GTK_CALENDAR_SHOW_DAY_NAMES:
  94 @GTK_CALENDAR_NO_MONTH_CHANGE:
  95 @GTK_CALENDAR_SHOW_WEEK_NUMBERS:
  96 @GTK_CALENDAR_WEEK_START_MONDAY:
  97
  98 <!-- ##### FUNCTION gtk_calendar_new ##### -->
  99 <para>
 100 Creates a new calendar, with the current date being selected.
 101 </para>
 102
 103 @Returns: a #GtkCalendar.
 104
 105
 106 <!-- ##### FUNCTION gtk_calendar_select_month ##### -->
 107 <para>
 108 Shifts the calendar to a different month.
 109 </para>
 110
 111 @calendar: a #GtkCalendar.
 112 @month: a month number.
 113 @year: the year the month is in.
 114 @Returns: %TRUE.
 115
 116
 117 <!-- ##### FUNCTION gtk_calendar_select_day ##### -->
 118 <para>
 119 Selects a day from the current month.
 120 </para>
 121
 122 @calendar: a #GtkCalendar.
 123 @day: the day number to select.
 124
 125
 126 <!-- ##### FUNCTION gtk_calendar_mark_day ##### -->
 127 <para>
 128 Places a visual marker on a particular day.
 129 </para>
 130
 131 @calendar: a #GtkCalendar.
 132 @day: the day number to mark.
 133 @Returns: %TRUE.
 134
 135
 136 <!-- ##### FUNCTION gtk_calendar_unmark_day ##### -->
 137 <para>
 138 Removes the visual marker from a particular day.
 139 </para>
 140
 141 @calendar: a #GtkCalendar.
 142 @day: the day number to unmark.
 143 @Returns: %TRUE.
 144
 145
 146 <!-- ##### FUNCTION gtk_calendar_clear_marks ##### -->
 147 <para>
 148 Remove all visual markers.
 149 </para>
 150
 151 @calendar: a #GtkCalendar.
 152
 153
 154 <!-- ##### FUNCTION gtk_calendar_display_options ##### -->
 155 <para>
 156 Sets display options (whether to display the heading and the month headings).
 157 </para>
 158
 159 @calendar: a #GtkCalendar.
 160 @flags: the display options to set.
 161
 162
 163 <!-- ##### FUNCTION gtk_calendar_get_date ##### -->
 164 <para>
 165 Obtains the selected date from a #GtkCalendar.
 166 </para>
 167
 168 @calendar: a #GtkCalendar.
 169 @year: location to store the year number.
 170 @month: location to store the month number.
 171 @day: location to store the day number.
 172
 173
 174 <!-- ##### FUNCTION gtk_calendar_freeze ##### -->
 175 <para>
 176 Locks the display of the calendar until it is thawed with gtk_calendar_thaw().
 177 </para>
 178
 179 @calendar: a #GtkCalendar.
 180
 181
 182 <!-- ##### FUNCTION gtk_calendar_thaw ##### -->
 183 <para>
 184 Defrosts a calendar; all the changes made since the last
 185 gtk_calendar_freeze() are displayed.
 186 </para>
 187
 188 @calendar: a #GtkCalendar.
 189
 190
 191 <!-- ##### SIGNAL GtkCalendar::day-selected ##### -->
 192 <para>
 193 Emitted when the user selects a day.
 194 </para>
 195
 196 @calendar: the object which received the signal.
 197
 198 <!-- ##### SIGNAL GtkCalendar::day-selected-double-click ##### -->
 199 <para>
 200
 201 </para>
 202
 203 @calendar: the object which received the signal.
 204
 205 <!-- ##### SIGNAL GtkCalendar::month-changed ##### -->
 206 <para>
 207 Emitted when the user clicks a button to change the selected month on a
 208 calendar.
 209 </para>
 210
 211 @calendar: the object which received the signal.
 212
 213 <!-- ##### SIGNAL GtkCalendar::next-month ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @calendar: the object which received the signal.
 219
 220 <!-- ##### SIGNAL GtkCalendar::next-year ##### -->
 221 <para>
 222
 223 </para>
 224
 225 @calendar: the object which received the signal.
 226
 227 <!-- ##### SIGNAL GtkCalendar::prev-month ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @calendar: the object which received the signal.
 233
 234 <!-- ##### SIGNAL GtkCalendar::prev-year ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @calendar: the object which received the signal.
 240