X11workbench Toolkit  1.0
Dialog Box Resources

To simplify the creation of one of the most COMMON types of windows, the Dialog Box, the X11workbench Toolkit uses a TEXT RESOURCE format that can be subsequently passed to a high-level function to create a dialog box, either modal or modeless. The return value from a modal dialog box will be based on the value passed to WBEndModal().

For more information on creating a dialog box, see DLGCreateDialogWindow().

The format of the dialog box resource begins with the 'BEGIN_DIALOG' keyword, and ends with the 'END_DIALOG' keyword. In between are the various dialog controls, in their 'tab order', such that the first control in the list that is capable of receiving the input focus will get the focus when the window is made visible.

A typical dialog window resource might look as follows:

BEGIN_DIALOG FONT:Variable HEIGHT:50 WIDTH:200 TITLE:"Sample Message Box Dialog Window"

The general form of a dialog resource keyword is as follows:

KEYWORD[:type] [ID:value] [property[:value] [property[:value] [...]]]

where KEYWORD is defined as BEGIN_DIALOG, END_DIALOG, or CONTROL and 'type' is valid ONLY for 'CONTROL' and 'ID' is valid ONLY for 'CONTROL' or sub-dialogs and 'property' represents one or more properties (which may or may not have values).

The value of a property is always separated from the property by a : with no white space. If the value contains white space, it must be quoted (as in the above sample). A doubled quote mark will translate into a single quote if embedded within identical quote marks, such as

"This is a ""quote"" mark"

translating into

This is a "quote" mark

Properties that use reserved keywords will NORMALLY have their values stored directly into the corresponding area(s) within the dialog box's defining structures. Additional properties (including custom properties) that are specified for a control will be stored in a 'property list' for that control using atoms to identify the property, and with the specified 'value' (as text).
For more information, see WBDialogPropList() WB_DIALOG_PROPLIST WB_DIALOG_PROP
In some cases, properties may be mutually exclusive, and by definition the last specified property will be the one that takes precedence. The same is true for duplicate entries.

The following pre-defined dialog control types are recognized:

Static controls. These can act as 'hot key' anchors for selecting the next control in the tab order when there is 'underline' text AND the user presses a hot-key consisting of CTRL + 'the underlined character'. By definition the input focus can NOT be assigned to a static control.

  • Frame: A static 'frame' or bounding box, optionally with a caption
  • Text: A static text control that can display 'underline' text
  • Icon: An icon image (includes a transparency pixmap)
  • Image: A regular pixmap image without transparency

Edit controls. Allows editing of text. Can have focus. Can be scrollable. No caption.

  • Edit: A single or multi-line text edit control.

Button controls. Mouse and keystroke activated (using hotkeys corresponding to underlined characters). Can have focus. Buttons are activated by 'space bar' when they have the input focus (pushbuttons are also activated by <ENTER> when the button has input focus). Default buttons are automatically 'activated' when the user presses <ENTER>, unless the control 'owns' the '<ENTER>' key press event (such as with an 'edit' control, or a pushbutton with the input focus). Nearly all button controls can be activated via a hot key using CTRL + 'the underlined text' in the caption.

  • PushButton: Rectangular push button with text.
  • DefPushButton: 'Default' rectangular pushbutton. Allows <ENTER> to activate it (under most circumstances)
  • CancelButton: 'Cancel' rectangular pushbutton. Allows <ESC> to activate it (under nearly all circumstances)
  • RadioButton: Round 'one of many' selection button.
  • FirstRadioButton: Defines start of new 'group' of radio buttons.
  • CheckButton: 'Check Box' button (2-state)
  • TriStateButton: 'Tri State' check button (3 state), typically on/off/gray

Scrolling controls. User-selectable value between two limits, using rotating or sliding effect.

  • HScroll: Horizontal scroll bar
  • VScroll: Vertical scroll bar
  • Slider: Horizontal or Vertical 'slider' (based on dimensions)
  • Knob: Rotating control (270 degrees or 360 degree continuous)

List controls. List, drop-down list, edit with dropdown list, and tree controls.

  • List: Classic listbox, optionally sortable, optionally multi-select
  • Combo: Classic drop-down list or edit with dropdown list
  • Tree: Tree control, as listbox with 'openable' hierarchy
  • ComboTree: Like drop-down list but with hierarchical tree

File/Path selection

  • FileList: Specialized List using filenames. Directories specified first, displayed in bold text
  • FileCombo: Specialized drop-down or editable combo box, similar to above
  • PathTree: Specialized Tree using path names, open directory to list/refresh contents

Sub-dialogs and Tab (container) control

  • Tab: Container for sub-dialogs, one per tab.

See Also: 'Standard Control Name' Atoms

RESERVED: adding the ability to register custom control types


Certain pre-defined properties have special meaning. The following is a brief description of what the semantics are.

ID: The identifier of a control or sub-dialog. A value is required. The value may be one of the pre-defined atoms, a custom (registered) atom with an associated integer ID value, or a hard-coded integer value. Control messages to and from this control (or sub-dialog) will always use the ID value as an integer, regardless, and so the pre-defined and registered atoms must have a unique integer associated with them.

X,Y,WIDTH,HEIGHT: These properties specify the size and position of a control (or dialog box) using 'dialog units', which are roughly equivalent to the default font size. The semantics are actually similar to those used by other operating systems in an attempt to make dialog boxes appear roughly the same (with respect to font size) at different screen resolutions.

FONT: The desired font face name and/or size. When specified for a dialog box, it alters the base dialog units accordingly, and applies for all controls that do not specify a font. Otherwise, it only applies to a single control.

TITLE: The 'title' string associated with a dialog box or control. The title for a control is normally stored as the 'CAPTION' property value. The value is required and must be a string, though quotes are only required when embedded white space is present.

VISIBLE: This property has no value, and its presence carries with it an implied value of TRUE for 'visibility'.

VALIGN_TEXT_*, HALIGN_TEXT_*: These properties define the text alignment for certain controls.

RESERVED: symbol name registration for dialog controls
The current list of pre-defined symbols is as follows:

  • IDOK
  • IDNO

The current list of recognized keywords is as follows:

  • BEGIN_DIALOG - identifies the start of a dialog definition
  • END_DIALOG - identifies the end of a dialog definition
  • FONT - identifies the font for the specified object (dialog or control)
  • CONTROL - specifies a control entry within a dialog definition
  • ID - specifies the ID of a control entry
  • X - specifies the X position of the upper left corner in dialog units
  • Y - specifies the Y position of the upper left corner in dialog units
  • WIDTH - specifies the width of the object (dialog or control) in dialog units
  • HEIGHT - specifies the height of the object (dialog or conrol) in dialog units
  • VISIBLE - indicates that the object is initially visible
  • TITLE - specifies the title (or caption) of the object
  • HALIGN_TEXT_LEFT - align text left in title/caption (default)
  • HALIGN_TEXT_RIGHT - align text right in title/caption
  • HALIGN_TEXT_CENTER - align text horizontally centered in title/caption
  • VALIGN_TEXT_TOP - top align text in title/caption
  • VALIGN_TEXT_BOTTOM - bottom align text in title/caption
  • VALIGN_TEXT_CENTER - vertically center text in title/caption (default)

Other text keywords and identifiers are reserved.
Internally defined controls - see also dialog_controls.h

#define FRAME_CONTROL_STR "Frame"
#define TEXT_CONTROL_STR "Text"
#define ICON_CONTROL_STR "Icon"
#define IMAGE_CONTROL_STR "Image"
#define EDIT_CONTROL_STR "Edit"
#define SLIDER_CONTROL_STR "Slider"
#define KNOB_CONTROL_STR "Knob"
#define LIST_CONTROL_STR "List"
#define COMBO_CONTROL_STR "Combo"
#define TREE_CONTROL_STR "Tree"
#define FILE_LIST_CONTROL_STR "FileList"
#define FILE_COMBO_CONTROL_STR "FileCombo"
#define PATH_TREE_CONTROL_STR "PathTree"
#define TAB_CONTROL_STR "Tab"