gtk_dialog_cauldron - produce gtk/gnome dialog boxes from format strings

#include <gtk/gtk.h>

#include <libgnomeui/libgnomeui.h> gchar *gtk_dialog_cauldron (gchar * title, glong options, const gchar * format,...)

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

The gtk_dialog_cauldron 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.

The gtk_dialog_cauldron_parse 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.

The gtk_dialog_cauldron function has had a wrapper coded for the Python programming language and is available with the pygnome package. See USAGE FROM WITHIN PYTHON below.

Arguments are:

title

is a literal string displayed on the window managers title bar.

option

is the inclusive OR of several predefined macros described below under GLOBAL OPTIONS, dictating look and behaviour.

format

Is a string containing a list of bracketing tokens and format specifiers.

user_data

Is passed to next_arg below and is not interpreted.

next_arg

Must be of the prototype

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

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

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");

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

|

Pack side by side.

||

Pack side by side with homogenous spacing - that is, the widget or frames to the left or right will always have the same size.

/

Pack on top of each other.

//

Pack on top of each other with homogenous spacing.

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.

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

%L

Label. Causes one va_arg conversion of type gchar * dictating the label's text. This is identical to inline label given in the example above, however this allows for internationalisation.

%F, %N, %E, %P

Entry. This is one of a File, Number, plain text Entry or Password entry widget. Causes one va_arg conversion of type gchar ** which must contain the default text to be inserted into the entry widget, and must be writable to return the result. If the g option is present then entries are the gnome versions of those entries instead. In the case of F and N, two more gchar * are converted - the history_id and the file browser or calculator window title respectively. In the case of E, only one more gchar * is converted: the history_id.

%D

Date edit widget. Causes two va_arg conversions of type gdouble * and type gint. The first represents the time in seconds since Jan 1 1970 and is used to initialise the widget as well as to store the result - it is cast internally to time_t. The second is the options flag and is the inclusive OR of one or more of GNOME_DATE_EDIT_SHOW_TIME, GNOME_DATE_EDIT_24_HR, and GNOME_DATE_EDIT_WEEK_STARTS_ON_MONDAY.

%B

Button with label. One va_arg conversion of type char *, dictating the button label. If this is NULL, then gtk_button_new is called instead of gtk_button_new_with_label. If the g option is present then a Gnome stock button is drawn, in which case you can pass a Gnome stock pixmap macro instead of a string.

%C

Check box. Two va_arg conversions of type gchar *label and gint *state. If label is NULL the same applies as with B. result is stored in state.

%R

Radio button. Two va_arg conversions of type gchar *label and gint *state. Multiple radio buttons within the same frame are grouped together. If label is NULL then same applies as with B.

%S

Seperator. Vertical or horizontal automatically determined.

%SB

Spin button. Two va_arg conversions of type double climb_rate and gint digits. This is not particularly useful on its own and must be used with option j which causes conversion of an adjustment parameter set.

%T

Text. One va_arg conversion of the type gchar **text. Must be writable if option e is used to indicate that the text is editable.

%X

User defined widget. This specifier causes two va_arg conversions: a function of type GtkWidget *(*func) (GtkWidget * widget, gpointer user_data) and gpointer user_data to be passed to the function. The function takes two arguments: the toplevel window widget (which is just to fill in a first argument and needn't have any use), and the user data. The function must return a widget which will then be packed into its enclosing frame.

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.

[

A visible frame encloses the widget specified between the brackets.

%[

A frame with a title. Results in one va_arg conversion of type char *title.

(

Invisible hbox or vbox, depending on the enclosed seperators.

{

Pane box (visible frame with adjustable seperator). Only two objects may be packed inside, further objects are ignored. It is best to pack only other containers into a pane.

The closing bracket may be followed by options. Eg

    [ %B ]seo

The closing ) may be followed by the options v or h. This indicates that the box must be packed into a scrollable window. Hence

    ( %C // %C // %C )v

A very useful option is the n option. This creates a notebook page from the frame. Eg,

    ( %C // %C )n ( %L / %E )n ( %Te )n

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.

x

expand, (see gtk_box_pack_start)

f

fill, (see gtk_box_pack_start)

p

padding, (see gtk_box_pack_start). This may be specified more than once for additional padding. Padding is in units of 3 pixels per p specified. This default can be changed, see GLOBAL OPTIONS below.

d

default, causes default fill, expand, and padding of the widget into its parent box. This must not be used with x, f, or p.

si, so, sei, seo

Shadow, (see gtk_frame_set_shadow_type). This stands for one of inner, outer, etched inner and etched outer. The s option must follow the ] and not the [.

c

callback. Indicates that we want a callback function to be run after the widget is created and packed. It causes two va_arg conversions: a function of type *(*func) (GtkWidget * widget, gpointer user_data) and gpointer user_data to be passed to the function. The function takes two arguments: the widget itself, and user_data. This option may be used if their are additional things we want to do to the widget that are out of the scope of the options.

r

results. For a button widget, causes clicking on the button to assign the current state of each widgets to any user pointers given. This may be given as an option to an `Apply' button, and will necesarily be given as an option to an `Ok' button.

q

quit. For a button widget, causes the button to exit the dialog.

j

adjustment. For the Spin Button widget, passes and adjustment object to the Spin Button. This causes 6 convertions: a double * where the initial value is obtained and where the result is stored, and five more double conversions containing: the lower bound, upper bound, step increment, page increment, and page size. (Note that page size must be more than the page increment).

e

editable. For the text widget, set it to be editable. In this case, the result is assigned to the passed arg. By default the text widget only shows the text and does not allow modification.

t

inactive. Use gtk_widget_set_sensitive to disabled (gray-out) the widget.

v

vertical scrollbar. For the text widget and for the [ ] frame, this adds a vertical scrollbar.

h

horizontal scrollbar. For the text widget and for the [ ] frame, this adds a horizontal scrollbar.

a

accelerator. Causes gchar *signal, gint key, gint modifier to be converted. This will add an accelerator in the obvious way. Note that for most widgets, an accelerator need not be added, because the appropriate accelerator is added automatically with the use of an ampersand, &, before the accelerator hotkey in the label. (See ACCELERATOR AMPERSANDS below.)

u

accelerator. This accelerator is used for dialogs that are to be internationalised and is similar to a. Causes gchar *signal, gchar *key, gint modifier to be converted. To the key argument is passed the same label that is used to label the widget. The widget will contain an underbar under the character following the & symbol. For example "clicked", "&Cancel", GDK_MOD1_MASK. Binds the widget to Alt-C and completely ignores the remaining characters. You can then use the same label for the actual contents of the cancel button to cause an underbar to be written under the `C'. Note that for most widgets, an accelerator need not be added, because the appropriate accelerator is added automatically with the use of an ampersand, &, before the accelerator hotkey in the label. (See ACCELERATOR AMPERSANDS below.)

o

focus. Sets the input focus to this widget. Only one widget must have this option. (Most dialogs have a default widget accepting keyboard input to avoid having to manually set focus with the mouse.)

g

gnome. Use the Gnome version of the widget. May cause additional conversions, see %E above.

n

notebook. Cause a [ ] to be become a notebook page. See FRAMES above.

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-buttons 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.

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. Otherwise the label of the widget that was used to exit the dialog is returned.

    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 ) ", 

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

The second argument of gtk_dialog_cauldron is an inclusive OR of one or more of the following macros OR'd together:

GTK_CAULDRON_TOPLEVEL or GTK_CAULDRON_DIALOG or GTK_CAULDRON_POPUP

These are options translated to the top level window. eg GTK_WINDOW_TOPLEVEL.

GTK_CAULDRON_SPACEx

Specify the equivalent width in pixels of each space or p characters. x can have a range of 1 to 15.

GTK_CAULDRON_IGNOREESCAPE

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

GTK_CAULDRON_IGNOREENTER

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

GTK_CAULDRON_GRAB

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

GTK_CAULDRON_PARENT

Window managers sometimes allow specification of a parent window so that the behaviour of the dialog and some other top level window are associated. Gtk allows you to set the parent of the dialog. If you want to enable this, use this flag and add in an extra parent argument after the options. The new protype becomes:

gchar *gtk_dialog_cauldron (gchar * title, glong options, GtkWidget * parent, const gchar * format,...)

This example should be self explanatary. Note that as in C the results are assigned only if the 'r' option in the button is present, otherwise, the default values of the widgets are returned regardless of changes made by the user. This functionality is available with the pygnome and pygtk packages.

s = [""]

def user_widget(window,b): def cb_func(w, b): b[0] = "Hello Pressed" w = gtk_button_new_with_label("Hello") gtk_signal_connect(w, "clicked", cb_func, (b,)) return w

(button, search_string, case_sens, whole_words, reg_exp) = gtk_dialog_cauldron ( "Search", 0, " ( %Ld | %Eod ) / %[ ( %Cd // %Cd // %Cd ) ]seo / ( %Bqrxfp || %Bqxfp ) / ( %Xxf ) ", ("Enter search string:", "some default search string", "Search options", "Case sensitive", 1, "Whole words only", 0, "Regular expression", 0, "Ok", "Cancel", user_widget, (s,)) )

print s[0] print (button) print (search_string) print ("%d %d %d" % (case_sens, whole_words, reg_exp))

Gtk_dialog_cauldron is completely my own invention.

Gtk_dialog_cauldron comes with Gnome and is part of the libgnomeui library. See www.gnome.org.

Paul Sheer <psheer@obsidian.co.za>

The outer must braces should not be present, because extra outermost braces are always added to make parsing easier. Adding your own will cause an extra frame to encapsulate your outermost frame which is harmless but inefficient.

It is not possible to have a user defined widget that clears the dialog or returns the results. This must be done using a B or Bg button.