hiCreateRadioField
hiCreateRadioField(
?name s_fieldName
?choices l_radioList
[ ?help g_fieldHelp ]
[ ?prompt t_fieldPrompt ]
[ ?value t_currentSelection ]
[ ?defValue t_defaultSelection ]
[ ?itemsPerRow x_itemsPerRow ]
[ ?font t_font ]
[ ?enabled g_enabled ]
[ ?invisible g_invisible ]
[ ?callback l_radioListCallbacks ]
)
=> r_fieldHandle
Description
Creates a radio field for a form.
A radio field contains several radio items which default to being displayed in one row. Each radio item conveys on or off status or yes or no meaning. The items in a radio field are mutually exclusive—no more than one may be set at any time. Each radio item within the radio field may specify its own callback.
If the radio field is instantiated in a one-dimensional form whose width is less than the width of the radio field, the ?itemsPerRow argument is set automatically and is based on the width of the longest ?choices string.
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_radioList
|
|
|
List of either strings or string-icon pairs or both representing the selections that can be made.
These strings or icons appear as the prompts for radio buttons.
A string-icon pair is a list of two items where the first item is a string and the second item is either a string with a valid icon name or an icon list.
|
|
?help g_fieldHelp
|
A string or symbol used to reference help. If not specified, s_fieldName is used. This argument is currently not used.
|
|
?prompt t_fieldPrompt
|
|
|
String specifying the prompt for the field. To reference it, use:
formHandle->hiFieldSym->prompt
|
|
?value t_currentSelection
|
|
|
String of the radio button representing the on value (defaulting to the first, if not specified). Must be a string in l_radioList.
|
|
?defValue t_defaultSelection
|
|
|
Optional default value of the field. This value is equal to the initial entry in currentSelection if defaultSelection is not specified. To reference the default value, use
formHandle->hiFieldSym->defValue
|
|
?itemsPerRow x_itemsPerRow
|
|
|
Optional integer argument specifying the number of toggle items to lay out in one row. 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 single 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_radioListCallbacks
|
|
|
Optional list of user-defined SKILL procedures that are executed when the corresponding item in the radioList is triggered. If only one callback is specified, it is called for each radio item when it is selected. If a list is given, the items in the list can be of symbol, string, or function object type.
|
|
?showTextWithIcon g_showTextWithIcon
|
|
|
Displays both icon and text for the radio button, if l_radioList contains a string-icon pair. The default value of this argument is nil, which means that only an icon is displayed for a radio button for which string-icon pair is specified.
|
Value Returned
|
r_fieldHandle
|
Handle to the radio field.
|
Examples
This example creates a form with a radio option field, myradio, that displays four options: item 1, item 2, item 3, item 4. Option item 2 is grayed out by using the enabledItems property after the form has been created.
(let ((myradiofield (hiCreateRadioField
?name 'myradio ?prompt "myradio" ?value "item 2"
?choices '("item 1" "item 2" "item 3" "item 4"))))
;; disable "item 2"
myradiofield->enabledItems = '(t nil t)
(hiDisplayForm (hiCreateAppForm ?name 'myform ?fields (list myradiofield))))
Related Topics
Form and Field Functions
Creating Context Menus for Fields
Return to top
