hiCreateCyclicField

hiCreateCyclicField( 
?name s_fieldName 
?choices l_enumerations 
?prompt t_fieldPrompt 
[ ?value g_currentValue ] 
[ ?defValue g_defaultValue ] 
[ ?callback g_callback ] 
[ ?help g_fieldHelp ] 
[ ?font t_font ]
[ ?enabled g_enabled ]
[ ?invisible g_invisible ]
[ ?keepHistory g_keepHistory ]
) 
=> r_fieldHandle

Description

Creates a cyclic field for a form. A cyclic field contains a list of string or icon enumerations, which are displayed in a drop-down list. Only one item can be selected at a time.

A maximum of 42 items are displayed in the drop-down list; if there are more items, a scroll bar appears.

This field can also have a context menu, that is, a pop-up menu that is displayed when you right-click on the field.

For information on creating tooltips for fields, see Creating Tool Tips for Fields.

Arguments

`?name` s_fieldName	Handle to this field within a form. To reference it, use: `formHandle->hiFieldSym`
`?choices` l_enumerations
	List of strings and/or icons that can be cycled through. The current value and default value (if any) must be contained within this enumerated list. A maximum of 42 items are displayed in the drop-down list; if there are more items, a scroll bar appears.
`?prompt` t_fieldPrompt
	String specifying the prompt for the field. To reference it, use: `formHandle->hiFieldSym->prompt`
`?value` g_currentValue
	The current value of the cyclic field. Must be a string or icon list specified in l_enumerations. If g_currentValue is not specified, it defaults to the first choice in the enumerations list. To reference the current value, use: `formHandle->hiFieldSym->value`
`?defValue` g_defaultValue
	Default value of the field (in the correct format). This value is equal to the initial entry in g_currentValue if g_defaultValue is not specified. To reference the default value, use: `formHandle->hiFieldSym->defValue`
`?callback` g_callback
	Callback for this field. If a callback of string type is specified, the item selected (either text or an icon) is appended to this callback before being executed by SKILL. If the callback is of symbol or function object type, it is called with the following syntax: < `cyclic field callback` > ( o_field g_scope g_item ) , where g_item specifies the item selected, which can be either text or icon. If the user selects an icon value in this field, then `form->field->value` is set to the icon list. You may associate a value or values with these icons by creating a multi-element list with `list`. The first element of this list must be the icon list. The second element may be user-defined data. When the value is set to an icon, you can retrieve the user data from this list. For example: layer1Icon = dlDlistToIcon(...) myIcon = dlDlistToIcon(...) layer1List = list( layer1Icon getLayerId("layer1")) myIconList = list( myIcon list("myIcon" 33) ) .... field = hiCreateCyclicField(?name ’icons ?prompt "Choose one:" ?choices list(layer1List myIconList "red" "yellow") ?value myIconList) In the above example, `form->field->value` contains something like: `((345233 10 10) ("myIcon" 33))` where the first element describes the icon.
`?help` g_fieldHelp	A string or symbol used to reference help. If not specified, s_fieldName is used. This argument is currently not used.
`?font` t_font	A font argument is accepted but is not supported at this time.
`?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`.
`?keepHistory` g_keepHistory
	`t` or `nil`. If you specify `t`, attempts to retain the ?value when choices are changed. The default value is `nil`.

Values Returned

r_fieldHandle

Handle to the cyclic field.

Examples

The following sample displays different types of fields in a form.

;;; creating the list of items in the cyclic field
trCyclicList = '(
   "1" "2" "3" "4" "5" "6" "7" "8" "9" "10" 
   "11" "12" "13" "14" "15" "16" "17" "18" "19" "20" "21" "22" 
   )

;;; creating the cyclic field
trCyclicField = hiCreateCyclicField(
   ?name       'trCyclicField
   ?prompt     "Cycle Through: "
   ?choices    trCyclicList 
   ?value      "3" 
   ?defValue   "7" 
   ?callback   "println" 
   )

;;; creating the boolean button field.
;;; The callback for the trBooleanButton field dynamically retrieves the new value
;;;of the field and embeds it in a message 
trBooleanButton = hiCreateBooleanButton( 
   ?name        'trBooleanButton 
   ?buttonText  "Boolean" 
   ?value        t 
   ?defValue     nil 
   ?callback    "println( hiGetCurrentForm()->trBooleanButton-> value )" 
   )

;;; creating the button box field
trButtonBoxField = hiCreateButtonBoxField( 
   ?name      'trButtonBoxField 
   ?prompt    "Button Box" 
   ?choices   '("Do a" "Do b" "Do c") 
   ?callback  '("println( 'a )" "println( 'b )" "println( 'c)" )
    )

;;; creating the radio field.
;;; The callback for the trConeRadioField field dynamically retrieves the new value
;;; of the field and imbeds it in a message 
trConeRadioField = hiCreateRadioField(
   ?name      'trConeRadioField
   ?prompt    "Cone Size: " 
   ?choices   list( "small" "medium" "large" ) 
   ?value     "small" 
   ?defValue  "large" 
   ?callback  '( "printf(  \"\n%s cone chosen \" hiGetCurrentForm() ->trConeRadioField->value )" )      
   )

;;; creating the scale field
trScaleField = hiCreateScaleField( 
   ?name      'trScaleField 
   ?prompt    "Slide " 
   ?value     500 
   ?defValue  250
   ?callback  "println(\"scale changed \")" 
   ?range     0:750 
   )

;;; creating the label field
trLabelField = hiCreateLabel( 
   ?name           'trLabelField 
   ?labelText      "Label"
   ?justification  CDS_JUSTIFY_RIGHT
   )

;;; creating the form
hiCreateAppForm(
   ?name       'trSampleForm
   ?formTitle   "Sample Form"
   ?callback   "println( 'FormAction )"
   ?fields
      list( 
         trCyclicField
         trBooleanButton
         trButtonBoxField
         trConeRadioField
         trScaleField
         trLabelField
         )
   ?unmapAfterCB   t
   ) ; hiCreateAppForm

;;; displaying the form
hiDisplayForm( trSampleForm )

Cadence User Interface SKILL Reference
Product Version IC23.1, September 2023