gtk_tut-9.html

GTK development guide

</PRE>
</CODE></BLOCKQUOTE>
<P>The first argument is the tooltip you've already created, followed by
the widget you wish to have this tooltip pop up for, and the text you
wish it to say. The last argument is a text string that can be used as
an identifier when using GtkTipsQuery to implement context sensitive
help. For now, you can set it to NULL.
<P>
<P>Here's a short example:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkTooltips *tooltips;
GtkWidget *button;
.
.
.
tooltips = gtk_tooltips_new ();
button = gtk_button_new_with_label ("button 1");
.
.
.
gtk_tooltips_set_tip (tooltips, button, "This is button 1", NULL);
</PRE>
</CODE></BLOCKQUOTE>
<P>There are other calls that can be used with tooltips. I will just list
them with a brief description of what they do.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tooltips_enable( GtkTooltips *tooltips );
</PRE>
</CODE></BLOCKQUOTE>
<P>Enable a disabled set of tooltips.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tooltips_disable( GtkTooltips *tooltips );
</PRE>
</CODE></BLOCKQUOTE>
<P>Disable an enabled set of tooltips.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tooltips_set_delay( GtkTooltips *tooltips,
                             gint         delay );
</PRE>
</CODE></BLOCKQUOTE>
<P>Sets how many milliseconds you have to hold your pointer over the
widget before the tooltip will pop up. The default is 500
milliseconds (half a second).
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tooltips_set_colors( GtkTooltips *tooltips,
                              GdkColor    *background,
                              GdkColor    *foreground );
</PRE>
</CODE></BLOCKQUOTE>
<P>Set the foreground and background color of the tooltips.
<P>And that's all the functions associated with tooltips. More than
you'll ever want to know :-)
<P>
<H2><A NAME="sec_ProgressBar"></A> <A NAME="ss9.4">9.4 Progress Bars </A>
</H2>

<P>Progress bars are used to show the status of an operation. They are
pretty easy to use, as you will see with the code below. But first
lets start out with the calls to create a new progress bar.
<P>There are two ways to create a progress bar, one simple that takes
no arguments, and one that takes an Adjustment object as an
argument. If the former is used, the progress bar creates its own
adjustment object.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_progress_bar_new( void );

GtkWidget *gtk_progress_bar_new_with_adjustment( GtkAdjustment *adjustment );
</PRE>
</CODE></BLOCKQUOTE>
<P>The second method has the advantage that we can use the adjustment
object to specify our own range parameters for the progress bar.
<P>The adjustment of a progress object can be changed dynamically using:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_set_adjustment( GtkProgress   *progress,
                                  GtkAdjustment *adjustment );
</PRE>
</CODE></BLOCKQUOTE>
<P>Now that the progress bar has been created we can use it.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_bar_update( GtkProgressBar *pbar,
                              gfloat          percentage );
</PRE>
</CODE></BLOCKQUOTE>
<P>The first argument is the progress bar you wish to operate on, and the
second argument is the amount "completed", meaning the amount the
progress bar has been filled from 0-100%. This is passed to the
function as a real number ranging from 0 to 1.
<P>GTK v1.2 has added new functionality to the progress bar that enables
it to display its value in different ways, and to inform the user of
its current value and its range.
<P>A progress bar may be set to one of a number of orientations using the
function
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_bar_set_orientation( GtkProgressBar *pbar,
                                       GtkProgressBarOrientation orientation );
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>orientation</CODE> argument may take one of the following
values to indicate the direction in which the progress bar moves:
<P>
<BLOCKQUOTE><CODE>
<PRE>
  GTK_PROGRESS_LEFT_TO_RIGHT
  GTK_PROGRESS_RIGHT_TO_LEFT
  GTK_PROGRESS_BOTTOM_TO_TOP
  GTK_PROGRESS_TOP_TO_BOTTOM
</PRE>
</CODE></BLOCKQUOTE>
<P>When used as a measure of how far a process has progressed, the
ProgressBar can be set to display its value in either a continuous
or discrete mode. In continuous mode, the progress bar is updated for
each value. In discrete mode, the progress bar is updated in a number
of discrete blocks. The number of blocks is also configurable.
<P>The style of a progress bar can be set using the following function.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_bar_set_bar_style( GtkProgressBar      *pbar,
                                     GtkProgressBarStyle  style );
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>style</CODE> parameter can take one of two values:
<P>
<BLOCKQUOTE><CODE>
<PRE>
  GTK_PROGRESS_CONTINUOUS
  GTK_PROGRESS_DISCRETE
</PRE>
</CODE></BLOCKQUOTE>
<P>The number of discrete blocks can be set by calling
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_bar_set_discrete_blocks( GtkProgressBar *pbar,
                                           guint           blocks );
</PRE>
</CODE></BLOCKQUOTE>
<P>As well as indicating the amount of progress that has occured, the
progress bar may be set to just indicate that there is some
activity. This can be useful in situations where progress cannot be
measured against a value range. Activity mode is not effected by the
bar style that is described above, and overrides it. This mode is
either TRUE or FALSE, and is selected by the following function.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_set_activity_mode( GtkProgress *progress,
                                     guint        activity_mode );
</PRE>
</CODE></BLOCKQUOTE>
<P>The step size of the activity indicator, and the number of blocks are
set using the following functions.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_bar_set_activity_step( GtkProgressBar *pbar,
                                         guint           step );

void gtk_progress_bar_set_activity_blocks( GtkProgressBar *pbar,
                                           guint           blocks );
</PRE>
</CODE></BLOCKQUOTE>
<P>When in continuous mode, the progress bar can also display a
configurable text string within its trough, using the following
function.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_set_format_string( GtkProgress *progress,
                                     gchar       *format);
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>format</CODE> argument is similiar to one that would be used in a C
<CODE>printf</CODE> statement. The following directives may be used within the
format string:
<P>
<UL>
<LI> %p - percentage</LI>
<LI> %v - value</LI>
<LI> %l - lower range value</LI>
<LI> %u - upper range value</LI>
</UL>
<P>The displaying of this text string can be toggled using:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_set_show_text( GtkProgress *progress,
                                 gint         show_text );
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>show_text</CODE> argument is a boolean TRUE/FALSE value. The
appearance of the text can be modified further using:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_set_text_alignment( GtkProgress   *progress,
                                      gfloat         x_align,
                                      gfloat         y_align );
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>x_align</CODE> and <CODE>y_align</CODE> arguments take values between 0.0
and 1.0. Their values indicate the position of the text string within
the trough. Values of 0.0 for both would place the string in the top
left hand corner; values of 0.5 (the default) centres the text, and
values of 1.0 places the text in the lower right hand corner.
<P>The current text setting of a progress object can be retrieved using
the current or a specified adjustment value using the following two
functions. The character string returned by these functions should be
freed by the application (using the g_free() function). These
functions return the formatted string that would be displayed within
the trough.
<P>
<BLOCKQUOTE><CODE>
<PRE>
gchar *gtk_progress_get_current_text( GtkProgress   *progress );

gchar *gtk_progress_get_text_from_value( GtkProgress *progress,
                                         gfloat       value );
</PRE>
</CODE></BLOCKQUOTE>
<P>There is yet another way to change the range and value of a progress
object using the following function:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_configure( GtkProgress  *progress,
                             gfloat        value,
                             gfloat        min,
                             gfloat        max );
</PRE>
</CODE></BLOCKQUOTE>
<P>This function provides quite a simple interface to the range and value
of a progress object.
<P>The remaining functions can be used to get and set the current value
of a progess object in various types and formats:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_progress_set_percentage( GtkProgress *progress,
                                  gfloat       percentage );

void gtk_progress_set_value( GtkProgress *progress,
                             gfloat       value );

gfloat gtk_progress_get_value( GtkProgress *progress );

gfloat gtk_progress_get_current_percentage( GtkProgress *progress );

gfloat gtk_progress_get_percentage_from_value( GtkProgress *progress,
                                               gfloat       value );
</PRE>
</CODE></BLOCKQUOTE>
<P>These functions are pretty self explanatory. The last function uses
the the adjustment of the specified progess object to compute the
percentage value of the given range value.
<P>Progress Bars are usually used with timeouts or other such functions
(see section on 
<A HREF="gtk_tut-17.html#sec_timeouts">Timeouts, I/O and Idle Functions</A>) to give the illusion of multitasking. All will employ the
gtk_progress_bar_update function in the same manner.
<P>Here is an example of the progress bar, updated using timeouts. This
code also shows you how to reset the Progress Bar.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* example-start progressbar progressbar.c */

#include &lt;gtk/gtk.h>

typedef struct _ProgressData {
    GtkWidget *window;
    GtkWidget *pbar;
    int timer;
} ProgressData;

/* Update the value of the progress bar so that we get
 * some movement */
gint progress_timeout( gpointer data )
{
    gfloat new_val;
    GtkAdjustment *adj;

    /* Calculate the value of the progress bar using the
     * value range set in the adjustment object */

    new_val = gtk_progress_get_value( GTK_PROGRESS(data) ) + 1;

    adj = GTK_PROGRESS (data)->adjustment;
    if (new_val > adj->upper)
      new_val = adj->lower;

    /* Set the new value */
    gtk_progress_set_value (GTK_PROGRESS (data), new_val);

    /* As this is a timeout function, return TRUE so that it
     * continues to get called */
    return(TRUE);
} 

/* Callback that toggles the text display within the progress
 * bar trough */
void toggle_show_text( GtkWidget    *widget,
                       ProgressData *pdata )
{
    gtk_progress_set_show_text (GTK_PROGRESS (pdata->pbar),
                                GTK_TOGGLE_BUTTON (widget)->active);
}

/* Callback that toggles the activity mode of the progress
 * bar */
void toggle_activity_mode( GtkWidget    *widget,
                           ProgressData *pdata )
{
    gtk_progress_set_activity_mode (GTK_PROGRESS (pdata->pbar),
                                    GTK_TOGGLE_BUTTON (widget)->active);
}

/* Callback that toggles the continuous mode of the progress
 * bar */
void set_continuous_mode( GtkWidget    *widget,
                          ProgressData *pdata )
{
    gtk_progress_bar_set_bar_style (GTK_PROGRESS_BAR (pdata->pbar),
                                    GTK_PROGRESS_CONTINUOUS);
}

/* Callback that toggles the discrete mode of the progress
 * bar */
void set_discrete_mode( GtkWidget    *widget,
                        ProgressData *pdata )
{
    gtk_progress_bar_set_bar_style (GTK_PROGRESS_BAR (pdata->pbar),
                                    GTK_PROGRESS_DISCRETE);
}
 
/* Clean up allocated memory and remove the timer */
void destroy_progress( GtkWidget     *widget,
                       ProgressData *pdata)
{
    gtk_timeout_remove (pdata->timer);
    pdata->timer = 0;
    pdata->window = NULL;
    g_free(pdata);
    gtk_main_quit();
}

int main( int   argc,