WwListUtils Function

PV-WAVE Foundation > Reference Guide > Procedure and Function Reference: W > WwListUtils Function

Manages the contents of a 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

status = WwListUtils(wid[, param1[, param2]])

Input Parameters

wid — The widget ID of a scrolling list created with WwList.

param1 — (optional) This parameter depends on keyword use in the function calling sequence. See Keywords for more information.

param2 — (optional) This parameter depends on keyword use in the function calling sequence. See Keywords for more information.

Returned Value

status — A value indicating the success or failure of the WwListUtils call.

1 — Indicates success.

0 — Indicates failure.

Keywords

Add — Add the items specified by param1 to the list following the list position specified by param2. If this keyword is used, you must also specify both of the following parameters.

param1 — A string or array of strings containing the items to add to the list.

param2 — (long) Specifies the position in the list below which the items are added. (Default: end of the list)

Delete — Delete the specified items from the list. If the All modifier keyword is also specified, all items in the list are deleted. If All is not specified with Delete, you must specify the following parameter:

param1 — A string or array of strings containing the items to delete from the list.

Deselect — Deselect the specified items from the list. If the All modifier keyword is also specified, all items in the list are deselected. If All is not specified with Deselect, you must specify the following parameter:

param1 — String or array of strings containing the items to deselect in the list.

GetItems — If nonzero, returns an array of strings in an output parameter param1 containing all the items in the list. If the modifier keyword Count is specified, the number of items is returned rather than the items themselves. If the Count keyword is used, you must specify the following output parameter:

param1 — Array of strings, or a long integer (optional) representing the number of items in the list is returned.

GetSelected — If nonzero, returns an array of strings in an output parameter param1 containing the selected items. If the modifier keyword Count is specified, the number of selected items is returned rather than the items themselves. If the Count keyword is used, you must specify the following parameter:

param1 — Array of strings, or a long integer (optional) representing the number of selected items in the list is returned.

Last — The new item is added as the last item of the list, if this keyword is not specified, the new item is added as the first item of the list.

Replace — Replace the specified items in the list, starting at a specified list position. Items cannot be added to the list using this keyword. If there are more new items than the number of items you are replacing, the new items are truncated. For example, if you are replacing the items in list1, which contains 3 items, with the items from list2, which contains 4 items, only the first 3 items of list2 are used. If this keyword is used, you must specify both of the following parameters.

param1 — String or array of strings containing the items to replace.

param2 — (long) The position in the list to begin replacing items.

Select — Select the specified items in the list. If the All modifier keyword is also specified, all items in the list are selected. If All is not specified with Select, you must specify the following parameter:

param1 — String or array of strings containing items to select in the list.

If the modifier keyword Notify is used with Select, the selectedCallback registered with the WwList routine is called.

Modifier Keywords

The following modifier keywords are only used in conjunction with the WwListUtils keywords listed.

All — If nonzero, all items in the list are selected, deselected, or deleted.

Count — If nonzero and the GetSelected or GetItems keywords are specified, the number of items in the list widget is returned.

Notify — If nonzero and the Select keyword is specified, calls a PV‑WAVE callback routine for the selected items.

Discussion

WwListUtils facilitates portability of PV‑WAVE applications between Microsoft Windows and X Windows environments. The WwListUtils function is a wrapper for the WtList function.

Example 1

This example shows the use of the WwListUtils function with WwList. When a user selects an item once or double-clicks on an item within the list, the callback ListCB is executed, and all the items are dynamically replaced in the list.

Enter the following code into a file, and compile it with the .RUN command. Then, enter WWLISTUTILS_EX at the WAVE> prompt. To dismiss the list box, select the appropriate function (such as Close) from the window manager menu.

PRO ListCB, wid, parent

   status = WwListUtils(wid, SINDGEN(9) + $

      STRJOIN(REPLICATE('b', 99)), 0, /Replace)

END

PRO wwlistutils_ex

   shell = WwInit('wwlistutils_ex', 'Examples', layout, /Form)

   items = SINDGEN(9) + STRJOIN(REPLICATE('a',99))

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

      /HorzSb, /Left, /Right)

   status = WwSetValue(list, Size=[100,100])

   status = WwSetValue(shell, /Display )

   WwLoop

END