hiCreateComboField

hiCreateComboField(
?name s_fieldName 
?items g_choices
[ ?prompt t_fieldPrompt ] 
[ ?value t_currentValue ]
[ ?help g_fieldHelp ] 
[ ?defValue t_defaultValue ] 
[ ?font t_font ] 
[ ?callback g_callback ]
[ ?modifyCallback g_modifyCallback ]
[ ?focusInCallback g_focusInCallback ]
[ ?format t_fieldFormat ] 
[ ?editable g_editable ]
[ ?enabled g_enabled ]
[ ?invisible g_invisible ]
[ ?nextField g_nextField ]
) 
=> r_fieldHandle

Description

Creates a drop-down combination field, which is a type-in field with an attached drop-down list. Users can either select an item from the list or type in a value.

In addition to the callbacks that can be specified through the arguments listed for this field, you can set a callback to run just before the drop-down list is displayed. This callback can be used to alter the contents of the drop-down list. You can set this callback by setting the hiShowPopupCallback property on the field with the following command:

hiFormHandle-><fieldName>->hiShowPopupCallback=t_value

where hiFormHandle is the handle to the form returned by hiCreateAppForm, hiFieldSymbol is the symbol of the field (set with the ?name argument), and t_value is a string which need to be evaluated just before the drop-down list is displayed.

The combination 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-><fieldName>`
`?items` g_choices	A list of strings that represent the choices in the drop-down list. The default value is `nil`. To reference it, use: `formHandle-><fieldName>->items` A maximum of 42 items are displayed in the drop-down list; if there are more items, a scroll bar appears.
`?prompt` t_fieldPrompt
	A string specifying the prompt for the field. To reference it, use`:` `formHandle-><fieldName>->prompt`
`?value` t_currentValue
	Initial and current value of this field. To reference it, use`:` `formHandle-><fieldName>->value`
`?help` g_fieldHelp	A string or symbol used to reference help. If not specified, s_fieldName is used. This argument is currently not used.
`?defValue` t_defaultValue
	Optional, default value of the field. This value is equal to the initial entry in t_currentValue if t_defaultValue is not specified. To reference the default value, use: `formHandle-><fieldName>->defValue`
`?font` t_font	An optional font argument is accepted but is not supported at this time.
`?callback` g_callback
	A string, symbol, or function object type callback that is executed if the value of the field changes. If a new value was typed in, the callback is called when the field has “lost focus” (for example, when the the user moves the cursor outside the form or tabs to another field) or when the user selects any button in the form. If a new value was selected from the drop-down list, then the callback is called immediately, not when the field loses focus. If the callback is of string type, you can specify one or more SKILL functions or even multiple SKILL statements that should be executed when the value of the field changes.
`?modifyCallback` g_modifyCallback
	SKILL function to be executed whenever any change is made in the text field, for example, by typing a value. The modify callback is called when a change is detected in the field but before the change is displayed. The callback can be of string, symbol, or function object type. A modify callback of symbol or function object type is passed following arguments: < `field modify callback` > ( o_field g_scope t_latestTextValue g_sourceOfChange) , where o_field is the field whose modify callback is triggered, g_scope is where the field is instantiated, t_latestTextValue is the latest text value of the field, and g_sourceOfChange is `t` or `nil, t` indicates that the change was made through the program (by changing the value of the field) and `nil` indicates that the change was made by a user action. The modify callback ofstring type is passed the following arguments: s_fieldName t_latestTextValue g_sourceOfChange where s_fieldName is the symbol of the field in which the change was made, t_latestTextValue is the latest text value of the field, and g_sourceOfChange is `t` or `nil` where `t` indicates that the change was made programmatically (by changing the `value` of the field) and `nil` indicates that the change was made by a user action. The modify callback function should return the following: `t \| nil \| value` If the modify callback function returns `t`, the changes made to the field are allowed and are displayed as they are entered. If the function returns `nil`, the changes made to the field are not allowed and are not displayed—the original value of the field is retained. If the function returns some other value, it must be a string. This value replaces the current value of the field.
`?focusInCallback` g_focusInCallback
	SKILL function to be executed whenever the field comes into focus, specifically when the type-in part of the field comes into focus. This happens either when you click in the type-in part of the field or when you dismiss the drop-down list, which shifts the focus to the type-in part of the field.)The callback can be of string, symbol, or function object type.
`?format` t_fieldFormat
	Optional string that can control the display of the value on the form. It is similar to `printf` and its default value is `"%s"`. Acceptable format characters are those allowed by the SKILL programming language.
`?editable` g_editable
	Enables the field for editiing.
`?enabled` g_enabled
	Specifies whether the field is enabled. The default value is `t`.
`?invisible` g_invisible
	Specifies whether the field is invisible. The default value is `nil`.
`?nextField` g_nextField
	Symbol or string indicating the next field to bring into focus when the `Tab` key is pressed. If you specify `nil` or do not specify this argument, the Tab traversal order is determined by the tabOrderIsAddOrder argument of `hiCreateAppForm` or `hiCreateScrollRegion`. If the tabOrderIsAddOrder argument is not set or if its value is `nil`, the default traversal order is based on the form layout —left-to-right and top-to-bottom— beginning with the field at the top-left corner of the form.

Values Returned

r_fieldHandle

Handle to the drop-down combo field.

Examples

mycombo=(hiCreateComboField ?name 'combo1 ?items '("1" "2" "3" "All")...)
mycombo->insertPolicy = 'InsertAtTop

Additional Information

You can set the insert policy (fieldHandle->insertPolicy=s_insertPolicy) by setting the insertPolicy property on the field object.

s_insertPolicy

Optionally sets the insert policy for items in a combo box.

Accepted values are:

NoInsert: new value cannot be inserted into the items list.
InsertAtTop: new value can be inserted as the first item the items list.
InsertAtBottom: new value can be inserted after the last item in the ?items list.

If the insert policy is not specified, the default is ’NoInsert (for backward compatability). Additionally, in the event of a combo-field value being changed, if the new value is not a member of the ?items list, and the insertPolicy value is either ’InsertAtTop or ’InsertAtBottom, ?items gets updated with the newly added value.

Setting form->combo->insertPolicy to either 'InsertAtTop or 'InsertAtBottom, results in any new value being added to the combo->items list. This also occurs if you enter a new value and select the Cancel button on the form. Here, hiFormCancel still revert the combo->value, but not combo->items.

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