---
name: "gtk_dialog_cauldron"
section: "3"
platform: "linux"
package: "libgnome-dev"
version: "1.4.2-37+b2"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/gtk_dialog_cauldron"
---

# gtk\_dialog\_cauldron(3)

produce gtk/gnome dialog boxes from format strings

## NAME

gtk\_dialog\_cauldron - 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 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.*

## EXAMPLE WITH EXPLANATION

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

- **\|**

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

## 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***.*

## 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\_SPACE***x**

  *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***,***...***)**\

## 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.*