GTK_DIALOG_CAULDRON(Linux Programmer's ManuGTK_DIALOG_CAULDRON(3)NAME
gtk_dialog_cauldron, gtk_dialog_cauldron_parse - produce
gtk/gnome dialog boxes from format strings
SYNOPSIS
#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)
DESCRIPTION
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 func
tion 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 man
agers 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_dia_
log_cauldron.c and the pygnome package.) The caul_
dron_type's are a small set of types used for
specifying and returning widget data. They are enu
merated as GTK_CAULDRON_TYPE_* in the header file
gtkcauldron.h.
EXAMPLE WITH EXPLANATION
The following simple example shows basic usage of gtk_dia
log_cauldron for those writing dialogs for GUI applica
tions:
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 indi
cating various packing, behaviour and/or data options.
A list of frames or widgets are seperated by one of sev
eral 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 wid
get 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 wid
get 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 ver
sions of those entries instead. In the case of F
and N, two more gchar * are converted - the his
tory_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 sec
ond 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 pre
sent 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 particu
larly 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 func
tion. 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 conver
sion 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 note
book will have its tags placed to the left descend
ing 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 func
tion to be run after the widget is created and
packed. It causes two va_arg conversions: a func
tion 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 wid
gets to any user pointers given. This may be given
as an option to an `Apply' button, and will nece
sarily 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 acceler
ator in the obvious way. Note that for most wid
gets, 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 con
tents of the cancel button to cause an underbar to
be written under the `C'. Note that for most wid
gets, 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_CAUL_
DRON_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.
EXAMPLESgtk_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", ®ular_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.
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_CAUL_
DRON_POPUP
These are options translated to the top level win
dow. 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 dia
log 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 * for_
mat,...)
USAGE FROM WITHIN PYTHON
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))
STANDARDS
Gtk_dialog_cauldron is completely my own invention.
AVAILABILITY
Gtk_dialog_cauldron comes with Gnome and is part of the
libgnomeui library. See www.gnome.org.
AUTHORS
Paul Sheer <psheer@obsidian.co.za>
BUGS
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.
Linux Manpage 27 September 1998 GTK_DIALOG_CAULDRON(3)
