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 intended 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 re- store the text in the message line. The MsgLine widget also supports input functions that get input syn- chronously from the user (i.e. they appear to block like gets() and scanf() do.) These functions set the keyboard focus to the MsgLine wid- get, 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 en- tered 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 in- put, 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 inser- tion cursor is not allowed to leave the editable region of the widget. RESOURCES The MsgLine widget inherits the resources of the XmText class, and de- fines 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 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 XmtNal- lowAsyncInput 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 XmN- cursorPositionVisible to True. XmtNinputCallback A list of callback procedures that will be invoked when the user asynchronously enters text into the MsgLine widget. If XmtNal- lowAsyncInput 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 ar- gument 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 XtNtrans- lations resource and the default MsgLine-specific translations. See the ``Translations'' section below for more information. TRANSLATIONS The MsgLine handles translations somewhat differently than other wid- gets do. It inherits an unmodified set of the XmText widget transla- tions. 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 Ms- gLine's new action procedures (described below). For example, the Re- turn 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 stan- dard bindings for the XmText widget: Button3 is used to extend the cur- rent 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 do- ing asynchronous input, this actions causes it to extract the user's input and notify the application by invoking the XmtNin- putCallback 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 in- dication 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 in- sertion 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 in- sertion 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 be- ginning-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 what- ever 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.0>