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

FreeBSD Manual Pages

  
 
  

home | help
dtksh(user cmd)						       dtksh(user cmd)

NAME
       dtksh  -- shell command language	interpreter with access	to many	X, Xt,
       Xm and XCDE functions

SYNOPSIS
       dtksh [-abCefimnuvx]  [-o option]   [+abCefmnuvx]   [+o option]	 [com-
       mand_file  [argument  | ... ] ]

       dtksh  [-abCefimnuvx]   [-o option]   [+abCefmnuvx]  [+o	option]	 [com-
       mand_string]  [command_name  [argument  | ... ] ]

       dtksh [-s]  [-abCefimnuvx]  [-o option]	[+abeCefmnuvx]	 [+o   option]
       [argument  | ...	]

DESCRIPTION
       The dtksh utility is a version of the KornShell extended	to support:

	  o  Access  to	 many  X,  Xt and Motif	facilities from	within a shell
	     script

	  o  Fully localized shell scripts

	  o  Access to the XCDE	application help system

	  o  Customization of script-based GUI attributes (such	 as  font  and
	     colors) using the XCDE customization tool

	  o  Response to session-management Save state directives

	  o  Response to window-management Close directives

	  o  Access to most of the XCDE	Desktop	Services Message Set

	  o  Access to many of the XCDE	Data Typing API	functions

	  o  Access to the XCDE	Action API functions

OPTIONS
       See sh(1).

OPERANDS
       See sh(1).

RESOURCES
       The  dtksh  interpreter has no relevant resources outside of those that
       affect the various widgets that can be instantiated from	within a dtksh
       script. Refer to	the manual page	of the relevant	widget for information
       on the resources	that apply to that widget.

STDIN
       See sh(1).

INPUT FILES
       See sh(1).

ENVIRONMENT VARIABLES
       The following information  describes  the  environment  variables  that
       dtksh  uses that	are in addition	to those documented in the manual page
       for the sh command language interpreter.

   Immediate Return Value (-)
       Many of the category 3 commands (as described in	the Return Values From
       Built-in	 Commands  section) return a single value using	an environment
       variable	specified as the first argument	to the command	(in  the  syn-
       opses for these special commands, the first argument has	the name vari-
       able). If this return value is immediately used in an  expression,  the
       special	environment  variable ``-'' can	be used	in place of a variable
       name. When dtksh	encounters ``-'' as the	name of	the environment	 vari-
       able in which the return	value is to be returned, it returns the	result
       as the value of the command. This allows	the shell script to embed  the
       command call in another command call. (This feature works only for com-
       mands that return a single value; the value is the first	 argument  and
       the argument has	the name variable). For	example:

       XtDisplay DISPLAY $FORM
       XSync $DISPLAY true

       can be replaced by the equivalent:

       XSync $(XtDisplay "-" $FORM) true

       The  reference  to  $DISPLAY is replaced	with the value returned	by the
       call to XtDisplay. This capability is available for all category	3 com-
       mands  except those that	create a widget, those that return more	than a
       single value and	those whose first argument is not named	variable. Com-
       mands  that  do	not  accept ``-'' as the environment variable name in-
       clude:  XtInitialize,   XtCreateApplicationShell,   XtCreatePopupShell,
       XtCreateManagedWidget and XtCreateWidget; all commands of the form:

       XmCreate...()

       and most	commands of the	form:

       tt_...()

   Variables Set By XtInitialize
       The XtInitialize	command	sets the following variables:

       DTKSH_APPNAME DTKSH_ARGV	DTKSH_TOPLEVEL

   Callback Context Variables
       An application registers	a callback with	a widget to specify which con-
       dition it is interested in, and what action should occur	when that con-
       dition occurs.  The action can be any arbitrary dtksh command line. For
       example:

       XtAddCallback $WIDGET activateCallback "ActivateProc"
       XtAddCallback $WIDGET activateCallback "XtSetSensitive $BUTTON false"

       A callback needs	to be passed some context so  it  can  determine  what
       condition led to	its call. For a	C procedure, this information is typi-
       cally passed in a call_data structure. For example, a Scale widget  in-
       voking  a  valueChangedCallback	passes in call_data an instance	of the
       following structure:

       typedef struct {
	       int     reason;
	       XEvent  *event;
	       int     value;
       } XmScaleCallbackStruct;

       The C application's callback does something like:

       if (scaleCallData->reason == XmCR_VALUE_CHANGED)	{
	       eventType = scaleCallData->event->type;
	       display = scaleCallData->event->xany.display;
       }

       Similarly in dtksh, when	a callback is invoked, the  following  special
       environment variables are set up	before the callback command executes:

       CB_WIDGET Set  to  the  widget handle for the widget invoking the call-
		 back.

       CB_CALL_DATA
		 Set to	the address of the call_data structure passed  by  the
		 widget	to the callback, but its usefulness lies in the	nested
		 sub-variables associated with it.

       The CB_CALL_DATA	environment variable represents	a pointer to a	struc-
       ture;  access to	its fields uses	a syntax similar to the	C code.	Nested
       environment variables are defined, named	the same as the	fields of  the
       structure  (but	folded	to  all	upper case), and use a dot to indicate
       containment of an element in a structure. Thus, the preceding  C	 code,
       to access the call_data provided	by the Scale widget, translates	to:

       if [${CB_CALL_DATA.REASON} = "CR_VALUE_CHANGED"]; then
	       eventType=${CB_CALL_DATA.EVENT.TYPE}
	       display=${CB_CALL_DATA.EVENT.XANY.DISPLAY}
       fi

       The same	is true	of the event structure within the call_data structure.

       For most	callback structures, the shell script is able to reference any
       of the fields defined for the particular	callback structure, using  the
       technique  previously described in this manual page. In most cases, the
       shell script is not able	to alter the values of the fields within these
       structures.  The	 exception  to this is the XmTextVerifyCallbackStruct,
       available during	the losingFocusCallback, the modifyVerifyCallback  and
       the  motionVerifyCallback  for  the text	widget.	The dtksh utility sup-
       ports the modification of certain fields	within this structure, to  the
       extent  that  it	is supported by	Motif. The following fields within the
       callback	structure can be modified:

       CB_CALL_DATA.DOIT
       CB_CALL_DATA.STARTPOS
       CB_CALL_DATA.ENDPOS
       CB_CALL_DATA.TEXT.PTR
       CB_CALL_DATA.TEXT.LENGTH
       CB_CALL_DATA.TEXT.FORMAT

       An example of how these fields can be modified:

       CB_CALL_DATA.DOIT="false"
       CB_CALL_DATA.TEXT.PTR="*"
       CB_CALL_DATA.TEXT.LENGTH=1

   Event Handler Context Variables
       As with callbacks, an application registers event handlers with a  wid-
       get  to	specify	 what  action  should  occur when one of the specified
       events occurs.  Again, the action can be	any  arbitrary	dtksh  command
       line.  For example:

       XtAddEventHandler $W "Button2MotionMask"	false "ActivateProc"
       XtAddEventHandler $W "ButtonPressMask|ButtonReleaseMask"		false "echo action"

       Just  as	 with callbacks, two environment variables are defined to pro-
       vide context to the event handler:

       EH_WIDGET Set to	the widget handle for the widget for which  the	 event
		 handler is registered.

       EH_EVENT	 Set  to  the  address	of the XEvent that triggered the event
		 handler.

       Access to the fields within the XEvent structure	is the same as for the
       CB_CALL_DATA  environment  variable previously described	in this	manual
       page. For example:

       if [${EH_EVENT.TYPE} = "ButtonPress"]; then
	       echo X =	${EH_EVENT.XBUTTON.X}
	       echo Y =	${EH_EVENT.XBUTTON.Y}
       elif [${EH_EVENT.TYPE} =	"KeyPress"]; then
	       echo X =	${EH_EVENT.XKEY.X}
	       echo Y =	${EH_EVENT.XKEY.Y}
       fi

   Translation Context Variables
       Xt provides for event translations to be	registered for a widget; their
       context	is  provided  in  the same way as with event handlers. The two
       variables defined for translation commands are:

       TRANSLATION_WIDGET
		 Set to	the widget handle for the widget for which the	trans-
		 lation	is registered.

       TRANSLATION_EVENT
		 Set  to the address of	the XEvent that	triggered the transla-
		 tion.

       Dot-notation provides access to the fields of the event:

       echo Event type = ${TRANSLATION_EVENT.TYPE}
       echo Display = ${TRANSLATION_EVENT.XANY.DISPLAY}

   Workspace Callback Context Variables
       An application can register a callback function	that  is  invoked  any
       time the	user changes to	a new workspace. When the callback is invoked,
       the following two special environment variables are set,	and can	be ac-
       cessed by the shell callback code:

       CB_WIDGET Set  to  the  widget handle for the widget invoking the call-
		 back.

       CB_CALL_DATA
		 Set to	the X atom that	uniquely identifies the	new workspace.
		 This  can be converted	to its string representation using the
		 XmGetAtomName command.

   Accessing Event Subfields
       The XEvent structure has	many different	configurations	based  on  the
       event's	type.  The dtksh utility provides access only to the most fre-
       quently used XEvents. Any of the	other standard	XEvents	 are  accessed
       using  the event	type XANY, followed by any of the subfields defined by
       the XANY	event structure, which includes	the following subfields:

       ${TRANSLATION_EVENT.XANY.TYPE}
       ${TRANSLATION_EVENT.XANY.SERIAL}
       ${TRANSLATION_EVENT.XANY.SEND_EVENT}
       ${TRANSLATION_EVENT.XANY.DISPLAY}
       ${TRANSLATION_EVENT.XANY.WINDOW}

       The dtksh utility supports full access to all of	the event  fields  for
       the following event types:##

       XANY
       XBUTTON
       XEXPOSE
       XNOEXPOSE
       XGRAPHICSEXPOSE
       XKEY
       XMOTION

       The following examples show how the subfields for the previously	listed
       event types are accessed:

       ${TRANSLATION_EVENT.XBUTTON.X}
       $(CB_CALL_DATA.EVENT.XKEY.STATE}
       ${EH_EVENT.XGRAPHICSEXPOSE.WIDTH}

   Input Context Variables
       Xt provides the XtAddInput(3) facility that allows  an  application  to
       register	 interest  in  activity	on a particular	file descriptor.  This
       generally includes data available for reading, the file descriptor  be-
       ing  ready  for writing,	and exceptions on the file descriptor. If pro-
       gramming	in C, the application provides a handler function that is  in-
       voked  when  the	 activity  occurs. When	reading	data from the file de-
       scriptor, it is up to the handler to  read  the	data  from  the	 input
       source and handle character escaping and	line continuations.

       The  dtksh  utility  also  supports the XtAddInput(3) facility, but has
       limited its functionality to reading data, and has  taken  the  reading
       function	a step further to make it easier for shell programmers to use.
       By default, when	a shell	script registers interest in a	file  descrip-
       tor,  dtksh  invokes  the shell script's	input handler only when	a com-
       plete line of text has been received. A complete	line of	 text  is  de-
       fined  to be a line terminated either by	an unescaped <newline> charac-
       ter, or by end-of-file. The input handler is also called	if no data  is
       available and end-of-file is reached. This gives	the handler the	oppor-
       tunity to use XtRemoveInput(3) to remove	the input source, and to close
       the file	descriptor.

       The  advantage  of  this	default	behavior is that input handlers	do not
       need to do escape processing or handle line continuations.  The	disad-
       vantage	is  that it assumes that all of	the input is line-oriented and
       contains	no binary information. If the input source does	contain	binary
       information,  or	 if  the input handler wants to	read the data from the
       input source directly, dtksh also supports a raw	 input	mode.  In  raw
       mode,  dtksh  does  not read any	of the data from the input source. Any
       time dtksh is notified that input is available on the input source,  it
       invokes the shell script's input	handler. It then becomes the handler's
       responsibility to read the  incoming  data,  to	perform	 any  required
       buffering  and  escape  processing,  and	 to detect when	end-of-file is
       reached (so that	the input source can be	removed	and the	file  descrip-
       tor closed).

       Whether	the input handler is configured	to operate in the default mode
       or in raw mode, dtksh sets  up  several	environment  variables	before
       calling	the  shell script's input handler. These environment variables
       provide the input handler with everything needed	to handle the incoming
       data:

       INPUT_LINE
		 If  operating in the default mode, this variable contains the
		 next complete line of input available from the	input  source.
		 If INPUT_EOF is set to	True, there is no data in this buffer.
		 If operating in raw mode, this	 environment  variable	always
		 contains an empty string.

       INPUT_EOF If  operating	in  the	 default mode, this variable is	set to
		 False any time	INPUT_LINE contains data, and is set  to  True
		 when end-of-file is reached. When end-of-file is reached, the
		 input handler for the shell script should unregister the  in-
		 put  source  and  close the file descriptor.  If operating in
		 raw mode, INPUT_EOF is	always set to False.

       INPUT_SOURCE
		 Indicates the file descriptor for which input	is  available.
		 If operating in raw mode, this	file descriptor	is used	to ob-
		 tain the pending input. The file descriptor is	also  used  to
		 close the input source	when it	is no longer needed.

       INPUT_ID	 Indicates the ID returned by XtAddInput when the input	source
		 was originally	registered. This information is	needed in  or-
		 der to	remove the input source	using XtRemoveInput.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       See sh(1).

STDERR
       See sh(1).

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       The  capabilities described here	are extensions to those	of the sh com-
       mand language interpreter. See  sh(1). The following subsections	give a
       synopsis	of each	of the built-in	commands added by dtksh	to sh. In gen-
       eral, argument ordering and types are the same as for  corresponding  C
       procedures, with	exceptions noted. For more detail on the functionality
       and arguments of	a command, see the standard documentation for the cor-
       responding X11, Xt, Motif or Desktop Services procedure.

       In definitions listed in	this document, arguments named variable, vari-
       able2, variable3	and so on, indicate that the shell script must	supply
       the name	of an environment variable, into which some value is returned.

       All  of	the  Xt	 commands used to create a new widget require that the
       widget class for	the new	widget be specified. The  widget  (or  gadget)
       class  name  is the standard class name provided	by Motif. For example,
       the class name for a Motif pushbutton widget is XmPushButton, while the
       class  name  for	the Motif label	gadget is XmLabelGadget. Commands that
       use their exit status to	return a Boolean value (which can be used  di-
       rectly as part of an if statement) are noted as such.

       Arguments enclosed within [] are	optional.

   Dtksh Built-in Xlib Commands
       XBell [display volume]

       XClearArea  [display  drawable]	 [optional  GC	arguments]  [x y width
       height exposures]

       XClearWindow [display drawable]

       XCopyArea [display src dest srcX	srcY width height destX	 destY]	  [op-
       tional GC arguments]

       XDefineCursor [display window cursor]

       XDrawArc	[display drawable]  [optional GC arguments]  [x	y width	height
       angle1 angle2]

       XDrawLine [display drawable]  [optional GC arguments]  [x1 y1 x2	y2]

       XDrawLines [display drawable]  [-coordinateMode]	  [optional  GC	 argu-
       ments]  [x1 y1 x2 y2]  [x3 y3 ...]

       The coordinateMode operand is either CoordModeOrigin or CoordModePrevi-
       ous.

       XDrawPoint [display drawable]  [optional	GC arguments]  [x y]

       XDrawPoints [display drawable]  [-coordinateMode]  [optional  GC	 argu-
       ments]  [x1 y1]	[x2 y2 x3 y3 ...]

       The coordinateMode operand is either CoordModeOrigin or CoordModePrevi-
       ous.

       XDrawRectangle [display drawable]  [optional GC arguments]  [x y	 width
       height]

       XDrawSegments  [display	drawable]   [optional GC arguments]  [x1 y1 x2
       y2]  [x3	y3 x4 y4 ...]

       XDrawString [display drawable]  [optional GC arguments]	[x y string]

       XDrawImageString	[display drawable]   [optional	GC  arguments]	 [x  y
       string]

       XFillArc	[display drawable]  [optional GC arguments]  [x	y width	height
       angle1 angle2]

       XFillPolygon [display drawable]	[-shape]  [-coordinateMode]  [optional
       GC arguments]  [x1 y1 x2	y2 ...]

       The shape operand is one	of Complex, Convex or Nonconvex, and where co-
       ordinateMode is either CoordModeOrigin or CoordModePrevious.

       XFillRectangle [display drawable]  [optional GC arguments]  [x y	 width
       height]

       XFlush [display]

       XHeightOfScreen [variable screen]

       XRaiseWindow [display window]

       XRootWindowOfScreen [variable screen]

       XSync [display discard]

       The discard operand is either True or False.

       XTextWidth [variable fontName string]

       The  XTextWidth command differs from the	C procedure; it	takes the name
       of a font instead of a pointer to a font	structure.

       XUndefineCursor [display	window]

       XWidthOfScreen [variable	screen]

   Built-in XtIntrinsic	Commands
       XtAddCallback [widgetHandle callbackName	dtksh-command]

       The callbackName	operand	is one of the standard Motif  or  Xt  callback
       names, with the Xt or Xm	prefix omitted;	for example, activateCallback.

       XtAddEventHandler  [widgetHandle	 eventMask  nonMaskableFlag dtksh-com-
       mand]

       The eventMask operand is	of the form mask| mask|	mask and the mask com-
       ponent is any of	the standard set of XEvent masks; for example, Button-
       PressMask, where	nonMaskableFlag	is either True or False.

       XtAddInput [variable]  [-r]  [fileDescriptor dtksh-command]

       The XtAddInput command registers	the indicated file descriptor with the
       X  Toolkit  as  an alternative input source (that is, for reading). The
       input handler for the shell script is responsible for unregistering the
       input  source  when  it is no longer needed, and	also to	close the file
       descriptor. If the -r option is specified (raw mode),  dtksh  does  not
       automatically  read any of the data available from the input source; it
       is up to	the specified dtksh command to read all	data. If the -r	option
       is  not	specified,  the	specified dtksh	command	is invoked only	when a
       full line has been read (that is, a line	terminated by  either  an  un-
       escaped	<newline>  character,  or end-of-file) and when	end-of-file is
       reached.	The raw	mode is	useful for handlers expecting to process  non-
       textual	data,  or for handlers not wanting dtksh to automatically read
       in a line of data. When end-of-file is detected,	it is the responsibil-
       ity  of	the input handler for the shell	script to use XtRemoveInput to
       remove the input	source,	and to close the file  descriptor,  if	neces-
       sary.  In  all  cases, several environment variables are	set up for the
       handler to use. These include the following:

       INPUT_LINE
		 Empty if raw mode; otherwise, contains	next line to  be  pro-
		 cessed.

       INPUT_EOF Set to	True if	end-of-file reached; otherwise,	set to False.

       INPUT_SOURCE
		 File descriptor associated with this input source.

       INPUT_ID	 ID  associated	 with this input handler; returned by XtAddIn-
		 put.

       XtAddTimeout [variable interval dtksh-command]

       XtAddWorkProc [variable dtksh-command]

       In dtksh, the dtksh-command is typically	a dtksh	 function  name.  Like
       regular	work  procedures,  this	function is expected to	return a value
       indicating whether the work procedure wants  to	be  called  again,  or
       whether	it  has	 completed  its	work and can be	automatically unregis-
       tered. If the dtksh function returns zero, the work  procedure  remains
       registered;  any	 other value causes the	work procedure to be automati-
       cally unregistered.

       XtAugmentTranslations [widgetHandle translations]

       XtCreateApplicationShell	[variable applicationName  widgetClass]	  [re-
       source:value ...]

       XtCallCallbacks [widgetHandle callbackName]

       The  callbackName  operand  is one of the standard Motif	or Xt callback
       names, with the Xt or Xm	prefix omitted;	for example, activateCallback.

       XtClass [variable widgetHandle]

       The command returns the name of the widget class	 associated  with  the
       passed-in widget	handle.

       XtCreateManagedWidget  [variable	 widgetName widgetClass	parentWidgetH-
       andle]  [resource:value ...]

       XtCreatePopupShell [variable widgetName widgetClass parentWidgetHandle]
       [resource:value ...]

       XtCreateWidget  [variable  widgetName  widgetClass  parentWidgetHandle]
       [resource:value ...]

       XtDestroyWidget [widgetHandle]  [widgetHandle ...]

       XtDisplay [variable widgetHandle]

       XtDisplayOfObject [variable widgetHandle]

       XtGetValues [widgetHandle resource:variable1]  [resource:variable2 ...]

       XtHasCallbacks [variable	widgetHandle callbackName]

       The callbackName	operand	is one of the standard Motif  or  Xt  callback
       names,  with the	Xt or Xm prefix	omitted: for example, activateCallback
       variable	is set to one of the strings  CallbackNoList,  CallbackHasNone
       or CallbackHasSome.

       XtInitialize  [variable	shellName applicationClassName applicationName
       arguments]

       Similar to a typical Motif-based	program,  the  arguments  argument  is
       used to reference any command-line arguments that might have been spec-
       ified by	the shell script user; these are typically referred using  the
       shell  syntax  of $@. The applicationName argument is listed because $@
       does not	include	$0. The	applicationName	 and  arguments	 are  used  to
       build  the  argument list passed	to the XtInitialize command. Upon com-
       pletion,	the environment	variable DTKSH_ARGV is	set  to	 the  argument
       list  as	returned by the	XtInitialize command; the DTKSH_TOPLEVEL envi-
       ronment variable	is set to the widget handle of the widget  created  by
       XtInitialize,  and the DTKSH_APPNAME environment	variable is set	to the
       value of	the applicationName argument. The command returns a value that
       can be used in a	conditional.

       XtIsManaged [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XtIsSubclass [widgetHandle widgetClass]

       The  widgetClass	operand	is the name of a widget	class. The command re-
       turns a value that can be used in a conditional.

       XtNameToWidget [variable	referenceWidget	name]

       XtIsRealized [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XtIsSensitive [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XtIsShell [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XtLastTimestampProcessed	[variable display]

       XtMainLoop

       XtManageChild [widgetHandle]

       XtManageChildren	[widgetHandle]	[widgetHandle ...]

       XtMapWidget [widgetHandle]

       XtOverrideTranslations [widgetHandle translations]

       XtParent	[variable widgetHandle]

       XtPopdown [widgetHandle]

       XtPopup [widgetHandle grabType]

       The grabType operand is one of the strings  GrabNone,  GrabNonexclusive
       or GrabExclusive.

       XtRealizeWidget [widgetHandle]

       XtRemoveAllCallbacks [widgetHandle callbackName]

       The  callbackName  operand  is one of the standard Motif	or Xt callback
       names, with the Xt or Xm	prefix omitted;	for example, activateCallback.

       XtRemoveCallback	[widgetHandle callbackName dtksh-command]

       The callbackName	operand	is one of the standard Motif  or  Xt  callback
       names, with the Xt or Xm	prefix omitted;	for example, activateCallback.
       As with traditional Xt callbacks, when a	callback is removed, the  same
       dtksh  command string must be specified as was specified	when the call-
       back was	originally registered.

       XtRemoveEventHandler [widgetHandle eventMask nonMaskableFlag dtksh-com-
       mand]

       The eventMask operand is	of the form mask| mask|	mask and the mask com-
       ponent is any of	the standard set of XEvent masks; for example, Button-
       PressMask,  where nonMaskableFlag is either True	or False. As with tra-
       ditional	Xt event handlers, when	an event handler is removed, the  same
       eventMask,  nonMaskableFlag  setting  and  dtksh	command	string must be
       specified as was	specified when the event handler was originally	regis-
       tered.

       XtRemoveInput [inputId]

       The inputId operand is the handle returned in the specified environment
       variable	when the alternative input source  was	registered  using  the
       XtAddInput command.

       XtRemoveTimeOut [timeoutId]

       The  timeoutId operand is the handle returned in	the specified environ-
       ment variable when the timeout was registered  using  the  XtAddTimeOut
       command.

       XtRemoveWorkProc	[workprocId]

       The workprocId operand is the handle returned in	the specified environ-
       ment variable when the work procedure was registered  using  the	 XtAd-
       dWorkProc command.

       XtScreen	[variable widgetHandle]

       XtSetSensitive [widgetHandle state]

       The state operand is either True	or False.

       XtSetValues [widgetHandle resource:value]  [resource:value ...]

       XtUninstallTranslations [widgetHandle]

       XtUnmanageChild [widgetHandle]

       XtUnmanageChildren [widgetHandle]  [widgetHandle	...]

       XtUnmapWidget [widgetHandle]

       XtUnrealizeWidget [widgetHandle]

       XtWindow	[variable widgetHandle]

   Built-in Motif Commands
       XmAddWMProtocolCallback [widgetHandle protocolAtom dtksh-command]

       The  protocolAtom  operand is typically obtained	using the XmInternAtom
       command.

       XmAddWMProtocols	[widgetHandle protocolAtom]  [protocolAtom ...]

       The protocolAtom	operand	is typically obtained using  the  XmInternAtom
       command.

       XmCommandAppendValue  [widgetHandle  string]   [XmCommandError widgetH-
       andle errorString]

       XmCommandGetChild [variable widgetHandle	childType]

       The childType operand is	one of the strings:

       DIALOG_COMMAND_TEXT
       DIALOG_PROMPT_LABEL
       DIALOG_HISTORY_LIST
       DIALOG_WORK_AREA

       XmCommandSetValue [widgetHandle commandString]

       XmCreateArrowButton   [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateArrowButtonGadget   [variable  parentWidgetHandle  name]	  [re-
       source:value ...]

       XmCreateBulletinBoard   [variable   parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateBulletinBoardDialog  [variable  parentWidgetHandle  name]  [re-
       source:value ...]

       XmCreateCascadeButton   [variable   parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateCascadeButtonGadget  [variable  parentWidgetHandle  name]  [re-
       source:value ...]

       XmCreateCommand	  [variable	parentWidgetHandle     name]	  [re-
       source:value ...]

       XmCreateDialogShell    [variable	   parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateDrawingArea   [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateDrawnButton    [variable	   parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateErrorDialog   [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateFileSelectionBox	  [variable   parentWidgetHandle  name]	  [re-
       source:value ...]

       XmCreateFileSelectionDialog [variable  parentWidgetHandle  name]	  [re-
       source:value ...]

       XmCreateForm [variable parentWidgetHandle name]	[resource:value	...]

       XmCreateFormDialog    [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateFrame [variable parentWidgetHandle name]	 [resource:value ...]

       XmCreateInformationDialog  [variable  parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateLabel [variable parentWidgetHandle name]	 [resource:value ...]

       XmCreateLabelGadget    [variable	   parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateList [variable parentWidgetHandle name]	[resource:value	...]

       XmCreateMainWindow    [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateMenuBar	   [variable	 parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateMenuShell    [variable	 parentWidgetHandle    name]	  [re-
       source:value ...]

       XmCreateMessageBox    [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateMessageDialog   [variable   parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateOptionMenu    [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreatePanedWindow   [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreatePopupMenu     [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreatePromptDialog   [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreatePulldownMenu    [variable    parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreatePushButton    [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreatePushButtonGadget	  [variable   parentWidgetHandle  name]	  [re-
       source:value ...]

       XmCreateQuestionDialog	[variable   parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateRadioBox	    [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateRowColumn    [variable	 parentWidgetHandle    name]	  [re-
       source:value ...]

       XmCreateScale [variable parentWidgetHandle name]	 [resource:value ...]

       XmCreateScrollBar     [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateScrolledList   [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateScrolledText    [variable    parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateScrolledWindow	[variable   parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateSelectionBox    [variable    parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateSelectionDialog	[variable   parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateSeparator     [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateSeparatorGadget	[variable   parentWidgetHandle	 name]	  [re-
       source:value ...]

       XmCreateText [variable parentWidgetHandle name]	[resource:value	...]

       XmCreateTextField     [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateToggleButton   [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateToggleButtonGadget  [variable  parentWidgetHandle  name]	  [re-
       source:value ...]

       XmCreateWarningDialog   [variable   parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateWorkArea	    [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       XmCreateWorkingDialog   [variable   parentWidgetHandle	name]	  [re-
       source:value ...]

       XmFileSelectionDoSearch [widgetHandle directoryMask]

       XmFileSelectionBoxGetChild [variable widgetHandle childType]

       The childType operand is	one of the strings:

       DIALOG_APPLY_BUTTON
       DIALOG_CANCEL_BUTTON
       DIALOG_DEFAULT_BUTTON
       DIALOG_DIR_LIST
       DIALOG_DIR_LIST_LABEL
       DIALOG_FILTER_LABEL
       DIALOG_FILTER_TEXT
       DIALOG_HELP_BUTTON
       DIALOG_LIST
       DIALOG_LIST_LABEL
       DIALOG_OK_BUTTON
       DIALOG_SEPARATOR
       DIALOG_SELECTION_LABEL
       DIALOG_TEXT
       DIALOG_WORK_AREA

       XmGetAtomName [variable display atom]

       XmGetColors [widgetHandle background variable variable2 variable3 vari-
       able4]

       The XmGetColors command differs from the	C procedure in that it takes a
       widgetHandle instead of a screen	pointer	and a colormap.

       XmGetFocusWidget	[variable widgetHandle]

       XmGetPostedFromWidget [variable widgetHandle]

       XmGetTabGroup [variable widgetHandle]

       XmGetTearOffControl [variable widgetHandle]

       XmGetVisibility [variable widgetHandle]

       XmInternAtom [variable display atomString onlyIfExistsFlag]

       The onlyIfExistsFlag operand can	be set to either True or False.

       XmIsTraversable [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmListAddItem [widgetHandle position itemString]

       The ordering of the arguments to	the XmListAddItem command differs from
       the corresponding C function.

       XmListAddItems [widgetHandle position itemString]  [itemString ...]

       The ordering of the arguments to	 the  XmListAddItems  command  differs
       from the	corresponding C	function.

       XmListAddItemsUnselected	 [widgetHandle	position  itemString]	[item-
       String ...]

       The ordering of the arguments to	the  XmListAddItemsUnselected  command
       differs from the	corresponding C	function.

       XmListAddItemUnselected [widgetHandle position itemString]

       The  ordering  of  the arguments	to the XmListAddItemUnselected command
       differs from the	corresponding C	function.

       XmListDeleteAllItems [widgetHandle]

       XmListDeleteItem	[widgetHandle itemString]

       XmListDeleteItems [widgetHandle itemString]  [itemString	...]

       XmListDeleteItemsPos [widgetHandle itemCount position]

       XmListDeletePos [widgetHandle position]

       XmListDeletePositions [widgetHandle position]  [position	...]

       XmListDeselectAllItems [widgetHandle]

       XmListDeselectItem [widgetHandle	itemString]

       XmListDeselectPos [widgetHandle position]

       XmListGetSelectedPos [variable widgetHandle]

       The command returns in variable a comma-separated list of indices.  The
       command returns a value that can	be used	in a conditional.

       XmListGetKbdItemPos [variable widgetHandle]

       XmListGetMatchPos [variable widgetHandle	itemString]

       The  command returns in variable	a comma-separated list of indices. The
       command returns a value that can	be used	in a conditional.

       XmListItemExists	[widgetHandle itemString]

       The command returns a value that	can be used in a conditional.

       XmListItemPos [variable widgetHandle itemString]

       XmListPosSelected [widgetHandle position]

       The command returns a value that	can be used in a conditional.

       XmListPosToBounds [widgetHandle position	variable  variable2  variable3
       variable4]

       The command returns a value that	can be used in a conditional.

       XmListReplaceItemsPos   [widgetHandle   position	  itemString]	[item-
       String ...]

       The ordering of the arguments to	the XmListReplaceItemsPos command dif-
       fers from the corresponding C function.

       XmListReplaceItemsPosUnselected	 [widgetHandle	 position  itemString]
       [itemString ...]

       The ordering of the arguments  to  the  XmListReplaceItemsPosUnselected
       command differs from the	corresponding C	function.

       XmListSelectItem	[widgetHandle itemString notifyFlag]

       The notifyFlag operand can be set to either True	or False.

       XmListSelectPos [widgetHandle position notifyFlag]

       The notifyFlag operand can be set to either True	or False.

       XmListSetAddMode	[widgetHandle state]

       The state operand can be	set to either True or False.

       XmListSetBottomItem [widgetHandle itemString]

       XmListSetBottomPos [widgetHandle	position]

       XmListSetHorizPos [widgetHandle position]

       XmListSetItem [widgetHandle itemString]

       XmListSetKbdItemPos [widgetHandle position]

       The command returns a value that	can be used in a conditional.

       XmListSetPos [widgetHandle position]

       XmListUpdateSelectedList	[widgetHandle]

       XmMainWindowSep1	[variable widgetHandle]

       XmMainWindowSep2	[variable widgetHandle]

       XmMainWindowSep3	[variable widgetHandle]

       XmMainWindowSetAreas [widgetHandle menuWidgetHandle commandWidgetHandle
       horizontalScrollbarWidgetHandle	verticalScrollbarWidgetHandle  workRe-
       gionWidgetHandle]

       XmMenuPosition [widgetHandle eventHandle]

       The eventHandle operand refers to an XEvent that	has typically been ob-
       tained  by  accessing  the  CB_CALL_DATA.EVENT,	EH_EVENT  or  TRANSLA-
       TION_EVENT environment variables.

       XmMessageBoxGetChild [variable widgetHandle childType]

       The childType operand is	one of the strings:

       DIALOG_CANCEL_BUTTON
       DIALOG_DEFAULT_BUTTON
       DIALOG_HELP_BUTTON
       DIALOG_MESSAGE_LABEL
       DIALOG_OK_BUTTON
       DIALOG_SEPARATOR
       DIALOG_SYMBOL_LABEL

       XmOptionButtonGadget [variable widgetHandle]

       XmOptionLabelGadget [variable widgetHandle]

       XmProcessTraversal [widgetHandle	direction]

       The direction operand is	one of the strings:

       TRAVERSE_CURRENT
       TRAVERSE_DOWN
       TRAVERSE_HOME
       TRAVERSE_LEFT
       TRAVERSE_NEXT
       TRAVERSE_NEXT_TAB_GROUP
       TRAVERSE_PREV
       TRAVERSE_PREV_TAB_GROUP
       TRAVERSE_RIGHT
       TRAVERSE_UP

       The command returns a value that	can be used in a conditional.

       XmRemoveWMProtocolCallback [widgetHandle	protocolAtom dtksh-command]

       The  protocolAtom  operand is typically obtained	using the XmInternAtom
       command.	As with	traditional WM callbacks, when a callback is  removed,
       the  same  dtksh	command	string must be specified as was	specified when
       the callback was	originally registered.

       XmRemoveWMProtocols [widgetHandle protocolAtom]	[protocolAtom ...]

       The protocolAtom	operand	is typically obtained using  the  XmInternAtom
       command.

       XmScaleGetValue [widgetHandle variable]

       XmScaleSetValue [widgetHandle value]

       XmScrollBarGetValues  [widgetHandle  variable variable2 variable3 vari-
       able4]

       XmScrollBarSetValues [widgetHandle value	sliderSize  increment  pageIn-
       crement notifyFlag]

       The notifyFlag operand can be set to either True	or False.

       XmScrollVisible	[widgetHandle  widgetHandle leftRightMargin topBottom-
       Margin]

       XmSelectionBoxGetChild [variable	widgetHandle childType]

       The childType operand is	one of the strings:

       DIALOG_CANCEL_BUTTON
       DIALOG_DEFAULT_BUTTON
       DIALOG_HELP_BUTTON
       DIALOG_APPLY_BUTTON
       DIALOG_LIST
       DIALOG_LIST_LABEL
       DIALOG_OK_BUTTON
       DIALOG_SELECTION_LABEL
       DIALOG_SEPARATOR
       DIALOG_TEXT
       DIALOG_WORK_AREA

       XmTextClearSelection [widgetHandle time]

       The time	operand	is typically either obtained from within an XEvent, or
       from a call to the XtLastTimestampProcessed command.

       XmTextCopy [widgetHandle	time]

       The time	operand	is typically either obtained from within an XEvent, or
       from a call to the XtLastTimestampProcessed command.  The  command  re-
       turns a value that can be used in a conditional.

       XmTextCut [widgetHandle time]

       The time	operand	is typically either obtained from within an XEvent, or
       from a call to the XtLastTimestampProcessed command.  The  command  re-
       turns a value that can be used in a conditional.

       XmTextDisableRedisplay [widgetHandle]

       XmTextEnableDisplay [widgetHandle]

       XmTextFindString	[widgetHandle startPosition string direction variable]

       The  direction operand is one of	the strings TEXT_FORWARD or TEXT_BACK-
       WARD. The command returns a value that can be used in a conditional.

       XmTextGetBaseline [variable widgetHandle]

       XmTextGetEditable [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmTextGetInsertionPosition [variable widgetHandle]

       XmTextGetLastPosition [variable widgetHandle]

       XmTextGetMaxLength [variable widgetHandle]

       XmTextGetSelection [variable widgetHandle]

       XmTextGetSelectionPosition [widgetHandle	variable variable2]

       The command returns a value that	can be used in a conditional.

       XmTextGetString [variable widgetHandle]

       XmTextGetTopCharacter [variable widgetHandle]

       XmTextInsert [widgetHandle position string]

       XmTextPaste [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmTextPosToXY [widgetHandle position variable variable2]

       The command returns a value that	can be used in a conditional.

       XmTextRemove [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmTextReplace [widgetHandle fromPosition	toPosition string]

       XmTextScroll [widgetHandle lines]

       XmTextSetAddMode	[widgetHandle state]

       The state operand can be	set to either True or False.

       XmTextSetEditable [widgetHandle editableFlag]

       The editableFlag	operand	can be set to either True or False.

       XmTextSetHighlight [widgetHandle	leftPosition rightPosition mode]

       The mode	operand	is one of the strings:

       HIGHLIGHT_NORMAL
       HIGHLIGHT_SELECTED
       HIGHLIGHT_SECONDARY_SELECTED

       XmTextSetInsertionPosition [widgetHandle	position]

       XmTextSetMaxLength [widgetHandle	maxLength]

       XmTextSetSelection [widgetHandle	firstPosition lastPosition time]

       The time	operand	is typically either obtained from within an XEvent, or
       from a call to the XtLastTimestampProcessed command.

       XmTextSetString [widgetHandle string]

       XmTextSetTopCharacter [widgetHandle topCharacterPosition]

       XmTextShowPosition [widgetHandle	position]

       XmTextXYToPos [variable widgetHandle x y]

       XmTextFieldClearSelection [widgetHandle time]

       The time	operand	is typically either obtained from within an XEvent, or
       from a call to the XtLastTimestampProcessed command.

       XmTextFieldGetBaseline [variable	widgetHandle]

       XmTextFieldGetEditable [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmTextFieldGetInsertionPosition [variable widgetHandle]

       XmTextFieldGetLastPosition [variable widgetHandle]

       XmTextFieldGetMaxLength [variable widgetHandle]

       XmTextFieldGetSelection [variable widgetHandle]

       XmTextFieldGetSelectionPosition [widgetHandle variable variable2]

       The command returns a value that	can be used in a conditional.

       XmTextFieldGetString [variable widgetHandle]

       XmTextFieldInsert [widgetHandle position	string]

       XmTextFieldPosToXY [widgetHandle	position variable variable2]

       The command returns a value that	can be used in a conditional.

       XmTextFieldRemove [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmTextFieldReplace [widgetHandle	fromPosition toPosition	string]

       XmTextFieldSetEditable [widgetHandle editableFlag]

       The editableFlag	operand	can be set to either True or False.

       XmTextFieldSetHighlight [widgetHandle leftPosition rightPosition	mode]

       The mode	operand	is one of the strings:

       HIGHLIGHT_NORMAL	HIGHLIGHT_SELECTED HIGHLIGHT_SECONDARY_SELECTED

       XmTextFieldSetInsertionPosition [widgetHandle position]

       XmTextFieldSetMaxLength [widgetHandle maxLength]

       XmTextFieldSetSelection [widgetHandle firstPosition lastPosition	time]

       The time	operand	is typically either obtained from within an XEvent, or
       from a call to the XtLastTimestampProcessed command.

       XmTextFieldSetString [widgetHandle string]

       XmTextFieldShowPosition [widgetHandle position]

       XmTextFieldXYToPos [variable widgetHandle x y]

       XmTextFieldCopy [widgetHandle time]

       The time	operand	is typically either obtained from within an XEvent, or
       from a call to the XtLastTimestampProcessed command.  The  command  re-
       turns a value that can be used in a conditional.

       XmTextFieldCut [widgetHandle time]

       The  time operand is typically either obtained from within an XEvent or
       from a call to the XtLastTimestampProcessed command.  The  command  re-
       turns a value that can be used in a conditional.

       XmTextFieldPaste	[widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmTextFieldSetAddMode [widgetHandle state]

       The state operand can be	set to either True or False.

       XmToggleButtonGadgetGetState [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmToggleButtonGadgetSetState [widgetHandle state	notifyFlag]

       The  state  operand  can	be set to either True or False.	The notifyFlag
       operand can be set to either True or False.

       XmToggleButtonGetState [widgetHandle]

       The command returns a value that	can be used in a conditional.

       XmToggleButtonSetState [widgetHandle state notifyFlag]

       The state operand can be	set to either True or  False.  The  notifyFlag
       operand can be set to either True or False.

       XmUpdateDisplay [widgetHandle]

   Built-in XCDE Application Help Commands
       DtCreateHelpQuickDialog	 [variable   parentWidgetHandle	  name]	  [re-
       source:value ...]

       DtCreateHelpDialog    [variable	  parentWidgetHandle	name]	  [re-
       source:value ...]

       DtHelpQuickDialogGetChild [variable widgetHandle	childType]

       The childType operand is	one of the strings:

       HELP_QUICK_OK_BUTTON
       HELP_QUICK_PRINT_BUTTON
       HELP_QUICK_HELP_BUTTON
       HELP_QUICK_SEPARATOR
       HELP_QUICK_MORE_BUTTON
       HELP_QUICK_BACK_BUTTON

       DtHelpReturnSelectedWidgetId [variable widgetHandle variable2]

       The variable operand is set to one of the strings:

       HELP_SELECT_VALID
       HELP_SELECT_INVALID
       HELP_SELECT_ABORT
       HELP_SELECT_ERROR

       and variable2 is	set to the widgetHandle	for the	selected widget.

       DtHelpSetCatalogName [catalogName]

   Built-in Localization Commands
       catopen [variable catalogName]

       Opens  the indicated message catalog, and returns the catalog ID	in the
       environment variable specified by variable.  If a shell script needs to
       close  the file descriptor associated with a message catalog, the cata-
       log ID must be closed using the catclose	command.

       catgets	[variable  catalogId   setNumber   messageNumber   defaultMes-
       sageString]

       Attempts	to extract the requested message string	from the message cata-
       log associated with the catalogId argument.  If the message string can-
       not  be	located,  the  default	message	string is returned.  In	either
       case, the returned message string is placed into	the environment	 vari-
       able indicated by variable.

       catclose	[catalogId]

       Closes the message catalog associated with the indicated	catalogId.

   Built-in Session Management Commands
       DtSessionRestorePath [widgetHandle variable sessionFile]

       Given  the  filename  for the session file (excluding any path informa-
       tion), this command returns the full pathname for the session  file  in
       the  environment	variable indicated by variable.	 The command returns a
       value that can be used in a conditional,	indicating whether the command
       succeeded.

       DtSessionSavePath [widgetHandle variable	variable2]

       The full	pathname for the session file is returned in environment vari-
       able indicated by variable. The filename	portion	of  the	 session  file
       (excluding  any	path information) is returned in the environment vari-
       able indicated by variable2. The	command	returns	a value	 that  can  be
       used in a conditional, indicating whether the command succeeded.

       DtShellIsIconified [widgetHandle]

       The command returns a value that	can be used in a conditional.

       DtSetStartupCommand [widgetHandle commandString]

       Part  of	 the session management	process	is telling the session manager
       how to restart the application the next time the	user reopens the  ses-
       sion.  This  command  passes  along the specified command string	to the
       session manager.	The widget  handle  should  refer  to  an  application
       shell.

       DtSetIconifyHint	[widgetHandle iconifyHint]

       The  iconifyHint	 operand can be	set to either True or False. This com-
       mand sets the initial iconified state for a shell window. This  command
       only  works  if	the window associated with the widget has not yet been
       realized.

   Built-in Workspace Management Commands
       DtWsmAddCurrentWorkspaceCallback	[variable widgetHandle dtksh-command]

       This command evaluates the specified dtksh command  whenever  the  user
       changes	workspaces.  The  handle  associated with this callback	is re-
       turned in the environment variable indicated by	variable.  The	widget
       indicated by widgetHandle should	be a shell widget.

       DtWsmRemoveWorkspaceCallback [callback-handle]

       The  callback-handle must be a handle that was returned by DtWsmAddCur-
       rentWorkspaceCallback.

       DtWsmGetCurrentWorkspace	[display rootWindow variable]

       This command  returns  the  X  atom  representing  the  user's  current
       workspace  in the environment variable indicated	by variable. The XmGe-
       tAtomName command maps the X atom into its string representation.

       DtWsmSetCurrentWorkspace	[widgetHandle workspaceNameAtom]

       This command changes the	user's current workspace to the	workspace  in-
       dicated	by  workspaceNameAtom. The command returns a value that	can be
       used in a conditional, indicating whether the command succeeded.

       DtWsmGetWorkspaceList [display rootWindow variable]

       This command returns in variable	a string of comma-separated  X	atoms,
       representing  the  current  set of workspaces defined for the user. The
       command returns a value that can	be used	in a  conditional,  indicating
       whether the command succeeded.

       DtWsmGetWorkspacesOccupied [display window variable]

       This  command returns a string of comma-separated X atoms, representing
       the current set of workspaces occupied by the indicated shell window in
       the  environment	variable indicated by variable.	 The command returns a
       value that can be used in a conditional,	indicating whether the command
       succeeded.

       DtWsmSetWorkspacesOccupied [display window workspaceList]

       This  command moves the indicated shell window to the set of workspaces
       indicated by the	string workspaceList, which must be a  comma-separated
       list of X atoms.

       DtWsmAddWorkspaceFunctions [display window]

       DtWsmRemoveWorkspaceFunctions [display window]

       DtWsmOccupyAllWorkspaces	[display window]

       DtWsmGetCurrentBackdropWindows [display rootWindow variable]

       This command returns in variable	a string of comma-separated window IDs
       representing the	set of root backdrop windows.

   Built-in Action Commands
       The set of commands in this section provides the	 programmer  with  the
       tools  for loading the action databases,	querying information about ac-
       tions defined in	the databases, and requesting that an action be	initi-
       ated.

       DtDbLoad

       This  command reads in the action and data types	databases.  It must be
       called before any of the	other Action or	 Data  Typing  Commands.   The
       shell  script  should also use the DtDbReloadNotify command so that the
       shell script can	be notified if new databases must be loaded.

       DtDbReloadNotify	[dtksh-command]

       The specified dtksh command is executed when the	 notification  is  re-
       ceived.	Typically,  the	 dtksh command includes	a call to the DtDbLoad
       command.

       DtActionExists [actionName]

       The command returns a value that	can be used in a conditional.

       DtActionLabel [variable actionName]

       If the action does not exist, then an empty string is returned.

       DtActionDescription [variable actionName]

       This command returns an empty string if the action is not  defined,  or
       if the DESCRIPTION attribute is not specified.

       DtActionInvoke  [widgetHandle  actionName  termOpts execHost contextDir
       useIndicator]  [dtksh-command]  [FILE  |	fileName ]  [ ...]

       The [FILE fileName] couplets can	be used	to specify file	 arguments  to
       be  used	 by  DtActionInvoke  when  invoking  the specified action. The
       dtksh-command argument is not supported in  XCDE	 1.0,  and  should  be
       specified as a null ("")	value.

   Built-in Data Typing	Commands
       DtDtsLoadDataTypes

       This command should be invoked before any of the	other data typing com-
       mands.

       DtDtsFileToDataType [variable filePath]

       This command returns the	name of	the data type associated with the file
       indicated  by the filePath argument in the variable argument. The vari-
       able argument is	set to an empty	string if the file cannot be typed.

       DtDtsFileToAttributeValue [variable filePath attrName]

       This command returns the	string representing the	value of the specified
       attribute  for  the data	type associated	with the indicated file	in the
       variable	argument. If the attribute is not defined, or if the file can-
       not be typed, the variable argument is set to an	empty string.

       DtDtsFileToAttributeList	[variable filePath]

       This  command  returns  the space-separated list	of attribute names de-
       fined for the data type associated with the indicated file in the vari-
       able argument. A	shell script queries the individual values for the at-
       tributes	using the DtDtsFileToAttributeValue command. The variable  ar-
       gument is set to	an empty string	if the file cannot be typed. This com-
       mand differs from the corresponding C function in that it only  returns
       the names of the	defined	attributes and not their values.

       DtDtsDataTypeToAttributeValue [variable dataType	attrName optName]

       This command returns the	string representing the	value of the specified
       attribute for the indicated data	type in	variable. If the attribute  is
       not defined, or if the indicated	data type does not exist, the variable
       argument	is set to an empty string.

       DtDtsDataTypeToAttributeList [variable dataType optName]

       This command returns the	space-separated	list of	 attribute  names  de-
       fined  for the indicated	data type in variable.	A shell	script queries
       the individual values for the attributes	using  the  DtDtsDataTypeToAt-
       tributeValue  command.  The variable argument is	set to an empty	string
       if the data type	is not defined.	This command differs from  the	corre-
       sponding	 C  function  in that it only returns the names	of the defined
       attributes, and not their values.

       DtDtsFindAttribute [variable name value]

       This command returns a space-separated list of data  type  names	 whose
       attribute,  indicated  by the name argument, has	the value indicated by
       the value argument. If an error occurs, the variable argument is	set to
       an empty	string.

       DtDtsDataTypeNames [variable]

       This  command  returns  a  space-separated list representing all	of the
       data types currently defined in the data	types database.	 If  an	 error
       occurs, the variable argument is	set to an empty	string.

       DtDtsSetDataType	[variable filePath dataType override]

       The  variable  argument is set to the resultant saved data type for the
       directory.

       DtDtsDataTypeIsAction [dataType]

       The command returns a value that	can be used in a conditional.

   Built-in XCDE Desktop Services Message Set Commands
       The following set of commands implement a subset	of  the	 Desktop  Ser-
       vices  Message  Set, allowing shell script participation	in the Desktop
       Services	protocol.  Many	of the ToolTalk	commands differ	slightly  from
       their  associated  C programming	call. For ToolTalk commands that typi-
       cally return a pointer, a C application can validate  that  pointer  by
       calling	the  tt_ptr_error  function;  this  C  function	call returns a
       Tt_status value,	which indicates	whether	the pointer was	valid, and  if
       not,  why it was	not. In	dtksh, all of the Desktop Services Message Set
       Commands	that return a pointer also  return  the	 associated  Tt_status
       value  for  the pointer automatically; this saves the shell script from
       needing to make an additional call to check the validity	of the	origi-
       nal pointer. In the case	of a pointer error occurring, dtksh returns an
       empty string for	the pointer value, and sets the	Tt_status code accord-
       ingly.  The  Tt_status  value  is  returned in the status argument. The
       Tt_status value is a string representing	the error, and can assume  any
       of the values shown in the manual page for  Tt/tt_c.h - Tttt_c(5).

       Some  of	 the  commands	take a message scope as	an argument. For these
       commands, the scope argument can	be set to a string representing	any of
       the  constants  documented  for	tt_message_scope(3), and in the	manual
       pages for the individual	ToolTalk functions.

       tt_file_netfile [variable status	file name]

       tt_netfile_file [variable status	netfile	name]

       tt_host_file_netfile [variable status host file name]

       tt_host_netfile_file [variable status host netfile name]

       ttdt_open [variable status  variable2  toolname	vendor	version	 send-
       Started]

       This  command  returns  in  the variable	argument the procId associated
       with the	connection.  It	returns	the file  descriptor  associated  with
       the connection in variable2; this file descriptor can be	used in	regis-
       tering an alternative Xt	input handler via the XtAddInput command.  The
       sendStarted  argument  is  True	or  False.  Any	 procIds  returned  by
       ttdt_open contain embedded spaces. To prevent dtksh  from  interpreting
       the  procId as multiple arguments (versus a single argument with	embed-
       ded spaces), references to the environment variable containing the pro-
       cId must	be within double quotes, as shown:

       ttdt_close STATUS "$PROC_ID" "" True

       tttk_Xt_input_handler [procId source id]

       In  order  for  the ToolTalk messages to	be received and	processed, the
       shell script must register an Xt	input handler for the file  descriptor
       returned	 by  the call to ttdt_open. The	Xt input handler is registered
       using the XtAddInput command, and the handler must be registered	 as  a
       raw  input  handler.  The input handler that the	shell script registers
       should invoke tttk_Xt_input_handler to get  the	message	 received  and
       processed. The following	code block demonstrates	how this is done:

       ttdt_open PROC_ID STATUS	FID "Tool" "HP"	"1.0" True
       XtAddInput INPUT_ID -r $FID "ProcessTTInput
       ProcessTTInput()
       {
	       tttk_Xt_input_handler $1	$INPUT_SOURCE $INPUT_ID
       }

       Refer  to  the  description  of the XtAddInput command for more details
       about alternative Xt input handlers. This command can be	 specified  as
       an alternative Xt input handler,	using the XtAddInput command. The pro-
       cId value should	be that	which was returned by the  ttdt_open  command.
       When  registering tttk_Xt_input_handler as an alternative Xt input han-
       dler, it	must be	registered as a	raw handler to prevent dtksh from  au-
       tomatically  breaking up	the input into lines. This can be done as fol-
       lows:

       XtAddInput returnId -r $tt_fd	     "tttk_Xt_input_handler

       The in the procId environment variable.

       ttdt_close [status procId newProcId sendStopped]

       This command closes the indicated communications	 connection,  and  op-
       tionally	 sends a Stopped notice, if the	sendStopped argument is	set to
       True. Because the procId	returned by the	call to	ttdt_open contains em-
       bedded spaces, it must be enclosed within double	quotes,	as shown:

       ttdt_close STATUS "$PROC_ID" "$NEW_PROC_ID" False

       ttdt_session_join [variable status sessId shellWidgetHandle join]

       This command joins the session indicated	by the sessId argument.	If the
       sessId argument does not	specify	a value	 (that	is,  it	 is  an	 empty
       string),	 then  the default session is joined. If the shellWidgetHandle
       argument	specifies a widget  handle  (that  is,	it  is	not  an	 empty
       string),	 then it should	refer to a mappedWhenManaged applicationShell-
       Widget. The join	argument is True or False.  This  command  returns  an
       opaque  pattern handle in the variable argument;	this handle can	be de-
       stroyed using the  ttdt_session_quit  command  when  it	is  no	longer
       needed.

       ttdt_session_quit [status sessId	sessPatterns quit]

       This  command  destroys	the message patterns specified by the sessPat-
       terns argument, and, if the quit	argument is set	to True, it quits  the
       session	indicated by the sessId	argument, or it	quits the default ses-
       sion if sessId is empty.

       ttdt_file_join [variable	status pathName	scope join dtksh-command]

       An opaque pattern handle	is returned in	the  variable  argument;  this
       should be destroyed by calling ttdt_file_quit when there	is no interest
       in monitoring messages for the indicated	file. The requested dtksh-com-
       mand  is	 evaluated  any	 time  a message is received for the indicated
       file. When this dtksh-command is	evaluated, the	following  environment
       variables are defined, and provide additional information about the re-
       ceived message:

       DT_TT_MSG The opaque handle for the incoming message.

       DT_TT_OP	 The string representing the operation to be  performed;  that
		 is, TTDT_DELETED, TTDT_MODIFIED, TTDT_REVERTED, TTDT_MOVED or
		 TTDT_SAVED.

       DT_TT_PATHNAME
		 The pathname for the file to which this message pertains.

       DT_TT_SAME_EUID_EGID
		 Set to	True if	the message was	sent by	an application operat-
		 ing with the same effective user ID and effective group ID as
		 this process.

       DT_TT_SAME_PROCID
		 Set to	True if	the message was	sent by	 an  application  with
		 the same procId (as returned by ttdt_open).

       When  the  callback  completes,	it must	indicate whether the passed-in
       message was consumed (replied-to, failed	or rejected). If the  callback
       returns	the message (as	passed in the DT_TT_MSG	environment variable),
       it is assumed that the message was not consumed.	 If  the  message  was
       consumed,  the  callback	 should	 return	zero, or one of	the values re-
       turned by the tt_error_pointer command. The  callback  can  return  its
       value in	the following fashion:

       return $DT_TT_MSG (or) return 0

       ttdt_file_quit [status patterns quit]

       This  command  destroys	the message patterns specified by the patterns
       argument, and also unregisters interest in the pathname that was	passed
       to  the ttdt_file_join command if quit is set to	True; the patterns ar-
       gument should be	the value returned by a	 call  to  the	ttdt_file_join
       command.

       ttdt_file_event [status op patterns send]

       This  command creates, and optionally sends, a ToolTalk notice announc-
       ing an event pertaining to a file. The file is indicated	by  the	 path-
       name  passed  to	 the ttdt_file_join command when patterns was created.
       The op argument indicates what should be	announced  for	the  indicated
       file, and can be	set to TTDT_MODIFIED, TTDT_SAVED or TTDT_REVERTED.  If
       op is set to TTDT_MODIFIED, this	command	registers to handle  Get_Modi-
       fied, Save and Revert messages in the scope specified when the patterns
       was created. If op is set to TTDT_SAVED or TTDT_REVERTED, this  command
       unregisters  from  handling  Get_Modified, Save and Revert messages for
       this file. If the send argument is set to True, the  indicated  message
       is sent.

       ttdt_Get_Modified [pathName scope timeout]

       This  commands sends a Get_Modified request in the indicated scope, and
       waits for a reply, or for the specified timeout	(in  milliseconds)  to
       elapse.	It  returns a value that can be	used in	a conditional. A value
       of True is returned if an affirmative  reply  is	 received  within  the
       specified timeout; otherwise, False is returned.

       ttdt_Save [status pathName scope	timeout]

       This command sends a Save request in the	indicated scope, and waits for
       a reply,	or for the indicated timeout (in milliseconds)	to  elapse.  A
       status  of TT_OK	is returned if an affirmative reply is received	before
       the timeout elapses; otherwise, a Tt_status error value is returned.

       ttdt_Revert [status pathName scope timeout]

       This command sends a Revert request in the indicated scope,  and	 waits
       for  a reply, or	for the	indicated timeout (in milliseconds) to elapse.
       A status	of TT_OK is returned if	an affirmative reply is	 received  be-
       fore  the  timeout  elapses;  otherwise,	a Tt_status error value	is re-
       turned.

       The following commands are typically used by  the  callback  registered
       with  the  ttdt_file_join command. They serve as	the mechanism for con-
       suming and destroying a message.	A message is consumed  by  either  re-
       jecting,	failing	or replying to it. The tt_error_pointer	is used	by the
       callback	to get a return	pointer	for indicating an error	condition.

       tt_error_pointer	[variable ttStatus]

       This command returns a magic value, which is used by ToolTalk to	repre-
       sent an invalid pointer.	The magic value	returned depends on the	ttSta-
       tus value passed	in. Any	of the valid Tt_status values  can  be	speci-
       fied.

       tttk_message_destroy [status msg]

       This  command  destroys	any  patterns that may have been stored	on the
       message indicated by the	msg argument, and then it  destroys  the  mes-
       sage.

       tttk_message_reject [status msg msgStatus msgStatusString destroy]

       This  command  sets  the	status and the status string for the indicated
       request message,	and then rejects the message.  It  then	 destroys  the
       passed-in  message if the destroy argument is set to True. This command
       is one way in which the callback	specified with the ttdt_file_join com-
       mand  consumes  a message. After	rejecting the message, it is typically
       safe to destroy the message using tttk_message_destroy.

       tttk_message_fail [status msg msgStatus msgStatusString destroy]

       This command sets the status and	the status string  for	the  indicated
       request message,	and then it fails the message. It destroys the passed-
       in message if the destroy argument is set to True. This command is  one
       way  in	which  the  callback specified with the	ttdt_file_join command
       consumes	a message. After failing the message, it is typically safe  to
       destroy the message, using tttk_message_destroy.

       tt_message_reply	[status	msg]

       This  command  informs  the  ToolTalk service that the shell script has
       handled the message specified by	the msg	argument.  After replying to a
       message,	 it  is	 typically  safe  to  destroy  the  message  using the
       tttk_message_destroy command.

   Listing Widget Information
       The DtWidgetInfo	command	provides the shell programmer a	mechanism  for
       obtaining information about the current set of instantiated widgets and
       their resources;	the information	is written  to	the  standard  output.
       This provides useful debugging information by including:

	  o  The  list of instantiated widgets,	including: the name, class and
	     parent of the widget; a handle for	the widget; the	 name  of  the
	     environment  variable  supplied  when the widget was created; the
	     state of the widget.

	  o  The list of resources supported by	a particular widget class.

	  o  The list of constraint resources supported	by a particular	widget
	     class.

       DtWidgetInfo  is	 called	by using any of	the following syntaxes;	all of
       the arguments are optional:

       DtWidgetInfo [widgetHandle  | widgetName	]

       If no arguments are supplied, information about all existing widgets is
       written to standard output; the information includes the	name, the han-
       dle, the	environment variable, the parent, the  widget  class  and  the
       state. If arguments are supplied, they should be	either widget handles,
       or the names of existing	widgets; in  this  case,  the  information  is
       written only for	the requested set of widgets.

       DtWidgetInfo [-r]  [widgetHandle	 | widgetClass ]

       If  no arguments	are supplied, the list of supported resources is writ-
       ten to standard output for all available	widget classes.	 If  arguments
       are supplied, they should be either widget handles, or the widget class
       names; in this case, the	information is written only for	the  requested
       set of widgets or widget	classes.

       DtWidgetInfo [-R]  [widgetHandle	 | widgetClass ]

       If  no  arguments  are  supplied,  the list of supported	constraint re-
       sources,	if any,	is written to standard output for all available	widget
       classes.	 If  arguments are supplied, they should be either widget han-
       dles, or	the widget class names;	in this	case, the information is writ-
       ten only	for the	requested set of widgets or widget classes.

       DtWidgetInfo [-c]  [widgetClass]

       If  no arguments	are supplied, the list of supported widget class names
       is written to standard output. If arguments are supplied, dtksh	writes
       the widget class	name (if it is defined); otherwise, it writes an error
       message to standard error.

       DtWidgetInfo [-h]  [widgetHandle]

       If no arguments are supplied, the list  of  active  widget  handles  is
       written to standard output. If arguments	are supplied, they should rep-
       resent widget handles, in which case the	name of	the associated	widget
       is written to standard output.

   Convenience Functions
       The  XCDE  system  includes a file of dtksh convenience functions. This
       file is itself a	shell script containing	shell functions	 that  may  be
       useful  to  a  shell programmer.	The shell functions perform frequently
       used operations.	These include functions	for quickly  creating  certain
       kinds  of  dialogs (help, error,	warning	and so on), and	a function for
       easily creating a collection of buttons and functions that make it eas-
       ier to configure	the constraint resources for a child of	a form widget.
       It is not a requirement that shell script writers use these convenience
       functions;  they	are supplied to	make it	easier for developers to write
       shorter and more	readable shell scripts.

       Before a	shell script can access	these functions, the shell script must
       first include the file containing the convenience functions. The	conve-
       nience functions	are located in	the  file  /usr/local/dt/lib/dtksh/Dt-
       Funcs.dtsh,  and	are included in	a shell	script using the following no-
       tation:

       . /usr/local/dt/lib/dtksh/DtFuncs.dtsh

   DtkshAddButtons
       This convenience	function adds one or more buttons  of  the  same  kind
       into  a	composite widget. Most frequently, it is used to add a collec-
       tion of buttons into a menupane or menubar.

       DtkshAddButtons [parent widgetClass label1  callback1]	[label2	 call-
       back2 ...]

       DtkshAddButtons	[-w]   [parent widgetClass variable1 label1 callback1]
       [variable2 label2 callback2 ...]

       The -w option indicates that the	convenience function should return the
       widget handle for each of the buttons it	creates.  The widget handle is
       returned	in the specified environment variable. The  widgetClass	 argu-
       ment can	be set to any one of the following, and	defaults to XmPushBut-
       tonGadget, if not specified:

       XmPushButton XmPushButtonGadget XmToggleButton XmToggleButtonGadget XmCascadeButton XmCascadeButtonGadget

       Examples:

       DtkshAddButtons $MENU XmPushButtonGadget	Open do_Open Save	  do_Save Quit exit
       DtkshAddButtons -w $MENU	XmPushButtonGadget B1 Open	   do_Open B2 Save do_Save

   DtkshSetReturnKeyControls
       This convenience	function configures a text widget (within a form  wid-
       get), so	the <carriage-return> key does not activate the	default	button
       within the form.	Instead, the <carriage-return> key moves the focus  to
       the  next text widget within the	form. This is useful if	a window, con-
       taining a series	of text	widgets	and the	default	button,	should not  be
       activated  until	 the  user presses the <carriage-return> key while the
       focus is	in the last text widget.

       DtkshSetReturnKeyControls  [textWidget  nextTextWidget  formWidget  de-
       faultButton]

       The  textWidget	argument  specifies  the widget	to be configured so it
       catches the <carriage-return> key, and forces the focus to move to  the
       next  text  widget  (as	indicated by the nextTextWidget	argument). The
       formWidget argument specifies the form containing the  default  button,
       and must	be the parent of the two text widgets. The defaultButton argu-
       ment indicates which component to treat as the  default	button	within
       the form	widget.

       Examples:

       DtkshSetReturnKeyControls $TEXT1	$TEXT2 $FORM $OK
       DtkshSetReturnKeyControls $TEXT2	$TEXT3 $FORM $OK

   DtkshUnder, DtkshOver, DtkshRightOf,	DtkshLeftOf
       These  convenience  functions  simplify	the  specification  of certain
       classes of form constraints. They provide a convenient way of attaching
       a  component  to	one edge of another component. They are	used when con-
       structing the resource list for a widget. This behavior is accomplished
       using the ATTACH_WIDGET constraint.

       DtkshUnder [widgetId]  [offset]

       DtkshOver [widgetId]  [offset]

       DtkshRightOf [widgetId]	[offset]

       DtkshLeftOf [widgetId]  [offset]

       The  widgetId argument specifies	the widget to which the	current	compo-
       nent is to be attached. The offset value	is optional, and  defaults  to
       zero, if	not specified.

       Example:

       XtCreateManagedWidget BUTTON4 button4 pushButton	$FORM	      labelString:"Exit" $(DtkshUnder $BUTTON2)		$(DtkshRightOf $BUTTON3)

   DtkshFloatRight, DtkshFloatLeft, DtkshFloatTop, DtkshFloatBottom
       These  convenience  functions  simplify	the  specification  of certain
       classes of form constraints. They provide a convenient way of position-
       ing  a  component, independent of the other components within the form.
       As the form grows or shrinks, the component maintains its relative  po-
       sition within the form. The component may still grow or shrink, depend-
       ing on the other	form constraints specified for the component. This be-
       havior is accomplished using the	ATTACH_POSITION	constraint.

       DtkshFloatRight [position]

       DtkshFloatLeft [position]

       DtkshFloatTop [position]

       DtkshFloatBottom	[position]

       The optional position argument specifies	the relative position to which
       the indicated edge of the component is positioned.  A default  position
       is used,	if one is not specified.

       Example:

       XtCreateManagedWidgetBUTTON1 button1 pushButton	       $FORM labelString:"Ok" $(DtkshUnder $SEPARATOR)	       $(DtkshFloatLeft	10) $(DtkshFloatRight 40)

   DtkshAnchorRight, DtkshAnchorLeft, DtkshAnchorTop, DtkshAnchorBottom
       These  convenience  functions  simplify	the  specification  of certain
       classes of form constraints. They provide a convenient way of attaching
       a  component  to	 one  of  the edges of a form widget in	such a fashion
       that, as	the form grows or shrinks, the component's position  does  not
       change.	However,  depending  on	the other form constraints set on this
       component, the component	may still grow or shrink in size. This	behav-
       ior is accomplished using the ATTACH_FORM constraint.

       DtkshAnchorRight	[offset]

       DtkshAnchorLeft [offset]

       DtkshAnchorTop [offset]

       DtkshAnchorBottom [offset]

       The  optional  offset  argument	specifies how far from the edge	of the
       form widget the component should	be positioned.	If an  offset  is  not
       specified, zero is used.

       Example:

       XtCreateManagedWidget BUTTON1 button1 pushButton		$FORM labelString:"Ok" $(DtkshUnder $SEPARATOR)		$(DtkshAnchorLeft 10) $(DtkshAnchorBottom 10)

   DtkshSpanWidth, DtkshSpanHeight
       These  convenience  functions  simplify	the  specification  of certain
       classes of form constraints. They provide a convenient way of configur-
       ing  a  component such that it spans either the full height or width of
       the form	widget.	This behavior is accomplished by attaching  two	 edges
       of  the	component  (top	 and  bottom for DtkshSpanHeight, and left and
       right for DtkshSpanWidth) to the	form widget. The  component  typically
       resizes whenever	the form widget	is resized. The	ATTACH_FORM constraint
       is used for all attachments.

       DtkshSpanWidth [leftOffset rightOffset]

       DtkshSpanHeight [topOffset bottomOffset]

       The optional offset arguments specify how far from  the	edges  of  the
       form  widget  the  component should be positioned.  If an offset	is not
       specified, zero is used.

       Example:

       XtCreateManagedWidget SEP sep separator $FORM $(DtkshSpanWidth 1	1)

   DtkshDisplayInformationDialog,  DtkshDisplayQuestionDialog,	 DtkshDisplay-
       WarningDialog,
       DtkshDisplayWorkingDialog, DtkshDisplayErrorDialog"

       These convenience functions create a single instance of each of the Mo-
       tif feedback dialogs. If	an instance of the requested  type  of	dialog
       already exists, it is reused. The parent	of the dialog is obtained from
       the environment variable, TOPLEVEL, which should	be set by the  calling
       shell  script,  and  then should	not be changed.	The handle for the re-
       quested dialog is returned in one of the	 following  environment	 vari-
       ables:

       DTKSH_ERROR_DIALOG_HANDLE
       DTKSH_QUESTION_DIALOG_HANDLE
       DTKSH_WORKING_DIALOG_HANDLE
       DTKSH_WARNING_DIALOG_HANDLE
       DTKSH_INFORMATION_DIALOG_HANDLE

       When  attaching callbacks to the	dialog buttons,	the application	should
       not destroy the dialog; it should simply	unmanage the dialog so that it
       can  be used again later. If it is necessary to destroy the dialog, the
       associated environment variable should also be cleared, so  the	conve-
       nience function does not	attempt	to reuse the dialog.

       DtkshDisplay*Dialog  title  message  [okCallback	closeCallback	 help-
       Callback	dialogStyle]

       The Ok button is	always managed,	and by default unmanages  the  dialog.
       The  Cancel  and	 Help buttons are only managed when a callback is sup-
       plied for them. The dialogStyle argument	accepts	any  of	 the  standard
       resource	settings supported by the associated bulletin board resource.

       Example:

       DtkshDisplayErrorDialog "Read Error" "Unable to read the	file"	      "OkCallback" "CancelCallback" "" DIALOG_PRIMARY_APPLICATION_MODAL

   DtkshDisplayQuickHelpDialog,	DtkshDisplayHelpDialog
       These  convenience  functions  create  a	single instance	of each	of the
       help dialogs. If	an instance of the requested type of help  dialog  al-
       ready  exists,  it is reused. The parent	of the dialog is obtained from
       the environment variable, TOPLEVEL, which should	be set by the  calling
       shell  script,  and  then should	not be changed.	The handle for the re-
       quested dialog is returned in one of the	 following  environment	 vari-
       ables:

       DTKSH_HELP_DIALOG_HANDLE
       DTKSH_QUICK_HELP_DIALOG_HANDLE

       If  it  is  necessary  to destroy a help	dialog,	the application	should
       also clear the associated environment variable, so that the convenience
       function	does not attempt to reuse the dialog.

       DtkshDisplay*HelpDialog title helpType helpInformation [locationId]

       The  meaning  of	 the  arguments	depends	on the value specified for the
       helpType	argument. The meanings are explained in	the following table:

       helpType			      helpInformation	 locationId
       HELP_TYPE_DYNAMIC_STRING	      help string	 <not used>
       HELP_TYPE_FILE		      help file	name	 <not used>
       HELP_TYPE_MAN_PAGE	      manual page name	 <not used>
       HELP_TYPE_STRING		      help string	 <not used>
       HELP_TYPE_TOPIC		      help volume name	 help topic location ID

       Example:

       DtkshDisplayHelpDialog "Help On Dtksh" HELP_TYPE_FILE "helpFileName"

   Dtksh App-Defaults File
       The dtksh app-defaults file, named dtksh, is in a location based	on the
       following path description:

       /usr/local/dt/app-defaults/<LANG>

       The  only information contained in this app-defaults file is the	inclu-
       sion of the standard desktop base app-defaults file.  The  contents  of
       the dtksh app-defaults file is as follows:

       #include	"Dt"

   Non-String Values
       The  C  bindings	of the interfaces to X,	Xt and Motif include many non-
       string values defined in	headers. For example,  the  constraint	values
       for  a child of a form widget are declared, such	as XmATTACH_FORM, with
       an Xt or	Xm prefix followed by a	descriptive  name.  Equivalent	values
       are  specified  in  dtksh by omitting the prefix, just as in an app-de-
       faults file. For	 example:  XmDIALOG_COMMAND_TEXT  becomes  DIALOG_COM-
       MAND_TEXT; XtATTACH_FORM	becomes	ATTACH_FORM.

       A  Boolean value	can be specified as an argument	to a dtksh command us-
       ing the words True or False; case is not	significant.

   Return Values From Built-in Commands
       Graphical commands in dtksh fall	into one of four categories, based  on
       the definition of the corresponding C function in a windowing library:

	  1. The function returns no values. Example: XtMapWidget.

	  2. The function is void, but returns one or more values through ref-
	     erence arguments. Example:	XmGetColors.

	  3. The function returns a non-Boolean	value.	Example:  XtCreateMan-
	     agedWidget.

	  4. The function returns a Boolean value. Example: XtIsSensitive.

       A  category 1 command follows the calling sequence of its corresponding
       C function exactly; the number and order	of arguments can be determined
       by looking at the standard documentation	for the	function. Example:

       XtMapWidget $FORM

       A category 2 command also generally follows the calling sequence	as its
       corresponding C function. Where a C caller would	pass in	a pointer to a
       variable	 in  which  a  value  is returned, the dtksh command returns a
       value in	an environment variable. Example:

       XmGetColors $FORM $BG FOREGROUND	TOPSHADOW BOTTOMSHADOW SELECT
       echo "Foreground	color =	" $FOREGROUND

       A category 3 command differs slightly from its  corresponding  C	 func-
       tion.   Where the C function returns its	value as the value of the pro-
       cedure call, a dtksh command requires an	additional argument, which  is
       always  the  first argument, and	is the name of an environment variable
       into which the return value is placed. Example:

       XmTextGetString TEXT_VALUE $TEXT_WIDGET
       echo "The value of the text field is "$TEXT_VALUE

       A category 4 command returns a Boolean value that can be	used in	a con-
       ditional	 expression, just as with the corresponding C function.	If the
       C function also returns values through reference	variables (as in cate-
       gory 2),	the dtksh command also uses variable names for the correspond-
       ing arguments.  Example:

       if XmIsTraversable $PUSH_BUTTON;	then
	       echo "The pushbutton is traversable"
       else
	       echo "The pushbutton is not traversable"
       fi

       Generally, the order and	type of	arguments passed to a command  matches
       those passed to the corresponding C function, except as noted for cate-
       gory 3 commands.	Other exceptions are described in the applicable  com-
       mand descriptions.

   Widget Handles
       Where  a	 C  function  returns a	widget handle, the corresponding dtksh
       commands	set an environment variable equal to the widget	handle.	 These
       are  category  3	commands; they take as one of their arguments the name
       of an environment variable in which to return the widget	handle.	 (This
       is  an ASCII string used	by dtksh to access the actual widget pointer.)
       For example, either of the following commands could be used to create a
       new form	widget;	in both	cases, the widget handle for the new form wid-
       get is returned in the environment variable FORM:

       XtCreateManagedWidget FORM name XmForm $PARENT
       XmCreateForm FORM $PARENT name

       After either of the above commands, $FORM can be	used to	reference  the
       form  widget.  For  instance,  to create	a label	widget within the form
       widget just created, the	following command could	be used:

       XmCreateLabel LABEL $FORM namelabelString:"Hi Mom"	  topAttachment:ATTACH_FORM leftAttachment:ATTACH_FORM

       There is	a special widget handle	called NULL, provided for cases	 where
       a shell script may need to specify a NULL widget. For example, the fol-
       lowing disables the defaultButton resource for a	form widget:

       XtSetValues $FORM defaultButton:NULL

   Widget Resources
       Some of the Xt and Motif	commands allow the shell script	to pass	 in  a
       variable	 number	 of  arguments,	representing resource and value	pairs.
       This is similar to the arglist passed in	to the corresponding Xt	or Mo-
       tif  C function.	Examples of these commands include any of the commands
       used to create a	widget,	and the	XtSetValues  command.  In  dtksh,  re-
       sources	are specified by a string with the following syntax: resource:
       value.

       The name	of the resource	is  given  in  the  resource  portion  of  the
       string;	it  is constructed by taking the corresponding Xt or Motif re-
       source name and omitting	the Xt or Xm prefix. The value to be  assigned
       to  the resource	is given in the	value portion of the string. The dtksh
       utility automatically converts the value	string to an  appropriate  in-
       ternal representation.  For example:

       XtSetValues $WIDGET height:100 width:200	resizePolicy:RESIZE_ANY
       XmCreateLabel LABEL $PARENT myLabel labelString:"Close Dialog"

       When widget resources are retrieved using XtGetValues, the return value
       has the same syntax. For	example:

       XtGetValues $WIDGET height:HEIGHT resizePolicy:POLICY	     sensitive:SENSITIVE
       echo $HEIGHT
       echo $POLICY
       echo $SENSITIVE

       Certain types of	resource values	have special representation. These in-
       clude  string tables and	bit masks. For instance, the XmList widget al-
       lows a string table to be specified both	for the	items and the selecte-
       dItems  resources.  In dtksh, a string table is represented as a	comma-
       separated list of strings, which	is compatible with how	Motif  handles
       them  from a resource file. When	a resource that	returns	a string table
       is queried using	XtGetValues(3),	the resulting value is again a	comma-
       separated  set  of strings. A resource that expects a bit mask value to
       be passed in, expects the mask to be specified as a string composed  of
       the  various  mask  values separated by the ``|'' character. When a re-
       source that returns a bit mask is queried, the return value also	 is  a
       string representing the enabled bits, separated by the ``|'' character.
       For example, the	following sets the mwmFunctions	resource for the  Ven-
       dorShell	widget class:

       XtSetValues mwmFunctions	MWM_FUNC_ALL|MWM_FUNC_RESIZE

   Unsupported Resources
       The  dtksh  utility  supports  most of the resources provided by	Motif;
       however,	there are certain resources that dtksh does not	 support.  The
       list  of	 unsupported resources follows.	Several	of these resources can
       be specified at widget creation time by using XtSetValues,  but	cannot
       be retrieved using XtGetValues; these are indicated by the asterisk (*)
       following the resource name.

       All Widget And Gadget Classes:
		 Any font list resource	(*) Any	pixmap resource	( *)

       Composite:
		 insertPosition	children

       Core:	 accelerators translations (*) colormap

       XmText:	 selectionArray	selectionArrayCount

       ApplicationShell:
		 argv

       WMShell:	 iconWindow windowGroup

       Shell:	 createPopupChildrenProc

       XmSelectionBox:
		 textAccelerators

       Manager,	Primitive and Gadget Subclasses:
		 userData

       XmFileSelectionBox:
		 dirSearchProc fileSearchProc qualifySearchDataProc

EXIT STATUS
       See sh(1).

CONSEQUENCES OF	ERRORS
       See sh(1).

APPLICATION USAGE
   Initializing	The Toolkit Environment
       Before any of the Xlib, Xt or Motif commands can	be invoked, the	 shell
       script  must first initialize the Xt toolkit by invoking	the XtInitial-
       ize command, which returns an application shell	widget.	 XtInitialize,
       as  with	 all  of the commands that return a widget handle, returns the
       widget handle in	the environment	variable named in its first  argument.
       For example:

       XtInitialize TOPLEVEL myShellName Dtksh $0$@

       Shell  script  writers should invoke the	XtInitialize command as	one of
       the first commands within a dtksh shell script. This  allows  dtksh  to
       locate  its  message  catalog  and  the correct app-defaults file. If a
       shell error occurs before XtInitialize has been called, it is  possible
       that  unlocalized  error	 messages  may be displayed. The dtksh utility
       provides	a default app-defaults file to use if the call to XtInitialize
       specifies  an  application  class name of Dtksh.	This app-defaults file
       loads in	the standard set of desktop  application  default  values,  so
       that  these  applications have a	consistent look	with other desktop ap-
       plications.

   Responding to a Window Manager Close	Notice
       When the	user selects the Close item on the window manager menu for  an
       application,  the  application  is terminated unless it has arranged to
       catch the Close notification. Multiple windows managed by the  applica-
       tion  disappear,	 and  application  data	 may be	left in	an undesirable
       state. To avoid this, dtksh provides  for  catching  and	 handling  the
       Close notification.  The	application must:

	  o  Define a procedure	to handle the Close notification

	  o  Request  notification when	Close is selected and override the re-
	     sponse, so	the application	is not shut down

       The following code illustrates this processing:

       # This is the `callback'	invoked	when the user selects
       # the `Close' menu item
       WMCallback()
       {
	       echo "User has selected the Close menu item"
       }
       # Create	the toplevel application shell
       XtInitialize TOPLEVEL test Dtksh	"$@"
       XtDisplay DISPLAY $TOPLEVEL
       # Request notification when the user selects the	`Close'
       # menu item
       XmInternAtom DELETE_ATOM	$DISPLAY "WM_DELETE_WINDOW" false
       XmAddWMProtocolCallback $TOPLEVEL $DELETE_ATOM "WMCallback"
       # Ask Motif to not automatically	close down your
       # application window
       XtSetValues $TOPLEVEL deleteResponse:DO_NOTHING

   Responding to a Session Management Save State Notice
       Session management facilities allow applications	to save	their  current
       state  when  the	 user terminates the current session, so that when the
       user later restarts the session,	an application returns to the state it
       was  in.	  In dtksh this	is accomplished	by setting up a	handler	analo-
       gously to handling a Close notification.	If no such handler is set  up,
       the  application	 has  to be restarted manually in the new session, and
       does not	retain any state.  To set up a handler to save state, the  ap-
       plication must do the following:

	  o  Define  functions to save state at	end-of-session,	and restore it
	     on	start-up.

	  o  Register interest in the session management notification.

	  o  Register the function to save state.

	  o  Determine if saved	state should be	restored at start-up.

       The following code illustrates this process:

       #! /usr/local/dt/bin/dtksh
       # Function invoked when the session is being ended by the user
       SessionCallback()
       {
	       # Get the name of the file into which we	should save our
	       # session information
	       if DtSessionSavePath $TOPLEVEL PATH SAVEFILE; then
		       exec 9>$PATH
		       # Save off whether we are currently in an iconified state
		       if DtShellIsIconified $TOPLEVEL;	then
			       print -u9 `Iconified'
		       else
			       print -u9 `Deiconified'
		       fi
		       # Save off the list of workspaces we currently reside in
		       if DtWsmGetWorkspacesOccupied $(XtDisplay "-" $TOPLEVEL)
				       $(XtWindow "-" $TOPLEVEL)
				       CURRENT_WS_LIST;
		       then
			       # Map the comma-separated list of atoms into
			       # their string representation
			       oldIFS=$IFS
			       IFS=","
			       for item	in $CURRENT_WS_LIST;
			       do
				       XmGetAtomName NAME $(XtDisplay "-" $TOPLEVEL)
					       $item
				       print -u9 $NAME
			       done
			       IFS=$oldIFS
		       fi
		       exec 9<&-
		       # Let the session manager know how to invoke us when
		       # the session is	restored
		       DtSetStartupCommand $TOPLEVEL
			       "/usr/local/dt/contrib/dtksh/SessionTest	$SAVEFILE"
	       else
		       echo "DtSessionSavePath FAILED!!"
		       exit -3
	       fi
       }
       # Function invoked during a restore session; restores the
       # application to	its previous state
       RestoreSession()
       {
	       # Retrieve the path where our session file resides
	       if DtSessionRestorePath $TOPLEVEL PATH $1; then
		       exec 9<$PATH
		       read -u9	ICONIFY
		       # Extract and restore our iconified state
		       case $ICONIFY in
			       Iconified) DtSetIconifyHint $TOPLEVEL True;;
			       *) DtSetIconifyHint $TOPLEVEL False;
			esac
		       # Extract the list of workspaces	we belong in, convert
		       # them to atoms,	and ask	the workspace manager to relocate
		       # us to those workspaces
		       WS_LIST=""
		       while read -u9 NAME
		       do
			       XmInternAtom ATOM $(XtDisplay "-" $TOPLEVEL)
					       $NAME False
			       if [ ${#WS_LIST}	-gt 0 ]; then
				       WS_LIST=$WS_LIST,$ATOM
			       else
				       WS_LIST=$ATOM
			       fi
		       done
		       DtWsmSetWorkspacesOccupied $(XtDisplay "-" $TOPLEVEL)
				       $(XtWindow "-" $TOPLEVEL) $WS_LIST
		       exec 9<&-
		else
		       echo "DtSessionRestorePath FAILED!!"
		       exit -3
	       fi
       }
       ################## Create the Main UI #######################
       XtInitialize TOPLEVEL wmProtTest	Dtksh "$@"
       XtCreateManagedWidget DA	da XmDrawingArea $TOPLEVEL
       XtSetValues $DA height:200 width:200
       XmInternAtom SAVE_SESSION_ATOM $(XtDisplay "-" $TOPLEVEL)
		       "WM_SAVE_YOURSELF" False
       # If a command-line argument was	supplied, then treat it	as the
       # name of the session file
       if (( $#	> 0))
       then
	       # Restore to the	state specified	in the passed-in session file
	       XtSetValues $TOPLEVEL mappedWhenManaged:False
	       XtRealizeWidget $TOPLEVEL
	       XSync $(XtDisplay "-" $TOPLEVEL)	False
	       RestoreSession $1
	       XtSetValues $TOPLEVEL mappedWhenManaged:True
	       XtPopup $TOPLEVEL GrabNone
       else
	       # This is not a session restore,	so come	up in the default state
	       XtRealizeWidget $TOPLEVEL
	       XSync $(XtDisplay "-" $TOPLEVEL)	False
       fi
       # Register the fact that	we are interested in participating in
       # session management
       XmAddWMProtocols	$TOPLEVEL $SAVE_SESSION_ATOM
       XmAddWMProtocolCallback $TOPLEVEL $SAVE_SESSION_ATOM
			       SessionCallback
       XtMainLoop

   Cooperating with WorkSpace Management
       The dtksh utility provides access to all	of the major workspace manage-
       ment functions of the desktop libraries,	including functions for:

	  o  Querying and setting the set of workspaces	with which an applica-
	     tion is associated.

	  o  Querying the list of all workspaces.

	  o  Querying and setting the current workspace.

	  o  Requesting	that an	application be	notified  any  time  the  user
	     changes to	a different workspace.

       From a user's perspective, workspaces are identified by a set of	names,
       but from	the workspace manager's	perspective, workspaces	are identified
       by  X  atoms.  Whenever	the  shell script asks for a list of workspace
       identifiers, a string of	X atoms	is returned; if	more than one  X  atom
       is present, the list is comma-separated.

       The  workspace manager expects that the shell script uses the same for-
       mat when	passing	workspace identifiers back to it. During a given  ses-
       sion,  it  is  safe for the shell script	to work	with the X atoms since
       they remain constant over the lifetime of the session. However, as  was
       shown  in  the  Session	Management  shell script example, if the shell
       script  is  going  to  save  and	 restore  workspace  identifiers,  the
       workspace  identifiers  must be converted from their X atom representa-
       tion to a string	before they are	saved. Then, when the session  is  re-
       stored,	the  shell script needs	to remap the names into	X atoms	before
       passing the information on to the workspace manager. Mapping between  X
       atoms  and  strings  and	between	strings	and X atoms uses the following
       two commands:

       XmInternAtom ATOM $DISPLAY $WORKSPACE_NAME false
       XmGetAtomName NAME $DISPLAY $ATOM

   Creating Localized Shell Scripts
       Scripts written for dtksh are internationalized,	and then localized, in
       a  process very similar to C applications. All strings that may be pre-
       sented to the user are identified in the	script;	a  post-processor  ex-
       tracts  the  strings  from  the script, and from	them builds a catalog,
       which can then be translated to any desired locale. When	the script ex-
       ecutes, the current locale determines which message catalog is searched
       for strings to display. When a string is	to be presented, it is identi-
       fied  by	a message-set ID (corresponding	to the catalog), and a message
       number within the set; these values determine what text the user	 sees.
       The following code illustrates the process:

       # Attempt to open our message catalog
       catopen MSG_CAT_ID "myCatalog.cat"
       # The localized button label is in set 1, and is	message	# 2
       XtCreatePushButton OK $PARENT ok
       labelString:$(catgets $MSG_CAT_ID 1 2 "OK")
       # The localized button label is in set 1, and is	message	#3
       XtCreatePushButton CANCEL $PARENT cancel
       labelString:$(catgets $MSG_CAT_ID 1 3 "Cancel")
       # Close the message catalog, when no longer needed
       catclose	$MSG_CAT_ID

       The  file descriptor returned by	catopen	must be	closed using catclose,
       and not using the sh exec command.

   Using the dtksh Utility to Access X Drawing Functions
       The commands of the dtksh utility include standard Xlib	drawing	 func-
       tions  to  draw lines, points, segments,	rectangles, arcs and polygons.
       In the standard C  programming  environment,  these  functions  take  a
       graphics	 context,  or  GC  as  an argument, in addition	to the drawing
       data.  In dtksh drawing functions, a collection of GC options are spec-
       ified in	the argument list to the command. By default, the drawing com-
       mands create a GC that is used for that specific	command	and then  dis-
       carded.	If the script specifies	the -gc	option,	the name of the	graph-
       ics context object can be passed	to the command;	this GC	is used	in in-
       terpreting  the command,	and the	variable is updated with any modifica-
       tions to	the GC performed by the	command.

       -gc GC	 GC is the name	of an environment variable that	 has  not  yet
		 been  initialized,  or	 which has been	left holding a graphic
		 context by a previous drawing	command.  If  this  option  is
		 specified, it must be the first GC option specified.

       -foreground color
		 Foreground  color, which can be either	the name of a color or
		 a pixel number.

       -background color
		 Background color, which can be	either the name	of a color  or
		 a pixel number.

       -font font name
		 Name of the font to be	used.

       -line_width number
		 Line width to be used during drawing.

       -function drawing function
		 Drawing function, which can be	any of the following: xor, or,
		 clear,	and, copy, noop, nor, nand, set, invert, equiv,	andRe-
		 verse,	orReverse or copyInverted.

       -line_style style
		 Line  style,  which  can  be any of the following: LineSolid,
		 LineDoubleDash	or LineOnOffDash.

   Setting Widget Translations:
       The dtksh utility provides mechanisms for  augmenting,  overriding  and
       removing	widget translations, much as in	the C programming environment.
       In C, an	application installs a set of translation  action  procedures,
       which  can  then	 be attached to	specific sequences of events (transla-
       tions are composed of an	event sequence and the associated action  pro-
       cedure).	 Translations  within  dtksh are handled in a similar fashion,
       except only a single action procedure is	available. This	action	proce-
       dure,  named  ksh_eval,	interprets any arguments passed	to it as dtksh
       commands, and evaluates them when the translation  is  triggered.   The
       following shell script segment gives an example of how translations can
       be used:

       BtnDownProcedure()
       {
	 echo "Button Down event occurred in button "$1
       }
       XtCreateManagedWidget BUTTON1 button1 XmPushButton $PARENT
	 labelString:"Button 1"
	 translations:'#augment
	     <EnterNotify>:ksh_eval("echo Button1 entered")
	     <Btn1Down>:ksh_eval("BtnDownProcedure 1")'
       XtCreateManagedWidget BUTTON2 button2 XmPushButton $PARENT
	 labelString:"Button 2"
       XtOverrideTranslations $BUTTON2
		'#override
	     <Btn1Down>:ksh_eval("BtnDownProcedure 2")'

EXAMPLES
       None.

SEE ALSO
       sh(1).

							       dtksh(user cmd)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | RESOURCES | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | SEE ALSO

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

home | help