L_CREATE

Create a list

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

be modified by the load method when loading an item.
be modified by passing a new value into L_PROCESS or L_SELECT for the current item, as long as the request flag is not D_LRESTORE (or D_LCANCEL, a synonym).
be modified by calling L_DATA with D_LWRITE.
be modified in the list item arrive, leave, or double-click method.
be searched with a D_LFIND request in the L_PROCESS subroutine—L_FINDSPEC specifies which will be searched.

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:

The row and column placement of the list is inherited from the input window.
The number of items visible at once is the maximum number that will fit without causing the list to occlude the information bar.
The list is allowed to be null.
The list contains vertical (and horizontal, if appropriate) scroll bars. (On Windows, these scroll bars take up slightly more screen area.)
The input window set context and field display is not maintained for each list item.
No methods are specified for the class.

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 has a value of 1, existing items will only be loaded at the bottom of the list, forward.
If initial is greater than 1 and equal to last, existing items will only be loaded at the top of the list, backward.
If initial is greater than 1 but less than last, existing items may be loaded at either end, but loading will begin at the bottom, forward.
If initial is greater than 1 but inaccurate, the list allows items to be loaded before the logical item 1. On Windows, you should never allow a “Page Up” operation to load an entire page previous to logical item 1.

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.

Synergy runtime errors are defined in rdeferr.h.
421, E_AXERR, “Error while processing an ActiveX control”—An ActiveX error occurred as the ActiveX list was loaded. This is often caused by dependencies on a missing file.
422, E_AXNOLOAD, “Could not load ActiveX control”—The runtime was not able to load the ActiveX list because the ActiveX list control was not registered and could not be automatically registered. This is often caused by a missing file.
Synergy window errors are documented in $ERR_WNDERR:
4, WE_OUTOFMEM. “Not enough memory (needed n, had n)”—There isn’t enough memory to create the supporting windows for the list.
9, WE_DUPWNDNAME, “Window name already defined”—A window already exists with the name of one of the generated supporting windows (which are inputWindowName_LST on all platforms and on Unix and OpenVMS, inputWindowName_HDR for headers and inputWindowName_FTR for footers).
10, WE_TOOMANYWND, “Too many windows (max of 1024)”—The supporting windows created for the list exceed the number allowed by Toolkit, which is 1024.
18, WE_OUTOFRES, “Windows resource error”—There aren’t enough system resources to create the list.
UI Toolkit errors:
521, DTK_NOCLASS, “List class class not found”—The name passed as class is not a valid list class.
522, DTK_NOCLSLIB, “List class class not loaded - no library supplied”—The number passed as channel is not the channel number for the window library that contains the list class class.
523, DTK_NOCLSWND, “Id n is not a list class”—The name passed as class is not a valid list class.
530, DTK_INPINUSE, “Input window n is already associated with a list”—The ID passed in window_id is for an input window that is already associated with a list. An input window can be associated with only one list.