L_CREATE

Create a list

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall L_CREATE(list_id, window_id, [data], [channel], [class], [row], [column], 
&     [D_NOPLC], [disabled], [initial], [last][, error])

Arguments

list_id

Returned with the ID of the list created. (n)

window_id

The ID of the input window to associate with the list. (n)

data

(optional) The initial contents of the associated non‑window data to store or retrieve for each list item. See the Discussion below for more information. (a)

channel

(optional) The window library channel to load the list class from if it’s not already loaded. (n)

class

(optional) The name of the list class. (a)

row

(optional) The row position of the list. (n)

column

(optional) The column position of the list. (n)

D_NOPLC

(optional) The no‑placement flag; if passed, the list is not placed. (n)

disabled

(optional) The true/false flag that indicates whether the list is disabled. (n)

initial

(optional) The item number of the initial item to load. (n)

last

(optional) The estimated number of items that will be loaded. (n)

error

(optional) The returned Toolkit error number, or 0 if the list is successfully created. (n)

Discussion

L_CREATE creates a new list, associating it with the specified input window. Only one list can be associated with the input window (window_id).

Since Toolkit appends the “_LST” to the end of the input window name, the maximum size of this name is 11.

The title of the list, if any, and its position (if not passed in the row and column arguments, nor specified in the list class) are inherited from the input window. If the input window has a border, the list also inherits that. (When the list is deleted, the input window’s border is reset to its state prior to list creation.)

You should never explicitly remove the input window associated with a list, because doing so will corrupt the placement order.

Non‑window data is additional information that you don’t want displayed, but that you want to be maintained with the list. There are two pieces of data associated with every item in a list: an image of the input window’s display (sometimes referred to as “window data,” and the contents of the “a_itemdata” record (often referred to as “non‑window data.”) The latter can be confusing, because it almost always includes a storage representation of the former in order to be useful. Non‑window data is not required at all, but lists are most often useful if the data for each item can be stored or retrieved in a record form (as opposed to merely a display form).

The data record passed to L_CREATE establishes the default value for non‑window data for each item. This is the value that is assigned to the record before the load method is called. It is also assigned to any new item created with D_LAPPEND or D_LINSERT. The same thing happens for window data; in this case, the image of the input window when L_CREATE was called is used.

Both window and non‑window data can

The “initial data” is stored only once. When new items are created, they are initially set to this value. It is expected that the item will be modified by the load method or subsequent processing. It is really only intended to ensure that the initial state of the data is valid. For instance, you might want integer fields in the record initialized to integer 0, as opposed to blanks.

To change the data for each item in the list, you would need to use L_DATA or L_PROCESS to access each item, or you would need to restart the list (L_RESTART) and provide the modified data in the load method.

If class is passed and it is loaded from channel, it will remain loaded when this subroutine returns. If channel is not passed and the class specified in class is not already loaded, an error will occur. (L_CREATE will not use g_utlib by default.) If class is not passed or if it is blank, the default class will be used. The default list class has the following characteristics:

You can override the row and column placement, whether from the specified class or the default class, by specifying row and column. You can override the default placement by passing a non‑zero no_placement value. The coordinates that you set when no_placement is passed are now retained and used when the list is placed. You can also create the list in a disabled state by passing a non‑zero disabled value.

By default, lists are loaded by the L_PROCESS subroutine beginning with the first, or topmost, item displayed, and proceeding down the list either until no more items exist or until the display area of the list is full. When more display items are required (for example, when the user moves down from the last item in the list), additional items are requested from the calling routine (or are obtained by calling the specified LLOAD_METHOD) until no more are available. Because each new requested item is loaded at the bottom of the known list and follows the last item requested, we refer to this method as “loading at the bottom of the list, forward.”

Sometimes, however, you’ll want to load the last window of items first, as for a transaction entry subroutine that displays a history of previous transactions but allows new transactions at the bottom. If several previous transactions exist, a significant pause would occur if the first set of items had to be loaded first, followed by all the other items as the list was traversed to get to the end.

An alternative method of loading items begins with the last item in the list, loads items in reverse order until the display is full, and then requests additional items as needed as the user moves up through the list. Because each new requested item is loaded at the top of the known list and precedes the last item requested, we refer to this method as “loading at the top of the list, backward.”

A third method of loading combines the previous two. This method (sometimes known as two‑way or bi‑directional loading) begins anywhere in the list, loads the first window of items in a forward direction, and requests additional items as needed at either end of the list. Items requested at the top of the known list are expected to be retrieved backwards, while items at the bottom of the list are retrieved forwards. You might use this combination method for lists with a known starting point that is preceded and followed by a potentially large number of items (for example, a “search” function in a transaction history file).

The initial argument determines how list items will be loaded into the list on subsequent calls to L_PROCESS:

If initial is not passed, the default initial item is 1.

If last is not passed or if it has a value of zero, the calling routine is unable to determine the number of list items. This number will be determined internally by UI Toolkit. In such a case, Toolkit assumes that last is greater than initial.

If error is passed, it is returned as 0 if the list is successfully created. If the list cannot be created, error is returned with the number for the Toolkit error. If error is not passed, all errors are fatal.

Error can be one of the Synergy runtime errors, Synergy window errors, or Toolkit errors listed below. You can use %U_GETWNDERR to retrieve error text.

See also

List load method and LLOAD_METHOD for more information about using load methods.

Examples

The following example creates a list from the class “lst_lookup” defined in the library opened on g_utlib. Inpid is the associated input window, and lookup_data contains the initial contents of the associated data to store or retrieve for each list item.

xcall l_create(lstid, inpid, lookup_data, g_utlib, "lst_lookup")

The next example creates a list from the list class “lst_trans” defined in the library opened on g_utlib. The ID of the associated input window is contained in item_id, and trans_data contains the initial contents of the associated data to store or retrieve for each list item. The list is initially disabled and not placed on the screen. However, its placement is specified as row 5, column 20, which is where it will be placed if L_PLACE is called without re‑specifying these parameters. Presuming that nmitems is greater than 1, loading of items into the list will be in reverse order, starting with the last item. Any error that occurs while attempting to create the list will be returned in error.

xcall l_create(trans_lst, item_id, trans_data, g_utilib, "lst_trans", 5,
&              20, D_NOPLC, TRUE, nmitems, nmitems, error)