gtkcauldron

Name

gtkcauldron -- Produce gtk/gnome dialog boxes from format strings.

Synopsis


#include <gnome.h>


#define     GTK_CAULDRON_TOPLEVEL
#define     GTK_CAULDRON_DIALOG
#define     GTK_CAULDRON_POPUP
#define     GTK_CAULDRON_SPACE_SHIFT
#define     GTK_CAULDRON_SPACE_MASK
#define     GTK_CAULDRON_SPACE1
#define     GTK_CAULDRON_SPACE2
#define     GTK_CAULDRON_SPACE3
#define     GTK_CAULDRON_SPACE4
#define     GTK_CAULDRON_SPACE5
#define     GTK_CAULDRON_SPACE6
#define     GTK_CAULDRON_SPACE7
#define     GTK_CAULDRON_SPACE8
#define     GTK_CAULDRON_SPACE9
#define     GTK_CAULDRON_SPACE10
#define     GTK_CAULDRON_SPACE11
#define     GTK_CAULDRON_SPACE12
#define     GTK_CAULDRON_SPACE13
#define     GTK_CAULDRON_SPACE14
#define     GTK_CAULDRON_SPACE15
#define     GTK_CAULDRON_IGNOREESCAPE
#define     GTK_CAULDRON_IGNOREENTER
#define     GTK_CAULDRON_GRAB
void        (*GtkCauldronNextArgCallback)   (gint cauldron_type,
                                             gpointer user_data,
                                             void *result);
GtkWidget*  (*GtkCauldronCustomCallback)    (GtkWidget *widget,
                                             gpointer user_data);
gchar*      gtk_dialog_cauldron             (const gchar *title,
                                             glong options,
                                             ...);
gchar*      gtk_dialog_cauldron_parse       (const gchar *title,
                                             glong options,
                                             const gchar *format,
                                             GtkCauldronNextArgCallback next_arg,
                                             gpointer user_data,
                                             GtkWidget *parent);

Description

The following simple example shows basic usage of gtk_dialog_cauldron() for those writing dialogs for GUI applications:

    gtk_dialog_cauldron ("Search", 0,
        " ( (Enter search string:) | Eod ) / ( Bqrxfp || Bqxfp ) ", 
            &search_string, "Ok", "Cancel");
  

The format string consists of a list of frames or widgets which are packed consecutively into the top-level window. Each frame is specified with an opening and closing frame token (a bracket). Each widget specifier consists of a % followed by one or more capital letters indicating the widget type, followed by zero or more small letters indicating various packing, behaviour and/or data options.

A list of frames or widgets are seperated by one of several seperator-tokens. Their meanings are:

If no seperator is specified, then a | seperator is implied. Frames can be nested infinitely within each other. Only one type of seperator can be used within a single frame. If more than one kind of seperator is used within a single frame, then each seperator within that frame will revert to the type of the first seperator within that frame.

In the above example, the E stands for Entry-widget and the B stands for Button-widget. Each of these widgets incurs one format conversion: in the case of the entry widget, a char ** must be passed, while in that case of the button widget, a char * must be passed. The entry widget will store its result into search_string if the dialog is not cancelled and hence search_string must be writable. The entry widget also derives its default text from this variable.

The dialog consists of two frames placed above each other, (defined by the two pairs of brackets). The buttons are of the same size, while the label and entry widgets are spaced as they require.

Reference

The following is a complete list of the widgets. Each widget can take additional options which are described in options section below.


Frames

Different kinds of brackets specify different kinds of frames. These may also take an option, although the option must be specified after the closing bracket and not after the opening bracket.


Options

Conversions caused by an option happen in the following order, regardless of the order in which the options are given: g, j, a, u then c.


Accelerator ampersands

Any widget's text having an & sign in it will have an underbar placed below the letter after the & sign. The & will not be shown. To draw an actual & sign, use a double ampersand: &&

Buttons, check-boxes, and radio-buttonsP will also have an accelerator automatically added to them along with the underbar. It will be bound to the key Alt-X where X is the letter following the ampersand.


Examples

    gtk_dialog_cauldron ("Search", 0,
    " ( Ld | Eod ) / %[ ( Cd // Cd // Cd ) ]seo / ( Bqrxfp || Bqxfp ) ", 
/* L */		"Enter search string:",
/* E */		&search_string,
/* %[ */		"Search options",
/* C */		"Case sensitive", &case_sensitive,
/* C */		"Whole words only", &whole_word,
/* C */		"Regular expression", &regular_expression,
/* B */		"Ok",
/* B */		"Cancel");

Interwidget spacing can be increased by inserting more space characters between format specifiers, however only the first gab is looked at. Eg, spreading out the check boxes can be done with:


    " ( Ld | Ed ) / %[ ( Cd           // Cd // Cd ) ]seo / 
( Bqrefp || Bqefp ) ", 

The space between the widget and its parent box can be adjusted by adding space after the bracket, eg:

    " (          Ld | Ed ) / %[ ( Cd // Cd // Cd ) ]seo /
( Bqrefp || Bqefp ) ", 

Each space character counts 3 pixels by default. This default can be changed, see global options.

Details

GTK_CAULDRON_TOPLEVEL

#define GTK_CAULDRON_TOPLEVEL	(0x1L<<0)

This is translated to the top level window (GTK_WINDOW_TOPLEVEL)


GTK_CAULDRON_DIALOG

#define GTK_CAULDRON_DIALOG		(0x1L<<1)

This is translated to the top level window (GTK_WINDOW_TOPLEVEL)


GTK_CAULDRON_POPUP

#define GTK_CAULDRON_POPUP		(0x1L<<2)

This is translated to the top level window (GTK_WINDOW_TOPLEVEL)


GTK_CAULDRON_SPACE_SHIFT

#define GTK_CAULDRON_SPACE_SHIFT	(3)


GTK_CAULDRON_SPACE_MASK

#define GTK_CAULDRON_SPACE_MASK	(0xFL<<GTK_CAULDRON_SPACE_SHIFT)


GTK_CAULDRON_SPACE1

#define GTK_CAULDRON_SPACE1		(0x1L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 1 pixels of each space or p characters.


GTK_CAULDRON_SPACE2

#define GTK_CAULDRON_SPACE2		(0x2L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 2 pixels of each space or p characters.


GTK_CAULDRON_SPACE3

#define GTK_CAULDRON_SPACE3		(0x3L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 3 pixels of each space or p characters.


GTK_CAULDRON_SPACE4

#define GTK_CAULDRON_SPACE4		(0x4L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 4 pixels of each space or p characters.


GTK_CAULDRON_SPACE5

#define GTK_CAULDRON_SPACE5		(0x5L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 5 pixels of each space or p characters.


GTK_CAULDRON_SPACE6

#define GTK_CAULDRON_SPACE6		(0x6L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 6 pixels of each space or p characters.


GTK_CAULDRON_SPACE7

#define GTK_CAULDRON_SPACE7		(0x7L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 7 pixels of each space or p characters.


GTK_CAULDRON_SPACE8

#define GTK_CAULDRON_SPACE8		(0x8L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 8 pixels of each space or p characters.


GTK_CAULDRON_SPACE9

#define GTK_CAULDRON_SPACE9		(0x9L<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 9 pixels of each space or p characters.


GTK_CAULDRON_SPACE10

#define GTK_CAULDRON_SPACE10		(0xAL<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 10 pixels of each space or p characters.


GTK_CAULDRON_SPACE11

#define GTK_CAULDRON_SPACE11		(0xBL<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 11 pixels of each space or p characters.


GTK_CAULDRON_SPACE12

#define GTK_CAULDRON_SPACE12		(0xCL<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 12 pixels of each space or p characters.


GTK_CAULDRON_SPACE13

#define GTK_CAULDRON_SPACE13		(0xDL<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 13 pixels of each space or p characters.


GTK_CAULDRON_SPACE14

#define GTK_CAULDRON_SPACE14		(0xEL<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 14 pixels of each space or p characters.


GTK_CAULDRON_SPACE15

#define GTK_CAULDRON_SPACE15		(0xFL<<GTK_CAULDRON_SPACE_SHIFT)

Specify a width of 15 pixels of each space or p characters.


GTK_CAULDRON_IGNOREESCAPE

#define GTK_CAULDRON_IGNOREESCAPE	(0x1L<<7)

Normalling, pressing the Escape key terminates the dialog. This prevents this.


GTK_CAULDRON_IGNOREENTER

#define GTK_CAULDRON_IGNOREENTER	(0x1L<<8)

Normalling, pressing the Enter/Return key assigns the values and terminates. This prevents this.


GTK_CAULDRON_GRAB

#define GTK_CAULDRON_GRAB		(0x1L<<9)

Causes a grab on the dialog - that is, no other widgets in the application will work until the dialog exits.


GtkCauldronNextArgCallback ()

void        (*GtkCauldronNextArgCallback)   (gint cauldron_type,
                                             gpointer user_data,
                                             void *result);

cauldron_type : 
user_data : 
result : 


GtkCauldronCustomCallback ()

GtkWidget*  (*GtkCauldronCustomCallback)    (GtkWidget *widget,
                                             gpointer user_data);

widget : 
user_data : 
Returns : 


gtk_dialog_cauldron ()

gchar*      gtk_dialog_cauldron             (const gchar *title,
                                             glong options,
                                             ...);

This function parses a format string with a variable length list of arguments. The format string describes a dialog box and has intuitive tokens to represent different frames and widgets. The dialog box is drawn whereupon gtk_dialog_cauldron() blocks until closed or until an appropriate button is pushed. Results from the widgets are then stored into appropriate variables passed in the argument list in order to be retrieved by the caller.

Retuns NULL is returned if the dialog is cancelled. GTK_CAULDRON_ENTERP is returned if the user pressed enter (return-on-enter can be overridden - see global options below), and GTK_CAULDRON_ESCAPEP is returned if the user pressed escape. Otherwise the label of the widget that was used to exit the dialog is returned.

title : dialog title
options : dialog options, see the macro definitions
... : 
Returns : 


gtk_dialog_cauldron_parse ()

gchar*      gtk_dialog_cauldron_parse       (const gchar *title,
                                             glong options,
                                             const gchar *format,
                                             GtkCauldronNextArgCallback next_arg,
                                             gpointer user_data,
                                             GtkWidget *parent);

This function parses a format string exactly like gtk_dialog_cauldron(), however it derives arguments for the format string from a user function next_arg. gtk_dialog_cauldron_parse() is primarily used for creating wrappers for interpreted languages.

Each subsequent call to next_arg must assign to <type>*result</type> a pointer to data of the type specified by <type>cauldron_type</type>. (An example can be found in <filename>gtk_dialog_cauldron.c</filename> and the pygnome package.) The \fIcauldron_type\fP's are a small set of types used for specifying and returning widget data. They are enumerated as <type>GTK_CAULDRON_TYPE_*</type> in the header file gtkcauldron.h.

NULL is returned if the dialog is cancelled. GTK_CAULDRON_ENTER is returned if the user pressed enter (return-on-enter can be overridden - see global options below), and GTK_CAULDRON_ESCAPE is returned if the user pressed escape. GTK_CAULDRON_ERROR is returned by gtk_dialog_cauldron_parse() if an error occurred (like a malformed format string). The error message can be retrieved by gtk_dialog_cauldron_get_error(). Otherwise the label of the widget that was used to exit the dialog is returned.

title : dialog title
options : dialog options, see the macro definitions
format : format string that describes the dialog
next_arg : user function.
user_data : data to pass to user function
parent : 
Returns :