gtk_tut-9.html

GTK development guide

          char *argv[])
{
    ProgressData *pdata;
    GtkWidget *align;
    GtkWidget *separator;
    GtkWidget *table;
    GtkAdjustment *adj;
    GtkWidget *button;
    GtkWidget *check;
    GtkWidget *vbox;

    gtk_init (&argc, &argv);

    /* Allocate memory for the data that is passwd to the callbacks */
    pdata = g_malloc( sizeof(ProgressData) );
  
    pdata->window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
    gtk_window_set_policy (GTK_WINDOW (pdata->window), FALSE, FALSE, TRUE);

    gtk_signal_connect (GTK_OBJECT (pdata->window), "destroy",
                        GTK_SIGNAL_FUNC (destroy_progress),
                        pdata);
    gtk_window_set_title (GTK_WINDOW (pdata->window), "GtkProgressBar");
    gtk_container_set_border_width (GTK_CONTAINER (pdata->window), 0);

    vbox = gtk_vbox_new (FALSE, 5);
    gtk_container_set_border_width (GTK_CONTAINER (vbox), 10);
    gtk_container_add (GTK_CONTAINER (pdata->window), vbox);
    gtk_widget_show(vbox);
  
    /* Create a centering alignment object */
    align = gtk_alignment_new (0.5, 0.5, 0, 0);
    gtk_box_pack_start (GTK_BOX (vbox), align, FALSE, FALSE, 5);
    gtk_widget_show(align);

    /* Create a Adjusment object to hold the range of the
     * progress bar */
    adj = (GtkAdjustment *) gtk_adjustment_new (0, 1, 150, 0, 0, 0);

    /* Create the GtkProgressBar using the adjustment */
    pdata->pbar = gtk_progress_bar_new_with_adjustment (adj);

    /* Set the format of the string that can be displayed in the
     * trough of the progress bar:
     * %p - percentage
     * %v - value
     * %l - lower range value
     * %u - upper range value */
    gtk_progress_set_format_string (GTK_PROGRESS (pdata->pbar),
                                    "%v from [%l-%u] (=%p%%)");
    gtk_container_add (GTK_CONTAINER (align), pdata->pbar);
    gtk_widget_show(pdata->pbar);

    /* Add a timer callback to update the value of the progress bar */
    pdata->timer = gtk_timeout_add (100, progress_timeout, pdata->pbar);

    separator = gtk_hseparator_new ();
    gtk_box_pack_start (GTK_BOX (vbox), separator, FALSE, FALSE, 0);
    gtk_widget_show(separator);

    /* rows, columns, homogeneous */
    table = gtk_table_new (2, 3, FALSE);
    gtk_box_pack_start (GTK_BOX (vbox), table, FALSE, TRUE, 0);
    gtk_widget_show(table);

    /* Add a check button to select displaying of the trough text */
    check = gtk_check_button_new_with_label ("Show text");
    gtk_table_attach (GTK_TABLE (table), check, 0, 1, 0, 1,
                      GTK_EXPAND | GTK_FILL, GTK_EXPAND | GTK_FILL,
                      5, 5);
    gtk_signal_connect (GTK_OBJECT (check), "clicked",
                        GTK_SIGNAL_FUNC (toggle_show_text),
                        pdata);
    gtk_widget_show(check);

    /* Add a check button to toggle activity mode */
    check = gtk_check_button_new_with_label ("Activity mode");
    gtk_table_attach (GTK_TABLE (table), check, 0, 1, 1, 2,
                      GTK_EXPAND | GTK_FILL, GTK_EXPAND | GTK_FILL,
                      5, 5);
    gtk_signal_connect (GTK_OBJECT (check), "clicked",
                        GTK_SIGNAL_FUNC (toggle_activity_mode),
                        pdata);
    gtk_widget_show(check);

    separator = gtk_vseparator_new ();
    gtk_table_attach (GTK_TABLE (table), separator, 1, 2, 0, 2,
                      GTK_EXPAND | GTK_FILL, GTK_EXPAND | GTK_FILL,
                      5, 5);
    gtk_widget_show(separator);

    /* Add a radio button to select continuous display mode */
    button = gtk_radio_button_new_with_label (NULL, "Continuous");
    gtk_table_attach (GTK_TABLE (table), button, 2, 3, 0, 1,
                      GTK_EXPAND | GTK_FILL, GTK_EXPAND | GTK_FILL,
                      5, 5);
    gtk_signal_connect (GTK_OBJECT (button), "clicked",
                        GTK_SIGNAL_FUNC (set_continuous_mode),
                        pdata);
    gtk_widget_show (button);

    /* Add a radio button to select discrete display mode */
    button = gtk_radio_button_new_with_label(
               gtk_radio_button_group (GTK_RADIO_BUTTON (button)),
               "Discrete");
    gtk_table_attach (GTK_TABLE (table), button, 2, 3, 1, 2,
                      GTK_EXPAND | GTK_FILL, GTK_EXPAND | GTK_FILL,
                      5, 5);
    gtk_signal_connect (GTK_OBJECT (button), "clicked",
                        GTK_SIGNAL_FUNC (set_discrete_mode),
                        pdata);
    gtk_widget_show (button);

    separator = gtk_hseparator_new ();
    gtk_box_pack_start (GTK_BOX (vbox), separator, FALSE, FALSE, 0);
    gtk_widget_show(separator);

    /* Add a button to exit the program */
    button = gtk_button_new_with_label ("close");
    gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
                               (GtkSignalFunc) gtk_widget_destroy,
                               GTK_OBJECT (pdata->window));
    gtk_box_pack_start (GTK_BOX (vbox), button, FALSE, FALSE, 0);

    /* This makes it so the button is the default. */
    GTK_WIDGET_SET_FLAGS (button, GTK_CAN_DEFAULT);

    /* This grabs this button to be the default button. Simply hitting
     * the "Enter" key will cause this button to activate. */
    gtk_widget_grab_default (button);
    gtk_widget_show(button);

    gtk_widget_show (pdata->window);

    gtk_main ();
    
    return(0);
}
/* example-end */
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss9.5">9.5 Dialogs</A>
</H2>

<P>The Dialog widget is very simple, and is actually just a window with a
few things pre-packed into it for you. The structure for a Dialog is:
<P>
<BLOCKQUOTE><CODE>
<PRE>
struct GtkDialog
{
      GtkWindow window;
    
      GtkWidget *vbox;
      GtkWidget *action_area;
};
</PRE>
</CODE></BLOCKQUOTE>
<P>So you see, it simply creates a window, and then packs a vbox into the
top, which contains a separator and then an hbox called the
"action_area".
<P>The Dialog widget can be used for pop-up messages to the user, and
other similar tasks. It is really basic, and there is only one
function for the dialog box, which is:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_dialog_new( void );
</PRE>
</CODE></BLOCKQUOTE>
<P>So to create a new dialog box, use,
<P>
<BLOCKQUOTE><CODE>
<PRE>
    GtkWidget *window;
    window = gtk_dialog_new ();
</PRE>
</CODE></BLOCKQUOTE>
<P>This will create the dialog box, and it is now up to you to use it.
You could pack a button in the action_area by doing something like this:
<P>
<BLOCKQUOTE><CODE>
<PRE>
    button = ...
    gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area),
                        button, TRUE, TRUE, 0);
    gtk_widget_show (button);
</PRE>
</CODE></BLOCKQUOTE>
<P>And you could add to the vbox area by packing, for instance, a label 
in it, try something like this:
<P>
<BLOCKQUOTE><CODE>
<PRE>
    label = gtk_label_new ("Dialogs are groovy");
    gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->vbox),
                        label, TRUE, TRUE, 0);
    gtk_widget_show (label);
</PRE>
</CODE></BLOCKQUOTE>
<P>As an example in using the dialog box, you could put two buttons in
the action_area, a Cancel button and an Ok button, and a label in the
vbox area, asking the user a question or giving an error etc. Then
you could attach a different signal to each of the buttons and perform
the operation the user selects.
<P>If the simple functionality provided by the default vertical and
horizontal boxes in the two areas doesn't give you enough control for
your application, then you can simply pack another layout widget into
the boxes provided. For example, you could pack a table into the
vertical box.
<P>
<H2><A NAME="sec_Pixmaps"></A> <A NAME="ss9.6">9.6 Pixmaps </A>
</H2>

<P>Pixmaps are data structures that contain pictures. These pictures can
be used in various places, but most commonly as icons on the X
desktop, or as cursors.
<P>A pixmap which only has 2 colors is called a bitmap, and there are a
few additional routines for handling this common special case.
<P>To understand pixmaps, it would help to understand how X window
system works. Under X, applications do not need to be running on the
same computer that is interacting with the user. Instead, the various
applications, called "clients", all communicate with a program which
displays the graphics and handles the keyboard and mouse. This
program which interacts directly with the user is called a "display
server" or "X server." Since the communication might take place over
a network, it's important to keep some information with the X server.
Pixmaps, for example, are stored in the memory of the X server. This
means that once pixmap values are set, they don't need to keep getting
transmitted over the network; instead a command is sent to "display
pixmap number XYZ here." Even if you aren't using X with GTK
currently, using constructs such as Pixmaps will make your programs
work acceptably under X.
<P>To use pixmaps in GTK, we must first build a GdkPixmap structure using
routines from the GDK layer. Pixmaps can either be created from
in-memory data, or from data read from a file. We'll go through each
of the calls to create a pixmap.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GdkPixmap *gdk_bitmap_create_from_data( GdkWindow *window,
                                        gchar     *data,
                                        gint       width,
                                        gint       height );
</PRE>
</CODE></BLOCKQUOTE>
<P>This routine is used to create a single-plane pixmap (2 colors) from
data in memory. Each bit of the data represents whether that pixel is
off or on. Width and height are in pixels. The GdkWindow pointer is to
the current window, since a pixmap's resources are meaningful only in
the context of the screen where it is to be displayed.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GdkPixmap *gdk_pixmap_create_from_data( GdkWindow *window,
                                        gchar     *data,
                                        gint       width,
                                        gint       height,
                                        gint       depth,
                                        GdkColor  *fg,
                                        GdkColor  *bg );
</PRE>
</CODE></BLOCKQUOTE>
<P>This is used to create a pixmap of the given depth (number of colors) from
the bitmap data specified. <CODE>fg</CODE> and <CODE>bg</CODE> are the foreground and
background color to use.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GdkPixmap *gdk_pixmap_create_from_xpm( GdkWindow   *window,
                                       GdkBitmap  **mask,
                                       GdkColor    *transparent_color,
                                       const gchar *filename );
</PRE>
</CODE></BLOCKQUOTE>
<P>XPM format is a readable pixmap representation for the X Window
System. It is widely used and many different utilities are available
for creating image files in this format. The file specified by
filename must contain an image in that format and it is loaded into
the pixmap structure. The mask specifies which bits of the pixmap are
opaque. All other bits are colored using the color specified by
transparent_color. An example using this follows below.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GdkPixmap *gdk_pixmap_create_from_xpm_d( GdkWindow  *window,
                                         GdkBitmap **mask,
                                         GdkColor   *transparent_color,
                                         gchar     **data );
</PRE>
</CODE></BLOCKQUOTE>
<P>Small images can be incorporated into a program as data in the XPM
format. A pixmap is created using this data, instead of reading it
from a file. An example of such data is
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* XPM */
static const char * xpm_data[] = {
"16 16 3 1",
"       c None",
".      c #000000000000",
"X      c #FFFFFFFFFFFF",
"                ",
"   ......       ",
"   .XXX.X.      ",
"   .XXX.XX.     ",
"   .XXX.XXX.    ",
"   .XXX.....    ",
"   .XXXXXXX.    ",
"   .XXXXXXX.    ",
"   .XXXXXXX.    ",
"   .XXXXXXX.    ",
"   .XXXXXXX.    ",
"   .XXXXXXX.    ",
"   .XXXXXXX.    ",
"   .........    ",
"                ",
"                "};
</PRE>
</CODE></BLOCKQUOTE>
<P>When we're done using a pixmap and not likely to reuse it again soon,
it is a good idea to release the resource using
gdk_pixmap_unref(). Pixmaps should be considered a precious resource,
because they take up memory in the end-user's X server process. Even
though the X client you write may run on a powerful "server" computer,
the user may be running the X server on a small personal computer.
<P>Once we've created a pixmap, we can display it as a GTK widget. We
must create a GTK pixmap widget to contain the GDK pixmap. This is
done using
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_pixmap_new( GdkPixmap *pixmap,
                           GdkBitmap *mask );
</PRE>
</CODE></BLOCKQUOTE>
<P>The other pixmap widget calls are
<P>
<BLOCKQUOTE><CODE>
<PRE>
guint gtk_pixmap_get_type( void );

void  gtk_pixmap_set( GtkPixmap  *pixmap,
                      GdkPixmap  *val,
                      GdkBitmap  *mask );

void  gtk_pixmap_get( GtkPixmap  *pixmap,
                      GdkPixmap **val,
                      GdkBitmap **mask);
</PRE>
</CODE></BLOCKQUOTE>
<P>gtk_pixmap_set is used to change the pixmap that the widget is currently
managing. Val is the pixmap created using GDK.
<P>The following is an example of using a pixmap in a button.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* example-start pixmap pixmap.c */

#include &lt;gtk/gtk.h>