Managing Controls

These sections deal with general manipulation of specific controls, which have names given by control-id parameters.

You can create control groups, containing several controls. These control groups are created with specific names - control group ids.

Verify a Control

To verify that a named control has been created (i.e. verify the control-id is in use), use the following AiF escape sequence:

ESC_9 w control-id ESC\

Where:

control-id

Control id or group id.

This returns:

<STX> status <CR>

Where:

status

0 = Control-id/group-id not in use. 1 = Control-id/group-id is in use.

Enabling/Disabling a Control

To enable or disable a named control (or control group), use the following AiF escape sequence:

ESC_11 {; enable} w control-id ESC\

Where:

enable	1 = disable control. 2* = enable control.
control-id	Control id or group id.

Enabled controls will accept user input, disabled controls will not.

If you disable a control that currently has focus, or would have if the application were the active top level Window, then focus is shifted to the root.

Showing/Hiding a Control

To show or hide a named control (group) on the screen, use the following AiF escape sequence:

ESC_12 {; show} w control-id ESC\

Where:

show	1 = hide control. 2* = show control.
control-id	Control id or group id.

If you hide a control that currently has focus, or would have if the application were the active top level Window, then focus is shifted to the root.

Destroying a Control

To destroy a named control, string list or control group, use the following AiF escape sequence:

ESC_10 {; delete} w control-id ESC\

Where:

delete	Use only if the id is that of a control group: 1 = do not delete controls inside group 2* = delete all controls in group.
control-id	Control id, string list id or control group id.

Destroying a control will flush it from HostAccess's memory. The control is immediately removed from the screen.

If the specified control currently has focus, or would have focus if the application were the active top level Window, then focus is shifted to the root.

Deleting a control group will by default delete all the controls in that group. To retain the controls, set the delete parameter to 1.

Re-sizing/Moving a Control’s Window

To re-size and/or move a control's window, use the following AiF escape sequence:

ESC_13 ; y ; x ; h ; wid w control-id ESC\

Where:

y	New y co-ordinate of top of control.
x	New x co-ordinate of left of control.
h	New height of control, in characters.
wid	New width of control, in characters.
control-id	Control id.

If y and x are set to (0,0), then the window is not moved.

Changing Control Colours

To change the foreground, background and grayed colours for a control, use the following AiF escape sequence:

ESC_14 {; fore} {; back} {; grayed} w control-id ESC\

Where:

fore	Foreground colour, in range 1..16.  (*=16).
back	Background colour, in range 1..16.  (*=1).
grayed	Grayed colour, in range 1-16.     (*=1). Used by some controls when disabled.
control-id	Control id.

How the colours are used depends on the control type and contents. Text labels for buttons are always shown in the foreground colour (unless the control is disabled).

Reporting Events

When an event is reported to the host, information about that event is sent in the following format:

<STX> WC<CR> id , event{, Argument} <CR>

Where:

WC	Literal characters.
id	Control id of control associated with the event or ? if no event available.
event	Event number - see Event Numbers Defined below.
Argument	Optional argument associated with event.

Event Numbers Defined

Currently defined event numbers are:

1	ENTER pressed.
2	Esc pressed.
3	Button clicked.
4	Check box or radio button check state change. Argument: 1 = button is now unchecked, 2 = button now checked.
5	Contents of edit box, or the contents of the edit box part of simple and dropdown combo boxes, have been changed by user. Argument: edit box contents, escape sequence number 1, see Reading From an Edit Box for the format.
6	List box selection change. Argument: host string of newly selected item, or “?” if nothing selected.
7	List box double click. Argument: host string of double clicked item.
8	FOCUS: sent whenever the user changes focus from one control to another. Returns 4 parameters: old control (string label), event (1=ENTER, 3=CLICKED, 9=TABBED), New control (string label) and Amend flag (set to 2 if old control had changed since it gained focus, otherwise 1).
9	TAB: control has been tabbed from.
10	CLICKEDON: left mouse down event over control when a different control, or the root, had the focus, resulting in focus moving to the clicked on control. Argument: id of control that has just lost the focus.
11	Secondary Window activate: the user is changing focus from a secondary window.
12	Secondary Window close: the user is trying to close a secondary window.
13	LISTBOX: tells host when a user scrolls off the end of a partially displayed string list.

Enabling Event Reporting

You can set or clear specific event reporting for named controls or control groups. For example, you could disable reporting for return keys pressed by the user.

To set/clear event reporting for controls/groups, use the following AiF escape sequence:

ESC_15 {; enable} ; event1 {checksum} w control-id ... ESC\

Where:

enable	1 = disable events (discards outstanding stacked events). 2* = enable events. 3 = stack events.
event1 ...	Event number - see Event Numbers Defined.
checksum	1* No checksumming 2 Use length checksum.
control-id	Is the control id or control group id.

Examples

To disable button click reporting for button with id 'but1', use the following AiF escape sequence:

ESC_15 ; 1 ; 4 w but1 ESC\

To enable enter key and button click reporting for button with id 'helpbut', use

ESC_15 ; 2 ; 1 ; 3 w helpbut ESC\

Requesting events for use with stacked events.

When you enable an event, you can specify that the events are stacked. This means the events are not reported until your program is ready to receive the event. Then you can send an escape sequence to get the next event from the stack.

To request an event from the stacked event handling system, use the following AiF escape sequence:

ESC_6 ; mode w {control_id} ESC\

Where:

mode	1= Get next stacked event. Wait if no event is available. 2= Get next stacked event. Return if no event is available. 3= Get last reported stacked event. 4= Flush event stack.
control_id	If mode is 1 or 2, control_id is optional and takes events only from that named control. Control_id is not relevant for modes 3 and 4.

Getting events

ESC_6 ; {wait_code} w { control-id } ESC \

Where:

wait_code	1 = get next event. Don't respond until an event is generated.
	2 = get next event, or return immediately.
	3 = get last event.
	4 = flush all events.
control-id1 ...	Is the control id or control group id.

If control_id is specified, then the command applies only to that control. If it is not specified, then it applies to all controls.

This returns:

<STX> WC <CR> control event {argument} <CR>

Where:

control	Control id or '?' if no event available.
event	Event number.
argument	Optional argument for event.

Setting Input Focus to a Named Control

To set the input focus to a named control, use the following AiF escape sequence:

ESC_16 w control-id ESC\

Where:

control-id

Is the control id.

If the id given does not match a known control, or it is the string “root”, focus is returned to the background terminal characters.

Setting Input Focus to an Unknown Control

To set input focus to the next/previous control in the tabbing order, use the following AiF escape sequence:

ESC_17 ; direction w ESC\

Where:

direction

1 = set the input focus to the previous control. 2* = set the input focus to the next enabled and visible control.

If there are no such controls, focus will be left with the root.

Using Control Groups

You can create control groups, holding several different controls, for ease of use. Once you have created groups of controls, you can use any of the generic control management facilities documented in this section on entire control groups (for example, showing/hiding controls).

To add or remove controls to/from a control group, use the following AiF escape sequence:

ESC_18 ; add w group-id ; control-id1 ... ESC\

Where:

add	1 = remove one or more controls from a control group 2* = add one or more controls to a control group.
group-id	Control group id.
control-id1 ....	Individual control id(s). You have to define (create) each control id separately before using it with a control group.

Creating a Control Group

To create a new control group, add one or more controls to a group with the required id and the group will be automatically created.

Example

To create a control group named buttons, holding the controls radio1, radio2 and check1, use the following AiF escape sequence:

ESC_18 ; 2 w buttons ; radio1 ; radio2 ; check1 ESC\

To delete the control radio2 from that control group, use the following AiF escape sequence:

ESC_18 ; 1 w buttons ; radio2 ESC\

Returning an Alternate Message

To tell a control to return a different string to the host when the given event occurs for which reporting is enabled, use the following AiF escape sequence:

ESC_19 ; event ; class w control-id ; message ESC\

Where:

event	Event number, see Event Numbers Defined for details.
class	1* = Send message back as a string (default behaviour). 2 = Treat message as the name of a macro file to execute. 3 = Send message back as a string and pass focus back to Terminal Window

 

control-id	Control id.
message	Alternate message.

When an alternate message is set, it will be sent to the host unmodified. It will not have a CR sent after it.

For example, to cause a single character, 'X', to be sent to the host when the 'ed' control has been tabbed to (tab = event number 9), use:

ESC_19 ; 9 w ed ; X ESC\

Setting the Accelerator Character

To set the accelerator character for a named control, use the following AiF escape sequence:

ESC_20 w control-id ; accel ESC\

where accel is the accelerator character.

This allows the control to receive the focus when the user presses Alt plus the given key, but only when the control is capable of accepting the focus, and keystrokes are being processed by controls (if the root has the focus, they may not be). This does not change the visual appearance of the control at all. It is usual to indicate to the user what the accelerator key is by underlining it in the label nearest the control.

In the case of button controls (push, check and radio), there is no need to issue this escape, since the accelerator key will be set automatically by searching the label for the first and prefixed character.

Example

To allow Alt/E to be the accelerator key for control with id 'edit', use:

ESC_20 w edit ; E ESC\

Setting the Return Key Meaning

Normally, pressing a Return key reports a RETURN event to the host. To set the event returned (for a named control), use the following AiF escape sequence:

ESC_21 ; meaning w control-id ESC\

Where:

meaning	1 = set RETURN event returned to be a TAB. 2 = set RETURN event returned to be a RETURN (i.e. default return behaviour).
control-id	Control id.