WwList Function

Creates a scrolling list widget.

Note:

Making piecemeal changes to large lists requires multiple memory allocations and can result in repeated redraws of the list contents as each change is made. To avoid this, write your code so changes are made in bulk using one of the following methods: WwSetValue: this method always uses bulk changes. WtList: delete the entire list with the 'DeleteAll' function and update with the 'Add' function WwListUtils: delete the entire list using the Delete keyword in conjunction with the All keyword and then update the list using the Add keyword. In general it is much more efficient to delete and replace the entire list in two operations than it is to iteratively remove or replace many individual items in an existing list.

Usage

list = WwList(parent, [items,] selectedCallback, defaultCallback)

Input Parameters

parent — The widget ID of the parent widget.

items — (optional) A string array containing the items to appear on the list. If the items parameter is undefined or is defined as an array of null strings, the function looks for item strings in a resource specification (see Discussion).

selectedCallback — A string containing the name of the callback that is executed when an item is selected.

defaultCallback — A string containing the name of the callback that is executed when a user double-clicks on an item.

Returned Value

list — The widget ID of the list widget.

Keywords

Browse — If specified and nonzero, the list uses the “browse” selection method. This method allows the user to select at most one item at a time. Whenever the user selects an item, the currently selected item is deselected. When the user presses the mouse selection button and drags the pointer over the list, the current selection moves along with the pointer.

Extended — If specified and nonzero, the list uses the “extended” selection method. This method allows the user to select multiple items at a time. Whenever the user selects an item, the currently selected item is deselected; however, when the user presses the mouse selection button and drags the pointer over the list, multiple items are selected. The selected items include all items between the item on which the mouse selection button was pressed and the item currently under the pointer.

HorzSb — If present and nonzero, a horizontal scroll bar appears if the list contents are wider than the list.

Multi — If present and nonzero, the list widget uses multiple selection mode. The default is single selection mode.

Name — A string specifying the name of the List widget or an array of strings specifying the List widget name and the item names if the items parameter is not defined. This is part of the resource specification. The Name keyword can be used in place of the items parameter, although items will take precedence if both are given. (Default: list.)

Position — If the scrolling list widget is to be placed in a bulletin board layout, use this keyword to specify the x, y coordinates of the scrolling list widget within the bulletin board.

Selected — Specifies the string, or string array, of items to be initially selected in the list.

Tab_WinOff — (Windows only) If this keyword is present and nonzero, the tab navigation feature is turned off for this widget.

Note:

Use the arrows keys to traverse the list and the Spacebar to activate or deactivate the highlighted selection.

Visible — Specifies the number of items that are visible in the list widget.

Color/Font Keywords

Background — Specifies the background color name.

Font — Specifies the name of the font used for text.

MSFont — Adds support for Windows fonts.

Foreground — Specifies the foreground color name.

Attachment Keywords

Bottom — If a widget ID is specified (for example, Bottom=wid), then the bottom of the scrolling list widget is attached to the top of the specified widget. If no widget ID is specified (for example, /Bottom), then the bottom of the scrolling list widget is attached to the bottom of the parent widget.

Left — If a widget ID is specified (for example, Left=wid), then the left side of the scrolling list widget is attached to the right side of the specified widget. If no widget ID is specified (for example, /Left), then the left side of the scrolling list widget is attached to the left side of the parent widget.

Right — If a widget ID is specified (for example, Right=wid), then the right side of the scrolling list widget is attached to the left side of the specified widget. If no widget ID is specified (for example, /Right), then the right side of the scrolling list widget is attached to the right side of the parent widget.

Top — If a widget ID is specified (for example, Top=wid), then the top of the scrolling list widget is attached to the bottom of the specified widget. If no widget ID is specified (for example, /Top), then the top of the scrolling list widget is attached to the top of the parent widget.

Get/Set Value

getvalue — Returns an array of the selected items (string).

setvalue — Replaces current items with the new items (array of strings).

Callback Parameters

Any list widget callback procedure must have the following two parameters:

wid — List widget ID.

parent — Parent widget ID.

Discussion

A scrolling list allows users to select one or more items from a group of choices. Items are selected from the list with the mouse. An additional callback can be defined for the default action. This callback is executed when the user double-clicks on an item.

Part of the list item resource can be specified using the Name keyword, otherwise the default is the *.item_#.itemString resource (where itemString is the attribute).

Note:

The items parameter provides a method for “hard-coding” the list items in the application. For greater flexibility, create your resource file using a text editor, and load the resource containing the list of items using WtResource. The Name keyword can then be used in the WwList calling sequence to specify the List widget name and items in the resource specification.

Example 1

This example creates a scrolling list containing the items defined in the string array items. When the user selects an item (clicks it with the mouse), the first callback ListCB is executed. If the user double-clicks on an item, the callback DefaultCB is executed.

Enter the callback procedures into a file, and compile them with the .RUN command. Then, enter the widget commands at the WAVE> prompt. To dismiss the list box, select the appropriate function (such as Close) from the window manager menu.

Callback Procedures

PRO ListCB, wid, data

   PRINT,'Item Selected'

   value = WwGetValue(wid)

   PRINT, value

END

PRO DefaultCB, wid, data

   PRINT,'Default Item Selected'

   value = WwGetValue(wid)

   PRINT, value

END

Widget Commands

top = WwInit('ww_ex28', 'Examples', layout)

items = ['Presidents Day','St.Patricks Day', $

   'Easter', 'Memorial Day', '4th of July', $

   'Labor Day', 'Halloween', 'Thanksgiving', $

   'Hanukkah', 'Christmas', 'New Years Eve']

datelist = WwList(layout, items, 'ListCB', $

   'DefaultCB', Visible=7, /Multi)

status = WwSetValue(top, /Display)

WwLoop

Example 2

A typical resource specification for the list items used in WwList is:

Name = ['mylist', 'spring', 'summer']

myapp.mylist.summer.itemString: Summer 

See Also

WwListUtils

For detailed information on GUI development, refer to the PV‑WAVE Application Developer’s Guide.

For more information about how to write an application program based on PV‑WAVE Widgets, refer to Using Wave Widgets in the PV‑WAVE Application Developer’s Guide.

For additional information on the color and font keywords, see "Setting Colors and Fonts" in the PV‑WAVE Application Developer’s Guide.

For additional information on attachment keywords, see "Form Layout: Attachments" in the PV‑WAVE Application Developer’s Guide.

For information on Get and Set values, see "Setting and Getting Widget Values" in the PV‑WAVE Application Developer’s Guide.