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

FreeBSD Manual Pages


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

       XmtMsgLine - a Message Line widget.

       Include File:
	      #include _Xmt/MsgLine.h_


       Class Name:

       Class Pointer:

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

       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

       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.


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

	      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.

	      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.


       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


       The  MsgLine  widget  defines five new actions, used in the translation
       table shown above. They are the following:

	      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.

	      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.


	      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.

	      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.

       Chapter 22, The Message Line,
       XmtCreateMsgLine(), XmtMsgLineAppend, XmtMsgLineClear(),
       XmtMsgLineGetChar(), XmtMsgLineGetString(), XmtMsgLinePrintf(),

Xmt				  Motif	Tools			 XmtMsgLine(3)


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

home | help