Using the Editors


Chapter 14 . Data Entry Widgets

Data entry widgets are used to accept and display text or data that the user enters. They also accept data from external sources, like a database or LDB.

In addition, the following widget types function as input devices. These widgets accept data that a user specifies either by selecting an option or by setting a value on the device. They do not allow the user to actually type the data.

This chapter describes:


Defining the Input with Keystroke Filters

The Keystroke Filter property, a property for single line and multiline text widgets and combo boxes, provides a mechanism for validating input, character-by-character, as a user types. In addition, you can define a regular expression that also validates the entire field when the field is exited at runtime. In general, if a user attempts to enter a character that does not match the Keystroke Filter specification for the field, a warning beep sounds, and the character is rejected.

By default, the Keystroke Filter property is set to Unfiltered, meaning that entry of any character is accepted when typed.

How to Define an Input Data Filter for a Selected Widget

Under Input, in the Keystroke Filter property, select the desired filter from the Setting option menu. Possible filters are:

Digits Only Filter

Specifying Digits-only as a filter type:

In general, use this type of data filter for fields requiring no special punctuation or format, or if the input can be variable in length. For example, specify a digits-only filter for a field where a quantity is entered. On the other hand, if you have a field used for entering a number of fixed length and format, like a Social Security number or identification number, consider using an edit mask filter.

How to Embed Special Characters in a Digits-Only Field

You can embed alphabetic characters, punctuation, or special characters in a digits-only field.

  1. Select the data entry widget.
  2. Under Format/Display, enter the format in the Initial Text property.

    For example, an initial text entry of # - - displays in the field at runtime. The user can type numbers without overwriting the punctuation.

Refer to Chapter 10, "Controlling the Way Things Look," for more information on defining the display format.

Yes/No Entries

Specifying Yes-No as a Keystroke Filter setting allows entry of the initial letters of "yes" and "no." This edit uses the initial letters, in upper and lower case, defined in the SM_YES and SM_NO entries in the Panther message file. You can change the message file to support non-English equivalents of Y and N. Refer to "Setting Yes/No Values" in Application Development Guide for details on changing the default values.

By default, all of the following entries are acceptable at runtime: y, Y, n, N, or space, which is converted to n.

Character and Numeric Edits

The alphabetic and numeric keystroke filters let you enforce entry of alphabetic characters, numbers, or a combination of both. In general, these filters are useful for a field that accepts data that can vary in length, like names or titles, or that requires no special punctuation or format.

How to Embed Punctuation or Special Characters, Such as Hyphens, Periods, and Pound Signs (#)

  1. Select the data entry widget.
  2. Under Format/Display, specify the format in the Initial Text property. Refer to "Giving Widgets Initial Data" for details on defining display format.

Panther uses library functions to evaluate alphabetic and numeric input.

For information on how Panther interprets keystroke filters for multilingual applications, refer to "Keystroke Filter Translation" in Application Development Guide.

Alphabetic Edits

Allows only a-z, A-Z, and the space character. Alphabetic filters allow the entry of a variable number of characters. For example, in a Name field, the user can enter any size name, up to the length specified for the field.

Numeric Edits

Allows entry of digits, a plus or minus sign, and one decimal point. If a plus or minus sign is entered, it must be leftmost in the field. When a valid character is entered into the middle of an otherwise empty field, it is rejected (due to the leading/trailing blanks).

Numeric filters are useful when input data must be specified to be positive or negative, or when the data length is not fixed or formatted.

Alphanumeric Edits

Allows entry of any digits, the letters a-z and A-Z, and the space character.

Edit Masks

Edit masks let you:

Panther strips out the display characters, or mask, from the data. Library functions like sm_getfield return data characters only.

How to Define an Edit Mask

  1. Select the data entry widget.
  2. Under Input, set the Keystroke Filter to Edit Mask. The Edit Mask subproperty is displayed.
  3. In the Edit Mask property, type the display and data characters (refer to Table 14-1) required to define the mask.

    Note: If your edit mask includes embedded punctuation, omit the punctuation from other format properties, substring operations, and JPL procedures when validating, comparing, or manipulating the data.

    Table 14-1 Edit mask characters

    Character Name Function

    9

    Digit specification

    X

    Letter specification

    A

    Alphanumeric specification

    *

    asterisk

    Any character

    \

    backslash*

    Causes next character to be treated as a data character

    * To specify a backslash as display text, use two backslashes.

How to Specify a Range or Character/Numeric Restriction with an Edit Mask

  1. Select the data entry widget.
  2. Under Input, set the Keystroke Filter to Edit Mask. The Edit Mask subproperty is displayed.
  3. In the Edit Mask property, enter the display and data characters (refer to Table 14-1) required to define the mask. This filters the data as the user types it.
  4. Under Input, in the Regular Exp property, define an expression (refer to "Regular Expressions" on page 14-7 for details) to check the pattern (for example, numbers between 900 and 999) when the field is exited.

Examples of Edit Masks

Edit Mask Using Data and Display Characters

The following mask represents an 11-character field; seven of the characters are data characters; the letters C, N, pound sign, and hyphen are display characters:

CN#\9\9\9-\9\9\9\9

When the user enters the field, the cursor is positioned on the first data character, in this example, on the first digit position, bypassing the display characters (CN#).

Edit Mask on Widgets with Null Values

If a widget has an edit mask and also has the Null Field property under Format/ Display set to Yes, only the data characters are replaced by the null edit. Consider defining a null text string indicator in the Null Text property (a subproperty of Null Field), such as an asterisk, and set the Repeating property to Yes. This ensures that a field with the edit mask CN#\9\9\9-\9\9\9\9 appears as CN#***-**** when the field is null.

Edit Mask on a Widget with a Data Formatting Property Set to Date/Time

Include the display characters in the edit mask, for instance, as \9\9-\9\9-\9\9. Specify a custom date format in the Format Type property that does not include the special characters—for example, MON2DATE2YR2 as opposed to MON2-DATE2-YR2. This latter specification would result in an invalid date/time format error when the user enters a date value.

Regular Expressions

Regular expressions let you:

The rules for defining a regular expression are the same for both character-level and field-level expressions, except they are stored as different properties.

How to Define a Character-Level Expression

  1. Select the data entry widget.
  2. Under Input, set the Keystroke Filter property to Regular Exp. The Regular Exp subproperty is displayed.
  3. In the Regular Exp property, enter the expression string.

    At runtime, each character is checked against the regular expression as the use types. Invalid input is rejected immediately, and a warning beep is issued. The data is also verified when the field is validated, in the event that the user deleted a character, causing the string to be invalid.

How to Define a Field-Level Expression

Select the data entry widget. Under Input, type the expression string in the Regular Expression property.

At runtime, the content of the field is matched against the regular expression when the field is validated. If the data doesn't match the specified pattern, Panther displays a message (for example, Entry out of range) and the cursor is automatically positioned at the invalid character if the entry does not match the specified pattern.

Examples of Regular Expressions

[0-9]\{3\}-[a-zA-Z0-9]\{3,6\} defines an identification number of three-digits followed by a hyphen, followed by a minimum of three letters or numbers, but no more than six.

[iI][cC][eE] matches ice, icE, iCe, Ice, IcE, ICe, or ICE.

212-[0-9]\{3\}-[0-9]\{4\} matches any phone number having a 212 area code.

[0-9]\{3\}-[0-9]\{2\}-[0-9]\{4\} matches any social security number.

[a-zA-Z_][0-9a-zA-Z_]* matches an identifier in the C programming language.

Constructing Expressions

There are two kinds of rules for constructing a regular expression: one for forming simple expressions, and one for combining expressions into more complex expressions.

Rules for Defining a Simple Expression

The simplest regular expression is a single character, which matches itself. The regular expression z matches the string z. A blank in a regular expression matches a blank in a field. Table 14-2 identifies special characters you can use in constructing a regular expression.

Table 14-2 Special characters used in regular expressions

Character Name Function

\

backslash

Makes any special character, including itself, ordinary. Makes {},() and digits special in certain contexts.

.

dot

Matches any single character, including (but not limited to) itself.

[]

square brackets

Surround a character class expression

*

asterisk

Causes the preceding character class or single character expression to match zero or more occurrences

\( \)

quoted parentheses

Surround an arbitrary subexpression for the purpose of rematching

\1

quoted digits

Rematch a previous expression enclosed in quoted parentheses
\( \)

\{ \}

quoted curly braces

Surround a repeat count to the preceding character class or single character expression

The backslash (\):

Rules for Character Classes

Character classes are a group of characters between brackets ([]). A valid entry matches any of the specified characters within the brackets. For example, the expression [13579] matches any single, odd-digit; the expression [aA] matches an a of either case.

Table 14-3 lists special characters that you can include within a character class when constructing a regular expression.

The following exceptions indicate when a caret, hyphen or bracket stands for itself:

For example, to allow a field to accept any character except ^ (caret), - (hyphen), [ (opening square bracket), ] (closing square bracket, . (dot or period), or \ (backslash), use the following expression:

[^][.\-]
Rules for Combining Two or More Expressions

Put one expression after the other. The entered data must match whatever matches the first expression, followed by whatever matches the next, and so on. Data is matched sequentially with each subexpression.

For example, an expression that comprises the following subexpressions:

[^xXyYzZ][a-z][a-z][a-z][a-z]

accepts any five-letter word that doesn't begin with upper or lower case X, Y, or Z and whose second, third, and fourth letters are lower case characters.

Rules for Defining an Expression with a Repeated Pattern Match

You can define an expression that includes the number of times that the expression, or subexpression, is to be repeated.

Rules for Rematching Subexpressions

You can construct a complex expression using abbreviated syntax. These types of expressions are useful when specific repeated patterns are required as input in a field.

Converting Case

How to Ensure that Data is Entered in the Desired Case

  1. Select the data entry widget.
  2. Under Input, in the Convert Case property, specify the case style:

Controlling What Occurs on Input

For the most part, Input properties control the behavior of the field and not the actual content of the field. These properties apply to those widgets that accept data—single line and multiline text widgets, combo boxes, and, in some cases, scales.

Specifying a Range of Values

A range specification can ensure that a user stays within a specified range when entering data in the selected widget. Any widget that can accept data by user input, including a scale widget, can have a Minimum Value and Maximum Value property specification.

How to Set a Range

  1. Select the data entry widget or scale widget.

    Note: If the data entry widget has a Keystroke Filter property setting of Numeric, the values entered are compared numerically. Otherwise, the values are compared as character strings. For example, a Minimum Value of Martin and a Maximum Value of Mary accept any character string that falls within the specified range—where Marty is a valid entry, but Marilyn is not.

  2. Under Input, enter a value in the Minimum Value property. At runtime, empty fields are considered within the range specification. Scale widgets require both minimum and maximum values; by default, scale widgets have a minimum setting of 0 (zero).

    If you only specify a Minimum Value, then data greater than or equal to the specification are accepted at runtime and empty fields are considered to be within the range.

  3. Under Input, enter a value in the Maximum Value property. At runtime, empty fields are considered within the range specification. Scale widgets require both minimum and maximum values; by default, scale widgets have a maximum setting of 100.

    If you only specify a Maximum Value, then data less than or equal to the specification are accepted at runtime.

Defining Prerequisites or Restrictions on Input Data

The following properties let you define the restrictions or behavior of a field when the user brings focus to that field at runtime.

Required

How to Force Data Entry
  1. Select the data entry widget.
  2. Under Input, set the Required property appropriately:
Rules for Required Data and Null Edits

If the Null Field under Format/Display is set to Yes and the Required property is set to Yes, then the field must be non-null at runtime in order to pass validation. The null indicator string (set in the Null Text property) does not satisfy the requirement for data.

Rules for Data Required in Arrays

For widgets that are arrays, the Required property specifies that data is required only for the number of onscreen occurrences.

Must Fill

How to Ensure that a Field is Filled to its Maximum Length
  1. Select the data entry widget.
  2. Under Input, set the Must Fill property to Yes.

    At runtime, the field is considered valid in either of the following cases:

  3. To ensure that the field is completely filled and not left empty, set both the Must Fill property and the Required property to Yes.

Select on Entry

The Select on Entry property can be useful for:

How to Control if Data is Selected when Tabbing into a Field
  1. Select the data entry widget.
  2. Under Input, set the Select on Entry property appropriately:

Input Protection

By default, text widgets and combo boxes are not protected from data entry; however, you can change the property setting. At runtime, library functions can remove the input protection, while other functions can put data into fields that are protected.

How to Control Whether Data Can be Overwritten
  1. Select the data entry widget.
  2. Under Input, set the Input Protection property:

Protect from Clearing

All data entry and input device widgets (except for option menus which do not have this property) have the Clearing Protect property. You can protect the data in such widgets by setting the property accordingly.

How to Control Whether Existing Data in a Field Can be Cleared
  1. Select the widget.
  2. Under Input, set the Clearing Protect property:

Entering Data on Multiple Lines

Both a single line text widget having an array specification greater than one and a multiline text widget can accept and display multiple lines of text. However, they look different. An arrayed single line text widget displays as a collection of separate widgets, while a multiline text widget's onscreen elements are enclosed within a single border.

For character mode Panther applications, you can define different border styles, a title, and horizontal scroll bars on a multiline text widget.

Refer to "Arrays"in Application Development Guide for more information about using arrays.

Both single line and multiline text widgets can have a greater number of occurrences than can display on the screen. This is referred to as a scrolling array. On a multiline text widget you can include a vertical scroll bar to allow users to view offscreen occurrences.

If the maximum length of the widget is greater than the display length, the widget is referred to as a shifting field. When the Word Wrap property under Format/Display is set to No for a multiline text widget, you can include a horizontal scroll bar on the widget to allow users to view offscreen data. Refer to "Creating Shifting/Scrolling Fields" for more information on defining scrolling/shifting properties and behavior.

In addition, users can view offscreen data by using vertical scroll bars, the right/left arrow keys, or the SHIFT, SCROLL, or ZOOM keys.

Defining a Word Wrap Field

A multiline text widget, by default, accepts and displays data in a word wrap fashion. It is nonshifting and scrollable. As the user types into a multiline field, words shift between occurrences to avoid being split, and large unused portions of occurrences are eliminated. The following properties define a multiline text widget:

In word wrap fields, the following logical keys are available to aid in editing the content:

Mnemonic Long Name Description

WMODE

Wordwrap Mode

toggle control code display

WNL

Hard New Line

hard new line a word wrap field

WTAB

Hard Tab

hard tab in a word wrap field

Note: The ZOOM logical key is not supported if the Word Wrap property is set to Yes for a multiline text widget.

Word Wrap Function

For the most part, word wrap is handled by the native GUI (Motif and Windows specifically). Therefore, word wrapped fields behave as follows:


Using Input Devices

Scales and option menus provide users of your application with the ability to enter data without actually typing the information. Combo boxes provide both a list from which to choose as well as a means of typing data. These input device widgets are particularly useful when you want to provide users with a range or list of choices, but with some restrictions. These devices also occupy a minimal amount of space on a screen, and therefore are useful when conservation of screen real estate is an issue.

Using Scales

A scale widget allows a user to specify a numeric value within a predefined range of values. The scale widget can be horizontal or vertical in position and consists of:

Use the library functions sm_getfield and sm_putfield to retrieve and set a value at runtime.

How to Implement a Scale Widget

  1. Select a scale widget—either horizontal or vertical.
  2. Under Input, set the Minimum and Maximum Value properties to the desired values (refer to "Specifying a Range of Values" for more information).

By default, scales have a minimum value of 0 and a maximum value of 100. The length of the scale is determined by the maximum and minimum values and the number of decimal places you specify.

Note: Vertical widgets always have the lower end of the range at the lower end of the scale.

How to Set the Scale to an Initial Value

  1. Select the scale widget.
  2. Under Input, set the Initial Value property to a value that falls within the minimum and maximum range specifications.

    On screen entry, the scale's slider is positioned to this value and can act as a default.

    Note: If the user chooses the CLR (clear all) or FERA (clear field) keys, the scale resets to its minimum value, as opposed to the initial value specification.

  3. (Optional) To protect the initial value specification from being cleared, under Input, set the Clearing Protect property to Yes.

How to Allow a Decimal Value Specification on the Scale

Using Option Menus and Combo Boxes

Option menus and combo boxes are similar in appearance—each has a text portion and a list portion; however, option menus are protected from data entry, while combo boxes allow users to type into the text portion of the widget.

At runtime, the user can select from these widget types by:

  1. Clicking on the widget's indicator to expand the list of options or, for an option menu, entering the initial character of an item on the list.
  2. With the list expanded, a selection can be made by doing either of the following:

The list of options for these widgets can be populated in two ways:

To determine what selection is made or entered (if a combo box) by the user, use the library function sm_e_getfield.

Populating the List with Constant Data

To Populate an Option Menu or Combo Box List with Static Data
  1. Select or create an option menu or combo box.
  2. Under Identity, specify Constant Data (default) in the Drop-Down Source property.
  3. Select the Drop-Down Data property. The Drop-Down Data dialog box opens.
  4. Enter or edit data by doing any of the following:

In Motif, the drop-down list displays all occurrences to their full length. In character mode and Windows, the list width is determined by the length/width of the option menu widget itself, and therefore, some occurrences may appear truncated.

Defining the Number of Occurrences

For applications running in character mode and Windows, you can define the number of entries that are immediately visible when the user expands an option menu or combo box. This property setting is particularly useful if the data list is extensive or screen space is limited.

Note: In Motif, option menus and combo boxes do not scroll; therefore, the Drop-Down Size property has no effect.

How to Define the Number of Occurrences that Display on an Option Menu or Combo Box (for Windows and Character Mode Applications)

Using Data from an External Source

You can populate an option menu or combo box from an external source, for example, a screen that is dynamically populated from a database. You must also create the external source screen.

How to Populate an Option Menu or Combo Box List from an External Source
  1. Select an option menu or combo box.
  2. Under Identity, specify External Screen in the Drop-Down Source property.
  3. In the Drop-Down Screen property, type the screen name or choose More and select it from the Select Library Member dialog box.

    The screen you specify should consist of a list box (or any other array widget) that can have either a specific or infinite number of occurrences. It can be populated dynamically at runtime from still another source, such as another screen (LDB, local data block) or a database.

  4. Under Identity, in the Initialization subproperty, choose either of the following settings:
How to Create an External Source from a Database Column

Create a screen that holds a database-derived widget that you copied from a repository entry. The screen will contain a simple screen entry function that invokes a VIEW command, and fetches the required data.

  1. Select the widget in the untitled screen.
  2. Under Geometry, set the Array Size property to a number greater than 1.
  3. Under Geometry, set the Scrolling property to Yes.
  4. Set the Max Occurrences subproperty to the number of occurrences to be read in. A blank value allows for an unspecified number of occurrences (the actual maximum number is platform-specific).
  5. Select the screen (click in an empty area of the screen to deselect the widget).
  6. Under Focus, select JPL Procedures. The JPL Program Text dialog box opens.
  7. Type a simple procedure to call a VIEW transaction command, for example:
    proc procedureName
    {
    call sm_tm_command("VIEW")
    }

    Choose FileCloseJPL/Javascript to save the procedure and to return to the Properties window.

  8. Under Focus, type the procedureName in the Entry Function property.
  9. Save the screen (this is the name you provide in your option menu's Drop-Down Screen property).
How to Create an External Source from an LDB (Local Data Block)

Create a screen that holds one widget that has more than one occurrence (list box, multiline text, or single line text with an Array Size property value greater than 1). Refer to "Using Local Data Blocks" in Application Development Guide for more details on using LDBs.

When a widget gets its data from an LDB, the widget on the external screen should be initialized with no data.

Defining Initial Setting

Only the top portion of a combo box and option menu displays when the screen opens at runtime.

How to Define What Displays in the Text Portion of an Option Menu or Combo Box
  1. Select the option menu or combo box.
  2. Under Format/Display, enter the desired text string in the Initial Text property.

The data can be one of the items in the drop-down portion of the widget, and can serve as a default. If you clear the Initial Text property of any text, on entry to the screen, the option menu/combo box will be blank.