<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Combo Box</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="GTK+ 2.0 Tutorial"
HREF="book1.html"><LINK
REL="UP"
TITLE="Miscellaneous Widgets"
HREF="c753.html"><LINK
REL="PREVIOUS"
TITLE="Spin Buttons"
HREF="x967.html"><LINK
REL="NEXT"
TITLE="Calendar"
HREF="x1100.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>GTK+ 2.0 Tutorial</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x967.html"
ACCESSKEY="P"
><<< Previous</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Miscellaneous Widgets</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x1100.html"
ACCESSKEY="N"
>Next >>></A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="SEC-COMBOBOX"
>Combo Box</A
></H1
><P
>The combo box is another fairly simple widget that is really just a
collection of other widgets. From the user's point of view, the widget
consists of a text entry box and a pull down menu from which the user
can select one of a set of predefined entries. Alternatively, the user
can type a different option directly into the text box.</P
><P
>The following extract from the structure that defines a Combo Box
identifies several of the components:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>struct _GtkCombo {
GtkHBox hbox;
GtkWidget *entry;
GtkWidget *button;
GtkWidget *popup;
GtkWidget *popwin;
GtkWidget *list;
... };</PRE
></TD
></TR
></TABLE
><P
>As you can see, the Combo Box has two principal parts that you really
care about: an entry and a list.</P
><P
>First off, to create a combo box, use:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>GtkWidget *gtk_combo_new( void );</PRE
></TD
></TR
></TABLE
><P
>Now, if you want to set the string in the entry section of the combo
box, this is done by manipulating the <TT
CLASS="LITERAL"
>entry</TT
> widget directly:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> gtk_entry_set_text (GTK_ENTRY (GTK_COMBO (combo)->entry), "My String.");</PRE
></TD
></TR
></TABLE
><P
>To set the values in the popdown list, one uses the function:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_combo_set_popdown_strings( GtkCombo *combo,
GList *strings );</PRE
></TD
></TR
></TABLE
><P
>Before you can do this, you have to assemble a GList of the strings
that you want. GList is a linked list implementation that is part of
<A
HREF="c2023.html"
>GLib</A
>, a library supporting GTK. For the
moment, the quick and dirty explanation is that you need to set up a
GList pointer, set it equal to NULL, then append strings to it with</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>GList *g_list_append( GList *glist,
gpointer data );</PRE
></TD
></TR
></TABLE
><P
>It is important that you set the initial GList pointer to NULL. The
value returned from the g_list_append() function must be used as the new
pointer to the GList.</P
><P
>Here's a typical code segment for creating a set of options:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> GList *glist = NULL;
glist = g_list_append (glist, "String 1");
glist = g_list_append (glist, "String 2");
glist = g_list_append (glist, "String 3");
glist = g_list_append (glist, "String 4");
gtk_combo_set_popdown_strings (GTK_COMBO (combo), glist);
/* can free glist now, combo takes a copy */</PRE
></TD
></TR
></TABLE
><P
>The combo widget makes a copy of the strings passed to it in the glist
structure. As a result, you need to make sure you free the memory used
by the list if that is appropriate for your application.</P
><P
>At this point you have a working combo box that has been set up.
There are a few aspects of its behavior that you can change. These
are accomplished with the functions: </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_combo_set_use_arrows( GtkCombo *combo,
gboolean val );
void gtk_combo_set_use_arrows_always( GtkCombo *combo,
gboolean val );
void gtk_combo_set_case_sensitive( GtkCombo *combo,
gboolean val );</PRE
></TD
></TR
></TABLE
><P
>gtk_combo_set_use_arrows() lets the user change the value in the
entry using the up/down arrow keys. This doesn't bring up the list, but
rather replaces the current text in the entry with the next list entry
(up or down, as your key choice indicates). It does this by searching
in the list for the item corresponding to the current value in the
entry and selecting the previous/next item accordingly. Usually in an
entry the arrow keys are used to change focus (you can do that anyway
using TAB). Note that when the current item is the last of the list
and you press arrow-down it changes the focus (the same applies with
the first item and arrow-up).</P
><P
>If the current value in the entry is not in the list, then the
function of gtk_combo_set_use_arrows() is disabled.</P
><P
>gtk_combo_set_use_arrows_always() similarly allows the use the
the up/down arrow keys to cycle through the choices in the dropdown
list, except that it wraps around the values in the list, completely
disabling the use of the up and down arrow keys for changing focus.</P
><P
>gtk_combo_set_case_sensitive() toggles whether or not GTK
searches for entries in a case sensitive manner. This is used when the
Combo widget is asked to find a value from the list using the current
entry in the text box. This completion can be performed in either a
case sensitive or insensitive manner, depending upon the use of this
function. The Combo widget can also simply complete the current entry
if the user presses the key combination MOD-1 and "Tab". MOD-1 is
often mapped to the "Alt" key, by the <TT
CLASS="LITERAL"
>xmodmap</TT
> utility. Note,
however that some window managers also use this key combination, which
will override its use within GTK.</P
><P
>Now that we have a combo box, tailored to look and act how we want it,
all that remains is being able to get data from the combo box. This is
relatively straightforward. The majority of the time, all you are
going to care about getting data from is the entry. The entry is
accessed simply by <TT
CLASS="LITERAL"
>GTK_ENTRY (GTK_COMBO (combo)->entry)</TT
>. The
two principal things that you are going to want to do with it are
connect to the activate signal, which indicates that the user has
pressed the Return or Enter key, and read the text. The first is
accomplished using something like:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> g_signal_connect (GTK_COMBO (combo)->entry, "activate",
G_CALLBACK (my_callback_function), my_data);</PRE
></TD
></TR
></TABLE
><P
>Getting the text at any arbitrary time is accomplished by simply using
the entry function:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>gchar *gtk_entry_get_text( GtkEntry *entry );</PRE
></TD
></TR
></TABLE
><P
>Such as:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> gchar *string;
string = gtk_entry_get_text (GTK_ENTRY (GTK_COMBO (combo)->entry));</PRE
></TD
></TR
></TABLE
><P
>That's about all there is to it. There is a function</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>void gtk_combo_disable_activate( GtkCombo *combo );</PRE
></TD
></TR
></TABLE
><P
>that will disable the activate signal on the entry widget in the combo
box. Personally, I can't think of why you'd want to use it, but it
does exist.</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x967.html"
ACCESSKEY="P"
><<< Previous</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x1100.html"
ACCESSKEY="N"
>Next >>></A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Spin Buttons</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="c753.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Calendar</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
