W3cubDocs

/GTK 3.24

GtkComboBoxText

GtkComboBoxText — A simple, text-only combo box

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkBin
                    ╰── GtkComboBox
                        ╰── GtkComboBoxText

Implemented Interfaces

GtkComboBoxText implements AtkImplementorIface, GtkBuildable, GtkCellLayout and GtkCellEditable.

Includes

#include <gtk/gtk.h>

Description

A GtkComboBoxText is a simple variant of GtkComboBox that hides the model-view complexity for simple text-only use cases.

To create a GtkComboBoxText, use gtk_combo_box_text_new() or gtk_combo_box_text_new_with_entry().

You can add items to a GtkComboBoxText with gtk_combo_box_text_append_text(), gtk_combo_box_text_insert_text() or gtk_combo_box_text_prepend_text() and remove options with gtk_combo_box_text_remove().

If the GtkComboBoxText contains an entry (via the “has-entry” property), its contents can be retrieved using gtk_combo_box_text_get_active_text(). The entry itself can be accessed by calling gtk_bin_get_child() on the combo box.

You should not call gtk_combo_box_set_model() or attempt to pack more cells into this combo box via its GtkCellLayout interface.

GtkComboBoxText as GtkBuildable

The GtkComboBoxText implementation of the GtkBuildable interface supports adding items directly using the <items> element and specifying <item> elements for each item. Each <item> element can specify the “id” corresponding to the appended text and also supports the regular translation attributes “translatable”, “context” and “comments”.

Here is a UI definition fragment specifying GtkComboBoxText items:

CSS nodes

<object class="GtkComboBoxText">
  <items>
    <item translatable="yes" id="factory">Factory</item>
    <item translatable="yes" id="home">Home</item>
    <item translatable="yes" id="subway">Subway</item>
  </items>
</object>

GtkComboBoxText has a single CSS node with name combobox. It adds the style class .combo to the main CSS nodes of its entry and button children, and the .linked class to the node of its internal box.

Functions

gtk_combo_box_text_new ()

GtkWidget *
gtk_combo_box_text_new (void);

Creates a new GtkComboBoxText, which is a GtkComboBox just displaying strings.

Returns

A new GtkComboBoxText

Since: 2.24

gtk_combo_box_text_new_with_entry ()

GtkWidget *
gtk_combo_box_text_new_with_entry (void);

Creates a new GtkComboBoxText, which is a GtkComboBox just displaying strings. The combo box created by this function has an entry.

Returns

a new GtkComboBoxText

Since: 2.24

gtk_combo_box_text_append ()

void
gtk_combo_box_text_append (GtkComboBoxText *combo_box,
                           const gchar *id,
                           const gchar *text);

Appends text to the list of strings stored in combo_box . If id is non-NULL then it is used as the ID of the row.

This is the same as calling gtk_combo_box_text_insert() with a position of -1.

Parameters

combo_box

A GtkComboBoxText

id

a string ID for this value, or NULL.

[allow-none]

text

A string

Since: 2.24

gtk_combo_box_text_prepend ()

void
gtk_combo_box_text_prepend (GtkComboBoxText *combo_box,
                            const gchar *id,
                            const gchar *text);

Prepends text to the list of strings stored in combo_box . If id is non-NULL then it is used as the ID of the row.

This is the same as calling gtk_combo_box_text_insert() with a position of 0.

Parameters

combo_box

A GtkComboBox

id

a string ID for this value, or NULL.

[allow-none]

text

a string

Since: 2.24

gtk_combo_box_text_insert ()

void
gtk_combo_box_text_insert (GtkComboBoxText *combo_box,
                           gint position,
                           const gchar *id,
                           const gchar *text);

Inserts text at position in the list of strings stored in combo_box . If id is non-NULL then it is used as the ID of the row. See “id-column”.

If position is negative then text is appended.

Parameters

combo_box

A GtkComboBoxText

position

An index to insert text

id

a string ID for this value, or NULL.

[allow-none]

text

A string to display

Since: 3.0

gtk_combo_box_text_append_text ()

void
gtk_combo_box_text_append_text (GtkComboBoxText *combo_box,
                                const gchar *text);

Appends text to the list of strings stored in combo_box .

This is the same as calling gtk_combo_box_text_insert_text() with a position of -1.

Parameters

combo_box

A GtkComboBoxText

text

A string

Since: 2.24

gtk_combo_box_text_prepend_text ()

void
gtk_combo_box_text_prepend_text (GtkComboBoxText *combo_box,
                                 const gchar *text);

Prepends text to the list of strings stored in combo_box .

This is the same as calling gtk_combo_box_text_insert_text() with a position of 0.

Parameters

combo_box

A GtkComboBox

text

A string

Since: 2.24

gtk_combo_box_text_insert_text ()

void
gtk_combo_box_text_insert_text (GtkComboBoxText *combo_box,
                                gint position,
                                const gchar *text);

Inserts text at position in the list of strings stored in combo_box .

If position is negative then text is appended.

This is the same as calling gtk_combo_box_text_insert() with a NULL ID string.

Parameters

combo_box

A GtkComboBoxText

position

An index to insert text

text

A string

Since: 2.24

gtk_combo_box_text_remove ()

void
gtk_combo_box_text_remove (GtkComboBoxText *combo_box,
                           gint position);

Removes the string at position from combo_box .

Parameters

combo_box

A GtkComboBox

position

Index of the item to remove

Since: 2.24

gtk_combo_box_text_remove_all ()

void
gtk_combo_box_text_remove_all (GtkComboBoxText *combo_box);

Removes all the text entries from the combo box.

Parameters

combo_box

A GtkComboBoxText

Since: 3.0

gtk_combo_box_text_get_active_text ()

gchar *
gtk_combo_box_text_get_active_text (GtkComboBoxText *combo_box);

Returns the currently active string in combo_box , or NULL if none is selected. If combo_box contains an entry, this function will return its contents (which will not necessarily be an item from the list).

Parameters

combo_box

A GtkComboBoxText

Returns

a newly allocated string containing the currently active text. Must be freed with g_free().

[transfer full]

Since: 2.24

Types and Values

struct GtkComboBoxText

struct GtkComboBoxText;

See Also

GtkComboBox

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk3/3.24/GtkComboBoxText.html