- Generated on Sat Feb 1 2020 14:59:01 for X11workbench Toolkit by
1.8.15
|
X11workbench Toolkit
1.0
|
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:
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
translating into
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.
DIALOG CONTROL PRE-DEFINED TYPES
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.
Edit controls. Allows editing of text. Can have focus. Can be scrollable. No caption.
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.
Scrolling controls. User-selectable value between two limits, using rotating or sliding effect.
List controls. List, drop-down list, edit with dropdown list, and tree controls.
File/Path selection
Sub-dialogs and Tab (container) control
See Also: 'Standard Control Name' Atoms
RESERVED: adding the ability to register custom control types
PRE-DEFINED PROPERTIES
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.
DIALOG RESOURCE SUMMARY
RESERVED: symbol name registration for dialog controls
The current list of pre-defined symbols is as follows:
The current list of recognized keywords is as follows:
Other text keywords and identifiers are reserved.
Internally defined controls - see also dialog_controls.h
1.8.15