Labels are used a lot in GTK, and are relatively simple. Labels emit no signals as they do not have an associated X window. If you need to catch signals, or do clipping, use the EventBox widget.
To create a new label, use:
GtkWidget* gtk_label_new (char *str);
Where the sole argument is the string you wish the label to display.
To change the label's text after creation, use the function:
void gtk_label_set (GtkLabel *label,
char *str);
Where the first argument is the label you created previously (casted using the GTK_LABEL() macro), and the second is the new string.
The space needed for the new string will be automatically adjusted if needed.
To retrieve the current string, use:
void gtk_label_get (GtkLabel *label,
char **str);
Where the first arguement is the label you've created, and the second, the return for the string.
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 call to create a new progress bar.
GtkWidget *gtk_progress_bar_new (void);
Now that the progress bar has been created we can use it.
void gtk_progress_bar_update (GtkProgressBar *pbar, gfloat percentage);
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% (a real number between 0 and 1).
Progress Bars are usually used with timeouts or other such functions (see section on Timeouts, I/O and Idle Functions) to give the illusion of multitasking. All will employ the gtk_progress_bar_update function in the same manner.
Here is an example of the progress bar, updated using timeouts. This code also shows you how to reset the Progress Bar.
#include <gtk/gtk.h>
static int ptimer = 0;
int pstat = TRUE;
/* This function increments and updates the progress bar, it also resets
the progress bar if pstat is FALSE */
gint progress (gpointer data)
{
gfloat pvalue;
/* get the current value of the progress bar */
pvalue = GTK_PROGRESS_BAR (data)->percentage;
if ((pvalue >= 1.0) || (pstat == FALSE)) {
pvalue = 0.0;
pstat = TRUE;
}
pvalue += 0.01;
gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);
return TRUE;
}
/* This function signals a reset of the progress bar */
void progress_r (void)
{
pstat = FALSE;
}
void destroy (GtkWidget *widget, gpointer *data)
{
gtk_main_quit ();
}
int main (int argc, char *argv[])
{
GtkWidget *window;
GtkWidget *button;
GtkWidget *label;
GtkWidget *table;
GtkWidget *pbar;
gtk_init (&argc, &argv);
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
gtk_signal_connect (GTK_OBJECT (window), "destroy",
GTK_SIGNAL_FUNC (destroy), NULL);
gtk_container_border_width (GTK_CONTAINER (window), 10);
table = gtk_table_new(3,2,TRUE);
gtk_container_add (GTK_CONTAINER (window), table);
label = gtk_label_new ("Progress Bar Example");
gtk_table_attach_defaults(GTK_TABLE(table), label, 0,2,0,1);
gtk_widget_show(label);
/* Create a new progress bar, pack it into the table, and show it */
pbar = gtk_progress_bar_new ();
gtk_table_attach_defaults(GTK_TABLE(table), pbar, 0,2,1,2);
gtk_widget_show (pbar);
/* Set the timeout to handle automatic updating of the progress bar */
ptimer = gtk_timeout_add (100, progress, pbar);
/* This button signals the progress bar to be reset */
button = gtk_button_new_with_label ("Reset");
gtk_signal_connect (GTK_OBJECT (button), "clicked",
GTK_SIGNAL_FUNC (progress_r), NULL);
gtk_table_attach_defaults(GTK_TABLE(table), button, 0,1,2,3);
gtk_widget_show(button);
button = gtk_button_new_with_label ("Cancel");
gtk_signal_connect (GTK_OBJECT (button), "clicked",
GTK_SIGNAL_FUNC (destroy), NULL);
gtk_table_attach_defaults(GTK_TABLE(table), button, 1,2,2,3);
gtk_widget_show (button);
gtk_widget_show(table);
gtk_widget_show(window);
gtk_main ();
return 0;
}
In this small program there are four areas that concern the general operation of Progress Bars, we will look at them in the order they are called.
pbar = gtk_progress_bar_new ();
This code creates a new progress bar, called pbar.
ptimer = gtk_timeout_add (100, progress, pbar);
This code, uses timeouts to enable a constant time interval, timeouts are not necessary in the use of Progress Bars.
pvalue = GTK_PROGRESS_BAR (data)->percentage;
This code assigns the current value of the percentage bar to pvalue.
gtk_progress_bar_update (GTK_PROGRESS_BAR (data), pvalue);
Finally, this code updates the progress bar with the value of pvalue
And that is all there is to know about Progress Bars, enjoy.
The Dialog widgets are very simple, and is actually just a window with a few things pre-packed into it for you. The structure for a Dialog is:
struct GtkDialog
{
GtkWindow window;
GtkWidget *vbox;
GtkWidget *action_area;
};
So you see, it simple creates a window, and then packs a vbox into the top, then a seperator, and then an hbox for the "action_area".
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:
GtkWidget* gtk_dialog_new (void);
So to create a new dialog box, use,
GtkWidget window;
window = gtk_dialog_new ();
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 so:
button = ...
gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area), button,
TRUE, TRUE, 0);
gtk_widget_show (button);
And you could add to the vbox area by packing, for instance, a label in it, try something like this:
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);
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.
Undocumented.
Undocumented.