NAME

SYNOPSIS

Include File:

#include <Xmt/MsgLine.h>

Constructor:

XmtCreateMsgLine()

Class Name:

XmtMsgLine

Class Pointer:

xmtMsgLineWidgetClass

Class Hierarchy:

Core → XmPrimitive → XmText → XmtMsgLine

DESCRIPTION

The MsgLine widget also supports input functions that get input synchronously from the user (i.e. they appear to block like gets() and scanf() do.) These functions set the keyboard focus to the MsgLine widget, and make the widget ``modal'' in the same way that dialog boxes can be modal. This means that the user can type into the message line regardless of the pointer position, but cannot interact with any other widgets with mouse or keyboard until a string or a character is entered into the message line, or until the input is canceled with Ctrl-C or the osfCancel key (see the cancel-input() action.) Once input is entered or restored, the application's keyboard focus and modality are restored.

Text may also be entered asynchronously into a MsgLine widget, and the functions on the XmtNinputCallback list are invoked when this occurs. This is not a common use of the widget, however, and by default the widget is not editable in this way.

Whether a MsgLine widget is accepting synchronous or asynchronous input, only text typed by the user is editable. Any text output to the widget by the application is uneditable, and once the user enters text with the Return key, that text becomes uneditable as well. The insertion cursor is not allowed to leave the editable region of the widget.

RESOURCES

The MsgLine widget inherits the resources of the XmText class, and defines the following new resources.

XmtNallowAsyncInput

Whether or not the MsgLine widget will allow asynchronous input. If this resource is False, then XmNeditable, XmNtraversalOn, and XmNcursorPositionVisible will be set to False. This means that the MsgLine will not allow keyboard input, will not be part of keyboard navigation, and will not display a cursor. If XmtNallowAsyncInput is True then each of those resources will be made True and the user will be able to type text in the MsgLine at any time. When asynchronous input input is disabled by setting XmtNallowAsyncInput to False, the MsgLine synchronous input functions still work-they temporarily set XmNeditable and XmNcursorPositionVisible to True.

XmtNinputCallback

A list of callback procedures that will be invoked when the user asynchronously enters text into the MsgLine widget. If XmtNallowAsyncInput is True, the callbacks on this list are invoked by the end-input action, which is bound, by default, to the Return key. Any text entered by the user since the last invocation of the end-input action will be passed as the third, call_data argument to the callbacks. The input string will not include a terminating newline character.

XmtNmsgLineTranslations

A translation table that will be used to override the default XmText translations, any translations specified on the XtNtranslations resource and the default MsgLine-specific translations. See the ``Translations'' section below for more information.

TRANSLATIONS

The MsgLine handles translations somewhat differently than other widgets do. It inherits an unmodified set of the XmText widget translations. When a MsgLine widget is created, these default XmText resources are overridden, augmented, or replaced by any resources you (or the end user) specified on the XtNtranslations resource (and, in X11R5, also any resources specified with the baseTranslations pseudo-resource). This is the same process that all widgets follow to determine their translation table. The MsgLine widget goes two steps further, however: it over rides this resulting translation table with its own internal set of default MsgLine-specific translations (shown below) and then, finally, overrides these with any resources you (or the end-user) have specified on the XmtNmsgLineTranslations resource.

These are the default MsgLine translations:

Some of the translations shown in above are simply bindings for the MsgLine's new action procedures (described below). For example, the Return key is use to end input, and the osfCancel, key or Ctrl-C or Ctrl-G are used to cancel input. Other translations modify the cut-and-paste bindings to match the standard bindings for xterm rather than the standard bindings for the XmText widget: Button3 is used to extend the current selection, for example, and Button2 is used to paste the primary selection (at the insertion cursor position, rather than the mouse pointer position). These bindings also ensure that the user can not use the mouse to position the cursor within a prompt or other uneditable text. Finally, notice that the MsgLine widget overrides the single-line XmText widget binding for the TAB key-since the MsgLine is usually used for synchronous input, it does not make sense to use TAB for keyboard traversal.

ACTIONS

The MsgLine widget defines five new actions, used in the translation table shown above. They are the following:

end-input()

When the MsgLine is doing synchronous input, this action causes the synchronous input function to extract the user's input from the widget and return it to the caller. When the MsgLine is doing asynchronous input, this actions causes it to extract the user's input and notify the application by invoking the XmtNinputCallback callback list.

cancel-input()

If the MsgLine is doing synchronous input, this action causes the internal event loop to be terminated, the user's input to be erased, and the synchronous input function to return with an indication that the user canceled the input. If the MsgLine is not doing synchronous input, this action has no effect.

save-cursor-pos()

restore-cursor-pos()

This pair of actions saves and restores the position of the insertion cursor. They are intended to be used before and after mouse translations so that the insertion cursor can be moved while selecting text anywhere in the widget, but so that the insertion cursor is not left in text that the user is not allowed to edit.

beginning-of-line()

This action has the same name as, and overrides, the XmText beginning-of-line() action. Instead of moving the insertion cursor to the actual beginning of the line, however, it moves it to the first editable position; i.e. to the first character after whatever prompt is being displayed. Note that this action does not appear in the translation table shown above. Because of the way action procedures are scoped, the beginning-of-line() binding in the default XmText translation table will refer to this action procedure, and you can invoke it however you normally invoke the beginning-of-line() action on your system.

SEE ALSO