Starting a dialog¶

dialog

Start a dialog

SYNTAX

dialog [window_id] [focus = window_id | control_id] [cancel = label] [traps = label]

Cancel button
Default button
Active menus
Multi-row and free format textboxes
Disabled controls
Cutting and pasting data
Using the keyboard in a dialog

The program enters an event wait condition, and all windows and window controls that are enabled are available for activation and input using the mouse or keyboard. If a mouse is being used the user selects a control by clicking on it; otherwise keys may be used to move between and to activate controls. These are listed in full under Using the keyboard in a dialog.

The dialog command does not terminate until the dialog is closed or cancelled. The programmer must ensure that there is an event function, attached to one or more controls in the dialog window, which returns the value CLOSE_DIALOG or CANCEL DIALOG as appropriate.

If a control has a help caption assigned, and caption display is turned on, the caption is displayed while the control has input focus.

[window_id]	Specifies a window which is to be opened and brought to the foreground. The dialog operates within this window and its child windows only (though see note on WS_OWNED below). All other windows are automatically disabled until the dialog ends. This is known as a modal dialog. It is important to ensure that the window remains open until the dialog has terminated. If this clause is omitted all enabled windows are included in the dialog. It is recommended that this clause be used with top-level windows only. If it is used with a child window, it is not possible to disable the window’s parent. In programs compiled with scc 5.6.2 RC2 or later, a modal dialog on a window excludes all child windows with the style WS_OWNED from that dialog. The command !compat owned is available to force the old behaviour.
[focus = window_id \| control_id]	Specifies the window or control that has input focus when the dialog starts. If a control is specified, that control’s window also has focus by implication. If this clause is omitted, then the first control has input focus.
[cancel = label]	Specifies a line label to which program control is transferred if the dialog is cancelled. This occurs if the user presses the ESC key, or if an event function returns the value CANCEL_DIALOG. If the cancel = trap is absent, program control passes to the statement following the dialog if the dialog is cancelled. See Cancel button.
[traps = label]	General purpose trap clause that traps any condition not explicitly trapped, passing control to the line indicated by label. It has the lowest priority, and is only invoked if a trappable condition has not been more explicitly trapped.

RELATED TOPICS

Event function return values

input

setfocus

Traps

Cancel button¶

A push button or OLE control may be assigned the style flag WS_CANCEL_BUTTON. Pressing the ESC key has the same effect as pressing the cancel button, whether or not it has focus. The button is deemed to have been clicked and the event EV_BUTTON_CLICKED is generated. See Button style flags, Button events and functions, OLE control style flags.

Only one control should be defined as the cancel button.

If the button has an event function defined, the function is called with the event code EV_BUTTON_CLICKED. If the function returns the value CANCEL_DIALOG, the dialog is cancelled. Control is transferred to the line specified by the dialog’s cancel = clause, or if no such clause exists, to the statement following the dialog. If the function returns CLOSE_DIALOG, control passes to the statement after the dialog. If any other value is returned, the dialog is not cancelled. See Event function return values.

If the ESC key is pressed in a dialog but there is no cancel button, no action is taken unless the dialog has a cancel = clause, in which case control is transferred to the line specified.

EXAMPLE

This event function, assigned to the cancel button, offers the user a “Cancel dialog” prompt. If this is refused, the function returns the control_id of the control that previously had focus.

!function CancelEvent(EventCode, Object) {
     if (EventCode != EV_BUTTON_CLICKED) return
     prompt "Cancel dialog?" button = "YES" button = "NO", CDERR
     return CANCEL_DIALOG

CDERR:
     return sys.PreviousControl
}

In all cases, if a dialog is cancelled, control is transferred to the label specified in the cancel = clause. If this clause is absent, control passes to the statement following the dialog command.

The Sculptor variable sys.AutoCancel determines whether automatic validation and textbox validation functions are suppressed when a dialog is called by the cancel button or the ESC key.

If the cancel button is pressed while a textbox has focus, it is usually desirable to avoid validation of the data in the textbox. This can be achieved by the following code structure.

EXAMPLE

This EV_VALIDATE event function tests whether the current control is the cancel button, in which case validation is not performed.

!function ValEvent(EventCode, Object) {
     if (EventCode != EV_VALIDATE) return
     if (sys.CurrentControl ?= CancelButton) return OKAY
     return ValidateField(Object)
}

It is often advisable to perform all validation after all data entry has been completed - e.g. an “OKAY” button has been pressed.

Default button¶

A push button or OLE control may be assigned the style flag WS_DEFAULT_BUTTON. This button is given focus when no other push button has focus. If there is a button with WS_DEFAULT_BUTTON style, and the control with focus is not another push button or a free format textbox, (which uses RETURN to start a new line), pressing the RETURN key generates the event EV_BUTTON_CLICKED for the default button.

Only one control should be defined as the default button.

See Button style flags, Button events and functions, OLE control style flags .

Active menus¶

The menus that are to be active in each window should be selected by use of the command:

open menu_id [, menu_id…]

which should be executed before the dialog command. Only one menu can be opened in any one window. Opening a menu automatically closes any menu in the same window that is currently open. The focus = clause may be used to give a menu the initial input focus. See open.

Multi-row and free format textboxes¶

If the field linked to a multi-row textbox has more elements than the textbox has rows, then, whenever a row is cleared or displayed, Sculptor links the set of elements containing that row to the textbox. For example, if the textbox has 4 rows and the linked field has 12 elements, then the command

clear box_id[6]

indicates to Sculptor that elements 5-8 are currently linked to the textbox. This ensures that the correct element of the linked field is updated. The display of the other rows is not immediately updated, but it the user now moves to another row by means of the mouse or arrow keys, Sculptor updates the display value of that row . Therefore row 1 would display the value of element 5, row 3 element 7, and row 4 element 8.

It is strongly recommended that programs avoid this situation arising, by clearing and displaying an element set all at once.

Each line of text in a free format textbox is stored in the corresponding element of the linked array field.

Disabled controls¶

A disabled control cannot be accessed during a dialog. All controls are by default enabled when created, unless the style flag WS_DISABLED is included in their definition. The disable and enable commands are used to change the control’s state at run time.

Cutting and pasting data¶

The CTRL-C (Copy) , CTRL-V (Paste) and CTRL-X (Cut) keys have their usual function when a textbox or LIST_EDIT type listbox has focus during a dialog. Additionally, unless the EV_RIGHT_MOUSE_UP event has been trapped, a right click on these control types causes the Windows default menu to appear, with options to Undo, Cut, Copy, Paste, Delete and Select All.

RELATED TOPICS

The event_enable clause

Textbox events and functions

Listbox events and functions