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