FreeBSD Manual Pages
XmtMsgLine(3) Library Functions Manual XmtMsgLine(3) NAME XmtMsgLine - a Message Line widget. SYNOPSIS Include File: #include <Xmt/MsgLine.h> Constructor: XmtCreateMsgLine() Class Name: XmtMsgLine Class Pointer: xmtMsgLineWidgetClass Class Hierarchy: Core -> XmPrimitive -> XmText -> XmtMsgLine DESCRIPTION The XmtMsgLine widget is a simple subclass of the Motif XmText widget in- tended for displaying simple messages and obtaining simple input from the user. There are functions to clear the message line, display text in the message line, append text to the message line, and save and restore the text in the message line. The MsgLine widget also supports input functions that get input synchro- nously 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 can- cel-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 Re- turn 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. +-------------------------+---------------------+-------------------------+--------+---------+ | Name | Type | Class | Access | Default | +-------------------------+---------------------+-------------------------+--------+---------+ | XmtNallowAsyncInput | XtRBoolean | XmtCAllowAsyncInput | CSG | False | +-------------------------+---------------------+-------------------------+--------+---------+ | XmtNinputCallback | XtRCallback | XtCCallback | C | NULL | +-------------------------+---------------------+-------------------------+--------+---------+ | XmtNmsgLineTranslations | XtRTranslationTable | XmtCMsgLineTranslations | CG | NULL | +-------------------------+---------------------+-------------------------+--------+---------+ XmtNallowAsyncInput Whether or not the MsgLine widget will allow asynchronous input. If this resource is False, then XmNeditable, XmNtraversalOn, and XmN- cursorPositionVisible will be set to False. This means that the Msg- Line 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 asynchro- nous input input is disabled by setting XmtNallowAsyncInput to False, the MsgLine synchronous input functions still work-they tem- porarily 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 XmtNallowA- syncInput 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 call- backs. The input string will not include a terminating newline char- acter. XmtNmsgLineTranslations A translation table that will be used to override the default XmText translations, any translations specified on the XtNtranslations re- source 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: <Key>Return: end-input() <Key>osfCancel: cancel-input() Ctrl<Key>C: cancel-input() Ctrl<Key>G: cancel-input() ~Ctrl Shift ~Meta ~Alt<Btn1Down>: save-cursor-pos() extend-start() ~Ctrl ~Shift ~Meta ~Alt<Btn1Down>: save-cursor-pos() grab-focus() ~Ctrl ~Meta ~Alt<Btn1Motion>: extend-adjust() ~Ctrl ~Meta ~Alt<Btn1Up>: extend-end() restore-cursor-pos() ~Ctrl ~Meta ~Alt<Btn2Down>: copy-primary() ~Ctrl ~Meta ~Alt<Btn3Down>: save-cursor-pos() extend-start() ~Ctrl ~Meta ~Alt<Btn3Motion>: extend-adjust() ~Ctrl ~Meta ~Alt<Btn3Up>: extend-end() restore-cursor-pos() <Key>Tab: self-insert() Some of the translations shown in above are simply bindings for the Msg- Line'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 exam- ple, 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 wid- get and return it to the caller. When the MsgLine is doing asynchro- nous 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 inser- tion cursor. They are intended to be used before and after mouse translations so that the insertion cursor can be moved while select- ing 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 begin- ning-of-line() action. Instead of moving the insertion cursor to the actual beginning of the line, however, it moves it to the first ed- itable 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 Chapter 22, The Message Line, XmtCreateMsgLine(), XmtMsgLineAppend, XmtMsgLineClear(), XmtMsgLineGetChar(), XmtMsgLineGetString(), XmtMsgLinePrintf(), XmtMsgLineSet(). Xmt Motif Tools XmtMsgLine(3)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtMsgLine&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>