hiCreateStringField
hiCreateStringField(
?name s_fieldName
[ ?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 string field entry for a form. Any input typed into this field is surrounded by double quotation marks before being passed to SKILL to interpret.
A string field is a field allowing for typed input. Up to three methods of encouraging the desired format of the typed input may be specified: An initial string can indicate the format of the string to be entered, the prompt can convey the type of response desired, or a format string can be specified which is automatically imposed on any user input.
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
|
|
?prompt t_fieldPrompt
|
|
|
String specifying the prompt for the field. To reference it, use:
formHandle->hiFieldSym->prompt
|
|
?value t_currentValue
|
|
|
Initial and current value of this field. To reference it, use:
formHandle->hiFieldSym->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 set to the initial entry in ?value if this argument is not specified. To reference the value, use:
formHandle->hiFieldSym->defValue
|
|
?font t_font
|
An optional font argument is accepted but is not supported at this time.
|
|
?callback g_callback
|
|
|
A string, function object, or symbol type callback. For type-in fields, the callback is called when the field has “lost focus” (when the cursor leaves the form, the user tabs to another field, and so forth) or when the user selects any button in the form. If you want a callback that is called when the field comes into focus, use the g_focusInCallback argument.
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 of string 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.
|
|
?format t_fieldFormat
|
|
|
Optional string that can control the display of the value on the form. It is similar to printf.
Acceptable format characters are those allowed by the SKILL programming language.
|
|
?editable g_editable
|
|
|
Enables the field for editing.
|
|
?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.
|
|
?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.
|
Value Returned
|
r_fieldHandle
|
Handle to the string field.
|
Examples
Creates string entry for the form.
;****************************************
;Sample form and fields
;****************************************
; Create string entry for the form.
procedure( myformDefineFields()
strfldglb = hiCreateStringField(
?name `strfldglb
?prompt "sample string field" ;;; FIELD1, a string type
?defValue "initial string"
?callback "my_strfldglb_cb()"
?editable t
)
; Create a Boolean button for the form.
boolfldglb = hiCreateBooleanButton(
?name `boolfldglb
?buttonText "sample boolean field" ;;; FIELD2, a boolean type
?defValue t
?callback "my_boolfldglb_cb()"
)
list( strfldglb boolfldglb )
)
; Generate the form
procedure( myformcreateform()
if( !boundp(`myformglb) || (myformglb == nil)
then
myformglb = hiCreateAppForm(
?name `myformglb
?fields myformDefineFields()
?formTitle "My first Form"
?callback "myformglb_cb()"
?buttonLayout `OKCancel
)
)
myformglb
)
; Display the form
procedure( myformdisplayform()
myformcreateform() ;;; Creation and Display are separate
hiDisplayForm(`myformglb)
)
; Check the current state of the form
hiIsFormDisplayed(myformglb) =>nil
myformdisplayform()
hiIsFormDisplayed(myformglb)
=>t
The following sample displays different types of fields in a form.
;;; creating the File Name field
trFileNameField = hiCreateStringField(
?name 'trFileNameField
?prompt "File Name"
?defValue ".cshrc"
?callback "trDoFieldCheckCB( hiGetCurrentForm() )"
?editable t
)
;;; checking if the file exists
procedure( trDoFieldCheckCB( theForm )
if( isFile( theForm->trFileNameField->value )
then
println("File exists")
t
else
println("File Does Not Exist--Try Again")
nil
) ;if
) ; procedure
;;; creating the form
trFileForm = hiCreateAppForm(
?name ’trFileForm
?formTitle "File Form"
?callback ’trFileFormCB
?fields list( trFileNameField )
?unmapAfterCB t
)
procedure( trFileFormCB( theForm )
if( trDoFieldCheckCB( theForm )
then
hiSetCallbackStatus( theForm t )
hiHighlightField( theForm 'trFileNameField 'background )
view( theForm->trFileNameField->value )
else
hiSetCallbackStatus( theForm nil )
hiHighlightField( theForm 'trFileNameField 'highlight )
) ; if
) ; procedure
;;; displaying the form
hiDisplayForm( trFileForm )
Related Topics
hiCreateOutputStringField
Form and Field Functions
Return to top
