Class Documentation
Dialog |
1.0 |
ID_DIALOG |
Beta |
GUI |
December 2003 |
Rocklyte Systems |
Rocklyte Systems, 2003. All rights reserved. |
The Dialog class is used to pose a question and retrieve an answer from the user. |
Description
The Dialog class provides the means for the creation of simple dialog
windows, typically for the purpose of posing a question to the user and then
waiting for a response before continuing. You will need to specify the text
to be printed inside the dialog box and the buttons for the user to click on.
Optionally you may also specify an image to accompany the text for the purposes
of enhancing the message.
The following example illustrates how you can use the dialog control in
a DML script, for the purposes of requesting a Yes/No response from the user.
<dialog image="icons:items/question(48)"
buttons="yes;no" title="Confirmation Required"
flags="wait" responseobject="[variable]" responsefield="result"/>
A simple input box can be created inside the dialog window if you need the
user to type in a one-line string as part of the dialog response. To do this,
set the INPUT flag and write a string to the TextInput field if you wish to
set a pre-defined response. On successful completion, the TextInput field will
be updated to reflect the user's string entry.
If a dialog box needs to be used multiple times, create it as static
and then use the Show action to display the dialog window as required. This
is a good way of 'caching' the window so that it does not need to be recreated
from scratch each time that the dialog window needs to be displayed.
Any child objects that are initialised to a dialog will be activated in the
event that a successful response is given by the user. Failure to respond,
or a response of 'cancel', 'quit' or 'none' will prevent the activation
of the child objects.
Actions
The Dialog class supports the following actions:
GetUnlistedField | This action is supported for retrieving unlisted field values. |
SetUnlistedField | This action is supported for storing user specific variables in dialog objects. |
Show | Puts the dialog window on display. |
Structure
The Dialog object consists of the following public fields:
Buttons | Buttons for the dialog box are defined through this field. |
Flags | Optional flags may be set here. |
Icon | The icon that appears in the window title bar may be set here. |
Image | An icon file may be specified here in order to visually enhance the dialog message. |
Response | Holds the response value when a button is pressed. |
ResponseField | References a field in relation to the ResponseObject. |
ResponseObject | Refers to an object that will receive the results of button presses. |
Static | Set to TRUE to make the object static. |
String | The string that is to be printed inside the dialog box is declared here. |
Target | The target for the dialog box window is specified here. |
TextInput | Text to be placed inside the dialog input box may be set here. |
Title | Defines the window title for the dialog box. |
Window | Refers to the ID of the window created by the dialog object. |
Show |
Puts the dialog window on display. |
Call the Show action to display the dialog window. If you have set the WAIT
option in the Flags field, the process will be put to sleep in a message
processing loop while it waits for the user to respond to the dialog box.
After the Show action returns, you will be able to use the Response field to
read the user's response to the dialog box.
The WAIT option is recommended for script usage only. When programming,
a more reliable and controlled way to wait on the dialog box is to use a
loop such as the following:
while (!dialog->Response) {
WaitTime(0, 10000);
ProcessMessages(NULL, NULL);
}
The dialog object will automatically terminate itself after the Show
action is used and the user responds. This behaviour may be averted if you
set the Static field to TRUE.
|
|
Field: | Buttons |
Short: | Buttons for the dialog box are defined through this field. |
Type: | STRING |
Status: | Set |
Use the Buttons field to define a series of buttons that will appear in the
dialog box. Setting this field is compulsory in order for a dialog object to
initialise. This field is set using the following field format:
"response:text; response:text; ..."
Each button definition is separated by a semi-colon and the order that you
use reflects the button creation, scanning from left to right in the dialog
window. You must define a response type for each button, which may be one of
Cancel, Yes, YesAll, No, NoAll, Quit and Okay. A special response type of None
is also allowed if you want to create a dummy button that only closes the dialog
window. The response definition may be followed with a colon and then a text
description to be displayed inside the button area. If you do not wish to
declare a text description, you can follow-up with a semi-colon and then the
next button's description.
When a button is pressed, the matching response value will be written
to the Response field and then the dialog window will be closed.
|
|
Field: | Flags |
Short: | Optional flags may be set here. |
Type: | LONG |
Status: | Read/Init |
Optional flags that may be set against a dialog object are as follows:
WAIT | Normally when a dialog window is displayed, process control will return immediately to the program. This can be problematic if you require a response to the dialog box before continuing with your processing. To solve this issue, use the WAIT flag to curb the program flow until the dialog box receives a response from the user. |
INPUT | An input box can be created inside the dialog window by setting this flag. In this mode, the dialog box will return a user input string in the TextInput field after the user has responded to the dialog window. |
INPUTREQUIRED | This flag can be used in conjunction with the INPUT option. It forces the user to input at least one character in the input box, otherwise the dialog window will automatically cancel itself. |
|
|
Field: | Icon |
Short: | The icon that appears in the window title bar may be set here. |
Type: | STRING |
Status: | Get/Set |
A question-mark icon is set in the dialog window by default,
however you may change to a different icon image if you wish. If you are
going to refer to a stock icon, use the file format, "icons:category/name".
|
|
Field: | Image |
Short: | An icon file may be specified here in order to visually enhance the dialog message. |
Type: | STRING |
Status: | Get/Set |
Images may be used inside a dialog window to enhance the message that is
presented to the user. A number of icons are available in Athene's icon library
that are suitable for display in dialog boxes (the icons:items/ directory
contains most of these). The image should be no larger than 48x48 pixels and
no less than 32x32 pixels in size.
|
|
Field: | Response |
Short: | Holds the response value when a button is pressed. |
Type: | LONG |
Status: | Read |
This field holds the response value when a button is pressed in the
dialog box window. Valid response values are:
RSF_CANCEL |
RSF_QUIT |
RSF_NO |
RSF_NOALL |
RSF_YES |
RSF_YESALL |
RSF_OKAY |
If no response was returned (for example, the user killed the dialog window
rather than clicking a button) then the Response value will be NULL.
|
|
Field: | ResponseField |
Short: | References a field in relation to the ResponseObject. |
Type: | STRING |
Status: | Set |
This field is used when the ResponseObject field has been set. By setting
a field name here, the dialog object will automatically write the result
of any button-press to the referenced field name. The field must accept
strings.
|
|
Field: | ResponseObject |
Short: | Refers to an object that will receive the results of button presses. |
Type: | OBJECTID |
Status: | Read/Write |
When the user clicks on the button of a dialog box, you may need to record
the result in another location, especially in the event that the dialog object
is non-static and closes after usage. To write the response to another
object, refer to the unique ID of that object in this field. You will also need
to set the ResponseField to the name of the field that you would like to
update.
|
|
Field: | Static |
Short: | Set to TRUE to make the object static. |
Type: | OBJECTID |
Status: | Read/Write |
By default, a Dialog object will execute itself and then self-destruct
when a closing tag is received. If you would rather that the object stays in
the system, set this field to TRUE. If you do this, the only way to get a
Dialog object to perform is to call the Show action.
|
|
Field: | String |
Short: | The string that is to be printed inside the dialog box is declared here. |
Type: | STRING |
Status: | Get/Set |
The string that you would like to be displayed in the dialog box is specified
in this field. The string must be in UTF-8 format and may contain line feeds if
you need to separate the text. Each line of text will be automatically
word-wrapped to fit the dialog window if any of them are too wide.
|
|
Field: | Target |
Short: | The target for the dialog box window is specified here. |
Type: | OBJECTID |
Status: | Init |
The window for a dialog box will normally be created on the desktop. On
occasion it may be useful to have the window appear in a different area, such as
inside another window or screen. To do this, point the Target field to the
unique ID of the drawable that you want to open the window on.
The target may not be changed after initialisation.
|
|
Field: | TextInput |
Short: | Text to be placed inside the dialog input box may be set here. |
Type: | STRING |
Status: | Get/Set |
If you are creating a dialog box with a user input area, you may optionally
specify an input string to be displayed inside the input box. The user
will be able to edit the string as he sees fit. Once the user has responded
to the dialog window, you can read this field to discover what the user has
entered.
Note: When the user responds to an input entry field by pressing the
enter key, the dialog object will produce a response of "Okay". To aid
the predictability of the possible dialog responses, you should create
an okay button to accompany the input box.
|
|
Field: | Title |
Short: | Defines the window title for the dialog box. |
Type: | STRING |
Status: | Get/Set |
The window title for the dialog box is specified here as a standard UTF-8
text string.
|
|
Field: | Window |
Short: | Refers to the ID of the window created by the dialog object. |
Type: | OBJECTID |
Status: | Read |
This readable field references the ID of the dialog box's window. It is
only usable on successful initialisation of a dialog box. It is recommended
that you avoid tampering with the generated window, but direct access may be
useful for actions such as altering the window position.
|
|