guint8     spacing,
                            GdkPixmap *pixmap,
                            GdkBitmap *mask );
</PRE>
</CODE></BLOCKQUOTE>
<P>It's quite straightforward. All the calls have the CList as the first
argument, followed by the row and column of the cell, followed by the
data to be set. The <CODE>spacing</CODE> argument in gtk_clist_set_pixtext is
the number of pixels between the pixmap and the beginning of the
text. In all cases the data is copied into the widget.
<P>To read back the data, we instead use
<P>
<BLOCKQUOTE><CODE>
<PRE>
gint gtk_clist_get_text( GtkCList  *clist,
                         gint       row,
                         gint       column,
                         gchar    **text );

gint gtk_clist_get_pixmap( GtkCList   *clist,
                           gint        row,
                           gint        column,
                           GdkPixmap **pixmap,
                           GdkBitmap **mask );

gint gtk_clist_get_pixtext( GtkCList   *clist,
                            gint        row,
                            gint        column,
                            gchar     **text,
                            guint8     *spacing,
                            GdkPixmap **pixmap,
                            GdkBitmap **mask );
</PRE>
</CODE></BLOCKQUOTE>
<P>The returned pointers are all pointers to the data stored within the
widget, so the referenced data should not be modified or released. It
isn't necessary to read it all back in case you aren't interested. Any
of the pointers that are meant for return values (all except the
clist) can be NULL. So if we want to read back only the text from a
cell that is of type pixtext, then we would do the following, assuming
that clist, row and column already exist:
<P>
<BLOCKQUOTE><CODE>
<PRE>
gchar *mytext;

gtk_clist_get_pixtext(clist, row, column, &amp;mytext, NULL, NULL, NULL);
</PRE>
</CODE></BLOCKQUOTE>
<P>There is one more call that is related to what's inside a cell in the
clist, and that's
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkCellType gtk_clist_get_cell_type( GtkCList *clist,
                                     gint      row,
                                     gint      column );
</PRE>
</CODE></BLOCKQUOTE>
<P>which returns the type of data in a cell. The return value is one of
<P>
<BLOCKQUOTE><CODE>
<PRE>
  GTK_CELL_EMPTY
  GTK_CELL_TEXT
  GTK_CELL_PIXMAP
  GTK_CELL_PIXTEXT
  GTK_CELL_WIDGET
</PRE>
</CODE></BLOCKQUOTE>
<P>There is also a function that will let us set the indentation, both
vertical and horizontal, of a cell. The indentation value is of type
gint, given in pixels, and can be both positive and negative.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_clist_set_shift( GtkCList *clist,
                          gint      row,
                          gint      column,
                          gint      vertical,
                          gint      horizontal );
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss11.7">11.7 Storing data pointers</A>
</H2>

<P>With a CList it is possible to set a data pointer for a row. This
pointer will not be visible for the user, but is merely a convenience
for the programmer to associate a row with a pointer to some
additional data.
<P>The functions should be fairly self-explanatory by now.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_clist_set_row_data( GtkCList *clist,
                             gint      row,
                             gpointer  data );

void gtk_clist_set_row_data_full( GtkCList         *clist,
                                  gint              row,
                                  gpointer          data,
                                  GtkDestroyNotify  destroy );

gpointer gtk_clist_get_row_data( GtkCList *clist,
                                 gint      row );

gint gtk_clist_find_row_from_data( GtkCList *clist,
                                   gpointer  data );
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss11.8">11.8 Working with selections</A>
</H2>

<P>There are also functions available that let us force the (un)selection
of a row. These are
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_clist_select_row( GtkCList *clist,
                           gint      row,
                           gint      column );

void gtk_clist_unselect_row( GtkCList *clist,
                             gint      row,
                             gint      column );
</PRE>
</CODE></BLOCKQUOTE>
<P>And also a function that will take x and y coordinates (for example,
read from the mousepointer), and map that onto the list, returning the
corresponding row and column.
<P>
<BLOCKQUOTE><CODE>
<PRE>
gint gtk_clist_get_selection_info( GtkCList *clist,
                                   gint      x,
                                   gint      y,
                                   gint     *row,
                                   gint     *column );
</PRE>
</CODE></BLOCKQUOTE>
<P>When we detect something of interest (it might be movement of the
pointer, a click somewhere in the list) we can read the pointer
coordinates and find out where in the list the pointer is. Cumbersome?
Luckily, there is a simpler way...
<P>
<H2><A NAME="ss11.9">11.9 The signals that bring it together</A>
</H2>

<P>As with all other widgets, there are a few signals that can be used. The
CList widget is derived from the Container widget, and so has all the
same signals, but also adds the following:
<P>
<UL>
<LI>select_row - This signal will send the following information, in
order: GtkCList *clist, gint row, gint column, GtkEventButton *event
</LI>
<LI>unselect_row - When the user unselects a row, this signal is
activated. It sends the same information as select_row
</LI>
<LI>click_column - Send GtkCList *clist, gint column</LI>
</UL>
<P>So if we want to connect a callback to select_row, the callback
function would be declared like this
<P>
<BLOCKQUOTE><CODE>
<PRE>
void select_row_callback(GtkWidget *widget,
                         gint row,
                         gint column,
                         GdkEventButton *event,
                         gpointer data);
</PRE>
</CODE></BLOCKQUOTE>
<P>The callback is connected as usual with
<P>
<BLOCKQUOTE><CODE>
<PRE>
gtk_signal_connect(GTK_OBJECT( clist),
                   "select_row"
                   GTK_SIGNAL_FUNC(select_row_callback),
                   NULL);
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss11.10">11.10 A CList example</A>
</H2>

<P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* example-start clist clist.c */

#include &lt;gtk/gtk.h>

/* User clicked the "Add List" button. */
void button_add_clicked( gpointer data )
{
    int indx;
 
    /* Something silly to add to the list. 4 rows of 2 columns each */
    gchar *drink[4][2] = { { "Milk",    "3 Oz" },
                           { "Water",   "6 l" },
                           { "Carrots", "2" },
                           { "Snakes",  "55" } };

    /* Here we do the actual adding of the text. It's done once for
     * each row.
     */
    for ( indx=0 ; indx &lt; 4 ; indx++ )
        gtk_clist_append( (GtkCList *) data, drink[indx]);

    return;
}

/* User clicked the "Clear List" button. */
void button_clear_clicked( gpointer data )
{
    /* Clear the list using gtk_clist_clear. This is much faster than
     * calling gtk_clist_remove once for each row.
     */
    gtk_clist_clear( (GtkCList *) data);

    return;
}

/* The user clicked the "Hide/Show titles" button. */
void button_hide_show_clicked( gpointer data )
{
    /* Just a flag to remember the status. 0 = currently visible */
    static short int flag = 0;

    if (flag == 0)
    {
        /* Hide the titles and set the flag to 1 */
        gtk_clist_column_titles_hide((GtkCList *) data);
        flag++;
    }
    else
    {
        /* Show the titles and reset flag to 0 */
        gtk_clist_column_titles_show((GtkCList *) data);
        flag--;
    }

    return;
}

/* If we come here, then the user has selected a row in the list. */
void selection_made( GtkWidget      *clist,
                     gint            row,
                     gint            column,
                     GdkEventButton *event,
                     gpointer        data )
{
    gchar *text;

    /* Get the text that is stored in the selected row and column
     * which was clicked in. We will receive it as a pointer in the
     * argument text.
     */
    gtk_clist_get_text(GTK_CLIST(clist), row, column, &amp;text);

    /* Just prints some information about the selected row */
    g_print("You selected row %d. More specifically you clicked in "
            "column %d, and the text in this cell is %s\n\n",
            row, column, text);

    return;
}

int main( int    argc,
          gchar *argv[] )
{                                  
    GtkWidget *window;
    GtkWidget *vbox, *hbox;
    GtkWidget *scrolled_window, *clist;
    GtkWidget *button_add, *button_clear, *button_hide_show;    
    gchar *titles[2] = { "Ingredients", "Amount" };

    gtk_init(&amp;argc, &amp;argv);
    
    window=gtk_window_new(GTK_WINDOW_TOPLEVEL);
    gtk_widget_set_usize(GTK_WIDGET(window), 300, 150);

    gtk_window_set_title(GTK_WINDOW(window), "GtkCList Example");
    gtk_signal_connect(GTK_OBJECT(window),
                       "destroy",
                       GTK_SIGNAL_FUNC(gtk_main_quit),
                       NULL);
    
    vbox=gtk_vbox_new(FALSE, 5);
    gtk_container_set_border_width(GTK_CONTAINER(vbox), 5);
    gtk_container_add(GTK_CONTAINER(window), vbox);
    gtk_widget_show(vbox);
    
    /* Create a scrolled window to pack the CList widget into */
    scrolled_window = gtk_scrolled_window_new (NULL, NULL);
    gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window),
                                    GTK_POLICY_AUTOMATIC, GTK_POLICY_ALWAYS);

    gtk_box_pack_start(GTK_BOX(vbox), scrolled_window, TRUE, TRUE, 0);
    gtk_widget_show (scrolled_window);

    /* Create the CList. For this example we use 2 columns */
    clist = gtk_clist_new_with_titles( 2, titles);

    /* When a selection is made, we want to know about it. The callback
     * used is selection_made, and its code can be found further down */
    gtk_signal_connect(GTK_OBJECT(clist), "select_row",
                       GTK_SIGNAL_FUNC(selection_made),
                       NULL);

    /* It isn't necessary to shadow the border, but it looks nice :) */
    gtk_clist_set_shadow_type (GTK_CLIST(clist), GTK_SHADOW_OUT);

    /* What however is important, is that we set the column widths as
     * they will never be right otherwise. Note that the columns are
     * numbered from 0 and up (to 1 in this case).
     */
    gtk_clist_set_column_width (GTK_CLIST(clist), 0, 150);

    /* Add the CList widget to the vertical box and show it. */
    gtk_container_add(GTK_CONTAINER(scrolled_window), clist);
    gtk_widget_show(clist);

    /* Create the buttons and add them to the window. See the button
     * tutorial for more examples and comments on this.
     */
    hbox = gtk_hbox_new(FALSE, 0);
    gtk_box_pack_start(GTK_BOX(vbox), hbox, FALSE, TRUE, 0);
    gtk_widget_show(hbox);

    button_add = gtk_button_new_with_label("Add List");
    button_clear = gtk_button_new_with_label("Clear List");
    button_hide_show = gtk_button_new_with_label("Hide/Show titles");

    gtk_box_pack_start(GTK_BOX(hbox), button_add, TRUE, TRUE, 0);
    gtk_box_pack_start(GTK_BOX(hbox), button_clear, TRUE, TRUE, 0);
    gtk_box_pack_start(GTK_BOX(hbox), button_hide_show, TRUE, TRUE, 0);

    /* Connect our callbacks to the three buttons */
    gtk_signal_connect_object(GTK_OBJECT(button_add), "clicked",
                              GTK_SIGNAL_FUNC(button_add_clicked),
                              (gpointer) clist);
    gtk_signal_connect_object(GTK_OBJECT(button_clear), "clicked",
                              GTK_SIGNAL_FUNC(button_clear_clicked),
                              (gpointer) clist);
    gtk_signal_connect_object(GTK_OBJECT(button_hide_show), "clicked",
                              GTK_SIGNAL_FUNC(button_hide_show_clicked),
                              (gpointer) clist);

    gtk_widget_show(button_add);
    gtk_widget_show(button_clear);
    gtk_widget_show(button_hide_show);

    /* The interface is completely set up so we show the window and
     * enter the gtk_main loop.
     */
    gtk_widget_show(window);
    gtk_main();
    
    return(0);
}
/* example-end */
</PRE>
</CODE></BLOCKQUOTE>
<P>
<HR>
<A HREF="gtk_tut-12.html">Next</A>
<A HREF="gtk_tut-10.html">Previous</A>
<A HREF="gtk_tut.html#toc11">Contents</A>
</BODY>
</HTML>