FreeBSD Manual Pages

home | help

XmtInputField(3) Library Functions Manual XmtInputField(3)

NAME
XmtInputField - an input field widget.

SYNOPSIS
Include File:
#include <Xmt/InputField.h>

Constructor:
XmtCreateInputField()

Class Name:
XmtInputField

Class Pointer:
xmtInputFieldWidgetClass

Class Hierarchy:
Core -> XmPrimitive -> XmText -> XmtInputField

DESCRIPTION
The XmtInputField widget is a subclass of the Motif XmText widget. It adds
features to the XmText to make it easier to get textual input from the
user, for example in a dialog boxes that require input of various fields of
a database record. Input may be performed in insert or overstrike mode,
which is not possible with the standard XmText widget prior to Motif 1.2.

The InputField widget maintains the user's input value in the XmtNinput re-
source. 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 com-
mitting the value. When the user commits a new value, the procedures regis-
tered 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 ad-
dress 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 re-
jected, or if a pattern is specified, and the input does not match the pat-
tern, 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 wid-
get 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 In-
putField patterns, input verification and error handling.

RESOURCES

XmtNautoDelete
Whether the InputField should automatically delete constant charac-
ters (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 charac-
ters (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 can-
celled.

XmtNerrorBackground
The background color used to highlight bad input when the XmtNhigh-
lightOnError resource is True, when the widget is being displayed on
a color screen, and when the XmtNerrorString resource is unspeci-
fied. 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 con-
verted 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 han-
dling itself.

XmtNerrorForeground
The foreground color used to highlight bad input when the XmtNhigh-
lightOnError resource is True, when the widget is being displayed on
a color screen, and when the XmtNerrorString resource is unspeci-
fied. 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 wid-
get will be displayed with this foreground color until the user tra-
verses 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 dis-
played 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 XmtNcancel-
Callbacks 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 Xmt-
NerrorBackground resources are set, and the widget is being dis-
played on a color screen, then the specified colors will be used for
highlighting. Otherwise, the text will be highlighted by underlin-
ing. The default is False. This resource is only used when Xmt-
NerrorString 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 re-
source returns a string that is owned by the InputField widget and
must not be modified or freed. Note that this differs from the XmN-
value 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 pat-
tern 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 char-
acters to their right, rather than being inserted before those char-
acters. The default is False.

XmtNpattern
The pattern, if any, that the input string must match. If this re-
source 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 spec-
ified type, and if the conversion is successful, will store the con-
verted 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 char-
acters have special meaning and when they occur in the pattern, they con-
trol the category of characters that the user may enter at that position in
the input string. These special characters are the following:
|
Character | Meaning
----------+-------------------------------------------------------------
a | Any; any alphabetic character.
b | Both; any alphabetic character or digit.
c | Character; any character of any sort.
d | Digit; any digit.
o | Octal digit; any digit between 0 and 7.
h | Hexdecimal digit; any digit, or any letter between A and F.
A | Any alphabetic character; converted to uppercase.
B | Both-any alphabetic character or digit; uppercased
C | Any character; converted to uppercase.

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 al-
lowed at the end of the input string. This is because insertions and dele-
tions shift the position of any following characters and can cause a mis-
match 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 call-
back is a pointer to the following structure:

typedef struct {
String value; /* don't change this field, modify or free the string */
Boolean okay; /* set to True to prevent further error handling */
} 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 XmtNerrorCall-
back callback list with the okay field set to False. If a callback proce-
dure 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 com-
plete 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 speci-
fied.

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

typedef struct {
String value; /* this string can be replaced, but not modified or freed */
Boolean okay; /* initially True; set to False if the string is bad */
} 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 applica-
tion. 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 proce-
dures on this list are called before the procedures on the XmtNinputCall-
back 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 over-
strike 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 con-
tains 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 XmtLay-
out 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 Input-
Field is not sensitive.

SEE ALSO
Chapter 28, The Input Field Widget,
XmtCreateInputField(), XmtInputFieldGetString(), XmtInputFieldSetString(),
XmtRegisterInputField().

Xmt Motif Tools XmtInputField(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtInputField&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages