String Lists

String lists are used in conjunction with list boxes, simple combo boxes and drop-down 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, e.g. 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.

The upper  'realistic' limit is probably 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 the examples for details.

Creating a String List

To load a string list so it can be used by list type controls, call the following  subroutine from your application:

CALL PIX.GUI.LOAD.STRING(GUI.APP.NAME, CONTROL.DETAILS, STRING)

Where:

CONTROL.DETAILS	Control ID, STRING, TEXT1,...TEXTn

Where:

Control ID	The unique name for the control.
STRING	The text literal STRING.
TEXT1,...TEXTn	The list of text items to be placed into the String list.

String List Example 1

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

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

To create a String list containing the following list “England, America, Canada, Germany, France” use the following.

CONTROL.DETAILS = “COUNTRIES, STRING, England, America, Canada, Germany, France”
CALL PIX.GUI.LOAD.STRING(“”,CONTROL.DETAILS,””)

String List Example 2

To amend the above list so that the continents were adjacent to the countries for use in a tabular list box, use the following. (where “>” denotes a tab mark in the data)

CONTROL.DETAILS = “COUNTRIES, STRING, England>Euroupe, America>N.America, Canada>N.America, Germany>Euroupe, France>Europe”

String List Example 3

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 dash or minus sign (so you cannot have dashes in the text). 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 a  '@' 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.

String List Example 4

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 dropdownlist 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

Use the following:

CONTROL.DETAILS = “PEOPLE, STRING, @people.lst, A.Hedgecock-160, 
P.Hall-143”

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:host\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

String List Program Example

CALL PIX.GUI.LOAD.STRING ("","GROUP.LIST,STRING,Working,Gundogs,Hounds,Utility,Toys,Terriers","")
CALL PIX.GUI.LOAD.STRING ("" ,"BREEDS.LIST,STRING,Alaskan Malamutes,Bearded Collies,Belgian Shepherd Dogs,Boxers,Collies (Rough),Collies(Smooth),Dobermann, G.S.D,Rottweiler,Swedish Valhunds","")
CALL PIX.GUI.LOAD.STRING("" ,"CLASS.LIST,STRING,1>Minor Puppy,2>Puppy,3>Novice, 4>Junior, 5>Graduate,6>Post Graduate,7>Limit,8>Open,9>Veteran","")