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

FreeBSD Manual Pages

  
 
  

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

NAME
       XmtInputField - an input	field widget.

SYNOPSIS
       Include File:
	      #include _Xmt/InputField.h_

       Constructor:
	      XmtCreateInputField()

       Class Name:
	      XmtInputField

       Class Pointer:
	      xmtInputFieldWidgetClass

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

DESCRIPTION
       The  XmtInputField  widget is a subclass	of the Motif XmText widget. It
       adds features to	the XmText to make it easier to	get textual input from
       the  user,  for example in a dialog boxes that require input of various
       fields of a database record. Input may be performed in insert or	 over-
       strike  mode,  which  is	 not  possible with the	standard XmText	widget
       prior to	Motif 1.2.

       The InputField widget maintains the user's input	value in the XmtNinput
       resource. This resource does not	change (as the XmNvalue	resource does)
       as the user types into the field, but only when the user	enters	a  new
       value by	press ing the Return key or, when XmtNfocusOutAction is	XmtIN-
       PUT_COMMIT, by moving the keyboard focus	out of the  widget.   This  is
       referred	to as committing the value. When the user commits a new	value,
       the procedures registered on the	XmtNinputCallback  callback  list  are
       called.

       The InputField widget also supports two other ways of obtaining the in-
       put value. If the XmtNbufferSymbolName resource is specified,  the  In-
       putField	will lookup the	named symbol and store the input string	at the
       specified address. This symbol must be of  type	XmtRBuffer,  and  must
       specify	the  address  and the length of	a character array allocated by
       the application.

       If the XmtNtargetSymbolName resource is specified, the InputField  will
       lookup the named	symbol,	and will attempt to convert the	input value to
       the type	specified for that symbol. If the conversion succeeds, it will
       then  store the converted value at the address specified	by the symbol.
       If the conversion fails,	then the widget	treats the input as an error.

       The XmtNpattern resource	specifies what kind of	input  the  InputField
       widget  will  accept. It	is helpful when	the input, such	as a telephone
       number or a date, requires special formatting and needs to restrict in-
       put to digits, for example.

       When  a	new  value is entered into an InputField widget	(i.e. when the
       value is	going to be committed),	it is passed to	the procedures	regis-
       tered  on the XmtNverifyCallback	callback list. Any of these procedures
       may replace the input with something else, or may reject	 it.   If  the
       input  value  is	 rejected, or if a pattern is specified, and the input
       does not	match the pattern, or if a target type is specified,  and  the
       input  cannot  be  converted  to	 that type, then the InputField	widget
       calls the procedures registered on the XmtNerrorCallback	callback  list
       and  provides  feedback	to  the	 user that an error has	occurred. This
       feedback	can take a number of forms.

       The entry of the	new value can be canceled, either by the user perform-
       ing  an action that is bound to the cancel() action, or implicitly when
       the widget looses focus and XmtNfocusOutAction is set to	 XmtINPUT_CAN-
       CEL.  When this happens,	the widget's value reverts to the value	it had
       before the editing was started.

       See Chapter 28, The Input Field Widget, for more	information on all the
       features	of the InputField widget, and in particular for	information on
       InputField patterns, input verification and error handling.

       RESOURCES

       InputField inherits the resources of the	XmText class, and defines  the
       following  new  resources.  In addition,	it overrides the default value
       for the XmPrimitive XmNnavigationType resource to be XmNONE. This means
       that  traversal is possible between InputField widgets using the	up and
       down arrow keys.

       +---------------------+--------------------------+----------------------+--------+-----------------+
       |Name		     | Type			| Class		       | Access	| Default	  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNautoDelete	     | XtRBoolean		| XmtCAutoDelete       | CSG	| True		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNautoInsert	     | XtRBoolean		| XmtCAutoInsert       | CSG	| True		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNbeepOnError	     | XtRBoolean		| XmtCBeepOnError      | CSG	| True		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNbufferSymbolName | XtRString		| XmtCBufferSymbolName | CSG	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNcancelCallback   | XtRCallback		| XtCCallback	       | C	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNerrorBackground  | XtRPixel			| XmtCErrorBackground  | CSG	| unspecified	  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNerrorCallback    | XtRCallback		| XtCCallback	       | C	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNerrorForeground  | XtRPixel			| XmtCErrorForeground  | CSG	| unspecified	  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNerrorString	     | XtRString		| XmtCErrorString      | CSG	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNfocusOutAction   | XmtRXmtInputFieldActions	| XmtCFocusOutAction   | CSG	| XmtINPUT_COMMIT |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNhighlightOnError | XtRBoolean		| XmtCHighlightOnError | CSG	| False		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNinput	     | XtRString		| XmtCInput	       | CSG	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNinputCallback    | XtRCallback		| XtCCallback	       | C	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNmatchAll	     | XtRBoolean		| XmtCMatchAll	       | CSG	| True		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNoverstrike	     | XtRBoolean		| XmtCOverstrike       | CSG	| False		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNpattern	     | XtRString		| XmtCPattern	       | CSG	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNreplaceOnError   | XtRBoolean		| XmtCReplaceOnError   | CSG	| True		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNtargetSymbolName | XtRString		| XmtCTargetSymbolName | CSG	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       |XmtNverifyCallback   | XtRCallback		| XtCCallback	       | C	| NULL		  |
       +---------------------+--------------------------+----------------------+--------+-----------------+
       XmtNautoDelete
	      Whether the  InputField  should  automatically  delete  constant
	      characters  (such	 as  the parentheses around the	area code in a
	      telephone	number)	that appear in the XmtNpattern	resource.  The
	      default is True.

       XmtNautoInsert
	      Whether  the  InputField	should	automatically  insert constant
	      characters (such as the parentheses around the area  code	 in  a
	      telephone	 number)  that appear in the XmtNpattern resource. The
	      default is True.

       XmtNbeepOnError
	      Whether the InputField should beep when the user	enters	a  bad
	      value.  The  default  is True. Note that this is not the same as
	      the XmText XmNverifyBell resource, which must  be	 set  indepen-
	      dently.

       XmtNbufferSymbolName
	      The  name	 of  an	XmtSymbol with type XmtRBuffer which specifies
	      the address and size of a	character array	into which the	user's
	      input will be stored.

       XmtNcancelCallback
	      A	 list  of procedures to	be invoked when	the new	value entry is
	      cancelled.

       XmtNerrorBackground
	      The background color  used  to  highlight	 bad  input  when  the
	      XmtNhighlightOnError  resource is	True, when the widget is being
	      displayed	on a color screen, and when  the  XmtNerrorString  re-
	      source is	unspecified. The default is -1.	On some	high-end plat-
	      forms, this may be a valid Pixel value, but the InputField  wid-
	      get  treats  it  as a special value indicating that highlighting
	      should not be done by changing background	 color.	 If  this  re-
	      source  is  specified,  the  widget  will	be displayed with this
	      background color until the user traverses	back  to  the  widget,
	      presses Return, or modifies the value in the widget.

       XmtNerrorCallback
	      A	list of	procedures to be invoked when the user attempts	to en-
	      ter a value that does not	match the XmtNpattern resource,	is re-
	      jected  by  a procedure on the XmtNverifyCallback	callback list,
	      or cannot	be converted to	the type specified by the  XmtNtarget-
	      SymbolName  resource. A procedure	on this	callback list may pro-
	      vide a new (presumably error-free) string	to replace the	user's
	      input,  and  may also set	a flag to indicate that	the InputField
	      widget should do no further error	handling itself.

       XmtNerrorForeground
	      The foreground color  used  to  highlight	 bad  input  when  the
	      XmtNhighlightOnError  resource is	True, when the widget is being
	      displayed	on a color screen, and when  the  XmtNerrorString  re-
	      source is	unspecified. The default is -1.	On some	high-end plat-
	      forms, this may be a valid Pixel value, but the InputField  wid-
	      get  treats  it  as a special value indicating that highlighting
	      should not be done by changing foreground	 color.	 If  this  re-
	      source  is  specified,  the  InputField widget will be displayed
	      with this	foreground color until the user	traverses back to  the
	      widget, presses Return, or modifies the value in the widget.

       XmtNerrorString
	      A	 string	to display as feedback when the	user enters an invalid
	      value. The default is NULL. If specified,	this  string  will  be
	      displayed	 until	the user traverses back	to the widget, presses
	      Return, or modifies the value in the widget.

       XmtNfocusOutAction
	      What action should be taken when the widget looses focus	and  a
	      new  value  has  been  entered but not comitted. If it is	XmtIN-
	      PUT_COMMIT, the value  is	 committed  (just  as  if  Return  was
	      pressed).	 If  it	 is  XmtINPUT_CANCEL,  the input value is dis-
	      carded, the widget reverts to the	value it had before the	 edit-
	      ing  was	started, and the XmtNcancelCallbacks are called. If it
	      is XmtINPUT_NONE,	no action is  taken.  The  default  is	XmtIN-
	      PUT_COMMIT.

       XmtNhighlightOnError
	      Whether an invalid input value should be highlighted to bring it
	      to the user's attention.	If either of  the  XmtNerrorForeground
	      or  XmtNerrorBackground resources	are set, and the widget	is be-
	      ing displayed on a color screen, then the	specified colors  will
	      be  used	for  highlighting.  Otherwise,	the text will be high-
	      lighted by underlining.  The default is False. This resource  is
	      only used	when XmtNerrorString is	NULL.

       XmtNinput
	      The  most	 recently  entered  input value. Setting this resource
	      causes the new string to appear in the widget and	to  be	stored
	      in  the  buffer and tar get symbols, if they are specified. This
	      resource is not updated as the user edits	 the  value;  it  only
	      changes  when the	user types Return or traverses out of the wid-
	      get. Querying this resource returns a string that	 is  owned  by
	      the  InputField  widget  and must	not be modified	or freed. Note
	      that this	differs	from the XmNvalue resource of the widget which
	      changes  with  every  keystroke, and which returns a copy	of the
	      current value as a string	that must  be  freed.  If  no  initial
	      value  is	 specified for this resource, and XmtNbufferSymbolName
	      is specified, the	contents of the	buffer are used	as the initial
	      value.

       XmtNinputCallback
	      A	 callback  list	 that  is  invoked when	the XmtNinput resource
	      changes. The procedures on this list are invoked only  when  the
	      user  edits  the value and enters	it by typing the Return	key or
	      by moving	the input focus	out of the widget. They	 are  not  in-
	      voked  if	the user traverses through the widget without changing
	      the value	or strikes the Return key without making any changes.

       XmtNmatchAll
	      Whether an input string must match the entire pattern, if	a pat-
	      tern  is	specified with the XmtNpattern resource. If True, then
	      the input	string must  match  every  character  in  the  pattern
	      string.	If  False,  then  the input string is allowed to match
	      only a prefix of the pattern string. The default is True.

       XmtNoverstrike
	      Whether the InputField widget is in  overstrike  mode.  In  this
	      mode,  characters	inserted in the	middle of the string overwrite
	      the characters to	their right, rather than being inserted	before
	      those characters.	The default is False.

       XmtNpattern
	      The  pattern,  if	any, that the input string must	match. If this
	      resource is set, it specifies the	characters and types of	 char-
	      acters  that  must  appear  at each position in the input. It is
	      useful when the user is to enter data with a fixed format,  such
	      as  a telephone number. See the ``Pattern	Handling'' section be-
	      low for a	description of the pat tern syntax.

       XmtNreplaceOnError
	      Whether an invalid input value will  be  automatically  replaced
	      with the (valid) current value maintained	by the InputField wid-
	      get. The default is True.

       XmtNtargetSymbolName
	      The name of a symbol which specifies the type, address, and size
	      of  an  application  variable. If	specified, the InputField will
	      attempt to convert (using	a resource converter) any input	 value
	      to the specified type, and if the	conversion is successful, will
	      store the	converted value	at the specified address. By  default,
	      no  target  is  specified,  and the input	value will not be con-
	      verted in	this way. This resource	provides automatic  type  con-
	      version, but also	allows the application back-end	to simply read
	      input values from	its own	variables,  without  interacting  with
	      the widget.

       XmtNverifyCallback
	      A	callback list that is invoked in order to test the validity of
	      a	newly entered input value. The procedures  on  this  list  may
	      modify  the  value,  or  they may	reject it. If the value	is re-
	      jected, the callbacks on	the  XmtNinputCallback	list  are  not
	      called.

       Pattern Handling

       If  the XmtNpattern resource is set, it controls	the number and type of
       characters that may be entered into the InputField widget, and may also
       specify	certain	 characters  that are to be automatically inserted and
       deleted as the user types. The XmtNpattern resource is  a  string  con-
       taining	one  character for each	character of the desired input string.
       Several characters have special meaning and when	they occur in the pat-
       tern,  they  control the	category of characters that the	user may enter
       at that position	in the input string. These special characters are  the
       following:
		 |
       Character | Meaning
       ----------+-------------------------------------------------------------
       a	 | Any;	any alphabetic character.
       b	 | Both; any alphabetic	character or digit.
       c	 | Character; any character of any sort.
       d	 | Digit; any digit.
       o	 | Octal digit;	any digit between 0 and	7.
       h	 | Hexdecimal digit; any digit,	or any letter between A	and F.
       A	 | Any alphabetic character; converted to uppercase.
       B	 | Both-any alphabetic character or digit; uppercased
       C	 | Any character; converted to uppercase.

       Any  character in the pattern besides these special characters are lit-
       erals that must appear at the same position in the input	string as they
       do in the pattern.

       When the	XmtNpattern resource is	set, insertions	and deletions are only
       allowed at the end of the input string.	This is	because	insertions and
       deletions  shift	the position of	any following characters and can cause
       a mismatch against the pattern.

       CALLBACKS

       The InputField widget supports the following callback lists:

       XmtNerrorCallback
	      The procedures registered	on this	callback list are called  when
	      the  user	 enters	 an invalid value.  The	call_data argument for
	      this callback is a pointer to the	following structure:

	    typedef struct {

		 String	value;	 /* don't change this field, modify or free the	string */
		 Boolean okay;	 /* set	to True	to prevent further error handling */
	    } XmtInputFieldCallbackStruct;

       The value field points to the invalid input value that caused the error
       callbacks  to  be called. This string is	owned by the InputField	widget
       and should not be modified or freed. The	InputField  invokes  the  Xmt-
       NerrorCallback  callback	 list  with  the okay field set	to False. If a
       callback	procedure sets this field to True, then	the InputField	widget
       will not	perform	any subsequent error handling for the invalid value.

       XmtNinputCallback
	      The procedures registered	on this	callback list are called when-
	      ever the user enters a valid value. A value is entered when  the
	      user  presses Return, or moves the keyboard focus	out of the In-
	      putField widget, either with the mouse or	through	keyboard  tra-
	      versal. Note that	if the value has not been edited from its pre-
	      vious value, the callbacks are not called. A valid value is  one
	      that  matches the	complete XmtNpattern resource, if it is	speci-
	      fied and if XmtNmatchAll is True,	that is	not rejected by	any of
	      the  verify  callbacks,  and that	can be converted to the	target
	      type, if any is specified.  The call_data	argument to  the  Xmt-
	      NinputCallback  is  of  type  char  *,  and is the newly entered
	      value.  This string is owned by the InputField widget  and  must
	      not  be modified or freed	by the application.  The procedures on
	      this callback list are invoked only after	the new	value has been
	      stored in	the buffer and target, if either are specified.

       XmtNverifyCallback
	      The  procedures  on this callback	list are called	as part	of the
	      InputField's error checking procedure.  The  call_data  argument
	      to these procedures is a pointer to the following	structure:

	    typedef struct {

		 String	value;	 /* this string	can be replaced, but not modified or freed */
		 Boolean okay;	 /* initially True; set	to False if the	string is bad */
	    } XmtInputFieldCallbackStruct;

       The value field contains	the newly entered string.  The string is owned
       by the InputField widget, and should not	be modified or	freed  by  the
       application.   A	 callback procedure can	modify the value field itself,
       however,	so that	it points to a different string. If the	value field is
       changed	in  this  way, the InputField widget will make its own private
       copy of the new value and will proceed as if the	user had  entered  the
       new  string  rather  than the string it replaced. The InputField	widget
       invokes the procedures on this list with	the okay field	set  to	 True.
       Any of the procedures on	the list may reject the	input value by setting
       this field to False. Note that the procedures on	this list  are	called
       before the procedures on	the XmtNinputCallback callback list.

       TRANSLATIONS and	ACTIONS

       The  InputField	widget defines two new action procedures: overstrike()
       and cancel().

       If overstrike is	called with the	single argument	``on'',	it  will  turn
       overstrike  mode	 on  for  the widget by	setting	the XmtNoverstrike re-
       source. If called with the argument ``off'', it	will  turn  overstrike
       mode off. If called with	no argument, it	will toggle the	state of over-
       strike mode.

       If cancel is called, it will perform a cancel action -  if  the	widget
       contains	 an edited value, the edits are	discarded, and the XmtNcancel-
       Callbacks are called.

       The InputField widget inherits the translations of the Xm Text  widget,
       and  does  not  add  any	new translations of its	own. In	particular, it
       does not	bind the new overstrike() and cancel() actions to any key.  If
       you  want  to  allow  the  user to be able to switch between insert and
       overstrike modes	in the widget, or cancel inputs, you  must  add	 these
       translations explicitly.

       Sensitivity

       Because the InputField is often used with a caption provided by an Xmt-
       Layout parent widget, it	takes special care to notice when its own sen-
       sitivity	 state changes,	and updates the	XmtNlayoutSensitive constraint
       resource	as necessary so	that any caption will  appear  ``greyed	 out''
       when the	InputField is not sensitive.

SEE ALSO
       Chapter 28, The Input Field Widget,
       XmtCreateInputField(), XmtInputFieldGetString(),
       XmtInputFieldSetString(), XmtRegisterInputField().

Xmt				  Motif	Tools		      XmtInputField(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmtInputField&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help