NAME

SYNOPSIS

Include File:

#include <Xmt/Cli.h>

Constructor:

XmtCreateCli()
XmtCreateScrolledCli()

Class Name:

XmtCli

Class Pointer:

xmtCliWidgetClass

Class Hierarchy:

Core → XmPrimitive → XmText → XmtCli

DESCRIPTION

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 resources 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 useful 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:

XmtNcliTranslations

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

XmtNdisplayStderr

Whether this XmtCli widget should display output sent to the standard 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 resource, 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 history mechanism.

XmtNinputCallback

A list of callback procedures that will be invoked when the user enters 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 input 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 output. 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 saving. 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 exceed 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 translations. 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 resources 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 translations (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:

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 implement 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 XmText 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 selected 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 position 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-specific 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 system.

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 complete. 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 described below and the page-or space() action calls the XmText self-insert() action to insert the space character (or whatever character was used to invoke 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 default translation table, because it is instead invoked through the page or-end-input() action.

SEE ALSO