List Boxes

The following sections describe how to create both ordinary and incremental list boxes, how to read from and manipulate a list box.

Creating list boxes

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

ESC_45 ; y ; x ; h ; wid {; vis} {; en} {; font} {; box} {; sort} {; bar} {; msg} {; auto} {; border} 
{; size} {; style} w id {; str-id} {; sel} {; top} 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	1* = list box, possibly incremental, see Incremental List Boxes for details. 8 = tabular list box. This is a list box supporting tab characters, allowing you to input data in columns, see Example: Incremental List Boxes.
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 horizontal scroll bar, even if items too wide for box. 2* = use horizontal scroll bar, if items too wide for box.
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 display or hidden text.
auto	1 = no auto horizontal scroll in edit box of combo box. 2* = auto horizontal scroll in edit box of combo box.
border	1 = no border, list will try to use whole of control rectangle. 2* = normal border, only show integral no. of items. 3 = 3D Sculpted list type.
size	Sets the number of elements the list box will hold. For use with incremental list boxes. This must be at least one more than the number of elements.
style	0 = * standard incremental. Registers an event if a user pages off the bottom of the list box. 1 = extended incremental style. Registers events if the following occurs:      1: paging off the bottom of the list box.     -1: Paging off the top of the list box.
id	Control id of list 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.
top	Display/hidden text of item to be initially shown at the top of the box – optional. By default, the initially selected item is placed top most if possible.

Incremental List Boxes

You can use this feature to create list boxes with room for many entries, and create a corresponding string list with only a few strings.

This feature is useful if data transmission is slow, allowing you to update the list box incrementally as the user scrolls downwards.

You can get HostAccess to send notification messages to the host, whenever the user scrolls off the bottom of the visible strings, and so reveal an undefined entry. To do this, enable event number 13.

This notification takes the format:

<STX>13,<element number>,<number of elements><CR>

If the host defines a string list which is larger than the total elements set then the total elements becomes the number of strings in the string list.

When the notification is received, the host should respond by adding the required string to the end of the string list associated with the list box.

See Enabling Event Reporting for a description of enabling event numbers.

See Manipulating String Lists  for a description of adding a string to a string list.

Example: Incremental List Boxes

The host creates a list box with 100 entries, containing the entries in a string list named Fill-up, which contains only 10 strings.

The list box will display the 10 given strings and the remaining 90 will be empty.

The user may scroll down to reveal element 11 which is not available. HostAccess then sends

<STX>13,11,1<CR>

to the host. The host will then respond by adding a string (say, “Line 11”) to the end of the string list (after “Line 10”) associated with the list box, using the following AiF sequence:

ESC_40 w fill-up ; Line 10 ; Line 11 ESC\

The text “Line 11” will then be displayed in the list box.

Example 2: Incremental List Box

The following example creates a string list named str-list, containing the data described, then creates a simple list box, and a tabular list box, then sets the tab stops. The “è” symbol is used here to denote a tab character.

ESC_40 ; 1w str-list ;; 012345678901234567890123456789012345 ; NameèèDept.èExt. ; EddyèStabiloèèGraphicsè20 ; DavidèBaileyèDevelopmentè29 ; CynthiaèKadogoèLegalè42 ; JohnèMerrellsèDevelopmentè40 ; StoremanèNormanèStoresè45 ESC\

ESC_45 ; 1 ; 1 ; 4 ; 20 ;;; 3 ; 1 w listbox1 ; str-list ESC\

ESC_45 ; 10 ; 1 ; 7 ; 40 ;;;; 8 ; 1w listbox2 ; str-list ESC\

ESC_47 ; 11 ; 10 ; 20 ; 32 ; 40 ; 50 w listbox2 ESC\

ESC_14 ; 16 ; 4 w listbox2 ESC\

Note that the first box has a different font (8 point Helvetica) and background colour.

Reading from a List Box

You can read from a list box, using the AiF escape sequence described in the following sections to return a value to the host. This return value is formatted as:

<STX> value <CR>

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

Reading the Current Item

To return the display or hidden text of the currently selected item, use the following AiF escape sequence:

ESC_46 ; 1 w control-id ESC\

The text returned depends on the value passed in the msg parameter when the list box was created. See Setting the Current Item in a Combo Box for details.

If no hidden text was specified for the selected entry, the position of the item in the string list is returned.

If no item is selected, '?' is returned.

Reading the Top Item

To return the display or hidden text of the top visible item, use the following AiF escape sequence:

ESC_46 ; 2 w control-id ESC\

Reading Total Size

To return the total number of elements defined, use the following AiF escape sequence:

ESC_46 ; 7 w control-id ESC\