FreeBSD Manual Pages
XmtCli(3) Library Functions Manual XmtCli(3) NAME XmtCli - a Command Line Interface widget. SYNOPSIS Include File: #include <Xmt/Cli.h> Constructor: XmtCreateCli() XmtCreateScrolledCli() Class Name: XmtCli Class Pointer: xmtCliWidgetClass Class Hierarchy: Core -> XmPrimitive -> XmText -> XmtCli DESCRIPTION The XmtCli widget is a simple subclass of the Motif XmText widget which supports command-line (i.e. terminal-style) interaction between the user and an application. As with most terminal-based interfaces, the user is al- lowed to edit the text on the current line, but may not edit, nor move the cursor to, any previous lines. The Cli widget optionally displays a prompt at the beginning of each new line. The use is not allowed to backspace over this prompt. When the user strikes the Return key, the application is noti- fied (via the XmtNinputCallback) of the line just input, and a new line is begun. Lines are retained by the Cli widget after they scroll off the top of the widget, and the user may review them using the (optional) scrollbar. The XmtNsaveLines resource specifies a minimum number of lines that will be retained; when the number of lines exceeds this number, lines at the top of the buffer will be periodically removed to prevent the widget's memory us- age from growing without bounds. The Cli widget supports command history. By default, pressing the up arrow key will cause the widget to display the previously entered command, and pressing the down arrow key will display the next command. The number of commands saved by the Cli widget is controlled by the XmtNhistoryMaxItems resource. If the XmtNfildes resource is set to a valid file descriptor (generally a pipe or a socket), then the Cli widget will display any text it reads from that socket. Similarly, if the XmtNdisplayStdout or XmtNdisplayStderr re- sources are True then the Cli widget will reroute the stdout and stderr output streams and capture any text sent to those streams. This can be use- ful when porting terminal-based programs to X. RESOURCES Cli inherits the resources of the XmText class, overrides the default of XmNeditMode to XmMULTI_LINE_EDIT, and defines the following new resources: +----------------------------+---------------------+---------------------+--------+-----------+ | Name | Type | Class | Access | Default | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNcliTranslations | XtRTranslationTable | XmtCCliTranslations | CG | NULL | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNdisplayStderr | XtRBoolean | XmtCDisplayStderr | CSG | False | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNdisplayStdout | XtRBoolean | XmtCDisplayStdout | CSG | False | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNescapeNewlines | XtRBoolean | XmtCEscapeNewlines | CSG | True | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNfildes | XtRInt | XmtCFildes | CSG | 1 | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNhistory XmtRStringList | XtCReadOnly | G | NULL | | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNhistoryMaxItems | XtRShort | XmtCHistoryMaxItems | CSG | 50 | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNhistoryNumItems | XtRShort | XmtCHistoryNumItems | CSG | 0 | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNinputCallback | XtRCallback | XtCCallback | C | NULL | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNpageMode | XtRBoolean | XmtCPageMode | CSG | False | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNpageString | XtRString | XmtCPageString | CG | see below | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNpageWidget | XtRWidget | XtCReadOnly | G | NULL | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNprompt | XtRString | XmtCPrompt | CSG | NULL | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNsaveHistory | XtRBoolean | XmtCSaveHistory | CSG | True | +----------------------------+---------------------+---------------------+--------+-----------+ | XmtNsaveLines | XtRShort | XmtCSaveLines | CSG | 64 | +----------------------------+---------------------+---------------------+--------+-----------+ XmtNcliTranslations A translation table that will be used to override the default XmText translations, any translations specified on the XtNtranslations re- source, and the default Cli specific translations. See the ``Trans- lations'' section below for more information. XmtNdisplayStderr Whether this XmtCli widget should display output sent to the stan- dard error stream. If True, the stderr stream will be rerouted so that any output sent to it will appear in the XmtCli widget instead of in the xterm (or other terminal) that invoked the process. If False, the standard error stream will not be rerouted. Because there is only one standard error stream per process, only one XmtCli widget can set this resource True at any time. XmtNdisplayStdout Whether this Cli widget should display output sent to the standard output stream. If True, the stdout stream will be rerouted so that any output sent to it will appear in the Cli widget instead of in the xterm (or other terminal) that invoked the process. If False, the standard output stream will not be rerouted. Because there is only one standard output stream per process, only one Cli widget can set this resource True at any time. XmtNescapeNewlines If True (the default), this resource allows the user to continue long lines onto multiple lines. If this resource is True and the user types a `\' as the last character on the line, then the Cli widget will not call the XmtNinputCallback when the user types the Return key; instead it will just allow the user to continue input on the next line. XmtNfildes A Unix file descriptor. If specified, the Cli widget will display any text that it reads from this descriptor. This file descriptor is usually a pipe established for communication with another process; setting this resource allows a Cli widget to be used to monitor the output of another process. XmtNhistory A read-only array of strings that contain the command history for the Cli widget. You may not set this resource, but you may query the array and modify the strings it contains. XmtNhistoryMaxItems The maximum number of lines of user input that will be saved by the command history mechanism. When more command lines than this have been entered, the oldest lines are overwritten. If you set this re- source, it will cause the XmtNhistory array to be enlarged or shrunk with realloc(). XmtNhistoryNumItems The number of commands that are currently saved by the command his- tory mechanism. XmtNinputCallback A list of callback procedures that will be invoked when the user en- ters a command line. They 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. This in- put string does not include a terminating newline character. XmtNpageMode Whether or not the widget will ``page'' long blocks of output. If this resource is True, then the Cli will simulate a pager like more when more than one page of output is displayed with on intervening input. XmtNpageString The string to be displayed when the Cli widget is paging long out- put. The default is ``- Press Spacebar for More -''. XmtNpageWidget A read-only resource that returns the XmLabel widget used to display the XmtNpageString message. You might use this resource to set the colors of the page message. XmtNprompt The string to be automatically displayed whenever the Cli widget is ready to accept input from the user. XmtNsaveHistory Whether the user's input lines should be saved in the Cli command history buffer. You can set this resource to False to disable the saving of lines, and set it to True to re-enable command line sav- ing. Note that setting this resource to False does not prevent the user from accessing commands already in the XmtNhistory array; it just prevents any new lines from being saved there. XmtNsaveLines The minimum number of lines of text (input or output) that will be saved by the Cli widget for scrolling. When the number of lines ex- ceed this number, the widget will periodically trim the number of saved lines so that memory used by the widget does not grow without bounds. Note that this resource specifies the total number of lines saved, not just the number of lines that are saved once they have scrolled out of view. CALLBACKS The Cli widget supports a single callback list, XmtNinput Callback. The callbacks on this list are called when the user enters a command line (see the end-input() action below). The call_data for this callback is the string entered by the user. TRANSLATIONS The Cli widget inherits an unmodified set of the XmText widget transla- tions. When a Cli 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 re- sources specified with the baseTranslations pseudo resource). This is the same process that all widgets follow to determine their translation table. The Cli widget goes two steps further, however: it overrides this resulting translation table with its own internal set of default Cli-specific trans- lations (shown in the table) and then, finally, overrides these with any resources you (or the end-user) have specified on the XmtNcliTranslations resource. The Cli widget's Cli-specific translation table is the following: !<Key>osfUp: previous-command() !<Key>osfDown: next-command() Shift<Key>osfUp: scroll-backward() Shift<Key>osfDown: scroll-forward() !Shift<Btn1Down>: save-cursor-pos() extend-start() !<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>Return: page-or-end-input() !<Key>osfActivate: page-or-end-input() !<Key>space: page-or-space() These translations bind the Return key to the end-input action, which processes each command line as the user enter them. They bind the up and down arrow keys to the previous-command and next-command actions which im- plement the command history mechanism. The Cli widget does not allow the user to edit anything other than the current line, so these keys are no longer needed for cursor motion. Finally, the translations augment the Xm- Text text selection translations to support xterm-style cut-and-paste: mouse button 2 pastes at the cursor location rather than at the mouse pointer location, and mouse button 3 can be used to extend a selection, in the same way that button 1 can be used with the shift key. The save-cursor- pos and the restore-cursor-pos actions are crucial to allow text to be se- lected without moving the insertion cursor from its position on the current input line. ACTIONS The Cli widget defines ten new action procedures, which are described in the following paragraphs. scroll-forward() scroll-backward() These actions scroll the Cli widget up or down. By default they scroll by half a page. If passed a number as their first argument, they will scroll by that num ber of lines, or if passed the string ``page'' as their first argument, they will scroll by complete pages (where page size depends on the size of the Cli wid get.) previous-command() next-command() These actions implement the Cli command history mecha nism described above. By default they are bound to the up and down arrow keys. emacs users might also want to bind them to Ctrl-P and Ctrl-N, for example. beginning-of-line() This action moves the cursor to the beginning of the current input line. It is used to override the XmText action of the same name, because the XmText widget and the XmtCli widget have different notions of where the beginning of the line is. In the Cli widget, the beginning of the line is the posi- tion immediately fol lowing the prompt, which is generally not the first column of the widget. Furthermore, if the user has typed a lot of input that has wrapped onto more than one line, this action will move to the first input character on first line of that input, not the first character on the current line. Note that this action does not appear in the Cli-spe- cific translation table shown in Table 0-0. Because of the way action proce dures 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 sys- tem. save-cursor-position() restore-cursor-position() These actions are used as a pair at the beginning and end of any sequence of mouse actions that the user is allowed to make. They enforce the rule that the user should not be allowed to move the cursor off the cur rent line of input. Using these actions in conjunction with the standard XmText mouse selection actions allows the user to select text anywhere in the Cli widget by dragging with the mouse, but have the insertion cursor return to its proper place on the current line of input when the selection is com- plete. These actions do allow the cursor to be moved with the mouse within the cur rent line of input; just not off that line. page-or-end-input() page-or-space() These actions are meant to be bound to the Return and Space keys. If the Cli widget is currently paging long output, then these actions implement single-line and full-page paging respectively, and if the widget is not currently paging, then page-or-end-input() calls the end-input() action de- scribed below and the page-or space() action calls the XmText self-insert() action to insert the space character (or whatever character was used to in- voke the action.) end-input() This action tells the Cli widget that the user has entered a line of input. This is the procedure that calls the callbacks on the XmtNinputCallback list or arranges for the XmtCliGets() function to stop blocking and return the input to its caller. Note that this action does not appear in the de- fault translation table, because it is instead invoked through the page or- end-input() action. SEE ALSO Chapter 21, Command Line Input, XmtCliFlush(), XmtCliGets(), XmtCliPrintf(), XmtCliPuts(), XmtCreateCli(), XmtCreateScrolledCli(). Xmt Motif Tools XmtCli(3)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtCli&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>