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.
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.
EXAMPLE WITH EXPLANATION
The following simple example shows basic usage of gtk_dialog_cauldron
for those writing dialogs for GUI applications:
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.
|
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.
REFERENCE
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.
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.
[
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
is a button inside an shadowed frame. The shadow is of type etched
outer.
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
are checkboxes inside a scrollable window with a vertical scrollbar but
an automatic horizontal bar (automatic means it appears only if
necesary).
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
This creates a three page notebook. The n causes one additional
conversion of type char *, which is the text to go onto the tag.
If the v option is given in addition to the n option, then
the notebook will have its tags placed to the left descending
vertically, otherwise the tags are place in the conventional position
above the notebook.
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.
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.
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-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.
RETURN VALUES
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.
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:
Each space character counts 3 pixels by default. This default can
be changed, see GLOBAL OPTIONS.
GLOBAL OPTIONS
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:
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.
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.