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

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