## GtkList

GtkList — Widget for packing a list of selectable items

## Functions

GtkWidget * | gtk_list_new ()
void | gtk_list_insert_items ()
void | gtk_list_append_items ()
void | gtk_list_prepend_items ()
void | gtk_list_remove_items ()
void | gtk_list_remove_items_no_unref ()
void | gtk_list_clear_items ()
void | gtk_list_select_item ()
void | gtk_list_unselect_item ()
void | gtk_list_select_child ()
void | gtk_list_unselect_child ()
gint | gtk_list_child_position ()
void | gtk_list_set_selection_mode ()
void | gtk_list_extend_selection ()
void | gtk_list_start_selection ()
void | gtk_list_end_selection ()
void | gtk_list_select_all ()
void | gtk_list_unselect_all ()
void | gtk_list_scroll_horizontal ()
void | gtk_list_scroll_vertical ()
void | gtk_list_toggle_add_mode ()
void | gtk_list_toggle_focus_row ()
void | gtk_list_toggle_row ()
void | gtk_list_undo_selection ()
void | gtk_list_end_drag_selection ()

## Properties

GtkSelectionMode | selection-mode | Read / Write

## Signals

void | select-child | Run First
void | selection-changed | Run First
void | unselect-child | Run First

## Types and Values

struct | GtkList

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkObject
                ╰── GtkWidget
                    ╰── GtkContainer
                        ╰── GtkList

## Implemented Interfaces

GtkList implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <gtk/gtk.h>

## Description

The GtkList widget is a container whose children are displayed vertically in order, and can be selected. 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.

GtkList has been deprecated since GTK+ 2.0 and should not be used in newly written code. Use GtkTreeView instead.

## Functions

### gtk_list_new ()

    GtkWidget *
    gtk_list_new (void);

`gtk_list_new` is deprecated and should not be used in newly-written code.

Creates a new GtkList.

#### Returns

the newly-created GtkList

### gtk_list_insert_items ()

    void
    gtk_list_insert_items (GtkList *list,
                           GList *items,
                           gint position);

`gtk_list_insert_items` is deprecated and should not be used in newly-written code.

Inserts `items` into the `list` at the position `position`. The GList items must not be freed after.

#### Parameters

list | the list widget. |
items | the items. |
position | the position to insert `items` , starting at 0. |

### gtk_list_append_items ()

    void
    gtk_list_append_items (GtkList *list,
                           GList *items);

`gtk_list_append_items` is deprecated and should not be used in newly-written code.

Adds `items` to the end of the `list`.

#### Parameters

list | the list widget. |
items | the items. |

### gtk_list_prepend_items ()

    void
    gtk_list_prepend_items (GtkList *list,
                            GList *items);

`gtk_list_prepend_items` is deprecated and should not be used in newly-written code.

Inserts `items` at the beginning of the `list`.

#### Parameters

list | the list widget. |
items | the items. |

### gtk_list_remove_items ()

    void
    gtk_list_remove_items (GtkList *list,
                           GList *items);

`gtk_list_remove_items` is deprecated and should not be used in newly-written code.

Removes the `items` from the `list`.

#### Parameters

list | the list widget. |
items | the items to remove. |

### gtk_list_remove_items_no_unref ()

    void
    gtk_list_remove_items_no_unref (GtkList *list,
                                    GList *items);

`gtk_list_remove_items_no_unref` is deprecated and should not be used in newly-written code.

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.

#### Parameters

list | the list widget. |
items | the items. |

### gtk_list_clear_items ()

    void
    gtk_list_clear_items (GtkList *list,
                          gint start,
                          gint end);

`gtk_list_clear_items` is deprecated and should not be used in newly-written code.

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.

#### Parameters

list | the list widget. |
start | the index of the first item to remove. |
end | the index of the lest item to remove plus one. |

### gtk_list_select_item ()

    void
    gtk_list_select_item (GtkList *list,
                          gint item);

`gtk_list_select_item` is deprecated and should not be used in newly-written code.

Selects the child number `item` of the `list`. Nothing happens if `item` is out of bounds. The signal GtkList::select-child will be emitted.

#### Parameters

list | the list widget. |
item | the index of the child to select. |

### gtk_list_unselect_item ()

    void
    gtk_list_unselect_item (GtkList *list,
                            gint item);

`gtk_list_unselect_item` is deprecated and should not be used in newly-written code.

Unselects the child number `item` of the `list`. Nothing happens if `item` is out of bounds. The signal GtkList::unselect-child will be emitted.

#### Parameters

list | the list widget. |
item | the index of the child to unselect. |

### gtk_list_select_child ()

    void
    gtk_list_select_child (GtkList *list,
                           GtkWidget *child);

`gtk_list_select_child` is deprecated and should not be used in newly-written code.

Selects the given `child`. The signal GtkList::select-child will be emitted.

#### Parameters

list | the list widget |
child | the child to select. |

### gtk_list_unselect_child ()

    void
    gtk_list_unselect_child (GtkList *list,
                             GtkWidget *child);

`gtk_list_unselect_child` is deprecated and should not be used in newly-written code.

Unselects the given `child`. The signal GtkList::unselect-child will be emitted.

#### Parameters

list | the list widget. |
child | the child to unselect. |

### gtk_list_child_position ()

    gint
    gtk_list_child_position (GtkList *list,
                             GtkWidget *child);

`gtk_list_child_position` is deprecated and should not be used in newly-written code.

Searches the children of `list` for the index of `child`.

#### Parameters

list | the list widget. |
child | the child to look for. |

#### Returns

the index of the child, -1 if not found.

### gtk_list_set_selection_mode ()

    void
    gtk_list_set_selection_mode (GtkList *list,
                                 GtkSelectionMode mode);

`gtk_list_set_selection_mode` is deprecated and should not be used in newly-written code.

Set the list selection mode. The selection mode can be any value in GtkSelectionMode:

GTK_SELECTION_SINGLE | Zero or one element may be selected.
GTK_SELECTION_BROWSE | Exactly one element is always selected (this can be false after you have changed the selection mode).
GTK_SELECTION_MULTIPLE | Any number of elements may be selected. Clicks toggle the state of an item.
GTK_SELECTION_EXTENDED | 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.

#### Parameters

list | the list widget. |
mode | the new selection mode. |

### gtk_list_extend_selection ()

    void
    gtk_list_extend_selection (GtkList *list,
                               GtkScrollType scroll_type,
                               gfloat position,
                               gboolean auto_start_selection);

`gtk_list_extend_selection` is deprecated and should not be used in newly-written code.

Extends the selection by moving the anchor according to `scroll_type`. Only in GTK_SELECTION_EXTENDED.

#### Parameters

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. |

### gtk_list_start_selection ()

    void
    gtk_list_start_selection (GtkList *list);

`gtk_list_start_selection` is deprecated and should not be used in newly-written code.

Starts a selection (or part of selection) at the focused child. Only in GTK_SELECTION_EXTENDED mode.

#### Parameters

list | the list widget. |

### gtk_list_end_selection ()

    void
    gtk_list_end_selection (GtkList *list);

`gtk_list_end_selection` is deprecated and should not be used in newly-written code.

Ends the selection. Used with `gtk_list_extend_selection()` and `gtk_list_start_selection()`. Only in GTK_SELECTION_EXTENDED mode.

#### Parameters

list | the list widget. |

### gtk_list_select_all ()

    void
    gtk_list_select_all (GtkList *list);

`gtk_list_select_all` is deprecated and should not be used in newly-written code.

Selects all children of `list`. A signal will be emitted for each newly selected child.

#### Parameters

list | the list widget. |

### gtk_list_unselect_all ()

    void
    gtk_list_unselect_all (GtkList *list);

`gtk_list_unselect_all` is deprecated and should not be used in newly-written code.

Unselects all children of `list`. A signal will be emitted for each newly unselected child.

#### Parameters

list | the list widget. |

### gtk_list_scroll_horizontal ()

    void
    gtk_list_scroll_horizontal (GtkList *list,
                                GtkScrollType scroll_type,
                                gfloat position);

`gtk_list_scroll_horizontal` is deprecated and should not be used in newly-written code.

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.

#### Parameters

list | the list widget. |
scroll_type | the scrolling type. |
position | the position if `scroll_type` is GTK_SCROLL_JUMP |

### gtk_list_scroll_vertical ()

    void
    gtk_list_scroll_vertical (GtkList *list,
                              GtkScrollType scroll_type,
                              gfloat position);

`gtk_list_scroll_vertical` is deprecated and should not be used in newly-written code.

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.

#### Parameters

list | the list widget. |
scroll_type | the scrolling type. |
position | the position if `scroll_type` is GTK_SCROLL_JUMP |

### gtk_list_toggle_add_mode ()

    void
    gtk_list_toggle_add_mode (GtkList *list);

`gtk_list_toggle_add_mode` is deprecated and should not be used in newly-written code.

Toggles between adding to the selection and beginning a new selection. Only in GTK_SELECTION_EXTENDED. Useful with `gtk_list_extend_selection()`.

#### Parameters

list | the list widget. |

### gtk_list_toggle_focus_row ()

    void
    gtk_list_toggle_focus_row (GtkList *list);

`gtk_list_toggle_focus_row` is deprecated and should not be used in newly-written code.

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.

#### Parameters

list | the list widget. |

### gtk_list_toggle_row ()

    void
    gtk_list_toggle_row (GtkList *list,
                         GtkWidget *item);

`gtk_list_toggle_row` is deprecated and should not be used in newly-written code.

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.

#### Parameters

list | the list widget. |
item | the child to toggle. |

### gtk_list_undo_selection ()

    void
    gtk_list_undo_selection (GtkList *list);

`gtk_list_undo_selection` is deprecated and should not be used in newly-written code.

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".

#### Parameters

list | the list widget. |

### gtk_list_end_drag_selection ()

    void
    gtk_list_end_drag_selection (GtkList *list);

`gtk_list_end_drag_selection` is deprecated and should not be used in newly-written code.

Stops the drag selection mode and ungrabs the pointer. This has no effect if a drag selection is not active.

#### Parameters

list | the list widget. |

## Types and Values

### struct GtkList

    struct GtkList;

`GtkList` is deprecated and should not be used in newly-written code.

## Property Details

### The `“selection-mode”` property

      “selection-mode”           GtkSelectionMode

Flags: Read / Write

Default value: GTK_SELECTION_NONE

## Signal Details

### The `“select-child”` signal

    void
    user_function (GtkList   *list,
                   GtkWidget *widget,
                   gpointer   user_data)

The child `widget` has just been selected.

#### Parameters

list | the object which received the signal. |
widget | the newly selected child. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“selection-changed”` signal

    void
    user_function (GtkList *list,
                   gpointer user_data)

The selection of the widget has just changed.

#### Parameters

list | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“unselect-child”` signal

    void
    user_function (GtkList   *list,
                   GtkWidget *widget,
                   gpointer   user_data)

The child `widget` has just been unselected.

#### Parameters

list | the object which received the signal. |
widget | the newly unselected child. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

GtkContainer | For functions that apply to every GtkContainer (like GtkList).
GtkListitem | Children of a GtkList widget must be of this type.