Workbench User Guide : 6. Creating and Using Basic Fields : Scalar Fields : Single-line Entry Fields
 
Share this page                  
Single-line Entry Fields
A single-line entry field provides one line on which you can either display information for the end user or let the user enter (or modify) information. To restrict the content of the field, you can set it to any data type. For example, you can create an entry field in which only dates are allowed.
You can also provide a format to control the appearance of the data in the field. For information about setting up a format template, see Data Format Templates.
An entry field does not include a field title or prompt. To include a title or prompt, place free trim next to the field. For more information about creating trim, see Create a Free Trim.
For more information about using entry fields in portable forms, see the Programming Guide.
Create a Single-line Entry Field
You can create a single-line entry field on a form.
To create a single-line entry field
1. Open your frame in the Frame Editor (see Open an Existing Frame).
2. Select the Entry Field - Single Line icon on the field palette.
3. Position the cursor on the form, click, and then drag the cursor to size the entry field.
Note:  Simulate Mode provides an easy way to test the size of a field. You can create a field, switch to Simulate Mode, and enter text of the length that you expect users to enter. The text remains in the field when you switch back to development mode. If the field is too long or too short for the text, you can adjust it, using the text as a guide. To enter Simulate mode, click Tools, Simulate on the floating menu bar.
4. Set the properties for the entry field.
Note:  To resize entry fields, you can use the sizing handles technique described in Move and Resize Fields. Alternatively, modify the values of the corresponding Width or Height properties. Also, you can align an entry field with its corresponding free trim field using any of the various alignment commands on the Layout menu.
For complete descriptions of each field property, see Single-line Entry Field Properties and Common Field Properties.
Single-line Entry Field Properties
All the properties for single-line entry fields are described under Common Field Properties, with the exception of the following properties that are specific to the single-line entry field type:
CharsPerLine
Indicates the number of average-sized characters that a box trim, free trim, or entry field can display, thereby controlling the size of the field.
Note:  This number may differ from that specified for the MaxCharacters property. For example, suppose an entry field's data type is set to varchar(32), CharsPerLine is set to 10, and MaxCharacters to 32. The end user will be able to enter up to 32 characters, but the data in the entry field will scroll. When the entry field contains more characters than are visible, the end user can use the right and left arrow keys, and Home and End, to scroll through the entry field. The user can also insert and delete characters, using the Insert key to switch between overtype and insert mode.
ForceCase
For varchar data, specifies that input always be displayed in uppercase or lowercase, no matter how the end user enters it. Valid options are:
FC_UPPER
FC_LOWER
FC_NONE (no case shift)
Default: FC_NONE
FormatString
Specifies either a data format template or a format string for an entry field used as a table field cell. Valid formats vary, depending on the field's data type. If this property is not set, OpenROAD uses the data type's default format.
Note:  For more information about using various types of data format templates, see Data Format Templates.
InputMasking
Specifies whether an input mask is used to format automatically the data the end user enters. Valid values are:
TRUE
Designates that the field accepts only data that conforms to the data format template specified. (The format template is specified in the FormatString property value cell.)
FALSE
Specifies that the field accepts any data of the appropriate type, regardless of its format
Default: FALSE
Note:  For more information about input masking and using data format templates, see Data Format Templates.
IsMandatory
Specifies whether the end user is required to enter a value in the entry field before leaving it. If the end user never enters this field, this property can be used in conjunction with the CheckFailedMandatory method of the ActiveField class to check for a value.
Possible values are:
TRUE
Specifies that the end user must enter a value in the field before exiting it
FALSE
Specifies that the end user need not enter a value in the field before exiting it
IsMultiLine
Specifies whether an entry field is single- or multiline. Valid value are:
TRUE
Specifies that multiple lines of text can be entered in the entry field
FALSE
Specifies that the Lines property cannot be set to anything but 1. (FALSE is the default setting for single-line entry fields; TRUE is the default setting for multiline entry fields.)
Default: FALSE
IsPassword
Specifies whether text is displayed as the end user enters or edits text in the entry field. Possible values are:
TRUE
Specifies that text is not displayed
FALSE
Specifies that text is displayed
Default: FALSE
Lines
Indicates the number of lines displayed in a single-line entry field
Default: 1
Note:  Do not set this property to 1 to create a single-line entry field. To create a single-line entry field, you must set the IsMultiLine property to FALSE.
MaxCharacters
Specifies the value of MaxCharacters, which by default depends on the data type and the FormatString, and can be limited to a lesser value:
If the data type is Integer, MaxCharacters is 13 because the maximum number of characters for an integer is 13.
If the data type is Varchar(n), MaxCharacters is also n.
Note:  By setting the CharsPerLine property to the value of the MaxCharacters property, you can get an approximate match between the allowable number of characters in the field and the width of the field.
StringValue
Displays the text of the field, exactly as it appears. For multiline entry fields, this property does not include any extra spaces added for word wrap, although it does include hard tabs and newline characters.
TextValue
Displays the first 256 characters of text in the field, exactly as they appear. If this field is an entry field, then this property holds the first 256 characters of data. For multiline entry fields, this property does not include any extra spaces added for word wrap, although it does include hard tabs and newline characters.
If this field is a box trim or free trim field, this property holds the first 256 characters.
UseWidestCharacter
Specifies whether a maximum character width must be used to calculate the field width. This property applies only to entry fields, box trim, and free trim. It is used in conjunction with the CharsPerLine property. Possible values are:
TRUE
Specifies that a maximum character width is used to calculate the field width
FALSE
Specifies that a maximum character width is not used to calculate the field width
WidestCharacterWidth
Specifies the width (in pixels) to use for characters if UseWidestCharacter is set to UWC_USER