hiCreateListBoxField

hiCreateListBoxField(
?name s_fieldName
?choices l_listItems
[ ?prompt t_prompt ]
[ ?value l_selectedItem ] 
[ ?defValue l_defSelectedItem ] 
[ ?valueByPosition g_valueByPosition ]
[ ?callback g_callback ]
[ ?changeCB g_changeCB ]
[ ?numRows x_numRows ]
[ ?multipleSelect g_multipleSelect ]
[ ?doubleClickCB g_doubleClickCB ]
[ ?CBOnReselect g_CBOnReselect ]
[ ?keepHistory g_keepHistory ]
[ ?enabled g_enabled ]
[ ?invisible g_invisible ]
[ ?help g_fieldHelp ]
[ ?selectionEnabled g_selectionEnabled ]
)
=> r_fieldHandle

Description

Creates a list box field for a form.

Any string item selection changes in this field are tracked and are accessible by SKILL.

Arguments

?name s_fieldName	Handle to the list box field.
?choices l_listItems
	List of items displayed in the list box field. Each item can be either a string, or a pair of (string hiIcon). Each item is normally a null terminated string and must not contain the C newline character \n. The maximum limit on any individual string’s length is 2047 bytes (2 kilobytes - 1) but strings should be kept short and concise. Default Value: nil (nothing available to select)
?prompt t_prompt	Prompt to appear on the left side of the list box field. If no prompt is specified, none appears.
?value l_selectedItem
	Items selected in the list box field. The items must be valid values, that is, they must have been previously defined in l_listItems. You can specify the items as a list of strings or as a list of integers or ranges representing the position of the items. For example: ’( "b" "e" "f" "g" "j") ’(2 5 6 7 10) ’(2 ’(5 7) 10) The maximum limit on any individual string’s length is 2047 bytes (2 kilobytes - 1). The g_valueByPosition argument determines whether the l_selectedItem list is managed and reported as a list of strings or a list of integers. See the description of g_valueByPosition for more information. Default Value: nil (nothing selected) You can also set the value with the value property. For example: form -> listbox -> value = l_newValue
?defValue l_defSelectedItem
	Defaults selected in the list box field. The items must be defined in l_listItems. You can specify the items as a list of strings or as a list of integers or ranges representing the position of the items. For example: ’( "b" "e" "f" "g" "j") ’(2 5 6 7 10) ’(2 ’(5 7) 10) This argument is similar to l_selectedItem and is assigned to l_defselectedItem when the user presses the Defaults button on the form. The g_valueByPosition argument determines whether the l_defSelectedItem list is managed and reported as a list of strings or a list of integers. See the description of g_valueByPosition for more information. You can also set the default value with the defValue property. For example: form -> listbox -> defValue = l_newValue
?valueByPosition g_valueByPosition
	Lists l_selectedItem and defSelectedItem through the items in the value and default value. These are managed and reported as integers representing their position. The position is determined by the order of the items in the list box field—the first item is 1, the second 2, and so forth. If g_valueByPosition is non-nil, when you retrieve the value or default value of the field (for example, with form -> listbox -> defValue), you get a list of integers. To get the field’s value and default value as a list of strings even when g_valueByPosition is non-nil, use the hiGetListBoxValue function. You can also set the ?valueByPosition argument with the valueByPosition property. For example: form -> listbox -> valueByPosition = nil Default value: nil If you set g_valueByPosition to nil, the items in the value and default value lists—l_selectedItem and defSelectedItem— are managed and reported as strings. When you retrieve the value or default value of the field (for example, with form -> listbox -> value), you get a list of strings.
?callback g_callback
	Callback executed when the user has exited the list box field and the value has changed. The callback can be of string, symbol, or function object type.
?changeCB g_changeCB
	Callback for this field. It can be of string, symbol, or function object type. The callback is executed when the value (selected items) of the list box has changed. Programmatic SKILL changes can also trigger this callback, for example: form->listbox->value->list( “newValue”)
?numRows x_numRows
	Number of rows to be displayed in the list box field in a 1D form or minimum number of rows to be displayed in the list box field in a 2D form. Whenever a horizontal scroll bar appears in the field, the number of visible rows is reduced by one.
?multipleSelect g_multipleSelect
	If you specify t, multiple items can be selected in the list box. If you specify nil, only a single selection is allowed. Default Value: nil After the form is mapped, you can set this value with the multipleSelect property as follows: form->listboxField->multipleSelect=t/nil If ?multipleSelect is set to t and there are duplicate items in the ?choices list then ?valueByPosition should be set to t.
?doubleClickCB g_doubleClickCB
	Callback executed when the user double clicks an item in the list box. The double-clicked item is selected and all previously selected values are deselected. If the selected item has changed as a result of this double click,  t_changeCB is also called. Default Value: nil (no double click occurred) The callback can be of string, symbol, or function object type.
?CBOnReselect g_CBOnReselect
	Calls the change callback (t_changeCB) when a value is selected, even if it is the same value as before; otherwise, the change callback is called only when the value changes.
?keepHistory g_keepHistory
	t or nil. If you specify t, attempts to retain the ?value when choices are changed. The default value is nil. If g_valueByPosition is non-nil, the position integers are retained instead of strings. For example, if the current value is 3 and the item list is ("a" "b" "c" d"), when you change the item list to ("c" "d" "e" "f"), the current value remains 3 even though its corresponding string has changed from "c" to "e".
?enabled g_enabled
	Specifies whether the fields in the layout are enabled. The default value is t.
?invisible g_invisible
	Specifies whether the layout and the fields within are invisible. The default value is nil.
?help g_fieldHelp	A string or symbol used to reference help. If not specified, s_fieldName is used. This argument is currently not used.
?selectionEnabled g_selectionEnabled
	Specifies whether the selection in the list box field can be changed using mouse and keyboard. By default it is set to t, which means the selection can be changed. If you set the value to nil, the current selection cannot be changed interactively and gets displayed as read-only mode.

Values Returned

r_fieldHandle

Handle to the list box field.

Examples

The following sample shows you how to include a list box in a form. The user can rearrange the items of the list box by selecting the Move Up or Move Down buttons.

;;; The following procedures returns a copy of aList 
;;; with elem swapped one position closer to the top 
;;; of the list. == aList if elem is already on top 
;;; of the list.
procedure( trSwapElementTowardTop( elem aList )
   cond(
     ( !aList  nil )
     ( elem == car( aList )   aList )   ;;; already the first item
      ( elem == cadr( aList )
         `( ,elem ,car( aList ) ,@cddr( aList ))
         )
      ( t
         cons(
            car( aList )
            trSwapElementTowardTop( elem cdr( aList ))
            )
         ) ; t
      ) ; cond
   ) ; procedure

/*
trSwapElementTowardTop( 1 nil )
trSwapElementTowardTop( 1 '( 1 ) )
trSwapElementTowardTop( 1 '( 1 2 ) )
trSwapElementTowardTop( 1 '( 2 1 ) )
trSwapElementTowardTop( 1 '( 2 1 3 4 ) )
trSwapElementTowardTop( 1 '( 2 3 4 1 ) )
trSwapElementTowardTop( 1 '( 2 1 3 4 ) )
*/

;;; The following procedure returns a copy of aList with 
;;; elem swapped one position closer to the bottom of 
;;; the list.==aList if elem is already on the bottom of 
;;; the list.

procedure( trSwapElementTowardBottom( elem aList )
   cond(
      ( !aList nil )
      ( length( aList ) == 1 aList )
      ( elem == car( aList )               ;
         `( ,cadr( aList ) ,elem ,@cddr( aList ))
         )
      ( t
         cons(
            car( aList )
            trSwapElementTowardBottom( elem cdr( aList ))
            )
         ) ; t
      ) ; cond
   ) ; procedure

/*
trSwapElementTowardBottom( 1 nil )
trSwapElementTowardBottom( 1 '( 1 ) )
trSwapElementTowardBottom( 1 '( 1 2 ) )
trSwapElementTowardBottom( 1 '( 2 1 ) )
trSwapElementTowardBottom( 1 '( 2 1 3 4 ) )
trSwapElementTowardBottom( 1 '( 2 3 4 1 ) )
*/

;;; The following procedure returns a list build using the
;;; elements of aList as indices into anAssocList. It looks
;;; up each element of aList in anAssocList to determine the
;;; element to include in the result.
procedure( trReorderList( anAssocList aList )
    foreach( mapcan item aList
      list( cadr( assoc( item anAssocList )) )
      ) ; foreach
   ) ; procedure

;;; A list box field can only display text strings. 
;;; Since trListEditor should work on any list, the 
;;; code should translate back and forth from a data 
;;; item X to its print representation returned by 
;;; sprintf( nil "%L"X).
procedure( trListEditor_Choices( aList )
   foreach( mapcar item aList 
      sprintf( nil "%L" item )
      ) ; foreach
   ) ; procedure

;;; The following procedure recovers the underlying items 
;;; from their print representations.
procedure( trListEditor_AssocList( aList )
   foreach( mapcar item aList 
      list( sprintf( nil "%L" item ) item ) 
      ) ; foreach
   ) ; foreach

procedure( trListEditor( aList )
   let( ( listBoxField buttonBoxField aListChoices theForm moveUpButton moveDownButton )
      
      listBoxField = hiCreateListBoxField(
         ?name  'trListBoxField       
         ?prompt "Items"
         ?choices trListEditor_Choices( aList )
         ?numRows min( length( aList ) 10 )
         )

      ;;; creating the Move Up button
      moveUpButton = hiCreateButton(
         ?name  'trMoveUpButton
         ?buttonText "Move Up"
         ?callback "trListEditorCB( hiGetCurrentForm()
'MoveUp )"
         )

      ;;; creating the Move Down button
      moveDownButton = hiCreateButton(
         ?name  'trMoveDownButton
         ?buttonText "Move Down"
         ?callback "trListEditorCB( hiGetCurrentForm() 'MoveDown)"
         )

      ;;; creating the Delete button
      deleteButton = hiCreateButton(
         ?name  'trDeleteButton
         ?buttonText "Delete"
         ?callback "trListEditorCB( hiGetCurrentForm() 'Delete )"
         )
         
      ;;; creating the form
      theForm = hiCreateAppForm(
         ?name gensym( 'trListEditor )
         ?formTitle "List Editor"
         ?fields list( listBoxField moveUpButton moveDownButton  deleteButton )
         ?callback "trListEditorCB( hiGetCurrentForm()
'Apply )"
         )

      theForm->trListEditor_AssocList = trListEditor_AssocList( aList )
      ;;; displaying the form
      hiDisplayForm( theForm )
      ) ; let
   ) ; procedure

procedure( trListEditorCB( theForm theAction )
   prog( ( selectedItem choices )
      selectedItem = car( theForm->trListBoxField->value )
      when( !selectedItem
         printf( "You haven't selected an item yet\n" )
         return( nil )
         ) ; when
      choices = theForm->trListBoxField->choices
      case( theAction
         ( MoveUp 
            theForm->trListBoxField->choices =
trSwapElementTowardTop(
               selectedItem     ;;; selected element
               choices        ;;; within list of items
               )
            theForm->trListBoxField->value = list(
selectedItem )
            ) ; MoveUp
         ( MoveDown
            theForm->trListBoxField->choices =
trSwapElementTowardBottom(
   selectedItem      ;;; selected element
   choices       ;;; within list of items
               )
            theForm->trListBoxField->value = list(
selectedItem )
            ) ; MoveDown
         ( Delete 
            theForm->trListBoxField->choices = remove(   
               selectedItem     ;;; selected element
               choices         ;;; from list of items
               ) ; remove
            ;;; no selection
            ) ; Delete
         ( Apply 
            println( theForm->trListEditor_result =
trListEditor_ReorderList( theForm ))
            ) ; Apply
         ( t
            error( "Unsupported action: %L" theAction )
            ) ; t
         ) ; case
      ) ; let
   ) ; procedure

procedure( trListEditor_ReorderList( theForm )
   let( ( assocList choices )
      assocList  = theForm->trListEditor_AssocList
      choices = theForm->trListBoxField->choices
      trReorderList( assocList choices )
      ) ; let
   ) ; procedure

To test your list editor:

Z = trListEditor( ’( 1 2 3 ))

After the form is displayed, rearrange the list box by moving the items up or down.

Related Topics

Form and Field Functions

Creating Context Menus for Fields

Return to top