WgList Procedure

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

WgList Procedure

Displays a list of items and returns an array of indices into the list corresponding to user-selected items.

Usage

WgList, items, chosen

Input Parameters

items — A string array containing items to be displayed in the list.

Output Parameters

Chosen — An array of indices into the list corresponding to the items chosen by the user. If nothing is selected, a single-element long array containing –1 is returned.

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 previously 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.

This is the default behavior if neither Browse, Extended, nor Multi keywords are provided.

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 previously 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. Ignored if Multi keyword is present and nonzero.

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

Parent — The widget ID of the parent widget. If no parent is specified, the toolkit is initialized and WgList runs; in its own event loop.

Position — A two element vector containing the position, in pixels, of WgList's upper-left corner where [0,0] is the upper-left corner of the display.

Shell — (Output) The id of the newly created WgList widget.

Title — A string containing the title for the widget.

Visible — An integer specifying the number of items that are visible in the list.

Hide — An array of indices into items that should not be displayed.

Background — The background color (passed to all widgets).

Font — The font to use for widget text.

Foreground — The foreground color (passed to all widgets).

note

wglist_output — A common block internal to WgList containing one variable, which is the item(s) selected by the user. When WgList is called stand-alone, it runs in its own event loop. Once the user finishes making their selection, control is passed back to the calling routine and the user's selection can be accessed through the variable chosen. However, if WgList is called from an existing widget application, the tool must use this calling widget's event loop. In this case, WgList is executed and control is passed back immediately to the calling widget application, before widget application that calls WgList to have access to the most recent items chosen by the user, include this common block in the calling widget application.

Discussion

Double-clicking on a menu item causes WgList to exit and return the currently selected items. This functionality can be convenient as there is no need to move the mouse to click "OK" to confirm the selection(s).

Example 1

WgList called from the command line.

items = FINDFILE('*.pro')

IF STRMATCH(GETPLATFORM(), 'win') THEN fnt = 'Forte, 10' $

ELSE fnt='-adobe-*-bold-*-*-*'

WgList, items, chosen, Visible=10, Position=[500,300], $

   Back='Green', Fore='Blue', /Multi, Shell=theShellID, Font=fnt

IF chosen(0) NE -1 THEN PM, items(chosen), Title='You chose:' $

ELSE PM, 'Nothing chosen'

INFO, chosen

Example 2

WgList called from another widget application.

PRO BUTTONSCB, wid, which

   COMMON teststuff2, workArea, items

   COMMON wglist_output, choices

   IF STRMATCH(GETPLATFORM(), 'win') THEN BEGIN

      fnt = 'Forte, 10'

   ENDIF ELSE fnt='-adobe-*-bold-*-*-*'

   CASE which OF

      1: WgList, items, chosen, Parent=workArea, $

         Title='WgList', Font=fnt, Fore='Red', Pos=[100,600], $

         Shell=shell, Visible=5, /Extended

      2: BEGIN

      IF N_ELEMENTS(choices) GT 0 THEN $

         IF choices(0) NE -1 THEN PM, items(choices), $

            Title="You've chosen:" ELSE PM, 'Nothing Chosen' $

         ELSE BEGIN

            PRINT, STRING(7B)

            PRINT, 'Selections have not been made yet'

         ENDELSE

END

   ENDCASE

END

PRO WGLIST_TEST

   COMMON teststuff, workArea, items

   topShell = WwInit('WgList_test','WgList_test', workArea, $

      /Vertical, Position=[256,256], Spacing=5, Height=100, $

      Width=350)

   buttons = WwButtonBox(workArea, ['Call wglist', $

      'See result'], 'BUTTONSCB')

   items = STRING(CINDGEN(20))

   status=WwSetValue(topShell, /Display)

   WwLoop

END

Example 3

WgList called from the command line, using the Hide keyword.

items = ['a','b','c','d','e','f']

; Font choice syntax different for Windows or Unix...

IF STRMATCH(GETPLATFORM(), 'win') THEN fnt = 'Forte, 10' $

   ELSE fnt='-adobe-*-bold-*-*-*'

WgList, items, chosen, Visible=5, Position=[500,300], $

   Back='Green', Fore='Blue', /Multi, Shell=theShellID, $

   Font=fnt, Title='Full list'

IF chosen(0) NE -1 THEN PM, items(chosen), Title='You chose:' $

   ELSE PM, 'Nothing chosen'

INFO, chosen

; Now call WgList again, but hide what choices the user

; previously selected

WgList, items, chosen2, Hide=chosen, Visible=5, $

   Position=[500,300], Back='Green', Fore='Blue', /Multi, $

   Shell=theShellID, Font=fnt, Title='Remaining list'

IF chosen2(0) NE -1 THEN PM, items(chosen2), Title='You chose:' $

   ELSE PM, 'Nothing chosen'

INFO, chosen2