gtk2/docs/reference/gtk/tmpl/gtklist.sgml

363 lines
9.1 KiB
Plaintext
Raw Normal View History

1999-08-16 18:51:52 +00:00
<!-- ##### SECTION Title ##### -->
GtkList
<!-- ##### SECTION Short_Description ##### -->
Widget for packing a list of selectable items.
1999-08-16 18:51:52 +00:00
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GtkList widget is a container whose children are displayed
vertically in order, and can be selected.
1999-08-16 18:51:52 +00:00
The list has many selection modes, which are programmer selective and
depend on how many elements are able to be selected at the same time.
1999-08-16 18:51:52 +00:00
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>#GtkContainer</term>
<listitem><para>For functions that apply to every #GtkContainer
(like #GtkList).</para></listitem>
</varlistentry>
<varlistentry>
<term>#GtkListitem</term>
<listitem><para>Children of a #GtkList widget must be of this
type.</para></listitem>
</varlistentry>
</variablelist>
1999-08-16 18:51:52 +00:00
</para>
<!-- ##### STRUCT GtkList ##### -->
<para>
</para>
<!-- ##### FUNCTION gtk_list_new ##### -->
<para>
Creates a new #GtkList.
1999-08-16 18:51:52 +00:00
</para>
@Returns: the newly-created #GtkList
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_insert_items ##### -->
<para>
Inserts @items into the @list at the position @position. The #GList items
must not be freed after.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@items: the items.
@position: the position to insert @items, starting at 0.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_append_items ##### -->
<para>
Adds @items to the end of the @list.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@items: the items.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_prepend_items ##### -->
<para>
Inserts @items at the beginning of the @list.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@items: the items.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_remove_items ##### -->
<para>
Removes the @items from the @list.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@items: the items to remove.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_remove_items_no_unref ##### -->
<para>
Removes the @items from the @list, without unreferencing them. It
may be useful if you want to move the items from one list to another.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@items: the items.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_clear_items ##### -->
<para>
Removes the items between index @start (included) and @end (excluded)
from the @list. If @end is negative, or greater than the number of
children of @list, it's assumed to be exactly the number of
elements. If @start is greater than or equal to @end, nothing is
done.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@start: the index of the first item to remove.
@end: the index of the lest item to remove plus one.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_select_item ##### -->
<para>
Selects the child number @item of the @list. Nothing happens if @item
is out of bounds. The signal GtkList::select-child will be emitted.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@item: the index of the child to select.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_unselect_item ##### -->
<para>
Unselects the child number @item of the @list. Nothing happens if
@item is out of bounds. The signal GtkList::unselect-child will be
emitted.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@item: the index of the child to unselect.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_select_child ##### -->
<para>
Selects the given @child. The signal GtkList::select-child will be
emitted.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget
@child: the child to select.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_unselect_child ##### -->
<para>
Unselects the given @child. The signal GtkList::unselect-child will be
emitted.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@child: the child to unselect.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_child_position ##### -->
<para>
Searches the children of @list for the index of @child.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@child: the child to look for.
@Returns: the index of the child, -1 if not found.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_set_selection_mode ##### -->
<para>
Set the list selection mode. The selection mode can be any value in
#GtkSelectionMode:
<variablelist>
<varlistentry>
<term>#GTK_SELECTION_SINGLE</term>
<listitem><para>
Zero or one element may be selected.
</para></listitem>
</varlistentry>
<varlistentry>
<term>#GTK_SELECTION_BROWSE</term>
<listitem><para>
Exactly one element is always selected (this can be false after you have
changed the selection mode).
</para></listitem>
</varlistentry>
<varlistentry>
<term>#GTK_SELECTION_MULTIPLE</term>
<listitem><para>
Any number of elements may be selected. Clicks toggle the state of an
item.
</para></listitem>
</varlistentry>
<varlistentry>
<term>#GTK_SELECTION_EXTENDED</term>
<listitem><para>
Any number of elements may be selected. Click-drag selects a range of
elements; the Ctrl key may be used to enlarge the selection, and
Shift key to select between the focus and the child pointed to.
</para></listitem>
</varlistentry>
</variablelist>
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@mode: the new selection mode.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_extend_selection ##### -->
<para>
Extends the selection by moving the anchor according to @scroll_type. Only
in #GTK_SELECTION_EXTENDED.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@scroll_type: the direction and length.
@position: the position if @scroll_type is #GTK_SCROLL_JUMP.
@auto_start_selection: if %TRUE, gtk_list_start_selection() is automatically
carried out before extending the selection.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_start_selection ##### -->
<para>
Starts a selection (or part of selection) at the focused child. Only in
#GTK_SELECTION_EXTENDED mode.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_end_selection ##### -->
<para>
Ends the selection. Used with gtk_list_extend_selection() and
gtk_list_start_selection(). Only in #GTK_SELECTION_EXTENDED mode.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_select_all ##### -->
<para>
Selects all children of @list. A signal will be emitted for each
newly selected child.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_unselect_all ##### -->
<para>
Unselects all children of @list. A signal will be emitted for each
newly unselected child.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_scroll_horizontal ##### -->
<para>
Scrolls @list horizontaly. This supposes that the list is packed into a
scrolled window or something similar, and adjustments are well
set. Step and page increment are those from the horizontal adjustment
of @list. Backward means to the left, and forward to the
right. Out of bounds values are truncated.
@scroll_type may be any valid #GtkScrollType. If @scroll_type is
#GTK_SCROLL_NONE, nothing is done. If it's #GTK_SCROLL_JUMP, the list
scrolls to the ratio @position: 0 is full left, 1 is full right.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@scroll_type: the scrolling type.
@position: the position if @scroll_type is #GTK_SCROLL_JUMP
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_scroll_vertical ##### -->
<para>
Scrolls @list vertically. This supposes that the list is packed into a
scrolled window or something similar, and adjustments are well
set. Step and page increment are those from the vertical adjustment
of @list. Backward means up, and forward down. Out of bounds values are
truncated.
@scroll_type may be any valid #GtkScrollType. If @scroll_type is
#GTK_SCROLL_NONE, nothing is done. If it's #GTK_SCROLL_JUMP, the list
scrolls to the ratio @position: 0 is top, 1 is bottom.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@scroll_type: the scrolling type.
@position: the position if @scroll_type is #GTK_SCROLL_JUMP
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_toggle_add_mode ##### -->
<para>
Toggles between adding to the selection and beginning a new selection. Only
in #GTK_SELECTION_EXTENDED. Useful with gtk_list_extend_selection().
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_toggle_focus_row ##### -->
<para>
Toggles the focus row. If the focus row is selected, it's
unselected. If the focus row is unselected, it's selected. If the
selection mode of @list is #GTK_SELECTION_BROWSE, this has no effect,
as the selection is always at the focus row.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_toggle_row ##### -->
<para>
Toggles the child @item of list. If the selection mode of @list is
#GTK_SELECTION_BROWSE, the item is selected, and the others are
unselected.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
@item: the child to toggle.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_undo_selection ##### -->
<para>
Restores the selection in the last state, only if selection mode is
#GTK_SELECTION_EXTENDED. If this function is called twice, the selection is
cleared. This function sometimes gives stranges "last states".
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_list_end_drag_selection ##### -->
<para>
Stops the drag selection mode and ungrabs the pointer. This has no
effect if a drag selection is not active.
1999-08-16 18:51:52 +00:00
</para>
@list: the list widget.
1999-08-16 18:51:52 +00:00
<!-- ##### SIGNAL GtkList::select-child ##### -->
1999-08-16 18:51:52 +00:00
<para>
The child @widget has just been selected.
1999-08-16 18:51:52 +00:00
</para>
@list: the object which received the signal.
@widget: the newly selected child.
1999-08-16 18:51:52 +00:00
<!-- ##### SIGNAL GtkList::selection-changed ##### -->
1999-08-16 18:51:52 +00:00
<para>
The selection of the widget has just changed.
1999-08-16 18:51:52 +00:00
</para>
@list: the object which received the signal.
<!-- ##### SIGNAL GtkList::unselect-child ##### -->
<para>
The child @widget has just been unselected.
1999-08-16 18:51:52 +00:00
</para>
@list: the object which received the signal.
@widget: the newly unselected child.
1999-08-16 18:51:52 +00:00
<!-- ##### ARG GtkList:selection-mode ##### -->
<para>
</para>