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 As of GTK+ 2.4, #GtkCombo has been deprecated in favor of #GtkComboBoxEntry.
  28 </para>
  29
  30 <example id="gtkcombo-simple-example">
  31 <title>Creating a <structname>GtkCombo</structname> widget with simple text
  32 items.</title>
  33 <programlisting>
  34   GtkWidget *combo;
  35   GList *items = NULL;
  36
  37   items = g_list_append (items, "First Item");
  38   items = g_list_append (items, "Second Item");
  39   items = g_list_append (items, "Third Item");
  40   items = g_list_append (items, "Fourth Item");
  41   items = g_list_append (items, "Fifth Item");
  42
  43   combo = gtk_combo_new (<!-- -->);
  44   gtk_combo_set_popdown_strings (GTK_COMBO (combo), items);
  45 </programlisting>
  46 </example>
  47
  48 <example>
  49 <title>Creating a <structname>GtkCombo</structname> widget with a complex item.</title>
  50 <programlisting>
  51   GtkWidget *combo, *item, *hbox, *arrow, *label;
  52
  53   combo = gtk_combo_new (<!-- -->);
  54
  55   item = gtk_list_item_new (<!-- -->);
  56   gtk_widget_show (item);
  57
  58   /* You can put almost anything into the GtkListItem widget. Here we will use
  59      a horizontal box with an arrow and a label in it. */
  60   hbox = gtk_hbox_new (FALSE, 3);
  61   gtk_container_add (GTK_CONTAINER (item), hbox);
  62   gtk_widget_show (hbox);
  63
  64   arrow = gtk_arrow_new (GTK_ARROW_RIGHT, GTK_SHADOW_OUT);
  65   gtk_widget_show (arrow);
  66   gtk_box_pack_start (GTK_BOX (hbox), arrow, FALSE, FALSE, 0);
  67
  68   label = gtk_label_new ("First Item");
  69   gtk_widget_show (label);
  70   gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);
  71
  72   /* You must set the string to display in the entry field when the item is
  73      selected. */
  74   gtk_combo_set_item_string (GTK_COMBO (combo), GTK_ITEM (item), "1st Item");
  75
  76   /* Now we simply add the item to the combo's list. */
  77   gtk_container_add (GTK_CONTAINER (GTK_COMBO (combo)->list), item);
  78 </programlisting>
  79 </example>
  80
  81 <!-- ##### SECTION See_Also ##### -->
  82 <para>
  83
  84 </para>
  85
  86 <!-- ##### SECTION Stability_Level ##### -->
  87
  88
  89 <!-- ##### STRUCT GtkCombo ##### -->
  90 <para>
  91 The #GtkCombo-struct struct contains the following fields.
  92 (These fields should be considered read-only. They should never be set by
  93 an application.)
  94 </para>
  95
  96 @entry: the text entry field.
  97 @list: the list shown in the drop-down window.
  98 @Deprecated: 2.4: Use #GtkComboBox instead.
  99
 100 <!-- ##### ARG GtkCombo:allow-empty ##### -->
 101 <para>
 102
 103 </para>
 104
 105 <!-- ##### ARG GtkCombo:case-sensitive ##### -->
 106 <para>
 107
 108 </para>
 109
 110 <!-- ##### ARG GtkCombo:enable-arrow-keys ##### -->
 111 <para>
 112
 113 </para>
 114
 115 <!-- ##### ARG GtkCombo:enable-arrows-always ##### -->
 116 <para>
 117
 118 </para>
 119
 120 <!-- ##### ARG GtkCombo:value-in-list ##### -->
 121 <para>
 122
 123 </para>
 124
 125 <!-- ##### FUNCTION gtk_combo_new ##### -->
 126 <para>
 127 Creates a new #GtkCombo.
 128 </para>
 129
 130 @Returns: a new #GtkCombo.
 131 @Deprecated: 2.4: Use #GtkComboBox instead.
 132
 133
 134 <!-- ##### FUNCTION gtk_combo_set_popdown_strings ##### -->
 135 <para>
 136 Convenience function to set all of the items in the popup list.
 137 (See the <link linkend="gtkcombo-simple-example">example</link> above.)
 138 </para>
 139
 140 @combo: a #GtkCombo.
 141 @strings: a list of strings, or %NULL to clear the popup list
 142 @Deprecated: 2.4: Use #GtkComboBox instead.
 143
 144
 145 <!-- ##### FUNCTION gtk_combo_set_value_in_list ##### -->
 146 <para>
 147 Specifies whether the value entered in the text entry field must match one of
 148 the values in the list. If this is set then the user will not be able to
 149 perform any other action until a valid value has been entered.
 150 </para>
 151 <para>
 152 If an empty field is acceptable, the @ok_if_empty parameter should be %TRUE.
 153 </para>
 154
 155 @combo: a #GtkCombo.
 156 @val: %TRUE if the value entered must match one of the values in the list.
 157 @ok_if_empty: %TRUE if an empty value is considered valid.
 158 @Deprecated: 2.4: Use #GtkComboBox instead.
 159
 160
 161 <!-- ##### FUNCTION gtk_combo_set_use_arrows ##### -->
 162 <para>
 163 Specifies if the arrow (cursor) keys can be used to step through the items in
 164 the list. This is on by default.
 165 </para>
 166
 167 @combo: a #GtkCombo.
 168 @val: %TRUE if the arrow keys can be used to step through the items in
 169      the list.
 170 @Deprecated: 2.4: Use #GtkComboBox instead.
 171
 172
 173 <!-- ##### FUNCTION gtk_combo_set_use_arrows_always ##### -->
 174 <para>
 175 Obsolete function, does nothing.
 176 </para>
 177
 178 @combo: a #GtkCombo.
 179 @val: unused
 180 @Deprecated: 2.4: Use #GtkComboBox instead.
 181
 182
 183 <!-- ##### FUNCTION gtk_combo_set_case_sensitive ##### -->
 184 <para>
 185 Specifies whether the text entered into the #GtkEntry field and the text in
 186 the list items is case sensitive.
 187 </para>
 188 <para>
 189 This may be useful, for example, when you have called
 190 gtk_combo_set_value_in_list() to limit the values entered, but you are not
 191 worried about differences in case.
 192 </para>
 193
 194 @combo: a #GtkCombo.
 195 @val: %TRUE if the text in the list items is case sensitive.
 196 @Deprecated: 2.4: Use #GtkComboBox instead.
 197
 198
 199 <!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
 200 <para>
 201 Sets the string to place in the #GtkEntry field when a particular list item is
 202 selected. This is needed if the list item is not a simple label.
 203 </para>
 204
 205 @combo: a #GtkCombo.
 206 @item: a #GtkItem.
 207 @item_value: the string to place in the #GtkEntry when @item is selected.
 208 @Deprecated: 2.4: Use #GtkComboBox instead.
 209
 210
 211 <!-- ##### FUNCTION gtk_combo_disable_activate ##### -->
 212 <para>
 213 Stops the #GtkCombo widget from showing the popup list when the #GtkEntry
 214 emits the "activate" signal, i.e. when the Return key is pressed.
 215 This may be useful if, for example, you want the Return key to close a dialog
 216 instead.
 217 </para>
 218
 219 @combo: a #GtkCombo.
 220 @Deprecated: 2.4: Use #GtkComboBox instead.
 221
 222