forked from AuroraMiddleware/gtk
d07573c090
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.
231 lines
6.6 KiB
Plaintext
231 lines
6.6 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
GtkCombo
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
a text entry field with a dropdown list.
|
|
|
|
<!-- ##### 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().
|
|
</para>
|
|
<para>
|
|
Normally the arrow keys are only active when the contents of the text entry
|
|
field matches one of the items in the list. If the contents of the entry field
|
|
do not match any of the list items, then pressing the arrow keys does nothing.
|
|
However, by calling gtk_combo_set_use_arrows_always() you can specify that the
|
|
arrow keys are always active. If the contents of the entry field does not match
|
|
any of the items in the list, then pressing the up or down arrow key will set
|
|
the entry field to the last or first item in the list, respectively.
|
|
</para>
|
|
|
|
<example id="gtkcombo-simple-example">
|
|
<title>Creating a #GtkCombo 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 #GtkCombo 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), pixmap, 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>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### 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.)
|
|
|
|
<informaltable pgwide=1 frame="none" role="struct">
|
|
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
|
|
<tbody>
|
|
|
|
<row>
|
|
<entry>#GtkWidget *entry;</entry>
|
|
<entry>the text entry field.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>#GtkWidget *list;</entry>
|
|
<entry>the list shown in the drop-down window.</entry>
|
|
</row>
|
|
|
|
</tbody></tgroup></informaltable>
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_combo_new ##### -->
|
|
<para>
|
|
Creates a new #GtkCombo.
|
|
</para>
|
|
|
|
@Returns: a new #GtkCombo.
|
|
|
|
|
|
<!-- ##### 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.)
|
|
</para>
|
|
|
|
@combo: a #GtkCombo.
|
|
@strings: a list of strings.
|
|
|
|
|
|
<!-- ##### 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.
|
|
</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.
|
|
|
|
|
|
<!-- ##### 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.
|
|
</para>
|
|
|
|
@combo: a #GtkCombo.
|
|
@val: %TRUE if the arrow keys can be used to step through the items in the list.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_combo_set_use_arrows_always ##### -->
|
|
<para>
|
|
Specifies if the arrow keys will still work even if the current contents of the
|
|
#GtkEntry field do not match any of the list items.
|
|
</para>
|
|
|
|
@combo: a #GtkCombo.
|
|
@val: %TRUE if the arrow keys will still work even if the current contents of
|
|
the #GtkEntry field do not match any of the list items.
|
|
|
|
|
|
<!-- ##### 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.
|
|
</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.
|
|
</para>
|
|
|
|
@combo: a #GtkCombo.
|
|
@val: %TRUE if the text in the list items is case sensitive.
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
|
|
<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.
|
|
</para>
|
|
|
|
@combo: a #GtkCombo.
|
|
@item: a #GtkItem.
|
|
@item_value: the string to place in the #GtkEntry when @item is selected.
|
|
|
|
|
|
<!-- ##### 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.
|
|
</para>
|
|
|
|
@combo: a #GtkCombo.
|
|
|
|
|
|
<!-- ##### ARG GtkCombo:enable-arrow-keys ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkCombo:enable-arrows-always ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkCombo:case-sensitive ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkCombo:allow-empty ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### ARG GtkCombo:value-in-list ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|