NAME

SYNOPSIS

Include File:

#include <Xmt/InputField.h>

Constructor:

XmtCreateInputField()

Class Name:

XmtInputField

Class Pointer:

xmtInputFieldWidgetClass

Class Hierarchy:

Core → XmPrimitive → XmText → XmtInputField

DESCRIPTION

The InputField widget maintains the user's input value in the XmtNinput resource. This resource does not change (as the XmNvalue resource does) as the user types into the field, but only when the user enters a new value by press ing the Return key or, when XmtNfocusOutAction is XmtINPUT_COMMIT, by moving the keyboard focus out of the widget. This is referred to as committing the value. When the user commits a new value, the procedures registered on the XmtNinputCallback callback list are called.

The InputField widget also supports two other ways of obtaining the input value. If the XmtNbufferSymbolName resource is specified, the InputField will lookup the named symbol and store the input string at the specified address. This symbol must be of type XmtRBuffer, and must specify the address and the length of a character array allocated by the application.

If the XmtNtargetSymbolName resource is specified, the InputField will lookup the named symbol, and will attempt to convert the input value to the type specified for that symbol. If the conversion succeeds, it will then store the converted value at the address specified by the symbol. If the conversion fails, then the widget treats the input as an error.

The XmtNpattern resource specifies what kind of input the InputField widget will accept. It is helpful when the input, such as a telephone number or a date, requires special formatting and needs to restrict input to digits, for example.

When a new value is entered into an InputField widget (i.e. when the value is going to be committed), it is passed to the procedures registered on the XmtNverifyCallback callback list. Any of these procedures may replace the input with something else, or may reject it. If the input value is rejected, or if a pattern is specified, and the input does not match the pattern, or if a target type is specified, and the input cannot be converted to that type, then the InputField widget calls the procedures registered on the XmtNerrorCallback callback list and provides feedback to the user that an error has occurred. This feedback can take a number of forms.

The entry of the new value can be canceled, either by the user performing an action that is bound to the cancel() action, or implicitly when the widget looses focus and XmtNfocusOutAction is set to XmtINPUT_CANCEL. When this happens, the widget's value reverts to the value it had before the editing was started.

See Chapter 28, The Input Field Widget, for more information on all the features of the InputField widget, and in particular for information on InputField patterns, input verification and error handling.

RESOURCES

InputField inherits the resources of the XmText class, and defines the following new resources. In addition, it overrides the default value for the XmPrimitive XmNnavigationType resource to be XmNONE. This means that traversal is possible between InputField widgets using the up and down arrow keys.

XmtNautoDelete

Whether the InputField should automatically delete constant characters (such as the parentheses around the area code in a telephone number) that appear in the XmtNpattern resource. The default is True.

XmtNautoInsert

Whether the InputField should automatically insert constant characters (such as the parentheses around the area code in a telephone number) that appear in the XmtNpattern resource. The default is True.

XmtNbeepOnError

Whether the InputField should beep when the user enters a bad value. The default is True. Note that this is not the same as the XmText XmNverifyBell resource, which must be set independently.

XmtNbufferSymbolName

The name of an XmtSymbol with type XmtRBuffer which specifies the address and size of a character array into which the user's input will be stored.

XmtNcancelCallback

A list of procedures to be invoked when the new value entry is cancelled.

XmtNerrorBackground

The background color used to highlight bad input when the XmtNhighlightOnError resource is True, when the widget is being displayed on a color screen, and when the XmtNerrorString resource is unspecified. The default is -1. On some high-end platforms, this may be a valid Pixel value, but the InputField widget treats it as a special value indicating that highlighting should not be done by changing background color. If this resource is specified, the widget will be displayed with this background color until the user traverses back to the widget, presses Return, or modifies the value in the widget.

XmtNerrorCallback

A list of procedures to be invoked when the user attempts to enter a value that does not match the XmtNpattern resource, is rejected by a procedure on the XmtNverifyCallback callback list, or cannot be converted to the type specified by the XmtNtargetSymbolName resource. A procedure on this callback list may provide a new (presumably error-free) string to replace the user's input, and may also set a flag to indicate that the InputField widget should do no further error handling itself.

XmtNerrorForeground

The foreground color used to highlight bad input when the XmtNhighlightOnError resource is True, when the widget is being displayed on a color screen, and when the XmtNerrorString resource is unspecified. The default is -1. On some high-end platforms, this may be a valid Pixel value, but the InputField widget treats it as a special value indicating that highlighting should not be done by changing foreground color. If this resource is specified, the InputField widget will be displayed with this foreground color until the user traverses back to the widget, presses Return, or modifies the value in the widget.

XmtNerrorString

A string to display as feedback when the user enters an invalid value. The default is NULL. If specified, this string will be displayed until the user traverses back to the widget, presses Return, or modifies the value in the widget.

XmtNfocusOutAction

What action should be taken when the widget looses focus and a new value has been entered but not comitted. If it is XmtINPUT_COMMIT, the value is committed (just as if Return was pressed). If it is XmtINPUT_CANCEL, the input value is discarded, the widget reverts to the value it had before the editing was started, and the XmtNcancelCallbacks are called. If it is XmtINPUT_NONE, no action is taken. The default is XmtINPUT_COMMIT.

XmtNhighlightOnError

Whether an invalid input value should be highlighted to bring it to the user's attention. If either of the XmtNerrorForeground or XmtNerrorBackground resources are set, and the widget is being displayed on a color screen, then the specified colors will be used for highlighting. Otherwise, the text will be highlighted by underlining. The default is False. This resource is only used when XmtNerrorString is NULL.

XmtNinput

The most recently entered input value. Setting this resource causes the new string to appear in the widget and to be stored in the buffer and tar get symbols, if they are specified. This resource is not updated as the user edits the value; it only changes when the user types Return or traverses out of the widget. Querying this resource returns a string that is owned by the InputField widget and must not be modified or freed. Note that this differs from the XmNvalue resource of the widget which changes with every keystroke, and which returns a copy of the current value as a string that must be freed. If no initial value is specified for this resource, and XmtNbufferSymbolName is specified, the contents of the buffer are used as the initial value.

XmtNinputCallback

A callback list that is invoked when the XmtNinput resource changes. The procedures on this list are invoked only when the user edits the value and enters it by typing the Return key or by moving the input focus out of the widget. They are not invoked if the user traverses through the widget without changing the value or strikes the Return key without making any changes.

XmtNmatchAll

Whether an input string must match the entire pattern, if a pattern is specified with the XmtNpattern resource. If True, then the input string must match every character in the pattern string. If False, then the input string is allowed to match only a prefix of the pattern string. The default is True.

XmtNoverstrike

Whether the InputField widget is in overstrike mode. In this mode, characters inserted in the middle of the string overwrite the characters to their right, rather than being inserted before those characters. The default is False.

XmtNpattern

The pattern, if any, that the input string must match. If this resource is set, it specifies the characters and types of characters that must appear at each position in the input. It is useful when the user is to enter data with a fixed format, such as a telephone number. See the ``Pattern Handling'' section below for a description of the pat tern syntax.

XmtNreplaceOnError

Whether an invalid input value will be automatically replaced with the (valid) current value maintained by the InputField widget. The default is True.

XmtNtargetSymbolName

The name of a symbol which specifies the type, address, and size of an application variable. If specified, the InputField will attempt to convert (using a resource converter) any input value to the specified type, and if the conversion is successful, will store the converted value at the specified address. By default, no target is specified, and the input value will not be converted in this way. This resource provides automatic type conversion, but also allows the application back-end to simply read input values from its own variables, without interacting with the widget.

XmtNverifyCallback

A callback list that is invoked in order to test the validity of a newly entered input value. The procedures on this list may modify the value, or they may reject it. If the value is rejected, the callbacks on the XmtNinputCallback list are not called.

Pattern Handling

If the XmtNpattern resource is set, it controls the number and type of characters that may be entered into the InputField widget, and may also specify certain characters that are to be automatically inserted and deleted as the user types. The XmtNpattern resource is a string containing one character for each character of the desired input string. Several characters have special meaning and when they occur in the pattern, they control the category of characters that the user may enter at that position in the input string. These special characters are the following:

Any character in the pattern besides these special characters are literals that must appear at the same position in the input string as they do in the pattern.

When the XmtNpattern resource is set, insertions and deletions are only allowed at the end of the input string. This is because insertions and deletions shift the position of any following characters and can cause a mismatch against the pattern.

CALLBACKS

The InputField widget supports the following callback lists:

XmtNerrorCallback

The procedures registered on this callback list are called when the user enters an invalid value. The call_data argument for this callback is a pointer to the following structure:

typedef struct {

} XmtInputFieldCallbackStruct;

The value field points to the invalid input value that caused the error callbacks to be called. This string is owned by the InputField widget and should not be modified or freed. The InputField invokes the XmtNerrorCallback callback list with the okay field set to False. If a callback procedure sets this field to True, then the InputField widget will not perform any subsequent error handling for the invalid value.

XmtNinputCallback

The procedures registered on this callback list are called whenever the user enters a valid value. A value is entered when the user presses Return, or moves the keyboard focus out of the InputField widget, either with the mouse or through keyboard traversal. Note that if the value has not been edited from its previous value, the callbacks are not called. A valid value is one that matches the complete XmtNpattern resource, if it is specified and if XmtNmatchAll is True, that is not rejected by any of the verify callbacks, and that can be converted to the target type, if any is specified. The call_data argument to the XmtNinputCallback is of type char *, and is the newly entered value. This string is owned by the InputField widget and must not be modified or freed by the application. The procedures on this callback list are invoked only after the new value has been stored in the buffer and target, if either are specified.

XmtNverifyCallback

The procedures on this callback list are called as part of the InputField's error checking procedure. The call_data argument to these procedures is a pointer to the following structure:

typedef struct {

} XmtInputFieldCallbackStruct;

The value field contains the newly entered string. The string is owned by the InputField widget, and should not be modified or freed by the application. A callback procedure can modify the value field itself, however, so that it points to a different string. If the value field is changed in this way, the InputField widget will make its own private copy of the new value and will proceed as if the user had entered the new string rather than the string it replaced. The InputField widget invokes the procedures on this list with the okay field set to True. Any of the procedures on the list may reject the input value by setting this field to False. Note that the procedures on this list are called before the procedures on the XmtNinputCallback callback list.

TRANSLATIONS and ACTIONS

The InputField widget defines two new action procedures: overstrike() and cancel().

If overstrike is called with the single argument ``on'', it will turn overstrike mode on for the widget by setting the XmtNoverstrike resource. If called with the argument ``off'', it will turn overstrike mode off. If called with no argument, it will toggle the state of overstrike mode.

If cancel is called, it will perform a cancel action - if the widget contains an edited value, the edits are discarded, and the XmtNcancelCallbacks are called.

The InputField widget inherits the translations of the Xm Text widget, and does not add any new translations of its own. In particular, it does not bind the new overstrike() and cancel() actions to any key. If you want to allow the user to be able to switch between insert and overstrike modes in the widget, or cancel inputs, you must add these translations explicitly.

Sensitivity

Because the InputField is often used with a caption provided by an XmtLayout parent widget, it takes special care to notice when its own sensitivity state changes, and updates the XmtNlayoutSensitive constraint resource as necessary so that any caption will appear ``greyed out'' when the InputField is not sensitive.

SEE ALSO