Dialogs

Contents

• Name
• Syntax
• Description
• See also
• Files
• Author
• Doc
• Id

Name

Syntax

 #include <xite/Xdialog.h>

 int SelectReadFile( Widget parent, char *kind,
    char **return_text );

 int SelectWriteFile( Widget parent, char *kind,
    char **return_text );

 int FormDialog( Widget parent, char *header,
    char *dialog_spec, char **return_text,
    button_table buttons, int nbuttons,
    char *winName, char *iconName );

 int InformationBox( Widget parent, char *message,
    char *winName, char *iconName );

 int ConfirmationBox( Widget parent,
    char *message, char *buttonname1,
    char *buttonname2, char *winName,
    char *iconName );

 int SimpleDialog(Widget parent, char *title,
    char *deftext, char **return_text,
    char *buttonname1, char *buttonname2);

 Widget CreateDialog( Widget parent, char *title,
    char *textField, char *winName, char *iconName,
    struct DialogArg *args, unsigned int count );

 button_table init_button_table(
    button_table buttons, int length );

Description

SelectReadFile

Creates and pops up a file selection window which returns the chosen filename through return_text. The file-selection window contains a goto-button (change directory), a select-button (take the selected filename and return), an up-button (change to parent directory) and a cancel-button. The instance name of the shell widget is "fileSelectorShell".

The file-selector widget (descendant of "fileSelectorShell") is of class XfwfFileSelector. It has instance name given by kind (without the first character). The instance name when used in XITE is one of the string constants

 readBIFFfile
 readColortabfile
 readColormapfile
 readTIFFfile
 readMATfile
 readPSfile
 readfile

Actions

The QuitFileSel action function is installed, but not bound to any event. It will typically be bound to a ClientMessage event from the window manager, desiring to close the window.

Return value

 0 : button labeled cancel was pushed or the
     QuitFileSel action function was invoked.
 1 : button labeled select was pushed (or one
     of the accelerators were used).

Accelerators

Accelerators can be installed by the application (e.g. in an X resource file) so that the return key can invoke the callbacks of the goto-button (while mouse pointer is in the directory-name field) or the callbacks of the select-button (while mouse pointer is in the filename field). A <Btn2Down> event in the file list can also invoke the select-button callbacks.

Resources

You may find some of the resources for the file-selector widget particularly useful.

The directory path used:

 <widget class or instance>*currentDirectory:

Substitute <widget class or instance> by XfwfFileSelector (class) or one of the instance names mentioned above.

Examples

 XShow*XfwfFileSelector*currentDirectory: .
 XShow*XfwfFileSelector*currentDirectory:
    $HOME/img

A pattern which the filenames, displayed in the file list, must match:

 <widget class or instance>*pattern:

Example

  XShow*readBIFFfile*pattern: *.img

Whether or not to demand existence of the specified file:

 <widget class or instance>*checkExistence:

Examples

  XShow*readColortabfile*checkExistence:  True
  XShow*writeMacrofile*checkExistence: False

SelectWriteFile

This function is similar to SelectReadFile, except that the instance name of the fileselector widget is chosen among the string constants

 writeBIFFfile
 writeColortabfile
 writeColormapfile
 writeTIFFfile
 writeMATfile
 writePSfile
 writefile
 writeMacrofile

FormDialog

FormDialog creates a window which contains various user input-fields and buttons.

header will appear at the top of the window. Use a blank string if you simply want some space.

dialog_spec is expected to be a series of specifications of the form

 # <Leading text> # <option> # <type> # <default>

All the specifications will be presented in a window, expecting the user to take some action. <Leading text> is typically a question, <default> is the suggested answer. The user can change the answer. The results of the user actions will be returned in the string return_text.

The <option> field in the dialog specification will be returned in front of the answer. It may be empty.

The <type> field has the following interpretation

d

Input should be integer. Only digits and the minus-sign are allowed in the input. XfwfPrompt is used.

f

Input should be float (or double). Only digits, "." and the minus-sign are allowed in the input. XfwfPrompt is used.

s

Input should be string. All characters are allowed. The resulting input will be surrounded by "", to protect a multiword string input as a single string. Use the function remove_quotes_from_word(3) to remove these quotes. XfwfPrompt is used.

b

Input should be boolean. Toggle button of class XfwfToggle is used.

r0

Field is part of radio-group (of which exactly one member must be chosen). Members of the same radio-group must have the same leading text. Return default only if member is chosen. XfwfGroup is used.

This member will initially be off.

r1

Same as "r0", but this member will initially be on.

r0-

Same as "r0", but don't return default value (use only as visible label).

r1-

Same as "r1", but don't return default value (use only as visible label).

m0

Field is part of multiple-choice group (of which none, one or several may be chosen). Members of the same multiple-choice group must have the same leading text. XfwfGroup is used.

This member will initially be off.

m1

Same as "m0", but this member will initially be on.

m0-

Same as "m0", but don't return default value (use only as visible label).

m1-

Same as "m1", but don't return default value (use only as visible label).

For input fields of type d, f, and s:

Translations

 <EnterWindow>: highlight(Always)
 <LeaveWindow>: unhighlight()
 <Btn1Down>,<Btn1Up>: set() notify()

At the bottom of the window, a number of buttons (of class XfwfButton) may appear, depending on the buttons and nbuttons arguments. With buttons equal to NULL and nbuttons greater than zero and at most three, nbuttons default buttons are made, in the following order:

First button

X11 resource instance name: button0, label: "Abort". The callback function will close the dialog window, and FormDialog will return the value 0.

Second button

X11 resource instance name: button1, label: "Accept". The callback function will process the answers given and return them in return_text. Finally, the dialog is closed and FormDialog returns the value 1.

Third button

X11 resource instance name: button2, label: "Help". The callback function will create a help window with the default text content "For help, consult a manual page.".

Custom buttons can be supplied by giving a non-NULL reference for buttons. buttons is a table of button descriptions

 typedef {
   char *name, *label;
   XtCallbackProc callback;
   XtPointer closure;
 } button_element, *button_table;

name is the X11 resource instance name of the button widget, label is the visible text in the button, callback is the callback procedure added to the button's XtNactivate callback list, closure is the data passed to the callback function in its client_data argument. The function init_button_table can be used to create and initialize a button table with all element members pointing to NULL.

If name is NULL, a default X11 resource instance name for the button will be used. This is the concatenation of the string "button" and the button number (starting with "0").

If label is NULL, the same default values as for the above three default buttons will be used for the first three buttons. For additional buttons, no default is supplied. Use X11 resources for name to set it.

With callback equal to NULL, a default will be used. For the first three buttons the same functions will be used as for the three default buttons above. For additional buttons, the default callback function will close the dialog window and let FormDialog return the button number (starting with 0).

If closure is NULL, the same default values as for the above three default buttons will be used (i.e. NULL, NULL and the default help text respectively). For additional buttons, the default is a reference to an integer which contains the button number (starting with 0).

FormDialog is used by xshow (from XITE version 3.3) to interpret menu files. Prior versions used SimpleDialog, but FormDialog has a more user-friendly interface.

InformationBox

Creates a window containing message and a command button with label "Close", using CreateDialog. The window is popped down when the user pushes the button. If a translation is installed for the QuitDialog action function, then this could also pop down the window (e.g. bound to a ClientMessage event from the window manager).

Return value

 -1: Dialog window deleted by the QuitDialog
     action function. This is often bound to
     a desire by the window manager to close
     the window.
  0: ok-button was pushed.

ConfirmationBox

ConfirmationBox creates a window containing message and two command buttons labeled buttonname1 and buttonname2, using CreateDialog. The window is popped down when the user pushes one of the buttons. If a translation is installed for the QuitDialog action function, then this could also pop down the window (e.g. bound to a ClientMessage event from the window manager).

Return value

 -1: Dialog window deleted by the QuitDialog
     action function. This is often bound to
     a desire by the window manager to close
     the window.
  0: button labeled buttonname1 was pushed.
  1: button labeled buttonname2 was pushed.

SimpleDialog

Creates a dialog widget with a title, a text field deftext and two buttons (using CreateDialog). The user can edit the deftext field. The button labels are buttonname1 and buttonname2. The widget is popped up centered at the current mouse pointer position.

Callbacks

An event handling loop is installed so that the calling application waits for the dialog to finish. The callback function for the two buttons will break the event handler loop and return the (possibly user-edited) deftext string in return_text.

Actions

SimpleDialog installs the action function "returnok". It will break the event-handling loop, just as if the user had pushed one of the buttons. A copy of the (possibly user-edited) deftext string is returned in return_text in both cases.

"returnok" behaves as if the user had pushed the button labeled buttonname2. This action function is bound to the return key by CreateDialog, as explained below. Using the return key is in other words a keyboard shortcut for pushing the button.

Return value

 -1: Dialog window deleted by the QuitDialog
     action function. This is often bound to
     a desire by the window manager to close
     the window.
  0: button labeled buttonname1 was pushed.
  1: button labeled buttonname2 was pushed (or
     the keyboard shortcut was used)

CreateDialog

Creates a dialog widget with title at the top, a textField, count command-buttons, winName as window manager decoration title and iconName as window manager decoration title of iconified window. CreateDialog does not actually pop up the window.

The dialog widget is of class Dialog with instance name "dialog". It has two children, one of class Label (instance name "label") which holds title, the other of class AsciiText (instance name "value") which holds the user-editable textField.

args describes the count buttons of class XfwfButton inside the window. It is an array of structures with the attributes buttonName (type char *), handler (type XtCallbackProc) and data (type XtPointer). buttonName will become the button label, handler is a function which will be added to the XtNactivate list of all buttons, data is the client-data which is passed into the callback function when it is activated. The resource instance names of the buttons will be "button1", "button2" etc.

Actions

CreateDialog installs the action function QuitDialog. The action function will invoke the callback-function of the buttons, with client-data equal to -1 (or actually a pointer to this value). The action function is not bound to any event by CreateDialog, but will typically be bound to the event which is sent from the window manager to kill the window (<ClientMessage>WM_PROTOCOLS). This must be done by the calling application (e.g. via an X resource file).

Translations

If textField is not NULL, the following translation binding is installed on the textField part of the dialog widget:

 <Key>0xff0a: returnok()
 <Key>Return: returnok()

where the two keysymbols represent newline and carriage return respectively. The expected action function "returnok" is not installed by CreateDialog. It must be done by the caller. If it is installed, it means that the return key can be used as a shortcut to invoke "returnok" (typically the same as pushing an ok-button).

Return value

A reference to a transientShellWidgetClass widget with instance name "popup".

See also

Files

Author

Doc

Id