Edit Boxes

The following sections describe how to create, read and manipulate an edit box.

Creating an Edit Box

To create an edit box, use the following AiF escape sequence:

ESC_50 ; y ; x ; h ; wid {; vis} {; en} {; font} {; display} {; auto} {; acc} {; focus} {; edit} {; border}
{; scroll} ins/ovr w control-id {; contents} ESC\

Where:

`y`	y co-ordinate of top of box.
`x`	x co-ordinate of left of box.
`h`	Height of box, in rows.
`wid`	Width of box, in columns.
`vis`	1 = create hidden, 2* = create visible.
`en`	1 = initially disabled, 2* = initially enabled.
`font`	Selects font: 1* = terminal, 2 = system, 3 = 10pt Helvetica, 4 = 8pt Helvetica.
`display`	1* = display contents normally. 2 = force contents to upper case. 3 = force contents to lower case. 4 = 'password' - contents displayed as asterisks. (The password character may be switched from asterisk to something else).
`auto`	1 = do not automatically (horizontally) scroll the box. 2* = automatically (horizontally) scroll the box.
`acc`	1* = read/write access. 2 = read only access – user cannot change contents.
`focus`	1* = initially, contents not selected when box receives focus. 2 = initially, contents selected when box receives focus.
`edit`	1 = single line edit (* if height is 1). 2 = multi-line edit (* if height >1). 3 = multi-line edit with auto vertical scrolling.
`border`	1 = no border. The edit box height is exactly the multiple of character cells given. 2* = border. The box extends 4 pixels above and below the normal box rectangle This means that you cannot have two consecutive edit boxes on two consecutive lines. 3= 3D border.
`ins/ovr`	1= disable. 2= ins/ovr enabled.
`scroll`	1* = no scroll bars. 2 = horizontal scroll bar. 3 = vertical scroll bar. 4 = horizontal & vertical scroll bars.
`control-id`	Control id.
`contents`	Initial contents of box - optional.

The height of the box that you pass relates to the height in character cells of the control, and not to the number of lines of text the control will hold.

Creating an edit box example

This example creates a 3x10 edit box at (12,10), id edit, with a test string and scroll bar.

ESC_50 ; 12 ; 10 ; 3 ; 10 ;;;;;;;;;; 2 w edit ; Test text ESC\

Reading From an Edit Box

To read a value from an edit box, use the AiF escape sequences as described in the following sections.

In all cases, a value will be sent to the host. This return value is formatted as:

If an error is detected in the arguments, the value returned is a single question mark (STX ? CR).

Reading a Line in an Edit Box

To read the contents of a given line in the box, use the following AiF escape sequence:

ESC_51 ; 1; max-len ; line w control-id ESC\

Where:

max-len

Is the maximum length of the text returned. (*=80).

Remember to set max-len when reading a multiline control, since their contents will often exceed 80 characters.

line

Is the number (starting from 1) of the line you want. (*=all lines).

For single line edits, line is ignored, and the whole contents of the single line are returned, followed by CR.

For multi line edits, If line is given (and is greater than zero), then the contents of the specified line, only, are returned in the same format as for a single line edit.

If line is not given (or is given as 0), all lines in the edit box will be returned. Each line will be separated from the next by CR. Preceding the lines is the line count.

For example, if a multi-line edit contains 2 lines 'hello' and 'there', the reply would look like this:

2,hello<cr>there<cr>

For example, to return the contents of line 3 of edit box 'ed', use:

ESC _ 51 ; 1 ;; 3 w ed ESC\

80 characters at most will be returned.

Examining Details of Lines

To read the number of lines in a box (always 1 for single line edit), use the following AiF escape sequence:

ESC_51 ; 2 ; w control-id ESC\

To read the current length of a given line, use the following AiF escape sequence:

ESC_51 ; 3 {; line} w control-id ESC\

Where:

line

The relevant line number (*=1).

To read the line number of the first visible line in the box (for multi-line edits only), use the following AiF escape sequence:

ESC_51 ; 4 ; w control-id ESC\

Detecting Changes in an Edit Box

To return a flag that says if the edit box contents have been changed by the user.

ESC_51 ; 5 {; reset} w control-id ESC\

Where:

reset

0* = do not reset changed flag.
1 = reset changed flag.

The value returned is '1' if no change, or '2' if changed.

Telling the Host Which Characters are Selected

To return a selection indication - telling the host which characters are selected (for single line edits), use the following AiF escape sequence:

ESC_51 ; 6 ; line w control-id ESC\

The value returned is two comma-separated integers n,w, where:

`n`	The number of the first character in the selection (starting from1).
`w`	The number of selected characters.

If nothing is selected, the return value is '1,0'.

Manipulating an Edit Box

To manipulate an edit box, use the following AiF escape sequence features.

Setting contents in an edit box.
Limiting text entered.
Scrolling.
Changing ‘Password’ Character.
Setting Selection Range.
Using the Clipboard.
Initialising a Multi-line Edit Box.

There is no reply to this escape sequence.

Setting Contents in an Edit Box

To set the contents of an edit box, use the following AiF escape sequence:

ESC_52 ; 1 w control-id ; contents ESC\

Where:

contents

The new contents of the edit box.

Limiting Text Entered

To limit the amount of text that may be entered into the box, use the following AiF escape sequence:

ESC_52 ; 2 ; limit w control-id ESC\

Where:

limit

The maximum number of characters. This is a total limit, not just the limit on a single line (multi-line edit box users take note).

Scrolling

To scroll an edit box so that that the given line number is the first visible line (for multi line edits only), use the following AiF escape sequence:

ESC_52 ; 3; line w control-id ESC\

Where

line

The relevant line number.

Changing “Password” Character

To change the “password” character, use the following AiF escape sequence:

ESC_52 ; 4; w control-id ; char ESC\

Where:

char

The password character.

Setting Selection Range

To set the selection range (for single line edit boxes only), use the following AiF escape sequence:

ESC_52 ; 5; start ; len w control-id ESC\

Where:

`start`	The location (starting from 1) of the first character to be selected.
`len`	The number of characters that are to be selected.

Using the Clipboard

You can use the clipboard facilities as described:

To cut the selection in the edit box to the clipboard, use the following AiF escape sequence:

ESC_52 ; 6 w control-id ESC\

To copy the selection in the edit box to the clipboard, use the following AiF escape sequence:

ESC_52 ; 7 w control-id ESC\

To paste the clipboard contents into the edit box at the current insertion point, use the following AiF escape sequence:

ESC_52 ; 8 w control-id ESC\

This is ignored if the clipboard does not contain text.

To clear the current selection in the edit box (i.e., deletes it without placing it in the clipboard.), use the following AiF escape sequence:

ESC_52 ; 9 w control-id ESC\

Initialising a Multi-line Edit Box

To initialise a multi-line edit box with the contents of the named string list, use the following AiF escape sequence:

ESC_52 ; 10 w control-id; string ESC\

Where:

string

The string list id.