SaTwoList(3tlib)

SaTwoList: SaTwoList, SaTwoListAddItems, SaTwoListDeleteItems, SaTwoListGetItems, SaTwoListSelectItems, SaTwoListGetTabList, SaTwoListSetFocus -- SCO Visual Tcl interface for a two-list widget form

Synopsis

SaTwoList name label1 items1 label2 items2 buttonlabel1 buttonlabel2 [options]
SaTwoListAddItems twolist list items
SaTwoListDeleteItems twolist list
SaTwoListGetItems twolist list
SaTwoListSelectItems twolist list items
SaTwoListGetTabList twolist
SaTwoListSetFocus twolist [list]

Description

These interfaces implement a commonly used complex user interface widget, the two list. It consists of adjacent lists where items from one list can be moved or copied to the other. Two lists apply to any situation where a user must divide a set of items into two disjoint sets (e.g. allowed users, denied users) or where one list represents the set of all possible values and the other list a selected subset. Common usage arranges the two lists so that users will tend to ``build'' their selection by moving from left to right.

SaTwoList creates a form widget which includes two lists, each with a title, an initial list of items, and an optional search field. Push buttons and double-click actions cause items to migrate between the lists. Initial focus can be set to either list and the two list widgets can be included in a larger tab list in the event that the two list is embedded in a larger dialog.

In the documentation that follows, the two individual lists are referred to as ``1'' (leftmost) and ``2''.

SaTwoList: creates the two list form. SaTwoList returns the widget string of the new form.
A rich set of options to SaTwoList can be used to customize the behavior of the two list widget in a variety of ways (See below).
SaTwoListAddItems: adds items to one of the two lists.
SaTwoListDeleteItems: deletes items from one of the two lists.
SaTwoListGetItems: retrieve the items from one of the two lists.
SaTwoListSelectItems: selects one or more items in one of the two lists.
SaTwoListGetTabList: returns an ordered list of widgets in the two list form representing a logical sequence of traversal using the <Tab> key. This list must be added to a tab and/or focus list for the form containing the two list in the event that it provides additional widgets.
SaTwoListSetFocus: sets the focus to one of the two lists. List ``1'' is the default.

Arguments

name

SCO Visual Tcl widget name for the new form.

label1

title label for list 1.

buttonlabel1

label name for the 1 to 2 button.

items1

list of items for list 1.

label2

title label for list 2.

buttonlabel2

label name for the 2 to 1 button.

items2

list of items for list 2.

options

Tcl list of 0 or more options where each option is two item list giving the option keyword and a value:

-rows x: specifies the height of each list in rows. The default is 7.
-columns x: specifies the width of each list in columns. Normally this is set automatically to the widest element or list title.
-selection <multiple|single>: This indicates whether the list should be single or multi-select. The default is multi.
-search <list1|list2|neither|both>: optional text fields can be displayed which allow the user to search for an entry in the list by typing in the entry and pressing return. This causes the entry to be selected and all previously selected entries to be un-selected. The default is not to display these text fields. They can be turned on for each list individually or for both lists.
-sorting <none|(valid lsort options)>: normally the lists are sorted in ascending localized order. Specifying 'none' will turn off sorting. One can also specify different sorting instructions as long as they are valid lsort options (validity isn't checked up front but by lsort when it is called).
-copySelected <never|aToB|bToA|always>: by default, when ever an entry is transferred between lists the entry is moved; that is the entry is added to the destination list and removed from the orginating list. Entries can instead be copied from one list to the other which means that the entry in the orginating list is not removed. The copy behavior can be set for either transfer direction or for both (always).
-movement <next|follow>: indicates whether the selected items after a transfer operation (either the buttons or double click) are the items just transfered into the list (follow) or the next available item in the originating list (next). The default is next.

twolist

widget string for a specific two list. Returned by SaTwoList.

list

specifies one of the two lists, ``1'' or ``2''. Where optional, list defaults to ``1''.

items

list of 0 or more list items.

References

SaSetFocus(3tlib).