GtkCombo

GtkCombo — A text entry field with a dropdown list

Functions

GtkWidget * gtk_combo_new ()
void gtk_combo_set_popdown_strings ()
void gtk_combo_set_value_in_list ()
void gtk_combo_set_use_arrows ()
void gtk_combo_set_use_arrows_always ()
void gtk_combo_set_case_sensitive ()
void gtk_combo_set_item_string ()
void gtk_combo_disable_activate ()

Properties

gboolean allow-empty Read / Write
gboolean case-sensitive Read / Write
gboolean enable-arrow-keys Read / Write
gboolean enable-arrows-always Read / Write
gboolean value-in-list Read / Write

Types and Values

struct GtkCombo

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBox
                        ╰── GtkHBox
                            ╰── GtkCombo

Implemented Interfaces

GtkCombo implements AtkImplementorIface, GtkBuildable and GtkOrientable.

Includes

#include <gtk/gtk.h>

Description

The GtkCombo widget consists of a single-line text entry field and a drop-down list. The drop-down list is displayed when the user clicks on a small arrow button to the right of the entry field.

The drop-down list is a GtkList widget and can be accessed using the list member of the GtkCombo. List elements can contain arbitrary widgets, but if an element is not a plain label, then you must use the gtk_list_set_item_string() function. This sets the string which will be placed in the text entry field when the item is selected.

By default, the user can step through the items in the list using the arrow (cursor) keys, though this behaviour can be turned off with gtk_combo_set_use_arrows().

As of GTK+ 2.4, GtkCombo has been deprecated in favor of GtkComboBoxEntry.

Example 48. Creating a GtkCombo widget with simple text items.

1
2
3
4
5
6
7
8
9
 
GtkWidget *combo;
GList *items = NULL;
items = g_list_append (items, "First Item");
items = g_list_append (items, "Second Item");
items = g_list_append (items, "Third Item");
items = g_list_append (items, "Fourth Item");
items = g_list_append (items, "Fifth Item");
combo = gtk_combo_new ();
gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);

Example 49. Creating a GtkCombo widget with a complex item.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
 
GtkWidget *combo, *item, *hbox, *arrow, *label;
combo = gtk_combo_new ();
item = gtk_list_item_new ();
gtk_widget_show (item);
/* You can put almost anything into the GtkListItem widget. Here we will use
   a horizontal box with an arrow and a label in it. */
hbox = gtk_hbox_new (FALSE, 3);
gtk_container_add (GTK_CONTAINER (item), hbox);
gtk_widget_show (hbox);
arrow = gtk_arrow_new (GTK_ARROW_RIGHT, GTK_SHADOW_OUT);
gtk_widget_show (arrow);
gtk_box_pack_start (GTK_BOX (hbox), arrow, FALSE, FALSE, 0);
label = gtk_label_new ("First Item");
gtk_widget_show (label);
gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);
/* You must set the string to display in the entry field when the item is
   selected. */
gtk_combo_set_item_string (GTK_COMBO (combo), GTK_ITEM (item), "1st Item");
/* Now we simply add the item to the combo's list. */
gtk_container_add (GTK_CONTAINER (GTK_COMBO (combo)->list), item);

Functions

gtk_combo_new ()

GtkWidget *
gtk_combo_new (void);

gtk_combo_new has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

Creates a new GtkCombo.

Returns

a new GtkCombo.

gtk_combo_set_popdown_strings ()

void
gtk_combo_set_popdown_strings (GtkCombo *combo,
                               GList *strings);

gtk_combo_set_popdown_strings has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

Convenience function to set all of the items in the popup list. (See the example above.)

Parameters

combo

a GtkCombo.

  

strings

a list of strings, or NULL to clear the popup list

  

gtk_combo_set_value_in_list ()

void
gtk_combo_set_value_in_list (GtkCombo *combo,
                             gboolean val,
                             gboolean ok_if_empty);

gtk_combo_set_value_in_list has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

Specifies whether the value entered in the text entry field must match one of the values in the list. If this is set then the user will not be able to perform any other action until a valid value has been entered.

If an empty field is acceptable, the ok_if_empty parameter should be TRUE.

Parameters

combo

a GtkCombo.

  

val

TRUE if the value entered must match one of the values in the list.

  

ok_if_empty

TRUE if an empty value is considered valid.

  

gtk_combo_set_use_arrows ()

void
gtk_combo_set_use_arrows (GtkCombo *combo,
                          gboolean val);

gtk_combo_set_use_arrows has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

Specifies if the arrow (cursor) keys can be used to step through the items in the list. This is on by default.

Parameters

combo

a GtkCombo.

  

val

TRUE if the arrow keys can be used to step through the items in the list.

  

gtk_combo_set_use_arrows_always ()

void
gtk_combo_set_use_arrows_always (GtkCombo *combo,
                                 gboolean val);

gtk_combo_set_use_arrows_always has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

Obsolete function, does nothing.

Parameters

combo

a GtkCombo.

  

val

unused

  

gtk_combo_set_case_sensitive ()

void
gtk_combo_set_case_sensitive (GtkCombo *combo,
                              gboolean val);

gtk_combo_set_case_sensitive has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

Specifies whether the text entered into the GtkEntry field and the text in the list items is case sensitive.

This may be useful, for example, when you have called gtk_combo_set_value_in_list() to limit the values entered, but you are not worried about differences in case.

Parameters

combo

a GtkCombo.

  

val

TRUE if the text in the list items is case sensitive.

  

gtk_combo_set_item_string ()

void
gtk_combo_set_item_string (GtkCombo *combo,
                           GtkItem *item,
                           const gchar *item_value);

gtk_combo_set_item_string has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

Sets the string to place in the GtkEntry field when a particular list item is selected. This is needed if the list item is not a simple label.

Parameters

combo

a GtkCombo.

  

item

a GtkItem.

  

item_value

the string to place in the GtkEntry when item is selected.

  

gtk_combo_disable_activate ()

void
gtk_combo_disable_activate (GtkCombo *combo);

gtk_combo_disable_activate has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

Stops the GtkCombo widget from showing the popup list when the GtkEntry emits the "activate" signal, i.e. when the Return key is pressed. This may be useful if, for example, you want the Return key to close a dialog instead.

Parameters

combo

a GtkCombo.

  

Types and Values

struct GtkCombo

struct GtkCombo {
	GtkWidget *entry;
	
	GtkWidget *list;
};

GtkCombo has been deprecated since version 2.4 and should not be used in newly-written code.

Use GtkComboBox instead.

The GtkCombo struct contains the following fields. (These fields should be considered read-only. They should never be set by an application.)

Members

GtkWidget *entry;

the text entry field.

  

GtkWidget *list;

the list shown in the drop-down window.

  

Property Details

The “allow-empty” property

  “allow-empty”              gboolean

Whether an empty value may be entered in this field.

Flags: Read / Write

Default value: TRUE

The “case-sensitive” property

  “case-sensitive”           gboolean

Whether list item matching is case sensitive.

Flags: Read / Write

Default value: FALSE

The “enable-arrow-keys” property

  “enable-arrow-keys”        gboolean

Whether the arrow keys move through the list of items.

Flags: Read / Write

Default value: TRUE

The “enable-arrows-always” property

  “enable-arrows-always”     gboolean

Obsolete property, ignored.

Flags: Read / Write

Default value: TRUE

The “value-in-list” property

  “value-in-list”            gboolean

Whether entered values must already be present in the list.

Flags: Read / Write

Default value: FALSE

Generated by GTK-Doc V1.24.1