Home > Language Reference > Classes

StringList Class

  + Object
    + StringList

Description

The StringList class encapsulates the functions required to access a string list from the application resources. This class is neither instantiable, nor derivable, nor cloneable. The only instances available to the programmer are those automatically created by the compiler when you insert string lists in your project.

A string list is a collection of strings that is stored in the executable resource instead of being compiled with your code. Gathering all the strings the application requires into a resource is typically used to for localisation purposes: it is easier to translate an application whose all messages are grouped into a single location rather than spread over hundreds of lines of code. Moreover, string lists automatically handle localisation through the Palm OS^® overlay mechanism. See Localisation for more information.

String lists can also prove useful to store predefined string arrays that need to be accessed by index at runtime, such as a list of error messages, or a list of items intended to populate a listbox or a popup trigger, or any other string data that won't change at runtime.

Creating a string list

To add a new string list in your project, simply select the 'Project > Add String List' menu item. A new entry will be created in the Project Explorer Window, under the String List folder. Then, double click this item in the tree view to open the list in the editor, as shown below:

The first (grayed) column displays the string index. Strings are always numbered sequentially, starting from zero. This cannot be modified, as this limitation is imposed by the Palm OS^® resource format. The second column displays the optional symbolic name of the string. From your code, you can reference a given string either using its index or either using its symbolic name. Finally, the third column displays the string content itself.

Editing a string list is similar to editing a table, and rather intuitive: to insert a new string in the list, press Insert; to delete a given string, select the whole relevant row by clicking on its index in the leftmost column and press Delete; to edit the content of a cell, select it and press enter. You can also move the selection using the arrow keys.

A string can be empty. The compiler also recognizes the following escape sequences in string values:

Before saving your project, you may want to change the default name of your new string list in the Property Window for a more significative one. This name will be used to access this list from your code, and must be unique throughout your whole project.

A project can contain as many string lists as necessary.

Accessing a string list at runtime

For each string list in your project, the compiler automatically generates a global variable of type StringList whose name corresponds to the name of the list. You'll use this object variable to access the list at runtime. Moreover, for each symbolic name, the compiler automatically generates a global constant of type Integer whose value correspond to the index of the string in the list.

For example, supposing the string list shown on the screenshot above is named slShakespeare, the compiler will implicitly generate the following code in a module:

Public slShakespeare As New StringList

Public Const kPlay1 As Integer = 0
Public Const kPlay2 As Integer = 1
Public Const kPlay3 As Integer = 2

Since these variables and constants are global, two string lists cannot share the same name, and two strings (even in different lists) cannot share the same symbolic name, otherwise a compile-time error occurs.

To access a given string, simply call the String or the Format function of the relevant StringList object, specifying the index of the string to retrieve. For example:

MsgBox slShakespeare.String(kPlay1) ' Display "A Midsummer Night's Dream" in a dialog box
MsgBox slShakespeare.String(2)      ' Display "Romeo and Juliet" in a dialog box

The following example shows how to populate a Popup control with the content of a string list:

Private Sub Button1_Click()
  Dim i As Integer

  Popup1.Redraw=False
  For i=0 To slShakespeare.Count-1
    Popup1.AddItem slShakespeare.String(i)
  Next i
  Popup1.Redraw=True
End Sub

When you have to fill a control with a predefined set of strings, using a string list and the routine above is far more efficient than adding each string one by one, requires less heap usage, and saves room in your application data segment.

Members

System requirements