Class Documentation

Name:Dialog
Version:1.0
ID:ID_DIALOG
Status:Beta
Category:GUI
Date:December 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003. All rights reserved.
Short:  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 InputText field if you wish to set a pre-defined response. On successful completion, the InputText 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.
InputText  Text to be placed inside the dialog input box may be set here.
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.
Title  Defines the window title for the dialog box.
Window  Refers to the ID of the window created by the dialog object.
Action:Show
Short: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:

FlagDescription
WAITNormally 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.
INPUTAn 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 InputText 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:InputText
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: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:

Value
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: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.