Definition

Define an entry field.

[enabled | disabled] [visible | invisible]

[[color ] COLOR] [password] [required] [autotab]

entry field EF_NAME

size WIDTH HEIGHT at [position] X Y in DB_NAME

[parameter is PAR_STRING]

[helpid is HELP_ID]

[text size TEXT_LIMIT columns]

[font FONT_NAME]

[{left | right | [horizontal] center} align]

[group is GROUP_NAME]

[text TEXT_STRING]

[validation is

{ sysdate [DATE_FORMAT [SEP]

range LOWER UPPER [LOWER UPPER...] ]

| systime [TIME_FORMAT [SEP]

range LOWER UPPER [LOWER UPPER...] ]

| DATE_FORMAT[SEP][range LOWER UPPER [LOWER UPPER...] ]

| TIME_FORMAT[SEP][beforenoon STRING afternoon STRING]

[range LOWER UPPER [LOWER UPPER...] ]

| mask MASK_FORMAT [range LOWER UPPER [LOWER UPPER...] ]

| floatonly [range LOWER UPPER [LOWER UPPER...] ]

| numberonly [range LOWER UPPER [LOWER UPPER...] ]

| range LOWER UPPER [LOWER UPPER...] } ]

enabled | disabled

Define the entry field as selectable or not. If you define it as disabled, it is displayed grayed and cannot be selected. The default is enabled.

visible | invisible

A visible object is displayed when it is defined. An invisible object is not displayed until you specifically make it visible. The default is visible.

color COLOR

A color keyword, a string value representing a color keyword, or an integer value representing a color number corresponding to a color available on your system.

password

Display an asterisk for each character entered into the field.

required

The user must enter at least one non-blank character into the entry field.

autotab

Make the cursor automatically tab to the next dialog object when the user has entered the maximum number of characters.

entry field EF_NAME

The identifier for the entry field you are defining.

size WIDTH HEIGHT

Integer values representing the dimensions of the entry field in dialog units.

at X Y

Integer values representing the position of the entry field in dialog units.

in DB_NAME

The identifier for the dialog box or dialog region parent object.

parameter is PAR_STRING

A string value representing the parameter of the entry field. The default is "".

helpid is HELP_ID

A string or integer value representing the identifier of the help panel you want displayed when the user requests help for this control. This should match the help panel defined in the library specified by the help library declaration. The default is "".

text size TEXT_LIMIT columns

An integer value representing the maximum number of characters that can be entered into the entry field. The default is 32 characters; the maximum is 256.

font FONT_NAME

The name of the font in which you want the TEXT_STRING to appear. You may use either system or ESL fonts. (See the description of the font is Font Reference Definition.) You cannot change the font of a control at runtime.

left | right | [horizontal] center align

Align the text within the entry field as specified; the default is left.

group is GROUP_NAME

An identifier for the group of other dialog box control objects to which the entry field belongs.

text TEXT_STRING

A string value representing the initial value that the entry field will contain. If validation is specified, make sure the text you use follows the validation criteria. The default TEXT_STRING is "".

validation is

Validate this entry field using the specified validation format and optional bounds.

sysdate

Use the date format specified in the control panel when the runtime system is started.

Note that if a range specification is included, DATE_FORMAT specifies the format for the UPPER and LOWER specifications. DATE_FORMAT does not specify the format for accepted dates. That format is specified in the control panel when the runtime system is started.

DATE_FORMAT

One of the following string values representing a date format:

SEP

A one-character separator. If SEP is not specified, a forward slash (/) will be used for date formats, and a colon (:) will be used for time formats.

range

The range of values within a boundary. The user can enter the value of either boundary, but no less than the minimum (LOWER) and no greater than the maximum (UPPER). If you specify more than one range, the input validates successfully if it matches any of the ranges.

LOWER UPPER

Numeric values, quoted string values, or variables representing the minimum and maximum values that the entry field can contain. If you are using variables representing range boundaries, you cannot use variables that have been declared within a subroutine. Values or variables for floatonly must evaluate to floating point numbers. Values or variables for numberonly must evaluate to integers. Note that if you specify a format for a field, LOWER and UPPER must follow that format.

Note that LOWER and UPPER values and variables must evaluate to character strings for the following identifiers: DATE_FORMAT, TIME_FORMAT, MASK, and range LOWER UPPER [LOWER UPPER...] (where it appears alone).

Note that international character support is provided for ranges.

systime

Use the time format specified in the control panel when the runtime system is started.

Note that if a range specification is included, TIME_FORMAT specifies the format for the UPPER and LOWER specifications. TIME_FORMAT does not specify the format for accepted times. That format is specified in the control panel when the runtime system is started.

TIME_FORMAT

One of the following string values representing a time format:

beforenoon STRING afternoon STRING

Up to two characters that represent either before noon or after noon for a 12-hour clock. Use this specification with the hhmmssaa or the hhmmaa format. If you omit this field, the default is AM and PM.

To specify a 24-hour clock (international style), do not select these attributes. Instead, specify the 24-hour clock using the hhmmss or the hhmm format.

mask MASK_FORMAT

A quoted string representing the allowable characters and formatting of the entry field. The MASK_FORMAT string can consist of placeholder and protected characters. Placeholder characters are:

Note that international character support is provided for masks. For example, "ä", "à", "æ", and "ç" are accepted as alphabetic characters satisfying an A placeholder if an extended character set is being used.

If the length of the mask is not equal to the value specified by text size, the length of the mask will be the value used.

floatonly

Allow the entry and validation of floating point numbers. Note that internal representation of float numbers containing fractional parts is not exact, which can introduce a problem when ranges are involved. If the user enters a value that is the lower or upper limit of a floatonly range, they may get an out-of-range error.

numberonly

Allow the entry of integers only.

Description

An entry field is a dialog control and must have a dialog box or dialog region as its parent. Only the entry field keywords, the identifier, the at [position] specification, the size specification, and in DB_NAME are required in the definition.

When specifying attributes, parameter is, alignment, text size, font, helpid is, group is, and text can be specified in any order. In addition, required and autotab may be in either order. All other attributes must be specified in the order shown in the model.

If you have specified a validation is clause, text must be left-aligned.

If you have specified a validation is clause, make sure that the initial text in text TEXT_STRING follows the specified format. If initial text is invalid, you may find unexpected results. This is also true when using the change text action statement. Also note that any unfilled character positions in the mask will be evaluated by ESL as spaces, not as null characters.

You can also specify multiple ranges in the validation is clause.

Values for DATE_FORMAT and TIME_FORMAT within a range should contain separators.

The required keyword represents minimum validation, where the system checks the entry field to ensure if the user has entered at least one non-blank character. Note that you cannot leave a required field using the Tab key or the mouse without entering at least one non-blank character. The required data check is triggered when the user selects a push button with the verify keyword specified. (See the push button definition for setting the validate attribute.)

An entry field definition containing the required keyword and the validation is clause ensures minimum data check along with the validation specified in the validation is clause. However, do not specify required for those entry fields that should be skipped or have optional user input, as required demands entry of at least one non-blank character.

To successfully validate a floatonly entry field, a number must appear on either or both sides of the decimal point. A decimal point alone will not validate.

The decimal separator specified by the user for his or her system is supported in floatonly entry fields for user entry, display of text, and validation. For compatibility, a period may also be used as the decimal separator.

Alternate positive and negative signs are supported for numberonly and floatonly entry fields. A user may enter a leading sign, trailing sign, or parentheses as the sign for a number. For example, the following positive and negative numbers are valid. Positive numbers: 5, +99.5, 500+. Negative numbers: -6.3, 62-, (640.5). Only a single sign character or a single set of parentheses is allowed. Trailing spaces are not allowed. Validation recognizes the alternate signs.

When the text of statement queries the value of a floatonly or numberonly entry field, a user-defined decimal separator is replaced with a period and an alternate sign is replaced with a leading sign to maintain the representation used internally by ESL.

The following accelerators work in entry fields with and without validation masks: Ctrl+Ins for Copy, Shift+Del for Cut, and Shift+Ins for Paste. To copy or cut, you must first select the text with your mouse. If you do not select text first, a copy is ignored and a cut is treated as a d elete. When pasting into a field with a mask, you must first select the text to be replaced. If you do not select text first, or if the selected text is smaller than the pasted text, the system beeps and does not complete the paste. If pasted text does not match a mask size, you receive a beep warning you to edit the field. Protected characters changed by a paste are restored to their correct value.

If you move from an entry field to another control in a dialog box or dialog region, and there is an on validation or on validation failure routine for the entry field, expect the following: if the on validation or on validation failure routine contains a block that is not guarded, and if a response exists in your ESL program for the control to which you moved, the response will be taken; if the routine contains a guarded block, then a response to that control will not be taken.

Entry fields can contain a maximum of 256 characters when filled by a literal string or 32,766 when filled via a variable.

Validation

There are two types of validation:

character-by-character validation

field validation

Character-by-character validation occurs as the user types each character into the entry field. Field validation occurs when the user moves the input focus out of the entry field and into any other control in the dialog box or dialog region, except the Cancel push button.

If the user selects a different application or region while the focus is in the entry field, validation will not be triggered. If the user then returns the focus to the entry field or the Cancel push button, validation will not be triggered. However, if the user returns the focus to a different control, including the OK push button, in the same dialog box or dialog region, validation will occur.

Use the validation is clause to specify the validation criteria. Once set, it functions as a default.

Both masks and ranges support international characters. The mask or range is interpreted according to the character set being used when the program is run. The characters that a mask or range accept are determined by the composition of the character set and the rules that order the character set.

In the insert mode, pressing the backspace key deletes the position to the left of the cursor and erases the contents of that position. In the overstrike mode, pressing the backspace key does not delete the position to the left of the cursor, but it erases the contents of that position.

Masked Entry Fields

All mask characters, except placeholder characters and those enclosed within curly braces, are protected and used only for formatting. The user cannot enter data into a protected character's position in the entry field.

You can define a set of allowable characters for a position in an entry field by enclosing those characters within curly braces. For example, a mask of "{yYnN}" specifies a one-character entry field with a possible value of uppercase or lowercase "y" or "n".

In a masked entry field, pressing the Delete key shifts all characters up to the first protected character in the mask to the left. For example, if the entry field contains "(123)456-7890" and the cursor is on the "1", pressing the Delete key results in "(23 )456-7890".

Masked entry fields operate in insert mode like regular entry fields until there is no more space to enter characters. When there is no space between protected mask characters, ESL automatically switches to overwrite mode. Continuing the previous example, if the cursor is on the "2" and "1" is typed, the result will be "(123)456-7890" because there was a space after the "3". If the next character typed is "8", the result will be "(183)456-7890" because ESL switched into overwrite mode and overwrote the "2".

If an entry field's mask size and text size differ, the mask will be used and a warning issued.

Variables specifying a validation range are evaluated at runtime, not at compile- time.

Note: Within literal strings used as protected characters, use single quotes (' ') to encase characters that also function as placeholders. For example: "NAME: Bob Snow" is represented as "'N' 'A' ME: BBBBBBBB".

Example

string variable Opentime_SV is "09:00AM"

string Lower_SV is "12/01/94"

Upper_SV is "12/31/94"

invisible dialog box TimeTest_DB

. . .

entry field StartTime_EF

size 60 16 at position 6 20 in TimeTest_DB

text "09:00AM"

validation is

hhmmaa ":" beforenoon "AM" afternoon "PM"

range OpenTime "04:30PM"

required autotab entry field Social_Security_Number_EF

size 60 16 at 6 20 in MyDialogBox_DB

text size 11 columns

text "123-45-6789"

validation is mask "DDD-DD-DDDD"

enabled visible entry field DateRange_EF

size 50 10

at position 100 50

in DialogBox1_DB

validation is mmddyy "/" range "12/01/94" "12/31/94"

enabled visible entry field DateRange_EF

size 50 10

at position 100 50

in DialogBox1_DB

validation is mmddyy "/" range Lower Upper

See Also

multi line entry field Definition

push button Definition

response to OBJECT Response Definition