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 over-
strike 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
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 XmtIN-
PUT_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 in-
put value. If the XmtNbufferSymbolName resource is specified, the In-
putField 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 in-
put 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 regis-
tered 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 perform-
ing an action that is bound to the cancel() action, or implicitly when
the widget looses focus and XmtNfocusOutAction is set to XmtINPUT_CAN-
CEL. 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

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 indepen-
dently.

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 re-
source is unspecified. The default is -1. On some high-end plat-
forms, this may be a valid Pixel value, but the InputField wid-
get treats it as a special value indicating that highlighting
should not be done by changing background color. If this re-
source 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 en-
ter a value that does not match the XmtNpattern resource, is re-
jected by a procedure on the XmtNverifyCallback callback list,
or cannot be converted to the type specified by the XmtNtarget-
SymbolName resource. A procedure on this callback list may pro-
vide 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 re-
source is unspecified. The default is -1. On some high-end plat-
forms, this may be a valid Pixel value, but the InputField wid-
get treats it as a special value indicating that highlighting
should not be done by changing foreground color. If this re-
source 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 XmtIN-
PUT_COMMIT, the value is committed (just as if Return was
pressed). If it is XmtINPUT_CANCEL, the input value is dis-
carded, the widget reverts to the value it had before the edit-
ing was started, and the XmtNcancelCallbacks are called. If it
is XmtINPUT_NONE, no action is taken. The default is XmtIN-
PUT_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 be-
ing displayed on a color screen, then the specified colors will
be used for highlighting. Otherwise, the text will be high-
lighted 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 wid-
get. 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 in-
voked 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 pat-
tern 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 char-
acters 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 be-
low 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 wid-
get. 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 con-
verted in this way. This resource provides automatic type con-
version, 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 re-
jected, 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 con-
taining one character for each character of the desired input string.
Several characters have special meaning and when they occur in the pat-
tern, they control 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 lit-
erals 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 {
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 Xmt-
NerrorCallback 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 when-
ever the user enters a valid value. A value is entered when the
user presses Return, or moves the keyboard focus out of the In-
putField widget, either with the mouse or through keyboard tra-
versal. Note that if the value has not been edited from its pre-
vious value, the callbacks are not called. A valid value is one
that matches the complete XmtNpattern resource, if it is speci-
fied 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 Xmt-
NinputCallback 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 {
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
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 re-
source. If called with the argument ``off'', it will turn overstrike
mode off. If called with no argument, it will toggle the state of over-
strike mode.

If cancel is called, it will perform a cancel action - if the widget
contains an edited value, the edits are discarded, and the XmtNcancel-
Callbacks 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 Xmt-
Layout parent widget, it takes special care to notice when its own sen-
sitivity 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
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.0>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages