## GtkDropDown GtkDropDown — Choose an item from a list |

## Functions

GtkWidget * | gtk_drop_down_new ()
GtkWidget * | gtk_drop_down_new_from_strings ()
void | gtk_drop_down_set_model ()
GListModel * | gtk_drop_down_get_model ()
void | gtk_drop_down_set_selected ()
guint | gtk_drop_down_get_selected ()
gpointer | gtk_drop_down_get_selected_item ()
void | gtk_drop_down_set_factory ()
GtkListItemFactory * | gtk_drop_down_get_factory ()
void | gtk_drop_down_set_list_factory ()
GtkListItemFactory * | gtk_drop_down_get_list_factory ()
void | gtk_drop_down_set_expression ()
GtkExpression * | gtk_drop_down_get_expression ()
void | gtk_drop_down_set_enable_search ()
gboolean | gtk_drop_down_get_enable_search ()

## Properties

gboolean | enable-search | Read / Write
GtkExpression * | expression | Read / Write
GtkListItemFactory * | factory | Read / Write
GtkListItemFactory * | list-factory | Read / Write
GListModel * | model | Read / Write
guint | selected | Read / Write
GObject * | selected-item | Read

## Types and Values

| GtkDropDown

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkDropDown

## Implemented Interfaces

GtkDropDown implements GtkAccessible, GtkBuildable and GtkConstraintTarget.

## Includes

    #include <gtk/gtk.h>

## Description

GtkDropDown is a widget that allows the user to choose an item from a list of options. The GtkDropDown displays the selected choice.

The options are given to GtkDropDown in the form of GListModel, and how the individual options are represented is determined by a GtkListItemFactory. The default factory displays simple strings.

GtkDropDown knows how to obtain strings from the items in a GtkStringList; for other models, you have to provide an expression to find the strings via `gtk_drop_down_set_expression()`.

GtkDropDown can optionally allow search in the popup, which is useful if the list of options is long. To enable the search entry, use `gtk_drop_down_set_enable_search()`.

### CSS nodes

GtkDropDown has a single CSS node with name dropdown, with the button and popover nodes as children.

## Functions

### gtk_drop_down_new ()

    GtkWidget *
    gtk_drop_down_new (GListModel *model,
                       GtkExpression *expression);

Creates a new GtkDropDown.

You may want to call `gtk_drop_down_set_factory()` to set up a way to map its items to widgets.

#### Parameters

model | the model to use or `NULL` for none. | [transfer full][allow-none]
expression | the expression to use or `NULL` for none. | [transfer full][allow-none]

#### Returns

a new GtkDropDown

### gtk_drop_down_new_from_strings ()

    GtkWidget *
    gtk_drop_down_new_from_strings (const char * const *strings);

Creates a new GtkDropDown that is populated with the strings in `strings` .

#### Parameters

strings | The strings to put in the dropdown. | [array zero-terminated=1]

#### Returns

a new GtkDropDown

### gtk_drop_down_set_model ()

    void
    gtk_drop_down_set_model (GtkDropDown *self,
                             GListModel *model);

Sets the GListModel to use.

#### Parameters

self | a GtkDropDown |
model | the model to use or `NULL` for none. | [allow-none][transfer none]

### gtk_drop_down_get_model ()

    GListModel *
    gtk_drop_down_get_model (GtkDropDown *self);

Gets the model that provides the displayed items.

#### Parameters

self | a GtkDropDown |

#### Returns

The model in use.

[nullable][transfer none]

### gtk_drop_down_set_selected ()

    void
    gtk_drop_down_set_selected (GtkDropDown *self,
                                guint position);

Selects the item at the given position.

#### Parameters

self | a GtkDropDown |
position | the position of the item to select, or GTK_INVALID_LIST_POSITION |

### gtk_drop_down_get_selected ()

    guint
    gtk_drop_down_get_selected (GtkDropDown *self);

Gets the position of the selected item.

#### Parameters

self | a GtkDropDown |

#### Returns

the position of the selected item, or GTK_INVALID_LIST_POSITION if not item is selected

### gtk_drop_down_get_selected_item ()

    gpointer
    gtk_drop_down_get_selected_item (GtkDropDown *self);

Gets the selected item. If no item is selected, `NULL` is returned.

#### Parameters

self | a GtkDropDown |

#### Returns

The selected item.

[transfer none][type GObject][nullable]

### gtk_drop_down_set_factory ()

    void
    gtk_drop_down_set_factory (GtkDropDown *self,
                               GtkListItemFactory *factory);

Sets the GtkListItemFactory to use for populating list items.

#### Parameters

self | a GtkDropDown |
factory | the factory to use or `NULL` for none. | [allow-none][transfer none]

### gtk_drop_down_get_factory ()

    GtkListItemFactory *
    gtk_drop_down_get_factory (GtkDropDown *self);

Gets the factory that's currently used to populate list items.

The factory returned by this function is always used for the item in the button. It is also used for items in the popup if “list-factory” is not set.

#### Parameters

self | a GtkDropDown |

#### Returns

The factory in use.

[nullable][transfer none]

### gtk_drop_down_set_list_factory ()

    void
    gtk_drop_down_set_list_factory (GtkDropDown *self,
                                    GtkListItemFactory *factory);

Sets the GtkListItemFactory to use for populating list items in the popup.

#### Parameters

self | a GtkDropDown |
factory | the factory to use or `NULL` for none. | [allow-none][transfer none]

### gtk_drop_down_get_list_factory ()

    GtkListItemFactory *
    gtk_drop_down_get_list_factory (GtkDropDown *self);

Gets the factory that's currently used to populate list items in the popup.

#### Parameters

self | a GtkDropDown |

#### Returns

The factory in use.

[nullable][transfer none]

### gtk_drop_down_set_expression ()

    void
    gtk_drop_down_set_expression (GtkDropDown *self,
                                  GtkExpression *expression);

Sets the expression that gets evaluated to obtain strings from items when searching in the popup. The expression must have a value type of G_TYPE_STRING.

#### Parameters

self | a GtkDropDown |
expression | a GtkExpression, or `NULL`. | [nullable]

### gtk_drop_down_get_expression ()

    GtkExpression *
    gtk_drop_down_get_expression (GtkDropDown *self);

Gets the expression set with `gtk_drop_down_set_expression()`.

#### Parameters

self | a GtkDropDown |

#### Returns

a GtkExpression or `NULL`.

[nullable][transfer none]

### gtk_drop_down_set_enable_search ()

    void
    gtk_drop_down_set_enable_search (GtkDropDown *self,
                                     gboolean enable_search);

Sets whether a search entry will be shown in the popup that allows to search for items in the list.

Note that “expression” must be set for search to work.

#### Parameters

self | a GtkDropDown |
enable_search | whether to enable search |

### gtk_drop_down_get_enable_search ()

    gboolean
    gtk_drop_down_get_enable_search (GtkDropDown *self);

Returns whether search is enabled.

#### Parameters

self | a GtkDropDown |

#### Returns

`TRUE` if the popup includes a search entry

## Types and Values

### GtkDropDown

    typedef struct _GtkDropDown GtkDropDown;

## Property Details

### The `“enable-search”` property

      “enable-search”            gboolean

Whether to show a search entry in the popup.

Note that search requires “expression” to be set.

Owner: GtkDropDown

Flags: Read / Write

Default value: FALSE

### The `“expression”` property

      “expression”               GtkExpression *

An expression to evaluate to obtain strings to match against the search term (see “enable-search”). If “factory” is not set, the expression is also used to bind strings to labels produced by a default factory.

[type GtkExpression]

Owner: GtkDropDown

Flags: Read / Write

### The `“factory”` property

      “factory”                  GtkListItemFactory *

Factory for populating list items.

Owner: GtkDropDown

Flags: Read / Write

### The `“list-factory”` property

      “list-factory”             GtkListItemFactory *

The factory for populating list items in the popup.

If this is not set, “factory” is used.

Owner: GtkDropDown

Flags: Read / Write

### The `“model”` property

      “model”                    GListModel *

Model for the displayed items.

Owner: GtkDropDown

Flags: Read / Write

### The `“selected”` property

      “selected”                 guint

The position of the selected item in “model”, or GTK_INVALID_LIST_POSITION if no item is selected.

Owner: GtkDropDown

Flags: Read / Write

Default value: 4294967295

### The `“selected-item”` property

      “selected-item”            GObject *

The selected item.

Owner: GtkDropDown

Flags: Read

## See Also

GtkComboBox