Combo Boxes

The following sections describe how to create, read and manipulate combo boxes: A combo box can combine an edit box with a drop-down string list (see Combo Box example).

Creating a Combo Box

To create a combo box, use the following AiF escape sequence:

ESC_45 ; y ; x ; h ; wid {; vis} {; en} {; font} {; box} {; sort} {; bar} {; msg} {; auto} {; border} w c-id {; str-id} {; sel} 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`	Text font: 1* = Terminal. 2 = System. 3 = 10pt Helvetica. 4 = 8pt Helvetica.
`box`	2 = simple combo box. 3 =dropdown combo box. 4 =dropdown list combo box. 5 = simple combo box borderless. 6 =dropdown combo box, borderless. 7 = drop-down list combo box, borderless.
`sort`	1 = unsorted. The list items appear in the same order as in the string list. 2* = sorted. The list items will appear in alphabetical order.
`bar`	1 = no scroll bar, even if items too wide for box, 2* = use scroll bar, if needed.
`msg`	1*= messages sent between host and HostAccess will use display text. 2 = messages sent between host and HostAccess will use hidden text. msg selects whether the host wishes to use the display text or hidden text of string list entries when communicating with HostAccess and affects messages sent in both directions. Str-id and sel will be interpreted as display or hidden text depending on this value. It also affects subsequent event reporting (selection change and double click events), and the way items are specified and transmitted in other escape sequences.
`auto`	1 = no automatic horizontal scroll in edit box of combo box. 2* = automatic horizontal scroll in edit box of combo box.
`border`	1 = no border. The control uses the full depth of the control's rectangle, probably displaying a partial item at the bottom. 2* = normal border, only show integral no. of items.
`c-id`	Control id of combo box.
`str-id`	String list id, optional. If not given, list will initially be empty.
`sel`	Display/hidden text of item to be initially selected - optional. If not given, the first displayed entry in the list/combo box will be initially selected.

Combo Box example

This example creates a string list with control id str-list. It then creates:

A 5x10 simple combo box (combo1) at (10,10).
A 7x12 dropdown combo box (combo2) at (10,25).
Aa 5x10 drop-down list combo box (combo3) at (10,40).

All the boxes use str-list for their contents. Note that combo1 has changed background colour. See Changing Control Colours for details of this feature.

ESC_40 w str-list ;; line 1 ; line 2 ; line 3 ; line 4 ; line 5 ESC\

ESC_45 ; 10 ; 10 ; 5 ; 10 ;;;; 2 w combo1 ; str-list ESC\

ESC_14 ; 1 ; 8 w combo1 ESC\

ESC_45 ; 10 ; 25 ; 7 ; 12 ;;;; 3 w combo2 ; str-list ESC\

ESC_45 ; 10 ; 40 ; 5 ; 10 ;;;; 4 w combo3 ; str-list ESC\

Reading Combo Boxes

You can read from a combo box, using the escape sequence described in the following sections to return a value to the host.

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

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

Reading the Current Item in a Combo Box

To return the contents of the currently selected item, use the following AiF escape sequence:

ESC_46 ; 1 w control-id ESC\

The contents consists of either the display or hidden text for the selected item, depending on the value of the msg parameter when the combo box was created. See Creating a Combo Box.

If hidden text is returned, but was not defined for the selected entry, the position of the item in the string list is returned. This may not be the position of the selected item as displayed. If the box was created with alphabetic sorting turned on, the order of presentation in the combo box is quite separate from the order in the string list. The value that is returned will always be the order in the string list.

If no item is selected, the value returned is a single question mark (STX ? CR).

Reading if a Combo box is Visible

To return whether or not the list portion of a combo box is 'dropped down' (i.e. visible), use the following AiF escape sequence:

ESC_46 ; 3 w control-id ESC\

The value returned is 1 if it is not visible, 2 if it is.

Reading Changes to Combo Boxes

To read if the contents of the box have been changed by the user, use the following AiF escape sequence:

ESC_46 ; 4 w control-id ESC\

The value returned is 1 if unchanged, 2 if changed.

This applies to simple or dropdown combo box styles only (not dropdown list).

Reading the Contents of a Box

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

ESC_46 ; 5 {; length} w control-id ESC\

Where:

`Length`	The maximum length that is to be returned. (*=80).

This applies to simple or dropdown combo box styles only (not dropdown list).

The contents of the box are returned.

Reading Selected Characters

To return edit box selection indication (telling the host which characters are selected), use the following AiF escape sequence:

ESC_46 ; 6 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 from 1).
`w`	The number of selected characters.

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

This applies to simple or dropdown combo box styles only (not dropdown list).

Setting the Current Item in a Combo Box

To set an item to be selected, use the following AiF escape sequence:

ESC_47 ; 1 w control-id ; item ESC\

Where:

`item`	Display/hidden text of the required items.

The items are specified as display/hidden text of the required items, depending on the value passed in the msg parameter when the combo box was created.

See Creating a Combo Box for details.

Changing the String List to be Displayed in a Box

To change the string list that is to be displayed in the box, use the following AiF escape sequence:

ESC_47 ; 2 w control-id ; string-id ESC\

Where string-id is the (optional) string list id. If omitted, the box becomes empty.

Limiting Text in Combo Boxes

To limit the amount of text that may be entered, for simple or dropdown combo box styles only, use the following AiF escape sequence:

ESC_47 ; 3 ; limit w control-id ESC\

Where limit is the limit.

Setting the Edit Box Selection Range

To set the edit box selection range, for simple or dropdown combo box styles only, use the following AiF escape sequence:

ESC_47 ; 4 ; start ; length w control-id ESC\

Where:

`Start`	The position (starting from 1) of the first character to be selected.
`Length`	The number of characters that are to be selected.

Hiding and Showing Combo Boxes

To drop-down (show) or close up (hide) the list box part of the combo box, for simple or dropdown combo box styles only, use the following AiF escape sequence:

ESC_47 ; 5 {; show} w control-id ESC\

Where:

`show`	1 = hide. 2* = show.

Using the Clipboard (combo box styles)

For simple or dropdown combo box styles only, you can use the clipboard facilities as follows:

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

ESC_47 ; 6 w control-id ESC\

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

ESC_47 ; 7 w control-id ESC\

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

ESC_47 ; 8 w control-id ESC\

This is ignored if the clipboard does not contain text.

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

ESC_47 ; 9 w control-id ESC\