Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkcombo.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkCombo
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 a text entry field with a dropdown list.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkCombo widget consists of a single-line text entry field and a drop-down
  10 list. The drop-down list is displayed when the user clicks on a small arrow
  11 button to the right of the entry field.
  12 </para>
  13 <para>
  14 The drop-down list is a #GtkList widget and can be accessed using the
  15 <structfield>list</structfield> member of the #GtkCombo-struct.
  16 List elements can contain arbitrary widgets, but if an element is not a
  17 plain label, then you must use the gtk_list_set_item_string() function.
  18 This sets the string which will be placed in the text entry field when the
  19 item is selected.
  20 </para>
  21 <para>
  22 By default, the user can step through the items in the list using the
  23 arrow (cursor) keys, though this behaviour can be turned off with
  24 gtk_combo_set_use_arrows().
  25 </para>
  26 <para>
  27 Normally the arrow keys are only active when the contents of the text entry
  28 field matches one of the items in the list. If the contents of the entry field
  29 do not match any of the list items, then pressing the arrow keys does nothing.
  30 However, by calling gtk_combo_set_use_arrows_always() you can specify that the
  31 arrow keys are always active. If the contents of the entry field does not match
  32 any of the items in the list, then pressing the up or down arrow key will set
  33 the entry field to the last or first item in the list, respectively.
  34 </para>
  35
  36 <example id="gtkcombo-simple-example">
  37 <title>Creating a <structname>GtkCombo</structname> widget with simple text
  38 items.</title>
  39 <programlisting>
  40   GtkWidget *combo;
  41   GList *items = NULL;
  42
  43   items = g_list_append (items, "First Item");
  44   items = g_list_append (items, "Second Item");
  45   items = g_list_append (items, "Third Item");
  46   items = g_list_append (items, "Fourth Item");
  47   items = g_list_append (items, "Fifth Item");
  48
  49   combo = gtk_combo_new (<!-- -->);
  50   gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
  51 </programlisting>
  52 </example>
  53
  54 <example>
  55 <title>Creating a <structname>GtkCombo</structname> widget with a complex item.</title>
  56 <programlisting>
  57   GtkWidget *combo, *item, *hbox, *arrow, *label;
  58
  59   combo = gtk_combo_new (<!-- -->);
  60
  61   item = gtk_list_item_new (<!-- -->);
  62   gtk_widget_show (item);
  63
  64   /* You can put almost anything into the GtkListItem widget. Here we will use
  65      a horizontal box with an arrow and a label in it. */
  66   hbox = gtk_hbox_new (FALSE, 3);
  67   gtk_container_add (GTK_CONTAINER (item), hbox);
  68   gtk_widget_show (hbox);
  69
  70   arrow = gtk_arrow_new (GTK_ARROW_RIGHT, GTK_SHADOW_OUT);
  71   gtk_widget_show (arrow);
  72   gtk_box_pack_start (GTK_BOX (hbox), pixmap, FALSE, FALSE, 0);
  73
  74   label = gtk_label_new ("First Item");
  75   gtk_widget_show (label);
  76   gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);
  77
  78   /* You must set the string to display in the entry field when the item is
  79      selected. */
  80   gtk_combo_set_item_string (GTK_COMBO (combo), GTK_ITEM (item), "1st Item");
  81
  82   /* Now we simply add the item to the combo's list. */
  83   gtk_container_add (GTK_CONTAINER (GTK_COMBO (combo)->list), item);
  84 </programlisting>
  85 </example>
  86
  87 <!-- ##### SECTION See_Also ##### -->
  88 <para>
  89
  90 </para>
  91
  92 <!-- ##### STRUCT GtkCombo ##### -->
  93 <para>
  94 The #GtkFixedChild-struct struct contains the following fields.
  95 (These fields should be considered read-only. They should never be set by
  96 an application.)
  97
  98 <informaltable pgwide="1" frame="none" role="struct">
  99 <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
 100 <tbody>
 101
 102 <row>
 103 <entry>#GtkWidget *entry;</entry>
 104 <entry>the text entry field.</entry>
 105 </row>
 106
 107 <row>
 108 <entry>#GtkWidget *list;</entry>
 109 <entry>the list shown in the drop-down window.</entry>
 110 </row>
 111
 112 </tbody></tgroup></informaltable>
 113 </para>
 114
 115
 116 <!-- ##### FUNCTION gtk_combo_new ##### -->
 117 <para>
 118 Creates a new #GtkCombo.
 119 </para>
 120
 121 @Returns: a new #GtkCombo.
 122
 123
 124 <!-- ##### FUNCTION gtk_combo_set_popdown_strings ##### -->
 125 <para>
 126 Convenience function to set all of the items in the popup list.
 127 (See the <link linkend="gtkcombo-simple-example">example</link> above.)
 128 </para>
 129
 130 @combo: a #GtkCombo.
 131 @strings: a list of strings.
 132
 133
 134 <!-- ##### FUNCTION gtk_combo_set_value_in_list ##### -->
 135 <para>
 136 Specifies whether the value entered in the text entry field must match one of
 137 the values in the list. If this is set then the user will not be able to
 138 perform any other action until a valid value has been entered.
 139 </para>
 140 <para>
 141 If an empty field is acceptable, the @ok_if_empty parameter should be %TRUE.
 142 </para>
 143
 144 @combo: a #GtkCombo.
 145 @val: %TRUE if the value entered must match one of the values in the list.
 146 @ok_if_empty: %TRUE if an empty value is considered valid.
 147
 148
 149 <!-- ##### FUNCTION gtk_combo_set_use_arrows ##### -->
 150 <para>
 151 Specifies if the arrow (cursor) keys can be used to step through the items in
 152 the list. This is on by default.
 153 </para>
 154
 155 @combo: a #GtkCombo.
 156 @val: %TRUE if the arrow keys can be used to step through the items in the list.
 157
 158
 159 <!-- ##### FUNCTION gtk_combo_set_use_arrows_always ##### -->
 160 <para>
 161 Specifies if the arrow keys will still work even if the current contents of the
 162 #GtkEntry field do not match any of the list items.
 163 </para>
 164
 165 @combo: a #GtkCombo.
 166 @val: %TRUE if the arrow keys will still work even if the current contents of
 167 the #GtkEntry field do not match any of the list items.
 168
 169
 170 <!-- ##### FUNCTION gtk_combo_set_case_sensitive ##### -->
 171 <para>
 172 Specifies whether the text entered into the #GtkEntry field and the text in
 173 the list items is case sensitive.
 174 </para>
 175 <para>
 176 This may be useful, for example, when you have called
 177 gtk_combo_set_value_in_list() to limit the values entered, but you are not
 178 worried about differences in case.
 179 </para>
 180
 181 @combo: a #GtkCombo.
 182 @val: %TRUE if the text in the list items is case sensitive.
 183
 184
 185 <!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
 186 <para>
 187 Sets the string to place in the #GtkEntry field when a particular list item is
 188 selected. This is needed if the list item is not a simple label.
 189 </para>
 190
 191 @combo: a #GtkCombo.
 192 @item: a #GtkItem.
 193 @item_value: the string to place in the #GtkEntry when @item is selected.
 194
 195
 196 <!-- ##### FUNCTION gtk_combo_disable_activate ##### -->
 197 <para>
 198 Stops the #GtkCombo widget from showing the popup list when the #GtkEntry
 199 emits the "activate" signal, i.e. when the Return key is pressed.
 200 This may be useful if, for example, you want the Return key to close a dialog
 201 instead.
 202 </para>
 203
 204 @combo: a #GtkCombo.
 205
 206
 207 <!-- ##### ARG GtkCombo:enable-arrow-keys ##### -->
 208 <para>
 209
 210 </para>
 211
 212 <!-- ##### ARG GtkCombo:enable-arrows-always ##### -->
 213 <para>
 214
 215 </para>
 216
 217 <!-- ##### ARG GtkCombo:case-sensitive ##### -->
 218 <para>
 219
 220 </para>
 221
 222 <!-- ##### ARG GtkCombo:allow-empty ##### -->
 223 <para>
 224
 225 </para>
 226
 227 <!-- ##### ARG GtkCombo:value-in-list ##### -->
 228 <para>
 229
 230 </para>
 231