Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XmtCli(3)		   Library Functions Manual		     XmtCli(3)

       XmtCli -	a Command Line Interface widget.

       Include File:
	      #include _Xmt/Cli.h_


       Class Name:

       Class Pointer:

       Class Hierarchy:
	      Core -> XmPrimitive -> XmText -> XmtCli

       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 allowed 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 al-
       lowed  to  backspace over this prompt. When the user strikes the	Return
       key, the	application is notified	(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 usage  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  com-
       mand,  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 XmtNdis-
       playStderr resources are	True then the Cli widget will reroute the std-
       out  and	 stderr	 output	 streams  and  capture	any text sent to those
       streams.	This can be useful when	porting	terminal-based programs	to X.


       Cli inherits the	resources of the XmText	class, overrides  the  default
       of  XmNeditMode to XmMULTI_LINE_EDIT, and defines the following new re-

       |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	    |
	      A	translation table that will be used to	override  the  default
	      XmText translations, any translations specified on the XtNtrans-
	      lations resource,	and the	default	Cli specific translations. See
	      the ``Translations'' section below for more information.

	      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.

	      Whether this Cli widget should display output sent to the	 stan-
	      dard  output stream. If True, the	stdout stream will be rerouted
	      so that any output sent to it will appear	in the Cli widget  in-
	      stead  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

	      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.

	      A	Unix file descriptor. If specified, the	Cli widget  will  dis-
	      play any text that it reads from this descriptor.	 This file de-
	      scriptor 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.

	      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.

	      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 en-
	      larged or	shrunk with realloc().

	      The number of commands that are currently	saved by  the  command
	      history mechanism.

	      A	list of	callback procedures that will be invoked when the user
	      enters a command line. They are invoked by the end-input())  ac-
	      tion,  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.

	      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.

	      The string to be displayed when the Cli widget  is  paging  long
	      output. The default is ``- Press Spacebar	for More -''.

	      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.

	      The string to be automatically displayed whenever	the Cli	widget
	      is ready to accept input from the	user.

	      Whether the user's input lines should be saved in	the  Cli  com-
	      mand  history buffer. You	can set	this resource to False to dis-
	      able the saving of lines,	and set	it to True to  re-enable  com-
	      mand  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.

	      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.


       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.


       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  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, fi-
       nally, 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 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.


       The  Cli	 widget	defines	ten new	action procedures, which are described
       in the following	paragraphs.

       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.)

       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.

       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, be-
       cause 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 in-
       put, 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  in-
       voke the	beginning-of-line() action on your system.

       These  actions  are  used as a pair at the beginning and	end of any se-
       quence 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 in-
       sertion	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.

       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 im-
       plement single-line and full-page paging	respectively, and if the  wid-
       get is not currently paging, then page-or-end-input() calls the end-in-
       put() 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.)

       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 XmtNinput-
       Callback	list or	arranges for the XmtCliGets() function to stop	block-
       ing  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.

       Chapter 21, Command Line	Input,
       XmtCliFlush(), XmtCliGets(), XmtCliPrintf(), XmtCliPuts(),
       XmtCreateCli(), XmtCreateScrolledCli().

Xmt				  Motif	Tools			     XmtCli(3)


Want to link to this manual page? Use this URL:

home | help