gtk2/docs/reference/gtk/tmpl/gtkcombo.sgml

223 lines
6.2 KiB
Plaintext
Raw Normal View History

1999-08-16 18:51:52 +00:00
<!-- ##### SECTION Title ##### -->
GtkCombo
<!-- ##### SECTION Short_Description ##### -->
2004-10-11 20:10:52 +00:00
A text entry field with a dropdown list
1999-08-16 18:51:52 +00:00
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
The drop-down list is a #GtkList widget and can be accessed using the
<structfield>list</structfield> member of the #GtkCombo-struct.
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.
</para>
<para>
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().
1999-08-16 18:51:52 +00:00
</para>
<para>
As of GTK+ 2.4, #GtkCombo has been deprecated in favor of #GtkComboBox.
</para>
<example id="gtkcombo-simple-example">
<title>Creating a <structname>GtkCombo</structname> widget with simple text
items.</title>
<programlisting>
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);
</programlisting>
</example>
<example>
<title>Creating a <structname>GtkCombo</structname> widget with a complex item.</title>
<programlisting>
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);
</programlisting>
</example>
1999-08-16 18:51:52 +00:00
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
2005-06-20 22:06:27 +00:00
<!-- ##### SECTION Stability_Level ##### -->
1999-08-16 18:51:52 +00:00
<!-- ##### STRUCT GtkCombo ##### -->
<para>
The #GtkFixedChild-struct struct contains the following fields.
(These fields should be considered read-only. They should never be set by
an application.)
1999-08-16 18:51:52 +00:00
</para>
@entry: the text entry field.
@list: the list shown in the drop-down window.
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
<!-- ##### ARG GtkCombo:allow-empty ##### -->
<para>
</para>
<!-- ##### ARG GtkCombo:case-sensitive ##### -->
<para>
</para>
<!-- ##### ARG GtkCombo:enable-arrow-keys ##### -->
<para>
</para>
<!-- ##### ARG GtkCombo:enable-arrows-always ##### -->
<para>
</para>
<!-- ##### ARG GtkCombo:value-in-list ##### -->
<para>
</para>
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_combo_new ##### -->
<para>
Creates a new #GtkCombo.
</para>
1999-08-16 18:51:52 +00:00
@Returns: a new #GtkCombo.
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
<!-- ##### FUNCTION gtk_combo_set_popdown_strings ##### -->
<para>
Convenience function to set all of the items in the popup list.
(See the <link linkend="gtkcombo-simple-example">example</link> above.)
1999-08-16 18:51:52 +00:00
</para>
@combo: a #GtkCombo.
@strings: a list of strings, or %NULL to clear the popup list
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_combo_set_value_in_list ##### -->
<para>
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.
</para>
<para>
If an empty field is acceptable, the @ok_if_empty parameter should be %TRUE.
1999-08-16 18:51:52 +00:00
</para>
@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.
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_combo_set_use_arrows ##### -->
<para>
Specifies if the arrow (cursor) keys can be used to step through the items in
the list. This is on by default.
1999-08-16 18:51:52 +00:00
</para>
@combo: a #GtkCombo.
@val: %TRUE if the arrow keys can be used to step through the items in
the list.
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_combo_set_use_arrows_always ##### -->
<para>
Obsolete function, does nothing.
1999-08-16 18:51:52 +00:00
</para>
@combo: a #GtkCombo.
@val: unused
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_combo_set_case_sensitive ##### -->
<para>
Specifies whether the text entered into the #GtkEntry field and the text in
the list items is case sensitive.
1999-08-16 18:51:52 +00:00
</para>
<para>
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.
1999-08-16 18:51:52 +00:00
</para>
@combo: a #GtkCombo.
added gtkaccelmap.sgml. other updates. Mon Nov 12 23:06:38 2001 Tim Janik <timj@gtk.org> * added gtkaccelmap.sgml. other updates. Mon Nov 12 23:08:37 2001 Tim Janik <timj@gtk.org> * gtk/maketypes.awk: fix type utils generation on unix. * gtk/gtkaccelmap.[hc]: new files, implementing a global accelerator registry. * gtk/gtkaccelgroup.[hc]: major API/implementation revamp: removed GTK_ACCEL_SIGNAL_VISIBLE, gtk_accel_group_get_default, gtk_accel_group_get_entry, gtk_accel_group_(un)lock_entry, gtk_accel_group_add/remove, gtk_accel_group_handle_add/remove, gtk_accel_group_create_add/remove, gtk_accel_group_entries_from_object. introduced ::accel_changed signal for change notification, and gtk_accel_group_connect/disconnect to connect closures to accel groups. made gtk_accel_group_attach/detach and gtk_accel_group_activate private functions. deprecated gtk_accel_group_ref/unref. * gtk/gtkaccellabel.[hc]: changes to make accellabels pay attention to accel group changed notification and basically operate on closures. removed gtk_accel_label_get_accel_object and gtk_accel_label_set_accel_object. introduced gtk_accel_label_set_accel_closure, and for convenience, gtk_accel_label_set_accel_widget. * gtk/gtkitemfactory.[hc]: removed accelerator propagation code which mostly moved into gtkaccelmap.[hc]. removed gtk_item_factory_parse_rc*, gtk_item_factory_dump_* and gtk_item_factory_print_func. * gtk/gtkmain.c: call _gtk_accel_map_init(). * gtk/gtkmenuitem.[hc]: introduced gtk_menu_item_set_accel_path(), that associates an accelerator path with menu items, through which persistent accelerator settings on menu items are enabled. * gtk/gtkmenu.[hc]: added gtk_menu_set_accel_path() so accelerator paths of menu item can be default constructed to allow installation of accelerators on menu items that don't come with an accelerator binding by default. * gtk/gtksettings.c: fix STRING type rc settings by special casing them appropriately in the parser. * gtk/gtksignal.[hc]: allow a class function offset of 0 for gtk_signal_newv(). * gtk/gtkwidget.[hc]: accelerator API revamp. removed ::accelerator_add/remove signals, gtk_widget_accelerator_signal, gtk_widget_accelerators_locked, gtk_widget_remove_accelerators and gtk_widget_(un)lock_accelerators. accelerators maintained through gtk_widget_add/remove_accelerator() are not runtime changable now, the correct sequence to setup a widget for runtime changable accelerators is now: gtk_accel_map_add_entry(accel_path, key, mods); _gtk_widget_set_accel_path(widget, accel_path, accel_group); * gtk/gtkwindow.[hc]: accelerator changes, proxy and coalesce accel group changes (as well as mnemonic changes) through the new signal ::accels_changed. Sat Nov 10 12:08:56 2001 Tim Janik <timj@gtk.org> * gtk/gtksettings.c (_gtk_settings_parse_convert): properly handle GString->string conversions.
2001-11-13 00:53:47 +00:00
@val: %TRUE if the text in the list items is case sensitive.
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
1999-08-16 18:51:52 +00:00
<para>
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.
1999-08-16 18:51:52 +00:00
</para>
@combo: a #GtkCombo.
@item: a #GtkItem.
@item_value: the string to place in the #GtkEntry when @item is selected.
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
1999-08-16 18:51:52 +00:00
<!-- ##### FUNCTION gtk_combo_disable_activate ##### -->
<para>
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.
1999-08-16 18:51:52 +00:00
</para>
@combo: a #GtkCombo.
2005-12-20 05:47:43 +00:00
@Deprecated: 2.4: Use #GtkComboBox instead.
1999-08-16 18:51:52 +00:00