HdyComboRow: Handy Reference Manual

## HdyComboRow HdyComboRow — A GtkListBox row used to choose from a list of items. |

## Functions

gchar * | (*HdyComboRowGetNameFunc) ()
gchar * | (*HdyComboRowGetEnumValueNameFunc) ()
GtkWidget * | hdy_combo_row_new ()
GListModel * | hdy_combo_row_get_model ()
void | hdy_combo_row_bind_model ()
void | hdy_combo_row_bind_name_model ()
void | hdy_combo_row_set_for_enum ()
gint | hdy_combo_row_get_selected_index ()
void | hdy_combo_row_set_selected_index ()
gboolean | hdy_combo_row_get_use_subtitle ()
void | hdy_combo_row_set_use_subtitle ()
void | hdy_combo_row_set_get_name_func ()
gchar * | hdy_enum_value_row_name ()

## Properties

int | selected-index | Read / Write
gboolean | use-subtitle | Read / Write

## Types and Values

#define | HDY_TYPE_COMBO_ROW
struct | HdyComboRowClass
| HdyComboRow

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkListBoxRow
                            ╰── HdyPreferencesRow
                                ╰── HdyActionRow
                                    ╰── HdyComboRow

## Implemented Interfaces

HdyComboRow implements AtkImplementorIface, GtkBuildable and GtkActionable.

## Description

The HdyComboRow widget allows the user to choose from a list of valid choices. The row displays the selected choice. When activated, the row displays a popover which allows the user to make a new choice.

The HdyComboRow uses the model-view pattern; the list of valid choices is specified in the form of a GListModel, and the display of the choices can be adapted to the data in the model via widget creation functions.

HdyComboRow is “activatable” if a model is set.

### CSS nodes

HdyComboRow has a main CSS node with name row.

Its popover has the node name popover with the .combo style class, it contains a GtkScrolledWindow, which in turn contains a GtkListBox, both are accessible via their regular nodes.

A checkmark of node and style class image.checkmark in the popover denotes the current item.

## Functions

### HdyComboRowGetNameFunc ()

    gchar *
    (*HdyComboRowGetNameFunc) (gpointer item,
                               gpointer user_data);

Called for combo rows that are bound to a GListModel with `hdy_combo_row_bind_name_model()` for each item that gets added to the model.

#### Parameters

item | the item from the model from which to get a name. | [type GObject]
user_data | user data. | [closure]

#### Returns

a newly allocated displayable name that represents `item` .

[transfer full]

### HdyComboRowGetEnumValueNameFunc ()

    gchar *
    (*HdyComboRowGetEnumValueNameFunc) (HdyEnumValueObject *value,
                                        gpointer user_data);

Called for combo rows that are bound to an enumeration with `hdy_combo_row_set_for_enum()` for each value from that enumeration.

#### Parameters

value | the value from the enum from which to get a name |
user_data | user data. | [closure]

#### Returns

a newly allocated displayable name that represents `value` .

[transfer full]

### hdy_combo_row_new ()

    GtkWidget *
    hdy_combo_row_new (void);

Creates a new HdyComboRow.

#### Returns

a new HdyComboRow

Since: 0.0.6

### hdy_combo_row_get_model ()

    GListModel *
    hdy_combo_row_get_model (HdyComboRow *self);

Gets the model bound to `self` , or `NULL` if none is bound.

#### Parameters

self | a HdyComboRow |

#### Returns

the GListModel bound to `self` or `NULL`.

[transfer none][nullable]

Since: 0.0.6

### hdy_combo_row_bind_model ()

    void
    hdy_combo_row_bind_model (HdyComboRow *self,
                              GListModel *model,
                              GtkListBoxCreateWidgetFunc create_list_widget_func,
                              GtkListBoxCreateWidgetFunc create_current_widget_func,
                              gpointer user_data,
                              GDestroyNotify user_data_free_func);

Binds `model` to `self` .

If `self` was already bound to a model, that previous binding is destroyed.

The contents of `self` are cleared and then filled with widgets that represent items from `model` . `self` is updated whenever `model` changes. If `model` is `NULL`, `self` is left empty.

#### Parameters

self | a HdyComboRow |
model | the GListModel to be bound to `self` . | [nullable]
create_list_widget_func | a function that creates widgets for items to display in the list, or `NULL` in case you also passed `NULL` as `model` . | [nullable][scope call]
create_current_widget_func | a function that creates widgets for items to display as the selected item, or `NULL` in case you also passed `NULL` as `model` . | [nullable][scope call]
user_data | user data passed to `create_list_widget_func` and `create_current_widget_func` |
user_data_free_func | function for freeing `user_data` |

Since: 0.0.6

### hdy_combo_row_bind_name_model ()

    void
    hdy_combo_row_bind_name_model (HdyComboRow *self,
                                   GListModel *model,
                                   HdyComboRowGetNameFunc get_name_func,
                                   gpointer user_data,
                                   GDestroyNotify user_data_free_func);

Binds `model` to `self` .

If `self` was already bound to a model, that previous binding is destroyed.

The contents of `self` are cleared and then filled with widgets that represent items from `model` . `self` is updated whenever `model` changes. If `model` is `NULL`, `self` is left empty.

This is more convenient to use than `hdy_combo_row_bind_model()` if you want to represent items of the model with names.

#### Parameters

self | a HdyComboRow |
model | the GListModel to be bound to `self` . | [nullable]
get_name_func | a function that creates names for items, or `NULL` in case you also passed `NULL` as `model` . | [nullable]
user_data | user data passed to `get_name_func` |
user_data_free_func | function for freeing `user_data` |

Since: 0.0.6

### hdy_combo_row_set_for_enum ()

    void
    hdy_combo_row_set_for_enum (HdyComboRow *self,
                                GType enum_type,
                                HdyComboRowGetEnumValueNameFunc get_name_func,
                                gpointer user_data,
                                GDestroyNotify user_data_free_func);

Creates a model for `enum_type` and binds it to `self` . The items of the model will be HdyEnumValueObject objects.

If `self` was already bound to a model, that previous binding is destroyed.

The contents of `self` are cleared and then filled with widgets that represent items from `model` . `self` is updated whenever `model` changes. If `model` is `NULL`, `self` is left empty.

This is more convenient to use than `hdy_combo_row_bind_name_model()` if you want to represent values of an enumeration with names.

See `hdy_enum_value_row_name()`.

#### Parameters

self | a HdyComboRow |
enum_type | the enumeration GType to be bound to `self` |
get_name_func | a function that creates names for items, or `NULL` in case you also passed `NULL` as `model` . | [nullable]
user_data | user data passed to `get_name_func` |
user_data_free_func | function for freeing `user_data` |

Since: 0.0.6

### hdy_combo_row_get_selected_index ()

    gint
    hdy_combo_row_get_selected_index (HdyComboRow *self);

Gets the index of the selected item in its GListModel.

#### Parameters

self | a GtkListBoxRow |

#### Returns

the index of the selected item, or -1 if no item is selected

Since: 0.0.7

### hdy_combo_row_set_selected_index ()

    void
    hdy_combo_row_set_selected_index (HdyComboRow *self,
                                      gint selected_index);

Sets the index of the selected item in its GListModel.

#### Parameters

self | a HdyComboRow |
selected_index | the index of the selected item |

Since: 0.0.7

### hdy_combo_row_get_use_subtitle ()

    gboolean
    hdy_combo_row_get_use_subtitle (HdyComboRow *self);

Gets whether the current value of `self` should be displayed as its subtitle.

#### Parameters

self | a GtkListBoxRow |

#### Returns

whether the current value of `self` should be displayed as its subtitle

Since: 0.0.10

### hdy_combo_row_set_use_subtitle ()

    void
    hdy_combo_row_set_use_subtitle (HdyComboRow *self,
                                    gboolean use_subtitle);

Sets whether the current value of `self` should be displayed as its subtitle.

If `TRUE`, you should not access HdyActionRow:subtitle.

#### Parameters

self | a HdyComboRow |
use_subtitle | `TRUE` to set the current value as the subtitle |

Since: 0.0.10

### hdy_combo_row_set_get_name_func ()

    void
    hdy_combo_row_set_get_name_func (HdyComboRow *self,
                                     HdyComboRowGetNameFunc get_name_func,
                                     gpointer user_data,
                                     GDestroyNotify user_data_free_func);

Sets a closure to convert items into names. See HdyComboRow:use-subtitle.

#### Parameters

self | a HdyComboRow |
get_name_func | a function that creates names for items, or `NULL` in case you also passed `NULL` as `model` . | [nullable]
user_data | user data passed to `get_name_func` |
user_data_free_func | function for freeing `user_data` |

Since: 0.0.10

### hdy_enum_value_row_name ()

    gchar *
    hdy_enum_value_row_name (HdyEnumValueObject *value,
                             gpointer user_data);

This is a default implementation of HdyComboRowGetEnumValueNameFunc to be used with `hdy_combo_row_set_for_enum()`. If the enumeration has a nickname, it will return it, otherwise it will return its name.

#### Parameters

value | the value from the enum from which to get a name |
user_data | unused user data. | [closure]

#### Returns

a newly allocated displayable name that represents `value` .

[transfer full]

Since: 0.0.6

## Types and Values

### HDY_TYPE_COMBO_ROW

    #define HDY_TYPE_COMBO_ROW (hdy_combo_row_get_type())

### struct HdyComboRowClass

    struct HdyComboRowClass {
      HdyActionRowClass parent_class;
    };

#### Members

### HdyComboRow

    typedef struct _HdyComboRow HdyComboRow;

## Property Details

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

      “selected-index”           int

The index of the selected item in its GListModel.

Owner: HdyComboRow

Flags: Read / Write

Allowed values: >= -1

Default value: -1

Since: 0.0.7

### The `“use-subtitle”` property

      “use-subtitle”             gboolean

`TRUE` to set the current value as the subtitle.

If you use a custom widget creation function, you will need to give the row a name conversion closure with `hdy_combo_row_set_get_name_func()`.

If `TRUE`, you should not access HdyActionRow:subtitle.

Owner: HdyComboRow

Flags: Read / Write

Default value: FALSE

Since: 0.0.10