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

   1 <!-- ##### SECTION Title ##### -->
   2 GtkList
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Widget for packing a list of selectable items.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkList widget is a container whose children are displayed
  10 vertically in order, and can be selected.
  11
  12 The list has many selection modes, which are programmer selective and
  13 depend on how many elements are able to be selected at the same time.
  14 </para>
  15
  16 <!-- ##### SECTION See_Also ##### -->
  17 <para>
  18 <variablelist>
  19 <varlistentry>
  20 <term>#GtkContainer</term>
  21 <listitem><para>For functions that apply to every #GtkContainer
  22 (like #GtkList).</para></listitem>
  23 </varlistentry>
  24 <varlistentry>
  25 <term>#GtkListitem</term>
  26 <listitem><para>Children of a #GtkList widget must be of this
  27 type.</para></listitem>
  28 </varlistentry>
  29 </variablelist>
  30 </para>
  31
  32 <!-- ##### STRUCT GtkList ##### -->
  33 <para>
  34
  35 </para>
  36
  37
  38 <!-- ##### FUNCTION gtk_list_new ##### -->
  39 <para>
  40 Creates a new #GtkList.
  41 </para>
  42
  43 @Returns: the newly-created #GtkList
  44
  45
  46 <!-- ##### FUNCTION gtk_list_insert_items ##### -->
  47 <para>
  48 Inserts @items into the @list at the position @position. The #GList items
  49 must not be freed after.
  50 </para>
  51
  52 @list: the list widget.
  53 @items: the items.
  54 @position: the position to insert @items, starting at 0.
  55
  56
  57 <!-- ##### FUNCTION gtk_list_append_items ##### -->
  58 <para>
  59 Adds @items to the end of the @list.
  60 </para>
  61
  62 @list: the list widget.
  63 @items: the items.
  64
  65
  66 <!-- ##### FUNCTION gtk_list_prepend_items ##### -->
  67 <para>
  68 Inserts @items at the beginning of the @list.
  69 </para>
  70
  71 @list: the list widget.
  72 @items: the items.
  73
  74
  75 <!-- ##### FUNCTION gtk_list_remove_items ##### -->
  76 <para>
  77 Removes the @items from the @list.
  78 </para>
  79
  80 @list: the list widget.
  81 @items: the items to remove.
  82
  83
  84 <!-- ##### FUNCTION gtk_list_remove_items_no_unref ##### -->
  85 <para>
  86 Removes the @items from the @list, without unreferencing them. It
  87 may be useful if you want to move the items from one list to another.
  88 </para>
  89
  90 @list: the list widget.
  91 @items: the items.
  92
  93
  94 <!-- ##### FUNCTION gtk_list_clear_items ##### -->
  95 <para>
  96 Removes the items between index @start (included) and @end (excluded)
  97 from the @list. If @end is negative, or greater than the number of
  98 children of @list, it's assumed to be exactly the number of
  99 elements. If @start is greater than or equal to @end, nothing is
 100 done.
 101 </para>
 102
 103 @list: the list widget.
 104 @start: the index of the first item to remove.
 105 @end: the index of the lest item to remove plus one.
 106
 107
 108 <!-- ##### FUNCTION gtk_list_select_item ##### -->
 109 <para>
 110 Selects the child number @item of the @list. Nothing happens if @item
 111 is out of bounds. The signal GtkList::select-child will be emitted.
 112 </para>
 113
 114 @list: the list widget.
 115 @item: the index of the child to select.
 116
 117
 118 <!-- ##### FUNCTION gtk_list_unselect_item ##### -->
 119 <para>
 120 Unselects the child number @item of the @list. Nothing happens if
 121 @item is out of bounds. The signal GtkList::unselect-child will be
 122 emitted.
 123 </para>
 124
 125 @list: the list widget.
 126 @item: the index of the child to unselect.
 127
 128
 129 <!-- ##### FUNCTION gtk_list_select_child ##### -->
 130 <para>
 131 Selects the given @child. The signal GtkList::select-child will be
 132 emitted.
 133 </para>
 134
 135 @list: the list widget
 136 @child: the child to select.
 137
 138
 139 <!-- ##### FUNCTION gtk_list_unselect_child ##### -->
 140 <para>
 141 Unselects the given @child. The signal GtkList::unselect-child will be
 142 emitted.
 143 </para>
 144
 145 @list: the list widget.
 146 @child: the child to unselect.
 147
 148
 149 <!-- ##### FUNCTION gtk_list_child_position ##### -->
 150 <para>
 151 Searches the children of @list for the index of @child.
 152 </para>
 153
 154 @list: the list widget.
 155 @child: the child to look for.
 156 @Returns: the index of the child, -1 if not found.
 157
 158
 159 <!-- ##### FUNCTION gtk_list_set_selection_mode ##### -->
 160 <para>
 161 Set the list selection mode. The selection mode can be any value in
 162 #GtkSelectionMode:
 163 <variablelist>
 164 <varlistentry>
 165 <term>#GTK_SELECTION_SINGLE</term>
 166 <listitem><para>
 167 Zero or one element may be selected.
 168 </para></listitem>
 169 </varlistentry>
 170
 171 <varlistentry>
 172 <term>#GTK_SELECTION_BROWSE</term>
 173 <listitem><para>
 174 Exactly one element is always selected (this can be false after you have
 175 changed the selection mode).
 176 </para></listitem>
 177 </varlistentry>
 178
 179 <varlistentry>
 180 <term>#GTK_SELECTION_MULTIPLE</term>
 181 <listitem><para>
 182 Any number of elements may be selected. Clicks toggle the state of an
 183 item.
 184 </para></listitem>
 185 </varlistentry>
 186
 187 <varlistentry>
 188 <term>#GTK_SELECTION_EXTENDED</term>
 189 <listitem><para>
 190 Any number of elements may be selected. Click-drag selects a range of
 191 elements; the Ctrl key may be used to enlarge the selection, and
 192 Shift key to select between the focus and the child pointed to.
 193 </para></listitem>
 194 </varlistentry>
 195 </variablelist>
 196 </para>
 197
 198 @list: the list widget.
 199 @mode: the new selection mode.
 200
 201
 202 <!-- ##### FUNCTION gtk_list_extend_selection ##### -->
 203 <para>
 204 Extends the selection by moving the anchor according to @scroll_type. Only
 205 in #GTK_SELECTION_EXTENDED.
 206 </para>
 207
 208 @list: the list widget.
 209 @scroll_type: the direction and length.
 210 @position: the position if @scroll_type is #GTK_SCROLL_JUMP.
 211 @auto_start_selection: if %TRUE, gtk_list_start_selection() is automatically
 212 carried out before extending the selection.
 213
 214
 215 <!-- ##### FUNCTION gtk_list_start_selection ##### -->
 216 <para>
 217 Starts a selection (or part of selection) at the focused child. Only in
 218 #GTK_SELECTION_EXTENDED mode.
 219 </para>
 220
 221 @list: the list widget.
 222
 223
 224 <!-- ##### FUNCTION gtk_list_end_selection ##### -->
 225 <para>
 226 Ends the selection. Used with gtk_list_extend_selection() and
 227 gtk_list_start_selection(). Only in #GTK_SELECTION_EXTENDED mode.
 228 </para>
 229
 230 @list: the list widget.
 231
 232
 233 <!-- ##### FUNCTION gtk_list_select_all ##### -->
 234 <para>
 235 Selects all children of @list. A signal will be emitted for each
 236 newly selected child.
 237 </para>
 238
 239 @list: the list widget.
 240
 241
 242 <!-- ##### FUNCTION gtk_list_unselect_all ##### -->
 243 <para>
 244 Unselects all children of @list. A signal will be emitted for each
 245 newly unselected child.
 246 </para>
 247
 248 @list: the list widget.
 249
 250
 251 <!-- ##### FUNCTION gtk_list_scroll_horizontal ##### -->
 252 <para>
 253 Scrolls @list horizontaly. This supposes that the list is packed into a
 254 scrolled window or something similar, and adjustments are well
 255 set. Step and page increment are those from the horizontal adjustment
 256 of @list. Backward means to the left, and forward to the
 257 right. Out of bounds values are truncated.
 258 @scroll_type may be any valid #GtkScrollType. If @scroll_type is
 259 #GTK_SCROLL_NONE, nothing is done. If it's #GTK_SCROLL_JUMP, the list
 260 scrolls to the ratio @position: 0 is full left, 1 is full right.
 261 </para>
 262
 263 @list: the list widget.
 264 @scroll_type: the scrolling type.
 265 @position: the position if @scroll_type is #GTK_SCROLL_JUMP
 266
 267
 268 <!-- ##### FUNCTION gtk_list_scroll_vertical ##### -->
 269 <para>
 270 Scrolls @list vertically. This supposes that the list is packed into a
 271 scrolled window or something similar, and adjustments are well
 272 set. Step and page increment are those from the vertical adjustment
 273 of @list. Backward means up, and forward down. Out of bounds values are
 274 truncated.
 275 @scroll_type may be any valid #GtkScrollType. If @scroll_type is
 276 #GTK_SCROLL_NONE, nothing is done. If it's #GTK_SCROLL_JUMP, the list
 277 scrolls to the ratio @position: 0 is top, 1 is bottom.
 278 </para>
 279
 280 @list: the list widget.
 281 @scroll_type: the scrolling type.
 282 @position: the position if @scroll_type is #GTK_SCROLL_JUMP
 283
 284
 285 <!-- ##### FUNCTION gtk_list_toggle_add_mode ##### -->
 286 <para>
 287 Toggles between adding to the selection and beginning a new selection. Only
 288 in #GTK_SELECTION_EXTENDED. Useful with gtk_list_extend_selection().
 289 </para>
 290
 291 @list: the list widget.
 292
 293
 294 <!-- ##### FUNCTION gtk_list_toggle_focus_row ##### -->
 295 <para>
 296 Toggles the focus row. If the focus row is selected, it's
 297 unselected. If the focus row is unselected, it's selected. If the
 298 selection mode of @list is #GTK_SELECTION_BROWSE, this has no effect,
 299 as the selection is always at the focus row.
 300 </para>
 301
 302 @list: the list widget.
 303
 304
 305 <!-- ##### FUNCTION gtk_list_toggle_row ##### -->
 306 <para>
 307 Toggles the child @item of list. If the selection mode of @list is
 308 #GTK_SELECTION_BROWSE, the item is selected, and the others are
 309 unselected.
 310 </para>
 311
 312 @list: the list widget.
 313 @item: the child to toggle.
 314
 315
 316 <!-- ##### FUNCTION gtk_list_undo_selection ##### -->
 317 <para>
 318 Restores the selection in the last state, only if selection mode is
 319 #GTK_SELECTION_EXTENDED. If this function is called twice, the selection is
 320 cleared. This function sometimes gives stranges "last states".
 321 </para>
 322
 323 @list: the list widget.
 324
 325
 326 <!-- ##### FUNCTION gtk_list_end_drag_selection ##### -->
 327 <para>
 328 Stops the drag selection mode and ungrabs the pointer. This has no
 329 effect if a drag selection is not active.
 330 </para>
 331
 332 @list: the list widget.
 333
 334
 335 <!-- ##### SIGNAL GtkList::select-child ##### -->
 336 <para>
 337 The child @widget has just been selected.
 338 </para>
 339
 340 @list: the object which received the signal.
 341 @widget: the newly selected child.
 342
 343 <!-- ##### SIGNAL GtkList::selection-changed ##### -->
 344 <para>
 345 The selection of the widget has just changed.
 346 </para>
 347
 348 @list: the object which received the signal.
 349
 350 <!-- ##### SIGNAL GtkList::unselect-child ##### -->
 351 <para>
 352 The child @widget has just been unselected.
 353 </para>
 354
 355 @list: the object which received the signal.
 356 @widget: the newly unselected child.
 357
 358 <!-- ##### ARG GtkList:selection-mode ##### -->
 359 <para>
 360
 361 </para>
 362