hiShowListBox

hiShowListBox(
?name s_listBoxHandle 
?choices lt_listItems 
?callback s_callback 
[?title t_listBoxTitle] 
[?multipleSelect g_multiSelect]
[?value lt_selectedItem]
[?appData g_appData]
[?applyButton g_applyButton]
) 
=> t / nil 

Description

Creates and displays a list box. The list box displays a list of strings. The list box can be created so that one item is selectable or multiple items are selectable. While the list box is displayed on the screen, the user may change the items in the list box, or change the item(s) selected. The list box remains on the screen until the user selects OK or Cancel. The list box is destroyed when it is removed from the screen.

Arguments

?name s_listBoxHandle
	A unique global SKILL handle to the created list box. The selected item and other useful information can be retrieved from the listBoxHandle. For example, if listBoxHandle was ’myListBox, the following could be accessed and/or set: myListBox->??   ;all list box properties (read-only) myListBox->hiListBoxSym   ;s_listBoxHandle  (read-only) myListBox->title   ;list box title (read-only) myListBox->value   ;selected item(s) myListBox->choices   ;item(s) displayed in list box myListBox->appData   ;application data
?choices lt_listItems
	List of strings that is displayed in the scrolling window. This list can be referenced or reset through: listBoxHandle->choices When the list box choices have been changed, any item(s) previously selected gets unselected (for example, listBoxHandle->value is set to nil).
?callback s_callback
	The user-defined SKILL procedure that is run when either the OK or Cancel button of the list box is pressed. This procedure must be in the following format: myListBoxCB(g_OKpressed o_listBox) where g_OKpressed is t if the user pressed the OK button and is nil if the user pressed Cancel. The argument o_listBox is the SKILL structure of the list box that was dismissed. Various elements can be accessed through this list box structure, as described above.
?title t_listBoxTitle
	Optional title of the list box displayed in the WindowManager banner. This title can also be referenced through: listBoxHandle->title
?multipleSelect g_multiSelect
	If set to t, multiple items in the list box can be selected; if set to nil, at most one item can be selected at a time. The default value is nil.
?value lt_selectedItem
	List of string item(s) that needs to appear as already selected when the list box is displayed. These strings must also be specified in l_listItems. If not specified, nothing is pre-selected. If this list contains more than one string, the argument g_multiSelect must be set to t. The currently selected item(s) can be referenced or set through: listBoxHandle->value
?appData g_appData
	Used to store any application-specific data associated with the list box. It can be referenced or set through: listBoxHandle->appData
?applyButton g_applyButton
	If set to t, places an Apply button in the list box. The default is nil (no Apply button). There is also an applying property which, if queried during the callback of the list box (via myListBox->applying), returns t if the Apply button was the reason for the callback, or nil if the callback was called because the user clicked OK.

Values Returned

t	The OK button was selected.
nil	The Cancel button was selected.

The list box symbol is reset to nil after the callback has been executed, and the list box is dismissed from the screen.

Examples

Creates and display a list box showing various flowers. The user should be able to select all of his/her favorite flowers.

hiShowListBox(?name ’myLB 
?title "Pick your favorite flowers" 
?choices list("daffodil" "lily" "freesia" "rose" "carnation")
?value list("rose" "freesia")
?callback ’myListBoxCB
?multipleSelect t )

; This procedure is called when the user selects OK or 
; Cancel on the list box
procedure(myListBoxCB(okPressed listbox "go")
    ; if user pressed OK, save the selected flowers
    if( okPressed  saveFlowers(listbox->value) )
)

; Change the list of flowers being displayed
myLB->choices = list("petunia" "tiger lily" 
"bird of paradise" "chrysanthemum")

; Select a flower
myLB->value = list("bird of paradise")

Creates a simple list box.

;;; trShowListBox generates a new list box displaying aList
procedure( trShowListBox( aList )
   let( ( listBoxSymbol )
      listBoxSymbol = gensym( 'trExampleListBox )
      hiShowListBox(
         ?name  listBoxSymbol      
         ?choices  aList
         ?callback  'trExampleListBoxCB
         ?title        sprintf( nil "List Box: %L"  listBoxSymbol )
         ?multipleSelect     t
         ?applyButton     t
         )
      ) ; let
   ) ; procedure

procedure( trExampleListBoxCB( ok theListBox )
   "The callback routine"
   println( list( ok theListBox->value ) )
   ) ; procedure

To test your application, create two different list boxes and verify that the two list boxes behave independently:

trShowListBox( '( "apple" "orange" "kiwi" ) )
trShowListBox( '( "wood" "water" "metal" ) )

Creates a list box that displays all the functions matching the specified pattern.

procedure( trFunctionListBox( pattern )
   "uses trListFunctions to compose a Show List Box"
   hiShowListBox( 
      ?name  gensym( 'trFunctionListBoxHandle ) 
      ?title  sprintf( nil "Matching: %s" pattern )
      ?choices  trListFunctions( pattern )
      ?callback  ’trFunctionListBoxCB
      ?applyButton  t
      ?multipleSelect  t
      ) ; hiShowListBox 
   ) ; procedure

procedure( trListFunctions( pattern )
   "returns a list of functions for the matching pattern"
   foreach( mapcar fun listFunctions( pattern )
      get_pname( fun )
      )
   ) ; procedure

procedure( trFunctionListBoxCB( ok theListBox  )
   let( ( theArglist )
      when( ok 
               foreach( funName theListBox->value
                  theArglist = arglist(makeSymbol(funName))
                  if( theArglist 
                     then 
                        printf("\n%s%L" funName theArglist)
                     else
                        printf( "\n%s()" funName )
                     ) ; if
                  ) ; foreach
               ) ; when
      ) ; let
   ) ; procedure

To find all the functions that start with "hiGet", type the following command in the CIW:

trFunctionListBox( "^hiGet" )

Additional Information

You can select mechanism for multiple selection in list boxes using hiShowListBox:

To select a continuous range of items:

1. Press the left mouse button.
2. Drag the cursor over the items you wish to select.
3. Release the mouse button.

Each time the left mouse button is pressed, a new selection process begins, and the previously selected items are unselected.

To modify a selection:

1. Press and hold the Shift key.
2. Move to the new endpoint of selected items.
3. Press the left mouse button.

The items between the initial start point and the new endpoint are selected; any previous selections are not unselected.

To add or delete items from the selected set:

1. Press and hold the Control key.
2. Move to the item you wish to add or delete.
3. Press the left mouse button (inverts the selection state of this item).
4. Drag the mouse button, if you wish to add or delete a range of items.

The item(s) selected or unselected gets added to or deleted from the selected set. Any previous selections remain unaffected.

Related Topics

List Box Functions

hiDisplayListBox

hiListBoxCancel

hiListBoxDone

Return to top