hiCreateMLTextField

hiCreateMLTextField( 
?name s_fieldName 
[ ?prompt t_prompt ] 
[ ?value t_value ] 
[ ?help g_fieldHelp ]
[ ?defValue t_defaultValue ] 
[ ?font t_font ] 
[ ?hasVerticalScrollbar g_hasVerticalScrollbar ]
[ ?hasHorizontalScrollbar g_hasHorizontalScrollbar ]
[ ?enableWordWrap g_enableWordWrap ]
[ ?editable g_editable ]
[ ?enabled g_enabled ]
[ ?invisible g_invisible ]
[ ?callback g_callback ]
[ ?focusInCallback g_focusInCallback ]
[ ?changeCB g_changeCB ]
[ ?nextField g_nextField ] 
) 
=> r_fieldHandle

Description

Creates a multiline text field entry for a form. Any input typed into this field gets converted to a single string accessible through SKILL.

To select the proper size and location of the multiline text field in a form, first select a specific size range for the field, and then use the hiGetTextFieldFit function to find out the pixel size it needs for the specified range.

To create a new line in a multiline text field, the user has to press either Control-Return or Shift-Return. Pressing just the Return key applies the changes indicated in the form. To move to the next tab stop, the user has to press Control-Tab. Pressing just the Tab key moves the cursor to the next field in the form.

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.
?prompt t_prompt	String indicating the prompt for the multiline text field. The prompt is displayed on the left side of the text field.
?value t_value	Indicates the content of the multiline text field. The string can contain the C newline character (’\n’) to indicate an advance to the next logical line. The last logical line may or may not have an ending newline. The maximum length of the string is 8191 bytes. The default value is nil.
?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
	Indicates the default content of the multiline text field. The value of the text field is set to defaultValue if the user clicks the Defaults button on a form.
?font t_font	The font to use in the mutliline text field. It must be nil, causing the font to be derived from the defaults.  The default is determined by the user’s .cdsinit file. If there is no font specified in the user .cdsinit, the fixed font is used. Using a specified font name is not supported.
?hasVerticalScrollbar g_hasVerticalScrollbar
	Indicates if there should be a vertical scroll bar displayed for the multiline text field . The default is to have a vertical scroll bar (t).
?hasHorizontalScrollbar g_hasHorizontalScrollbar
	Indicates if there should be a horizontal scroll bar displayed for this field . The default is to have a horizontal scroll bar (t). If set to t, the word wrapping feature get disabled.
?enableWordWrap g_enableWordWrap
	If this argument is set to t, and there is no horizontal scroll bar for the field, word wrapping occurs. The default is nil. If g_hasHorizontalScrollbar is set to t, the word wrapping feature gets disabled even if you set g_enableWordWrap to t.
?editable g_editable
	Enables the field for editing. The default is t.
?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 g_callback
	SKILL callback to be run when the user exits the text field. You provide this function.
?focusInCallback g_focusInCallback
	SKILL function to be run whenever the field comes into focus. You provide this function.
?changeCB g_changeCB
	SKILL callback to be run when a significant change occurs, for example if the user clicks Enter, pastes a newline, or exits the field after making changes to the text. Programmatic SKILL changes can also trigger this callback. The default 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 multiple-line text field.

Examples

The following sample uses a multiline text field to display the contents of a given file.

procedure( trMoreFile( )
   let( ( fileNameField  fileContentsField theForm )
;;; creating the File Name string field
      fileNameField = hiCreateStringField(
         ?name 'trFileNameField
         ?prompt "File Name"
         ?defValue ".cshrc"
         ?callback "trMoreFileCB( hiGetCurrentForm() 'trFileNameField )"
         )
   
;;; creating the Contents multiline text field for 
;;; viewing the file
       fileContentsField = hiCreateMLTextField(
         ?name 'trMLTextField
         ?prompt "Contents"
         ?defValue ""
         ?editable t  ;; so users can edit the file 
         )

;;; creating the form
      theForm = hiCreateAppForm(
         ?name gensym( 'trMoreFile   ) 
         ?formTitle  "File Browser"
         ?callback  "trMoreFileCB(hiGetCurrentForm() 'apply)"
         ?buttonLayout  'ApplyCancelDef
         ?fields
               list( fileNameField fileContentsField  )
         ) 
      hiDisplayForm( theForm )
      ) ; let
   ) ; procedure

procedure( trMoreFileCB( theForm actionOrField )
   case( actionOrField
      ;;; checking if the file exists
      ( trFileNameField  
         if( isFile( theForm->trFileNameField->value )
            then
               println("File exists")
               t
            else
               println("File Does Not Exist--Try Again")
               nil
            ) ;if
         )
      ( apply 
         when( trMoreFileCB( theForm 'trFileNameField )
            theForm->trMLTextField->value =
               trReadFileIntoString( 
theForm->trFileNameField->value )
            ) ; when
         )
      ( t 
         error( "Illegal action or unknown field: %L" actionOrField )
         )
      ) ; case
   ) ; procedure

;;; The following procedure returns a list of the lines 
;;; in the file in the correct order
procedure( trReadFile( pathname )
   let( ( inPort nextLine allLines )
      inPort = infile( pathname )
      when( inPort = infile( pathname )
         while( gets( nextLine inPort )
            allLines = cons( nextLine allLines )
            ); while
         close( inPort )
         ) ; when
      reverse( allLines )
      ) ; let
   ) ; procedure

;;; reading the entire file into a single string
procedure( trReadFileIntoString( pathname )
   let( ( allLines )
      allLines = trReadFile( pathname )
      when( allLines apply( 'strcat allLines ) )
      ) ; let
   ) ; procedure

To test your file browser:

trMoreFile

After the file browser is displayed, type the name of an existing file and press Apply to view the file.

Related Topics

Form and Field Functions

hiGetTextFieldFit

Creating Context Menus for Fields

Return to top