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_set_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 <note>
  60 <para>
  61 Note that <structfield>month</structfield> is zero-based (i.e it allowed values
  62 are 0-11) while <structfield>selected_day</structfield> is one-based
  63 (i.e. allowed values are 1-31).
  64 </para>
  65 </note>
  66
  67
  68 <!-- ##### SIGNAL GtkCalendar::day-selected ##### -->
  69 <para>
  70 Emitted when the user selects a day.
  71 </para>
  72
  73 @calendar: the object which received the signal.
  74
  75 <!-- ##### SIGNAL GtkCalendar::day-selected-double-click ##### -->
  76 <para>
  77
  78 </para>
  79
  80 @calendar: the object which received the signal.
  81
  82 <!-- ##### SIGNAL GtkCalendar::month-changed ##### -->
  83 <para>
  84 Emitted when the user clicks a button to change the selected month on a
  85 calendar.
  86 </para>
  87
  88 @calendar: the object which received the signal.
  89
  90 <!-- ##### SIGNAL GtkCalendar::next-month ##### -->
  91 <para>
  92
  93 </para>
  94
  95 @calendar: the object which received the signal.
  96
  97 <!-- ##### SIGNAL GtkCalendar::next-year ##### -->
  98 <para>
  99
 100 </para>
 101
 102 @calendar: the object which received the signal.
 103
 104 <!-- ##### SIGNAL GtkCalendar::prev-month ##### -->
 105 <para>
 106
 107 </para>
 108
 109 @calendar: the object which received the signal.
 110
 111 <!-- ##### SIGNAL GtkCalendar::prev-year ##### -->
 112 <para>
 113
 114 </para>
 115
 116 @calendar: the object which received the signal.
 117
 118 <!-- ##### ARG GtkCalendar:day ##### -->
 119 <para>
 120
 121 </para>
 122
 123 <!-- ##### ARG GtkCalendar:month ##### -->
 124 <para>
 125
 126 </para>
 127
 128 <!-- ##### ARG GtkCalendar:no-month-change ##### -->
 129 <para>
 130
 131 </para>
 132
 133 <!-- ##### ARG GtkCalendar:show-day-names ##### -->
 134 <para>
 135
 136 </para>
 137
 138 <!-- ##### ARG GtkCalendar:show-heading ##### -->
 139 <para>
 140
 141 </para>
 142
 143 <!-- ##### ARG GtkCalendar:show-week-numbers ##### -->
 144 <para>
 145
 146 </para>
 147
 148 <!-- ##### ARG GtkCalendar:year ##### -->
 149 <para>
 150
 151 </para>
 152
 153 <!-- ##### ENUM GtkCalendarDisplayOptions ##### -->
 154 <para>
 155 These options can be used to influence the display and behaviour of a #GtkCalendar.
 156 </para>
 157
 158 @GTK_CALENDAR_SHOW_HEADING: Specifies that the month and year should be displayed.
 159 @GTK_CALENDAR_SHOW_DAY_NAMES: Specifies that three letter day descriptions should be present.
 160 @GTK_CALENDAR_NO_MONTH_CHANGE: Prevents the user from switching months with the calendar.
 161 @GTK_CALENDAR_SHOW_WEEK_NUMBERS: Displays each week numbers of the current year, down the left side
 162  of the calendar.
 163 @GTK_CALENDAR_WEEK_START_MONDAY: Since GTK+ 2.4, this option is deprecated and ignored by GTK+.
 164  The information on which day the calendar week starts is derived from the locale.
 165
 166 <!-- ##### FUNCTION gtk_calendar_new ##### -->
 167 <para>
 168 Creates a new calendar, with the current date being selected.
 169 </para>
 170
 171 @Returns: a #GtkCalendar.
 172
 173
 174 <!-- ##### FUNCTION gtk_calendar_select_month ##### -->
 175 <para>
 176 Shifts the calendar to a different month.
 177 </para>
 178
 179 @calendar: a #GtkCalendar.
 180 @month: a month number between 0 and 11.
 181 @year: the year the month is in.
 182 @Returns: %TRUE.
 183
 184
 185 <!-- ##### FUNCTION gtk_calendar_select_day ##### -->
 186 <para>
 187 Selects a day from the current month.
 188 </para>
 189
 190 @calendar: a #GtkCalendar.
 191 @day: the day number between 1 and 31, or 0 to unselect
 192    the currently selected day.
 193
 194
 195 <!-- ##### FUNCTION gtk_calendar_mark_day ##### -->
 196 <para>
 197 Places a visual marker on a particular day.
 198 </para>
 199
 200 @calendar: a #GtkCalendar.
 201 @day: the day number to mark between 1 and 31.
 202 @Returns: %TRUE.
 203
 204
 205 <!-- ##### FUNCTION gtk_calendar_unmark_day ##### -->
 206 <para>
 207 Removes the visual marker from a particular day.
 208 </para>
 209
 210 @calendar: a #GtkCalendar.
 211 @day: the day number to unmark between 1 and 31.
 212 @Returns: %TRUE.
 213
 214
 215 <!-- ##### FUNCTION gtk_calendar_clear_marks ##### -->
 216 <para>
 217 Remove all visual markers.
 218 </para>
 219
 220 @calendar: a #GtkCalendar.
 221
 222
 223 <!-- ##### FUNCTION gtk_calendar_get_display_options ##### -->
 224 <para>
 225
 226 </para>
 227
 228 @calendar:
 229 @Returns:
 230
 231
 232 <!-- ##### FUNCTION gtk_calendar_set_display_options ##### -->
 233 <para>
 234
 235 </para>
 236
 237 @calendar:
 238 @flags:
 239
 240
 241 <!-- ##### FUNCTION gtk_calendar_display_options ##### -->
 242 <para>
 243 Sets display options (whether to display the heading and the month headings).
 244 </para>
 245
 246 @calendar: a #GtkCalendar.
 247 @flags: the display options to set.
 248 @Deprecated: Use gtk_calendar_set_display_options() instead
 249
 250
 251 <!-- ##### FUNCTION gtk_calendar_get_date ##### -->
 252 <para>
 253 Obtains the selected date from a #GtkCalendar.
 254 </para>
 255
 256 @calendar: a #GtkCalendar.
 257 @year: location to store the year number.
 258 @month: location to store the month number.
 259 @day: location to store the day number.
 260
 261
 262 <!-- ##### FUNCTION gtk_calendar_freeze ##### -->
 263 <para>
 264 Locks the display of the calendar until it is thawed with gtk_calendar_thaw().
 265 </para>
 266
 267 @calendar: a #GtkCalendar.
 268
 269
 270 <!-- ##### FUNCTION gtk_calendar_thaw ##### -->
 271 <para>
 272 Defrosts a calendar; all the changes made since the last
 273 gtk_calendar_freeze() are displayed.
 274 </para>
 275
 276 @calendar: a #GtkCalendar.
 277
 278