hiCreateToggleField

hiCreateToggleField( 
?name s_fieldName 
?choices l_toggleList 
[ ?help g_fieldHelp ] 
[ ?numSelect x_numSelectable ] 
[ ?prompt t_fieldPrompt ] 
[ ?value l_currentValues ] 
[ ?defValue l_defaultValues ]
[ ?itemsPerRow x_itemsPerRow ] 
[ ?font t_font ] 
[ ?enabled g_enabled ]
[ ?invisible g_invisible ]
[ ?callback l_toggleListCallbacks ] 
) 
=> r_fieldHandle

Description

Creates a toggle field entry for a form.

A toggle field may contain several toggle items which default to being displayed in one row. Each toggle item conveys on or off status, or yes or no meaning. A numSelectable argument is optional with toggle fields. This is the maximum number of toggle items that can be simultaneously “turned on.” If numSelectable is set to 1 (implying mutual exclusion), a radio type should be used instead. Each toggle item within the toggle field may specify its own callback.

You can enable/disable toggle items, created using hiCreateToggleField, individually using the following: form – toggle – item – enabled –> t/nil.

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_toggleList
	List of symbol, string, and icon, representing handles to individual toggle items within the field and their prompts. You can specify choice for the toggle field in the following ways: `list(symbol) list(symbol string) list(symbol nil icon) list(symbol string icon)` When you specify a list containing only the symbol for a toggle item, the prompt for the toggle item defaults to the print string of this symbol.
`?help` g_fieldHelp	A string or symbol used to reference help. If not specified, s_fieldName is used. This argument is currently not used.
`?numSelect` x_numSelectable
	Total number of choices (in toggleList) that may be selected at one time. This argument defaults to allowing all items to be selected.
`?prompt` t_fieldPrompt
	String specifying the prompt for the field. To reference it, use: `formHandle->hiFieldSym->prompt`
`?value` l_currentValues
	List where each entry is either `t` or `nil`, representing the on or off value of each choice in toggleList. If currentValues is not specified, this argument defaults to a list in which every entry is `nil`. To reference the current value, use: `formHandle->hiFieldSym->value` For toggle fields, an additional level of values may be obtained. The user may either inquire about all toggle values at once (a list) as shown above, or the value of an individual toggle item: `formHandle->hiFieldSym->toggleItemSym->value` (returns `t` or `nil` for the specified toggle item)
`?defValue` l_defaultValues
	Optional default value of the field. This value is equal to the initial entry in currentValues if defaultValues is not specified. To reference the default value, use: `formHandle->hiFieldSym->defValue`
`?itemsPerRow` x_itemsPerRow
	Row arrangement. This argument is useful for customizing the layout of toggle fields. The items are divided into as many rows as necessary, in row-major order, to accommodate this value. If itemsPerRow is 1, the buttons are arranged in a column. The toolkit imposes restrictions on the geometry allocated to these rows. Although an itemsPerRow value is specified, the toolkit may ignore this layout if it does not make optimum use of screen geometry.
`?font` t_font	An optional 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`.
`?callback` l_toggleListCallbacks
	Optional list of callback strings. If only one callback is specified, it is called for each toggle item, when it changes. If a list is given, the items in the list can be of symbol, string, or function object type. For more information on callback, see Cadence User Interface Callback Routines.

Value Returned

r_fieldHandle

Handle to the toggle field.

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