String Lists

String lists are used in conjunction with list boxes and combo boxes. String lists contain the entries used to populate these boxes. String lists are created and managed quite separately to the list/combo boxes which use them. You can therefore use a single string list in multiple boxes, and create and destroy boxes without destroying the underlying data.

Creating String Lists

To create string lists, either download the strings from the host, or read them in from a PC file. The second form is better suited to longer lists. Although there is no inbuilt limit to the number of items in such a list, they are not intended for very large lists, because:

• A list box control cannot contain more than 64k of text, for example, if the average string length is 90 bytes, a list box will not hold more than approximately 700 items.

• String lists are held in memory at all times.

• The time required to create large lists will be unacceptable to users.

• The time required to populate list/combo boxes with large lists will be unacceptable to users.

A realistic limit is a few hundred items.

Format of String Lists

In its simplest form, a string list has an id (a name), and an ordered sequence of strings. The order defines the default order in which the strings are displayed in a list or combo box (although this can be changed when the boxes are actually created).

String lists may also store a second, hidden, string for each item. This string is not displayed to the user, but can be used by the host application as an alternative way for list items to be specified in messages exchanged between HostAccess and the host. See Example of a string list and Example 2 - String lists for examples.

Manipulating String Lists

To create, add entries to and remove entries from, string lists, use the following AiF escape sequence:

ESC_40 {; add} w string-id ; text ; entry1... ESC\

Where:

add	1* = add strings to string list. 2 = remove strings from string list.
string-id	String list id.
text	The display text of the string list entry before which the new strings are to be inserted. Ignored if removing entries.
entry1 ...	1st and subsequent entries to be added/removed.

The entries in the list contain a 'display' part, and optionally, a 'hidden' part. If present, the hidden part is separated from the display part by a comma (so you cannot have a comma in the display part). If the hidden part is not given, a default hidden value will be automatically created if it is ever needed- this will be a string representation of the position of the entry in the string list (starting from 1; '1', '2', '3' etc).

List entries to be added/removed are given directly or indirectly. When given directly, a string parameter specifies the list entry in the format:

<display-part>  <, hidden-part>

If a string parameter starts with an '@' character, it is treated as an indirect entry. The '@' is stripped off, and the remainder treated as a PC file name. The file contains a list of entries in the above format. It is possible to mix the direct and indirect forms in a single escape sequence.

When adding strings, the second string parameter contains the display text of the existing string list entry before which the new entries are to be inserted. If missing, the new entries are added to the end of the list.

When removing entries, the hidden parts of entries are ignored.

Example of a string list

Consider a host application that needs to get the user to select a personnel record from a database. Each record includes the person's name. Each record has a record number. The host application wants to use a drop-down list style combo box (one in which the user cannot type an entry, but has to select from the list) to get the name. The host application is not really interested in the text of the name, but the record number it relates to.

This is more suited to a string list with hidden strings. The 'display' strings are the names of the people, the hidden strings are the associated record numbers. The host creates such a string list, then associates it with a 'dropdown combo' style box. The host also specifies that it wants to use the hidden strings when exchanging information with HostAccess about the selected list items. HostAccess will then send back the record number of the selected item, which the host application can use directly.

Create a list of people, with hidden strings (record numbers in some database). The bulk of the list is created from a PC file called people.lst. To this are added 2 people given directly. The list will be called 'people' and will eventually contain the following entries, in the order given:

Display text	Hidden text	Source
D. Bailey	173	People.lst
M. Woolley	174	People.lst
G. Baker	190	People.lst
F. Carden	191	People.lst
A.Hedgecock	160	Direct from host
P.Hall	143	Direct from host

ESC_40 w people ;; @people.lst ; A.Hedgecock, 160 ; P.Hall, 143 ESC\

people.lst is a standard DOS file with <CR><LF> characters separating each line of text. The file name could also include the full directory path, for example c:\windows\data\people.lst. By default, the path is your HostAccess directory. In this example, people.lst looks like this:

D.Bailey, 173

M.Woolley, 174

G.Baker, 190

F.Carden, 191

Example 2 - String lists

The host application has a screen on which one of the pieces of information the user has to enter is a city name. The host application designer chooses to do this with a simple combo box, which has a list of common cities, but will also let the user type in a city that's not on the list. All the host application wants to get from the user is the text of the city name.

This is best suited to the simple form of string list, without use of hidden strings. The host downloads the list of cities in a string list, then creates a 'simple combo' style box. When extracting the selected city, or the name the user entered, HostAccess sends the relevant text to the host.

Example

Create a list containing the following cities: Birmingham, Bristol, Coventry, Leeds, London, Manchester, and York, called 'cities'.

ESC_40 w cities ;; Birmingham ; Bristol ; Coventry ; Leeds ; London ; Manchester ; York ESC\

Reading From a String List

In all cases, a value will be returned to the host. This 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 String List Size

To return the number of items in a string list, use the following AiF escape sequence:

ESC_41 ; 1 w control-id ESC\

Reading Selected Display Text

To return the display text for the selected list item, use the following AiF escape sequence:

ESC_41 ; 2 ; item w control-id ESC\

Where item is the number of the relevant item (starting from 1).

Reading Selected Hidden Text

To return the hidden text for the selected list item, use the following AiF escape sequence:

ESC_41 ; 3 ; item w control-id ESC\

Where item is the number of the relevant item (starting from 1).

Clearing a String List

To delete all entries in a string list, use the following AiF escape sequence:

ESC_42 ; 1 w control-id ESC\

Where control-id is the control id for the string list.

Setting Special Characters

To set hidden text separator and indirect entry characters, use the following AiF escape sequence:

ESC_42 ; 2 w control-id ; string ESC\

Where string is a 2-character string  holding these characters in order.

For example, to set the default special characters (, @) in the string list named string1, use the following AiF escape sequence:

ESC_42 ; 2 w string1 ; ,@ ESC\