SplitListSelector

(System Library)

Description:	Draws a split view comprising two GridLists separated by control buttons. Items listed on the left may be selected to be transferred to the right. Items on the right may be returned to the left so long as they were originally listed on the left. Scrollbars will be drawn if required.
Returns:	Nothing
Usage:	Steady State only.
Function Groups:	Graphics
Related to:	SplitTagSelector | GridList
Format:	System.SplitListSelector(InitKeyArray, DestKeyArray[, LeftLabel, RightLabel, NumCols, Titles, ColWidthPercents, DestMax, EnableParm])
Parameters:

InitKeyArray

Required. An array of items passed in to form the initial list on the left.

DestKeyArray

Required. An array of destination items. Any items initially in the array will be displayed in the list on the right.

LeftLabel

Optional label for the left list.

RightLabel

Optional label for the right list.

NumCols

Number of columns for each list. Defaults to 1 if not specified.

Titles

Optional array of titles for both lists. The number of titles must match the number of columns. If this parameter is not specified, then no titles will be displayed for the columns.

ColWidthPercents

Optional array of column width percentages for both lists. Defaults to equal widths if not specified. The size of the array must match the number of columns. The array elements will hold normalized values. For example: ColWidths    = New(3) ColWidths[0] = .3 {30%} ColWidths[1] = .2 {20%} ColWidths[2] = .5 {50%}

DestMax

Maximum number of destination items. The default is invalid which is taken to mean unlimited.

EnableParm

Flag to enable controls. Defaults to 1 if not specified

Comments:

A tool intended to provide a user interface for selecting items from a list on the left and transferring them to the right. The InitKeyArray may be an array of arrays. i.e. each element of the main array may be a sub-array which will make up the columns. If an array of arrays is specified, the DestKeyArray must also be of the same format. The first column (the first element of every sub-array making up a row) will be regarded as the unique key for comparison purposes. The items on the left will be updated if the InitKeyArray changes in size. When items are moved from the right to the left, they are inserted into the left only if they exist in the InitKeyArray. If not, they are simply removed from the right list. The SplitListSelector should be called from within a GUITransform as shown in the following example.

Examples:

GUITransform(30, 270, 470, 90,
             1, 1, 1, 1, 1 { Scaling              },
             0, 0          { Movement             },
             1, 0          { Visibility, scaling  },
             0, 0, 0       { Selectability        },
             System.SplitListSelector(InitResourceList,
                               SelectedResources,
                               \GetPhrase("AvailableResourcesLabel"),
                               \GetPhrase("SelectedResourcesLabel")));