%\documentstyle[a4,11pt]{article}
\documentstyle{article}
%\documentstyle[palatino,a4,11pt]{article}

\author{Gustaf Neumann, Stefan~Nusser\\[.5cm]
{\sl neumann@wu-wien.ac.at, nusser@wu-wien.ac.at}\\[.5cm]
Wirtschaftsiuniversit{\"a}t Wien\\
Abteilung f{\"u}r Wirtschaftsinformatik\\
Augasse 2--6\\
A-1090 Vienna
}
\title{\Wafe -- \\ A Tcl Interface to the X Toolkit\\or\\
A Graphical Frontend for Applications in Various Programming Languages\\[.5cm]
Version: 1.0}

\setlength{\parindent}{0pt}
\setlength{\parskip}{5pt plus 2pt minus 1pt}

\def\Wafe{{{\em W\kern-.26em\lower.35ex\hbox{a}\kern.09em
    \raise.2ex\hbox{f}\kern.02em\raise.6ex\hbox{e}}\/}}
\def\Tcl{{\sc Tcl}\index{Tcl}}
\newcommand{\re}{\it}

\newdimen\defbr
\newdimen\erkl
\newdimen\diff
\newdimen\sepp

\erkl.35\textwidth
\defbr.30\textwidth
%\defbr.25\textwidth
\sepp1mm

\diff\erkl\advance\diff-\defbr
\long\def\returns#1{\goodbreak\medskip \nt{#1}\newline\nopagebreak}
\long\def\com#1#2{\goodbreak\medskip\te{#1}\ \arg{#2}\par\nopagebreak}
\long\def\ccom#1#2{\te{#1} \arg{#2}\par\nopagebreak}
\def\arg#1{{\it #1}}
\def\te#1{{\sf #1}\index{#1}}
\def\nt#1{{\it #1\/}}
\def\angs#1{{$\langle$#1$\rangle$}}
\newcommand{\hq}{$^?$}
\def\shortref{appendix \ref{short-reference} on page \pageref{short-reference}}
\def\xtref{\T{X Toolkit Intrinsics Reference Manual}\cite{OReillyRM}}
\def\T#1{{\em``#1''}}
%\typeout{erkl ist \the\erkl, defbr ist \the\defbr, diff ist \the\diff}

\newcommand{\I}{$\mid$}
\newcommand{\hstar}{$^*$}
\newcommand{\hplus}{$^+$}

\newenvironment{example}{\begin{quote}\begin{sl}}{\end{sl}\end{quote}}

\newenvironment{syntax}{
        \begin{raggedright}
	\begin{list}{ }{
		\setlength{\labelwidth}{\defbr}
		\setlength{\leftmargin}{\erkl}
		\setlength{\labelsep}{\sepp}
		\setlength{\topsep}{0cm}
		\setlength{\itemsep}{0.5ex}
		\setlength{\parsep}{0cm}
	}
}{\end{list}\end{raggedright}}

\newenvironment{cmdlineargs}{
	\begin{list}{ }{
		\setlength{\labelwidth}{1cm}
		\setlength{\leftmargin}{1cm}
		\setlength{\labelsep}{0cm}
	}
}{\end{list}}


\def\explain#1#2{\item[{\nt{#1}\hfill $\longrightarrow$\hspace{1em}}]{\rm #2}\nopagebreak}

\newenvironment{semantik}{\begin{list}{}{
		\setlength{\labelwidth}{.9\diff}
		\setlength{\leftmargin}{\diff}
		\setlength{\labelsep}{.1\diff}}
\item[]}{\end{list}}


\makeindex
\newenvironment{densi}%
{\begin{list}{$\bullet$}{\parsep0pt\itemsep0pt\topsep0pt}}{\end{list}}

\def\function#1#2#3#4{%   tcl-name x-name args
%\begin{densi}
\item[{\it f}] \strut
	{\bf #1}\index{#1} \dotfill {\sl #2}
	\ifx\@empty#2\else\index{#2}\fi
	\begin{list}{\hfill}%
	{\labelwidth2.3cm\leftmargin2.5cm\parsep0pt\itemsep0pt\topsep0pt}
	\item[\hbox to \labelwidth{Arguments:\hfill}] #3
	\item[\hbox to \labelwidth{Return value:\hfill}] #4
	\end{list}
%\end{densi}
}
\def\alias#1#2{%  alias tcl-name
\item[{\it f}] {\bf #1} \index{#1}\index{#2}\\
	alias; for arguments see: {\sl #2}
}

\def\widget#1#2#3{%  tcl-name x-name type
\item[{\it w}] {\bf #1} \dotfill {\sl #2}\index{#1}\index{#2}}

\def\pseudoWidget#1#2#3{%  tcl-name x-name class
\item[{\it w}] {\bf #1} \dotfill {\sl #2}\index{#1}\index{#2}\break
	for callbacks and functions see: {\sl #3}
}


\def\callback#1#2#3{%  tcl name x-name type
\begin{densi}
\item[{\sl c}] \strut
	\hbox to 5cm{\bf #1\hfill}%
	\hbox to 1 cm{#2\hfill}
	#3
\end{densi}
}
\def\callbackbeg#1{%  tcl name
\begin{densi} \item[{\sl c}] \strut \hbox to 5cm{\bf #1\hfill}}

\def\callbackmed#1{%  tcl name
\item[] \strut \hbox to 5cm{\bf #1\hfill}}

\def\callbackend#1#2#3{%  tcl name x-name type
\item[] \strut \hbox to 5cm{\bf #1\hfill} \hbox to 1 cm{#2\hfill} #3
\end{densi}}




\begin{document}
\maketitle

\begin{abstract}
\noindent \Wafe\ provides a flexible and easy to use interface to the
{\em X Toolkit} Release 4 or 5 (Xt), the {\em Athena} widget set
(Xaw) and (incomplete) to the OSF/Motif widget set (Xm). \Wafe\ is
implemented using the embeddable command language \Tcl. \Wafe\
allows access to Xt's functionality from all compiler and
interpreter languages, provided that they can communicate
unbuffered over {\em stdout} and {\em stdin}. Furthermore,
\Wafe\ can be used with \Tcl\ scripts for easily creating new
X Window Applications or user interfaces to existing Unix commands.
\end{abstract}


\clearpage
\tableofcontents
\clearpage
\def\supCmd#1#2{\footnote{The commands of #2 supported by \Wafe\ are 
listed in section \ref{#1} on page \pageref{#1}.}}

\section{Introduction}

\Wafe\ stands for {\em widget (Athena) front end} and provides an
interface to the X Toolkit. The name \Wafe\ is a historical leftover
and not fully appropriate since \Wafe\ supports not only the Athena
Widgets but also the Plotter Widget Set\supCmd{plotter}{the Plotter
widget set} and the OSF/Motif widget set.  The OSF/Motif support in
the current release is not complete, but should be sufficient for most
needs\footnote{The commands for OSF/Motif supported by \Wafe\ are
listed in sections \ref{motif11} and \ref{motif12}.}. In addition
\Wafe\ supports the XmGraph\supCmd{xmgraph}{the XmGraph widget} widget
(OSF/Motif only, for arbitrary graphs, directed or undirected) and
Mosaic's Hypertext Widget\supCmd{html}{the HTML widget} (based on
WWW's html) under Athena and OSF/Motif. Furthermore
\Wafe\ supports additional widespread packages such as XPM or RDD
(Drag and Drop library for drag and drop between multiple
applications\supCmd{rdd}{the drag and drop library}).

\Wafe\ can be used as a stand alone prototyping environment for X
Toolkit applications (interactive or using scripts) or as a frontend
to applications programs in various programming languages to provide a
graphical user interface without facing the need to enhance the
application languages with X Window and X Toolkit bindings. In addition
\Wafe\ can be used from the C language it the \Wafe-environment is 
linked together with another application program replacing the
standard \Wafe\ shell.

The basic idea of the frontend approach is to start an application in
two separate processes: one process is dealing purely with application
matters, the other one is responsible for the user interface. The two
processes communicate using sockets.  The application process writes
to stdout, its output is parsed and interpreted by the frontend. This
way the application process sends send commands or procedures to the
frontend process, which builds up the graphical user interface and
handles the incoming events.

The purpose of this manual is mostly to provide an overview of the
commands available in the \Wafe\ environment. A deeper discussion of
the design overview of \Wafe\ can be found in \cite{sandiego93}. A
more technical reference of the Widget sets and commands can be found
in \cite{OReillyPM,OReillyRM,XtDocu,AthenaDocu}. For more details
about the embeddable command language \Tcl\ refer to \cite{Tcl}.

The following section describes how to use \Wafe\ as a frontend and
the the command line arguments of \Wafe. Section
\ref{wafe-commands} describes the most important \Wafe\ commands (X
Toolkit specific commands, Athena Widget specific commands, XPM
\cite{xpm} specific commands). The Short Reference in \shortref\
was generated automatically from the \Wafe\ sources and provides the
complete set of \Wafe\ commands and the names of the X Toolkit or
OSF/Motif counterparts. The Short Reference is a complete assembly of
all \Wafe\ commands.


\subsection{Using \Wafe\ as a Frontend}

The way \Wafe\ communicates with the application process is controlled
by various command line arguments. If none of the options {\em -{}-d},
{\em -{}-e}, {\em -{}-f} or {\em -{}-v} is specified, the application
program will be started as a subprocess of \Wafe.  If the \Wafe\
application is called {\em myprog} and a link from \Wafe\ to the name
{\em xmyprog} is made, executing {\em xmyprog} starts \Wafe\ with
myprog as a subprocess.

\begin{verbatim} 
   ln -s /bin/X11/wafe xmyprog 
   xmyprog
\end{verbatim} 

If the local Unix variant does not support symbolic links, a hard link
may be used instead of the symbolic link in the example above.
\Wafe\ searches all directories in the path in order to spawn the
child-process {\em myprog} (the name is simply derived by removing
the leading character "x"). Alternatively the name of the
application program can be specified using the {\em -{}-p} command
line option.

\begin{verbatim} 
   wafe --p myprog 
\end{verbatim} 

The application {\em myprog} looses it's standard input and output
streams, diagnostic output will be merged with \Wafe's stderr.
\Wafe\ communicates with the application by reading it's stdout
and writing to the stdin stream. Commands to \Wafe\ must be prefixed
by a so called prompt character, defaulting to "\%", otherwise they are
just echoed to \Wafe's standard output. The prompt character can be
changed with the {\em -{}-c} command line option.  Furthermore, if
you want \Wafe\ to accept commands without prompt character, use
the {\em -{}-n} command line option (This means that the
application completely looses its output stream).

The application class is derivated from the link's name by
capitalizing the "x" and the first letter of the executable; any dots
will be substituted by dashes. This is the name, under which {\em X}
searches the application's defaults file. So, in our example, the
class is {\em XMyprog} and the corresponding app-defaults file will be
searched. The application instance name is the link's name with dots
substituted by dashes.

Command line arguments can be passed to the client with one
restriction: They mustn't begin with the characters "-{}-", since this is
reserved for \Wafe's arguments. Thus the command line

\begin{verbatim}
xmyprog filename --n 
\end{verbatim}

will cause \Wafe\ to spawn the process {\em myprog} with the
argument {\em filename}. The "-{}-n" is one of \Wafe's command
line arguments, which are described in the next section.


\subsection{Command Line Arguments}

The following command line options change the behavior of
\Wafe's communication mechanism:

\begin{cmdlineargs}

\item[{\bf -{}-c}{\it c}\hfill]

  This option simply allows the user to specify the prompt character
  which is not used if {\em -{}-n} is specified. It defaults to "\%".

\item[{\bf -{}-d}\hfill]

  Enter {\em direct mode}; this is a special mode, which is particulary
  useful for debugging or testing purposes. \Wafe\ can be used like a
  shell in this mode:
  \begin{verbatim}
  wafe --d --n
  \end{verbatim}
  Commands are now read from {\em stdin}, output is sent to {\em
  stdout}.  Additionally, the option {\em -{}-n} is recommended so that it
  is unnecessary to prefix every command with the prompt character.

  If \Wafe\ is called without any mode changing parameters or links, it
  will default to this interactive mode.

\item[{\bf -{}-e}\hfill]

  Takes the next argument to be a valid \Wafe\ command string and
  executes it. Note that \Wafe\ doesn't terminate automatically in this
  mode.

\item[{\bf -{}-f}\hfill]

  Run in {\em file mode}. The next argument after specifying {\em -{}-f}
  must be the name of a file containing valid \Tcl\ commands. The
  file will be executed by the \Tcl\ source command. 


\item[{\bf -{}-i}\hfill]

  Switches to {\em input mode}, which means that \Wafe\ reads
  from {\em stdin} (which it normally doesn't) and forwards the commands
  to the client-application. Be aware that programs using input-mode
  can't be executed in the background!

\item[{\bf -{}-n}\hfill]

  Turn of the prompt character mechanism. This causes \Wafe\ to
  regard every message it receives from the application as a
  \Wafe\ command.



\item[{\bf -{}-p}\hfill]
  Specify name of client program explicitly. The next argument after
  {\em -{}-p} must be the name of the program to be executed as client
  program.  This option can be used alternatively to the standard link
  mechanism described above where the leading ``x'' is stripped to
  derive the client program's name.

\item[{\bf -{}-v}\hfill]
  Displays the current version of \Wafe\ and exits immediately.

\item[{\bf -{}-C}{\it applicationClassName}]\hfill
  If this option is specified \Wafe\ will use the provided string as Xt
  application class.


\item[{\bf -{}-D}{\it option}]\hfill

   Starts \Wafe\ in {\em debug mode} and passes the specified
   {\em option} to the {\em debug library}. The following example 
   activates debugging and tracing (provided, wafe was compiled with
   the DBUG support enabled).
\begin{verbatim}
   wafe --Dd:t
\end{verbatim}
   The full set of debugging and profiling options can be found
   in the documentation of the debug library.


\item[{\bf -{}-S}{\it socketString}]\hfill

   This command line option can be used to communicate to \Wafe\
   (running typically as a subprocess of the application program)
   via sockets. Beginners my skip this point.

   {\em socketString} can be of the form
  
   \begin{enumerate}
	\item
	    {\em socketName}\hfill\break
            Example: \verb|--S/tmp/wafe.1052-1|
	\item
	    {\em portNumber}\hfill\break
            Example: \verb|--S8853|
	\item
	    {\em hostname:portNumber}\hfill\break
            Example: \verb|--Smohegan:8853|
   \end{enumerate}	

   If the {\bf -{}-S} option is used, \Wafe\ establishes during its
   initialization a socket communication determined by the {\em
   socketString} and connects its standard input and output to the
   created socket.

   \begin{enumerate}
	\item 
        If {\em socketString} is of the form {\em socketName},
        first the application program is responsible to create a
        unique socket name. Then it calls \Wafe\ with the -{}-S option,
        passing the socket name to \Wafe\.  \Wafe\ creates the specified
        unix domain socket (like a server) and waits, until the client
        application program connects.  \Wafe\ will remove the named
        socket on exit.

 	\item 
        If {\em socketString} is of the form {\em portNumber},
        \Wafe\ binds the specified port (like a server) and waits for
        the application program to connect on it. Note, that the
        specified port is blocked on the host for the whole \Wafe\
        session.

        \item If {\em socketString} is of the form {\em
        hostName:portNumber}, a simple two phase communication
        protocol is used to establish the connection.
         
        \begin{enumerate}
        \item
           In the first phase the application program on host {\em hostName}
           binds the specified port number (like a server), spawns \Wafe\ (for
           example using remote shell) with the option: 

           {\tt -{}-S{\em hostName}:{\em portNumber}}  

           \Wafe\ will connect to the specified host and port.

	\item
           In the second phase \Wafe\ will obtain a new unique port number, and
           establish itself as a sever listening on the new port. The
           Wafe will send the new obtained port number as a ASCII string
           to the application program over the primary socket.  The
           application program reads the new port number form the
           primary socket and will connect to \Wafe\ on the new port
           number and release the original port number such that another
           Wafe process can use {\em portNumber} as well.
	\end{enumerate}

     A sample implementation of an application program exploiting all
     three types of socket connections is provided in:\\
     {\tt wafe/apps/lang/sock.pl}
   \end{enumerate}

\item[{\bf -{}-T}{\it communicationChannels}]\hfill

  This option can be used to specify the file numbers of extra
  communication channel as a pair {\em wafeSide/clientSide}. See {\tt
  wafe/apps/util/wafe.pl} for an example usage.

\end{cmdlineargs}





\section{\Wafe's Predefined Variables}

During initialization \Wafe\ will set the \Tcl\ variables
{\em ARGC, ARGV} and {\em env} to the corresponding contents. {\em
ARGV} is C's argument vector in form of a \Tcl\ list, {\em ARGC} is its
length.  Starting with Version 0.96 \Wafe\ supports like tclsh {\em
argc, argv} and {\em argv0}. {\em argv0} is the program (or script)
name, {\em argv} is the argument list, {\em argc} is the length of
{\em argv}.  The older {\em ARGC} and {\em ARGV} will be dropped in
future versions.

The variable {\em tcl\_interactive} indicates whether \Wafe\ is
running in interactive mode or not (i.e. not in frontend mode, not as
a script; commands are accepted from a terminal).
 
The variable {\em XVERSION} is set to {\em R4} or {\em R5}, depending
under which version of X \Wafe\ was compiled. The variable {\em
WAFEVERSION} keeps the version number of \Wafe. {\em PACKAGES} is a
list of packages compiled into \Wafe. {\em PID} is the process id of
current process (similar to [pid] in tcl7.3). {\em CHILDPID} is the
process id of forked application program running as a coprocess of
Wafe (or 0).

The variable {\em WAFELIB} points to the location of the \Wafe\ library
(usually /usr/lib/X11/wafe).

The \Tcl\ variable {\em FILESEARCHPATH} is used locate bitmaps or pixmap
files for StringToBitmap or StringToPixmap converter (and for
bitmaps{\slash}pixmaps{\slash}gif files in HTML documents, when
compiled with Hypertext support).  For example:

\begin{footnotesize}
\begin{verbatim}
   set FILESEARCHPATH /usr/lib/X11/twm/%N:/usr/include/X11/%T/%N
   Command c topLevel bitmap ghostview.xpm
   realize
\end{verbatim}
\end{footnotesize}

In this example the file 'ghostview.xpm' will be searched first in 
/usr/lib/X11/twm and then in /usr/include/X11/bitmaps.

If wafe/mofe is compiled without XPM support, only .xbm files will be
converted. Wafe provides a reasonable default value for
FILESEARCHPATH. If the environment variable XFILESEARCHPATH is set,
its value will be used instead of the default. For a full documentation of
the percent codes in the FILESEARCHPATH see XtResolvePathname in \xtref.


\section{Widget Names and Widget References}
\label{widget-references}

Developing an user interface with Xt means creating instances of
widgets from a predefined widget set and arrange and configure these
according to application specific needs. Wafe supports the Athena
widget set, the OSF/Motif widget set, and several additional widgets
or widget sets (eg: Mosaic's HTML widget for hypertext applications
(can be used together with the Athena or OSF/Motif widget set), the
plotter widget set (linegraphs and bargraphs for Athena or OSF/Motif
(see section \ref{plotter}), the XmGraph widget (for arbitrary graph
structures; OSF/Motif only).

The created widgets can be composite or non-composite, whereas
composite widgets are commonly used for geometry management (defining
the graphical layout of an application). A composite widget and all
its children is commonly refered to as widget tree.

When an instance of a widget is created, the widget class defines its
attributes (resources) and its methods (mostly callbacks and actions
plus frequently additional procedures called the {\em programmatic
interface} in Xt terms).  

In \Wafe\ the creation of a widget is achieved through widget creating
commands (see section \ref{widget-create}). When a widget is created
the user provides a name and specifies a parent widget to determine
the position of new created widget in the widget trees of the
applicaton. So called application shells are the roots of the widget
trees and do not have parent widgets.

In general the names which are provided at widget creation time do not
have to be unique, but in many circumstances it is more conveniant if
they are. There are many situations where a user might want to refer
at a later time to a created widget:
\begin{itemize}
\item to change attributes of a widget,
\item to specify the position of a widget relative to another widget,
\item to apply procedures of its progammatic interface,
\item to delete a widget, and so on.
\end{itemize}
In order to refer to a widget, a widget reference is needed. The simplest
widget reference it the widget name (the name provided at widget creation).
However, since this name might be ambiguous, wafe provides the following
types of widget references:
\begin{itemize}
\item widget names
\item widget paths
\item widget IDs
\item anchored widget paths
\end{itemize}
A {\em widget path} starts with a widget name or the character ``*'',
followed by a widget name, followed optionally by ``*'' or ``.'' and
widget-name, where the optional part can be repeated several
times. Each time a widget is created, a unique {\em widget ID} is
returend, which can be used as wiget reference as well. Finally a
anchored widget path can be used to refer to a widget with a specified
name under a widget denoted by its widget ID: A {\em anchored widget
path} starts with an widget ID followed by ``*'' or ``.'' and a widget
name where the part after the widget id can be repeated several times.

Later in this text the term widget is commonly used instead of widget
reference in argument descriptions.

\section{\Wafe\ Commands}\label{wafe-commands}

In addition to the standard \Tcl\ commands, \Wafe\ makes
several new commands available for the client. 

Please note that according to the very nature of the {\em
Tcl\/} language and \Wafe's stream oriented communication
mechanism, every argument's type has to be {\em string}. Widgets, for
example, are always referenced by their names and conversions are done
as necessary.

For the description of the new commands, the following conventions
will be kept:

\begin{tabular}{ll}
\nt{expression}\hplus & means one or more occurrences of \nt{expression} \\
\nt{expression}\hstar & means zero or more occurrences of \nt{expression} \\
\nt{expression}\hq & means one or zero occurrences of \nt{expression} \\
\end{tabular}

To apply these rules on several arguments, angle brackets \angs{ } are
used. Terminal symbols are written in \te{sans-serif} and nonterminals
in \nt{italic} font style. Informal descriptions are typeset in the
normal text font style. Commands, which are different from their Xt
counterparts are described in detail, those which are added to
\Wafe\ without changes only have a short and informal description; it
is assumed that the user refers to the Xt programming and reference
manuals for a detailed description \cite{OReillyPM,OReillyRM}.




\subsection{Widget Creating Commands}\label{widget-create}

The widget creating all have the following structure:

\goodbreak\medskip \arg{widgetClass widgetName parentWidget \te{unmanaged}\hq \angs{attribute value}\hstar}\nobreak

\begin{syntax}
\explain{widgetClass}{\nt{athensWidgetClass \I\ motifWidgetClass \I\ others}}
\explain{widgetName}{string name of instance}
\explain{parentWidget}{widget reference to previously created parent widget 
        \I\ \te{topLevel}}
\explain{attribute}{attribute of this widgetclass, please refer 
	to a documentation of the widget set (eg.\
	\cite{OReillyRM} or \cite{AthenaDocu} for a complete 
        list of valid attributes). The \Wafe\ command \te{showRes} 
        can be used to display the names and types of attributes for 
        a created widget instance interactively}
\explain{value}{type, corresponding to the chosen attribute}
\end{syntax}

The names of the available widget classes depend on the compile
options of \Wafe. Below, only the names of the Athena widget classes are
listed (mostly for historical reasons).
\begin{syntax}
\explain{athenaWidgetClass}{\nt{shell \I\ simple \I\ menu \I\ text \I\ composite
	\I\ constraint}}
\explain{motifWidgetClass}{if \Wafe\ is compiled with OSF/Motif support,
       all its widgets are supported. Please refer to sections \ref{motif11} and       \ref{motif12}}
\explain{others}{depending on the compile options of \Wafe\ 
      the plotter widget set (refer to section \ref{plotter}), 
      the XmGraph widget (refer to section \ref{xmgraph}) and 
      the HTML widget (refer to section \ref{html}) might be supported}
\explain{shell}{\te{OverrideShell} \I\ \te{TransientShell} \I\
   \te{TopLevelShell}} 
\explain{simple}{\te{Command} \I\ \te{Label} \I\ \te{Grip} \I\ \te{Repeater}
	 \I\ \te{Toggle} \I\ \te{Scrollbar} \I\ \te{Tree} \I\
	\te{StripChart} \I\ \te{Panner} \I\ \te{List} \I\ \te{Mailbox}
	\I\ \te{Logo} \I\ \te{Repeater}} 
\explain{menu}{\te{SimpleMenu} \I\ \te{Sme} \I\ \te{SmeBSB} \I\
	\te{SmeLine} \I\ \te{MenuButton}} 
\explain{text}{\te{Text}}
\explain{composite}{\te{Box} \I\ \te{Porthole}}
\explain{constraint}{\te{Paned} \I\ \te{Viewport} \I\ \te{Form} \I\
   \te{Tree} \I\ \te{Dialog}} 
\end{syntax}

\begin{semantik}
   The defined constant {\em topLevel}, is used to reference the
   application's top level widget, which is created automatically at
   startup.. For a list of possible attribute{\slash}value pairs and
   detailed information about a widget's functionality compare to
   \cite{OReillyRM}\ or \cite{AthenaDocu}. If desired, a widget can be
   created without being managed by the parent by stating
   \te{unmanaged} after the parent's name. This can be advantageous if
   many widgets are created as children from the same parent or for
   dialog shells of the OSF/Motif widget set. They can be managed all
   together after the creation by using the \te{manageChild} command.
   
%   If \Wafe\ is compiled with the {\em At Plotter Widget Set}, the
%   following widgets are also available {\em AtPlotter, AtAxis,
%   AtXYLinePlot, AtLabelAxis, AtXYAxis, AtLinePlot, AtBarPlot} and {\em
%   AtTextPlot}. For their resources and programmatic interface check out
%   the documentation of the AtPlotter widget. 

   For a full list of all widget classes supported by \Wafe\ see the
   short reference guide in \shortref.
   
   Starting with version 0.96 attribute value pairs can be specified
   as either as a \Tcl\ list, or as separate arguments (like in earlier
   versions).
\end{semantik}

Note that the following command is the only exception from this
general structure of the widget creation commands.

\goodbreak\medskip \te{ApplicationShell} \arg{widget display 
\angs{attribute value}\hstar}\nobreak\par
\begin{syntax}
\explain{display}{string name of display}
\end{syntax}

\begin{semantik}
   Use this command to create a new application shell widget on the
   specified display, which will be the top of a new widget tree. Note
   that this shell widget can be iconified separately and is subject
   to the window manager's client decorations.
\end{semantik}




\subsection{Basic Toolkit Commands}

This section describes Xt specific commands. Most of these commands
correspond to commands described in the \xtref, where the leading {\em
Xt} or {\em Xaw} prefix
was removed. The \Wafe\ developer might wish to consult the {\em *Gen} 
files in the {\tt src} directory of the \Wafe\ distribution which are
used as input to the C generator. 


\subsubsection{Setting and Retrieving Resource Values}

\com{setValues}{widget \angs{attribute value}\hplus}
\ccom{sV}{\arg{widget \angs{attribute value}\hplus}}

\begin{semantik}
   Changes one or more attribute-value pairs of the specified widget.
   Conversion is done to the corresponding argument type. Note that
   some attributes, which have no string representations, can't be set
   by this command (eg the {\em colormap} attribute). This sort of
   attributes are either specified in \cite{OReillyRM} or have to be
   found out by trial and error. \Wafe\ allows the {\em callback}
   resource to be set to a \Tcl\ command.
   
   Starting with version 0.96 resource value pairs can be specified as
   either as a \Tcl\ list, or as separate arguments (like in earlier
   versions).
\end{semantik}


\returns{value}
\ccom{getValue}{\arg{widget attribute}}
\nopagebreak\nt{value}\newline
\ccom{gV}{\arg{widget attribute}}

\begin{syntax}
\explain{value}{string, actual data type depending on queried attribute}
\end{syntax}


\begin{semantik}
   The counterpart of \te{setValues} is \te{getValue}, which
   allows a specified attribute to be queried. Note that \Wafe\ tries
   to convert the result to the best possible string representation
   suitable for \Tcl. Some attributes are therefore returned in \Tcl\
   list structure (as for example the attributes of type
   \em{WidgetList}).
\end{semantik}


\subsubsection{Resource Management over Resource Database}

\com{mergeResources}{widget \angs{resName value}\hstar}

     \begin{syntax}
     \explain{widget}{widget to determine display}
     \explain{resName}{binding\hq  \angs{binding component}\hstar}
     \explain{binding}{"." \I\ "*"}
     \explain{component}{"A"-"Z" \I\ "a"-"z" \I\ "0"-"9" \I\ "\_" \I\ "-"}
     \end{syntax}

\begin{semantik}
   This command can be used to write one or more resource specifications
   into the resource database. It is useful to specify common resources
   of several widgets at the beginning of the application. Note that with
   \te{mergeResources} you can specify class names as well as instance
   names since the same syntax as in an application defaults file is
   used. Therefore your specification can, in contrast to the
   \te{setValues} command, be applied to several widgets
   in the application.
   
   Starting with version 0.96 resource value pairs can be specified
   as either as a \Tcl\ list, or as separate arguments (like in earlier
   versions).
\end{semantik}




\returns{string}
\ccom{getApplicationResource}{\arg{baseWidget resourceName resourceClass}}

     \begin{syntax}
     \explain{baseWidget}{widget reference}
     \explain{resourceName}{user provided name of additional resource}
     \explain{resourceClass}{user provided class name of additional resource}
     \end{syntax}

\begin{semantik}
     This command can be used to obtain values from the Xt's resource
     database. The provided \nt{resourceName} and \nt{resourceClass} 
     can be arbitrary, application specific strings and must not interfere
     with the widget's resources provided by the toolkit. 
     On success the return value is the resource value, on
     failure, an empty string is returned.


Example: the following resources are used for myApp
\begin{verbatim}
   myApp*printCmd: mp | lpr -pPs
\end{verbatim}
The application \verb|myApp| issuses the following command:
\begin{verbatim}
   set cmd [getApplicationResource topLevel \
       specificPrintCmd printCmd]
\end{verbatim}
to obtain the value for \verb|printCmd|.
\end{semantik}



\subsubsection{Obtaining Type and Class Information, Testing for Existance}

\returns{string}
\ccom{getClass}{\arg{widget}}

\begin{semantik}
   This function returns the class of a widget in form of a string 
\end{semantik}


\returns{string}
\ccom{getTypeOfAttribute}{\arg{widget attribute}}

\begin{semantik}
Use this function to determine the type of the given attribute 
in the  widgetclass of \nt{widget}. If the widgetclass does not have
an attribute with the given name, an empty string is returned.
\end{semantik}


\returns{int}
\ccom{isWidget}{\arg{widget}}

\begin{semantik}
This function returns 0 if no widget with the given name (widget path)
exists currently, otherwise non-zero.
\end{semantik}


\returns{widgetID}
\ccom{nameToWidget}{\arg{widget widgetPath}}

\begin{semantik}
            This command is a \Tcl{} binding for XtNameToWidget of Xt 
            and can be used to search for a widget specified in 
            \nt{widgetPath} in the widget tree under \nt{widgetRef}.
            If the command succeeds, the widget ID is returned,
            otherwise 0.
\end{semantik}


\returns{string}
\ccom{parent}{\arg{widget}}

\begin{semantik}
This function returns the name of the parent widget if the specified 
widget (widget path).
\end{semantik}


\returns{windowID}
\ccom{window}{\arg{widget}}

\begin{semantik}
      returns the window id of the specified widget.
\end{semantik}



\subsubsection{Managing, Mapping, Realizing and Destroying Widgets}

\com{mapWidget}{widget\hplus}
\begin{semantik}
   This function maps all specified widgets to the assoziated display
\end{semantik}

\com{unmapWidget}{widget\hstar}
\begin{semantik}
    This command takes any number of widgets as arguments and
        unmaps them. 
\end{semantik}


\com{manageChild}{widget\hstar}
\begin{semantik}
        This command takes any number of widgets as arguments and
        brings them under parental management. This is only necessary,
        when the widget creating commands are used with the
        \te{unmanaged} argument! 
\end{semantik}

\com{unmanageChild}{widget\hstar}
\begin{semantik}
        This command takes any number of widgets as arguments and
        removes them from parental management.
\end{semantik}


\com{realize}{}
\begin{semantik}
   This command realizes all top level application shells. The
   application's main shell with the name \te{topLevel} is created
   automatically.
\end{semantik}

\com{realizeWidget}{widget\hplus}
\begin{semantik}
   This function realizes all specified widgets. This command should
   only be used in cases where it is necessary to realize widgets
   separately. 
\end{semantik}

\com{unrealizeWidget}{widget\hstar}
\begin{semantik}
        This command takes any number of widgets as arguments and
        unrealizes them. 
\end{semantik}



\com{destroyWidget}{widget\hplus}
\begin{semantik}
	This command takes any number of widget-names as arguments,
	destroys them completely and releases all allocated resources. 
\end{semantik}







\subsubsection{Popup and Popdown Commands}

\com{popup}{popupShell grab}

\begin{syntax}
\explain{grab}{\te{none} \I\ \te{exclusive} \I\ \te{nonexclusive}}
\end{syntax}

\begin{semantik}
	{\em Shell} is the name of a previously (either with \te{
	TransientShell} or with \te{ OverrideShell}) created
	popup-shell. The kind of grab used is specified with
	\nt{grab}, which is the way how user events are constrained to
	the popup shell or its children. It can be one of the
	constants \te{none}, \te{nonexclusive} or \te{exclusive}.
\end{semantik}


\com{popupSpringLoaded}{popupShell}

\begin{semantik}
	This command displays the specified and previously created {\em shell}
	widget as a spring-loaded popup, which means that it is invisible to
	the window manager and disables user input to all windows except to
	the popup itself.
\end{semantik}


\com{popdown}{popupShell}

\begin{semantik}
   The command \te{popdown} ca be used to pop down a previously
   created and mapped popup shell. 
\end{semantik}


\returns{widgetList}
\com{popupChildren}{widget}

\begin{semantik}
   This command is similar to [gV Widget children] of a composite
   widget, but it returns the list of popup Shells (eg.:
   TransientShells) which are created as children of the given
   widget. Popup shells are not required to be children of composite
   widgets. If a widget has no popup children an empty list is
   returned.
\end{semantik}



\subsubsection{Modifying Sensitivity}

\com{setSensitive}{widget state}
\begin{semantik}
   The command \te{setSensitive} sets a widget and its children
   sensitive or insensitive depending on the boolean {\em state} argument
   (for details see XtSetSensitive in \xtref).
\end{semantik}


\com{setBusy}{widget state}
\begin{semantik}
   The command \te{setBusy} sets a given widget (typically a shell
   widget) and its children busy or not depending on the boolean {\em
   state} argument. If a widget is set busy a busy-cursor is set and
   input is inhibited for all children widgets. The appearance of the
   children widgets will not change.  If a shell is set busy and set
   non-busy some time later, all the sensitivity states before the
   setBusy command are reestablished.
\end{semantik}


\subsubsection{Raising and Lowering}

\com{raiseWindow}{widget}
\begin{semantik}
   The command \te{raiseWindow} raises the window of the specified
   {\em Widget}. For example {\tt raiseWindow topLevel} raises the
   topLevel shell.
\end{semantik}


\com{lowerWindow}{widget}
\begin{semantik}
   The command \te{lowerWindow} lowers the window of the specified
   {\em Widget}. 
\end{semantik}



\subsubsection{Translating Coordinates and Obtaining Sizes}

\com{translateCoords}{widget x y outX outY}

\begin{semantik}
This command translates {\em x} and {\em y} coordinates in the given widget 
into root window coordinates. After the execution the \Tcl\ variables
{\em outX}  and {\em outY} are bound with the resulting values.
\end{semantik}


\returns{int}
\ccom{widthOfScreen}{widget}

\begin{semantik}
   This function returns the width of the screen on which the
   specified widget is displayed in pixels.
\end{semantik}


\returns{int}
\ccom{heightOfScreen}{widget}
\begin{semantik}
   This function returns the height of the screen on which the
   specified widget is displayed in pixels.
\end{semantik}

\returns{int}
\ccom{textWidth}{widget fontResource string}
\begin{semantik}
   The function \te{textWidth} returns width of given \nt{string} in
   pixels using font from the \nt{fontResource} of the specified 
   \nt{widget}. This routine is necessary, as long we have no font to
   string converter.
\end{semantik}

\returns{int}
\ccom{fontHeight}{widget fontResource}
\begin{semantik}
            returns the height of a font in pixels. The font is
            taken is taken from the given \nt{fontResource} of the
            given widget.
\end{semantik}


\subsubsection{Locating Files}

\returns{string}
\ccom{resolvePathname}{widget type filename suffix path}

\begin{semantik}
   This function returns the fully qualified filename of a readable
   file with name {\em filename} and the specified {\em suffix} on the
   given {\em path}. {\em type} is either empty or the kind of file
   (eg. {\em bitmap} or {\em help}) and can be referred to via percent
   codes in the {\em path} argument. See XtResolvePathname in the
   \xtref\ for detailed information.  If no matching file can be located
   at the given path, tan empty string is returned.
\end{semantik}


\subsubsection{Terminating \Wafe}

\com{quit}{}

\begin{semantik}
   To terminate \Wafe\, use \te{quit}. To ensure that the spawned
   application process will also terminate, \Wafe\ sends it the {\em
   SIGTERM} signal. This -- of course -- won't happen in {\em file
   mode} or {\em direct mode}.

   When a Tcl procedure with the name \te{onExit} is defined by an
   application (without arguments), this routine will be executed
   whenever \Wafe\ exits.

\end{semantik}



\subsection{Callbacks and Actions}

The {\em X-toolkit} provides two mechanisms to link widgets to
application code: One of them are callbacks, easy to use for
predefined purposes, the other actions, which are more flexible and
configurable but involve a more complicated handling. This section
describes how these features are implemented in \Wafe, if your are not
familiar with the basic concepts of callbacks and actions please refer
to the Xt Programming Manual \cite{OReillyPM}. 

Callbacks which should be executed when certain widget specific
conditions occur (such as clicking with pointer button 1 in an Athena
Command widget) can be specified directly as resources during widget
creation or the \te{sV} command. The content of the callback resources
is a \Tcl\ command which should be executed. The content of a callback
resource can be retrieved using \te{gV}. When a callback is activated,
printf-like \% substitutions are performed in a first step.  In this
way \Wafe\ provides the functionality of {\em Xt\/}'s {\em call Data}
mechanism). The table below shows the \%-codes for the Athena widget.
Please refer to the short reference (in \shortref) for a complete
summary of the \%-codes. 

\begin{center}
\begin{tabular}{|l|l|l|l|l|}
\hline
{\em Widgets} & {\em Callback} & {\em Code} & {\em Description} & {\em Type}\\
\hline
all &  all      & \%w & name of widget & string\\
all &  all      & \%W & widget ID      & int\\
List & callback & \%i & index          & int\\
List & callback & \%s & active element  & string\\
Scrollbar & scrollProc & \%p & position & int\\
Scrollbar & jumpProc & \%p & percent & float\\
\hline
\end{tabular}
\end{center}

Please note that although different types are mentioned in the table,
all of these codes will be substituted by a string. The resulting
command string will be interpreted using \Tcl\ eval. To avoid 
unexpected side effects due to the substitution, characters like 
backslash, dollar or square brackets, which have special meanings in
\Tcl{} are escaped in \%s substitutions using a backslash. \%s should be
used inside double quoted strings.


\com{callback}{widget callbackResource type arg\hstar}

\begin{syntax}
\explain{callbackResource}{valid callback attribute of the specified widget}
\explain{type}{\te{none} \I\ \te{exclusive} \I\ \te{nonexclusive} \I\
	\te{popdown} \I\ \te{position} \I\ \te{positionCursor}}
\explain{arg}{additional arguments depending on type}
\end{syntax}

\begin{semantik}

	This command sets the callback resource of the named widget to
	one of Wafe's predefined Toolkit function. For valid \nt{types}
	refer to the following table. Note that the execution of a
	\Wafe\ command can be registered with the callback resource of a
	widget with the \te{setValues} command. 

\begin{center}
\begin{tabular}{|l|l|}
\hline
{\em Type} & {\em Description}\\
\hline
\te{none}           & realize a popup-shell, grab-type none\\
\te{exclusive}      & realize a popup-shell, grab-type exclusive\\
\te{nonexclusive}   & realize a popup-shell, grab-type nonexclusive\\
\te{popdown}        & unrealize a popup-shell\\
\te{position}       & position a popup-shell relative to its parent\\
\te{positionCursor} & position a popup-shell under the cursor\\
\hline
\end{tabular}
\end{center}

	According to the type used, {\em callback} takes the following
	additional arguments. 


\subsubsection*{Callback Types: none, exclusive, nonexclusive}


\com{callback}{widget  callbackResource \te{none} popupShell {\rm or}}
\ccom{callback}{widget callbackResource \te{exclusive} popupShell {\rm or}}
\ccom{callback}{widget callbackResource \te{nonexclusive} popupShell}

\begin{semantik}
   These callbacks all take one additional argument: {\em shell},
   specifying a popup-shell widget which will be realized with
   grab-type specified as \te{none}, \te{exclusive} or
   \te{nonexclusive}. Furthermore this callback will set the widget
   {\em widget} insensitive.
\end{semantik}


\subsubsection*{Callback Type: popdown}

\com{callback}{widget callbackResource \te{popdown} popupShell enableWidget}
\begin{syntax}
\explain{enableWidget}{name of a widget to be enabled after popdown}
\end{syntax}

\begin{semantik}
   This command registers a popdown callback for the specified
   widget. When the specified shell is popped down the widget
   {\em enableWidget} will be set sensitive.
\end{semantik}


\subsubsection*{Callback Type: position}

\com{callback}{widget callbackResource \te{position} baseWidget:offset}
\begin{syntax}
\explain{basis}{string name of a widget}
\end{syntax}

\begin{semantik}
   This command registers for the specified shell {\em widget} a popup
   callback that places the shell relative to another widget {\em
   baseWidget} and the specified offset.  The full syntax of the last
   parameter is {\em widgetname:xoffset/yoffset}.  If {\em yoffset}
   (and the slash) is omitted, {\em yoffset} is set to the value of
   {\em xoffset}. If {\em xoffset} is also omitted (no colon) {\em
   xoffset} and {\em yoffset} are set to the default value of 50.
\end{semantik}

For example the command
\begin{footnotesize}
\begin{verbatim}
callback d1 popupCallback position mainWindow:10/20
\end{verbatim}
\end{footnotesize}
registers a callback for a Dialog shell named {\tt d1} that will
position this shell with the xoffset 10 and the yoffset 20 from the
widget (of the same application) named mainWindow.


\subsubsection*{Callback Type: positionCursor}

\com{callback}{widget callbackResource \te{positionCursor} relPos}

\begin{semantik}
   This command registers for the specified shell \nt{widget} a
   popup callback that places the shell relative to the current cursor
   with the specified offset \nt{relPos}. If \nt{relPos} equals 0
   the shell will be centered over the cursor position.
\end{semantik}
\end{semantik}

For example the command
\begin{footnotesize}
\begin{verbatim}
callback d2 popupCallback positionCursor 40
\end{verbatim}
\end{footnotesize}
registers a callback for a Dialog shell named {\tt d2} that will
position this shell 40 pixel left and 40 pixel up above the cursor
when {\tt d2} is popped up.


\com{action}{widget type translations}

\begin{syntax}
\explain{type}{\te{augment} \I\ \te{override} \I\ \te{replace}}
\explain{translations}{string translation table -- refer to the Xt
	Reference Manual \cite{OReillyRM}, Appendix F, for a detailed description.}
\end{syntax}

\begin{semantik}
This command allows the {\em translations} resource to be modified. The
\nt{type} argument specifies, how the new bindings are merged with the
existing ones: \te{override} means that a translation specified for
an existing event overrides the old action, \te{augment} defines
precedence for the existing values. The use of \te{replace} means the
total replacement of the previous bindings by the translation table
specified.

If you are using the \te{replace} or \te{override} directives, you
will need information about a widget's actions and default bindings in
order to avoid conflicts with your own translations.  For a complete
description including the new R5 widgets refer to the MIT
documentation \cite{AthenaDocu}.

In addition to the standard Xt actions, \Wafe\ provides a feature for
binding the execution of a \Tcl\ command to an event. The globally
registered action

\ccom{exec}{(string\hstar)}

takes any number of strings as arguments, which compose together a
valid \Tcl\ command and arranges for it to be executed. Note that due to
the way Xt handles arguments to actions, you must not use a comma (",")
in the command, since it will be regarded as an argument separator and will
not be passed to the action!

	\begin{example} 

	Assuming an application with an Text
        widget named {\tt text}, the following statement will arrange
        for the contents of the Text widget to be sent to the
        application by specifying a translation for a Key event.

\begin{footnotesize}
\begin{verbatim}
action text override \
      {Meta<Key>s: exec(echo [gV text string])}
\end{verbatim}
\end{footnotesize}


	Whenever the key {\tt s} is pressed while the Meta-key is held
	down inside the text widget, the contents of it will be sent to the
	application.

	\end{example}

One of the big advantages in using actions instead of callbacks is the
possibility to access information from the event which triggered the
execution. This feature is supported in a restricted fashion by the
\te{exec} action with printf-like \% codes. The valid events and the
possible codes are  

\begin{itemize}
\item ButtonPress, ButtonRelease, MotionNotify
\item KeyPress, KeyRelease
\item EnterNotify, LeaveNotify
\item ClientMessage
\end{itemize}

\begin{center}
\begin{tabular}{|l|l|l|} 
\hline
{\em Code} & {\em Information} & {\em Valid Events}\\
\hline
\%t       & event type        & all of the above mentioned events \\
\%w       & widget            & all of the above mentioned events \\
\%W       & widget            & all of the above mentioned events \\
\%x       & x-coordinate      & all of the above mentioned events \\
\%y       & y-coordinate      & all of the above mentioned events \\
\%X       & x-root-coordinate & all of the above mentioned events \\
\%Y       & y-root-coordinate & all of the above mentioned events \\
\%a       & ascii-character   & KeyPress, KeyRelease \\
\%b       & number of button  & ButtonPress, ButtonRelease \\
\%k       & keycode           & KeyPress, KeyRelease \\
\%p       & protocol name     & ClientMessage \\
\%s       & keysym            & KeyPress, KeyRelease\\
\%S       & state             & ButtonPress, ButtonRelease, MotionNotify, \\
                             &&  KeyPress, KeyRelease\\
\hline
\end{tabular}
\end{center}

The user has to ensure by a corresponding binding in the translation
table that a \% substitution occurs only with a valid event type. The
\%t code will return \te{unknown} if the event is none of the above
mentioned. 

\begin{example}
   With the following translation a string containing the keycode,
   character and keysym will be sent to the application any time a key
   is pressed in a text widget called {\tt text}.

\begin{footnotesize}
\begin{verbatim}
action text override \
  {<KeyPress>: exec(echo K:%k C:%a KS:%s)}
\end{verbatim}
\end{footnotesize}
\end{example}
\end{semantik}


\com{installAccelerators}{destination source}

     \begin{syntax}
     \explain{destination}{widget in which events occur}
     \explain{source}{widget whose actions are invoked}
     \end{syntax}

\begin{semantik}

Accelerators provide a facility by which actions defined in one
widget can be triggered by events in another widget (refer to the Xt
Programming Manual \cite{OReillyPM}). The resource named 
\te{accelerators} of the \te{source} widget
should be set to the accelerator table before this
command is issued (eg. via the application default file).

The command \te{installAllAccelerators} installs the accelerators
from \te{source} and its children to \te{destination}.
 
Note that two directives controlling the merging process can be specified 
as a part of the accelerator table: \te{override} means that the accelerators have
precedence over the source widget's translations, \te{augment} means
that existing bindings can't be overridden by the accelerators.

\end{semantik}


\com{callCallbacks}{widget callback \angs{type data}}

     \begin{syntax}
     \explain{callback}{callback resource name}
     \explain{type}{{\sf float}}
     \explain{data}{string containing a value according to type}
     \end{syntax}

\begin{semantik}

Callbacks can be called not only by the widget itself but also by the
application using \te{callCallbacks}. If it is desired to pass a
callData information to the callback procedure, this can be done by
specifying \te{type} and \te{data}, otherwise the callData argument
defaults to \te{NULL}. 

\end{semantik}


\com{callActionProc}{widget eventInfo action arg\hstar}

     \begin{syntax}
     \explain{eventInfo}{{\sf "" \I\ \angs{buttonEvent \nt{button}} \I\ \angs{keyEvent \nt{key}}}}
     \explain{button}{{\sf button1 \I\ button2 \I\ button3 \I\ button4 \I\ button5}}
     \explain{key}{string containing a key}
     \explain{action}{string name of an action procedure}
     \explain{arg}{string}
     \end{syntax}

\begin{semantik}

This command can be used to explicitly invoke the action procedure
named \te{action} of \te{widget} with the string arguments \te{arg}.
The contents of the event union, which is passed to the action
procedure, can be influenced with the \nt{eventInfo} argument. If this
argument is empty, an {\em XAnyEvent} structure is passed to the
action. If \te{buttonEvent} is specified with a certain button, an
{\em XButtonEvent} structure is passed. This structure contains as the
{\em button} member the specified button, all other members are filled
automatically. Alternatively, an {\em XKeyEvent} structure can be
passed with the {\em keycode} member set according to the specified
key.

Please note that this command does not offer all the features of it's
Xt counterpart, which is due to the very complex structure of the XEvent
union.

\end{semantik} 

\com{removeCallbacks}{widget callback}

\begin{semantik}

The command \te{removeCallbacks} is used to un-register all callback
procedures currently associated with the callback resource
\te{callback} of \te{widget}.

\end{semantik}

\com{setWMProtocols}{widget protocol}
\begin{syntax}
\explain{widget}{Name of a widget}
\explain{protocol}{\te{WM\_TAKE\_FOCUS} \I\ \te{WM\_SAVE\_YOURSELF} \I\
\te{WM\_DELETE\_WINDOW}} 
\end{syntax}

\begin{semantik}
Use this command to set the WM\_PROTOCOLS property of the specified
widget's window (usually a shell widget) to one of the three
predefined values.
\end{semantik}



\subsection{Widget specific commands}




Besides of the commands which provide the basic functionality, \Wafe\
offers widget specific commands -- either for reasons of convenience
or because some Xt features had to be implemented in a different
manner. All of these commands are described in the following sections. 


\subsubsection{Scrollbar}


\com{XawScrollbarSetThumb}{scrollbarWidget top shown}

\begin{syntax}
\explain{scrollbarWidget}{name of a Scrollbar widget instance}
\explain{top}{string which contains a float value}
\explain{shown}{string which contains a float value}
\end{syntax}

\begin{semantik}
This command is not more than a convenience function for accessing the
top and shown attributes of a previously created Scrollbar widget.  It
moves the Scrollbar's thumb to a new position, where
\nt{top} specifies the position of the top and \nt{shown}
the length of the thumb, both as a fraction of the Scrollbar's total
length.

Using this command is saver than using \te{setValues}, because setting
a float attribute might cause problems on some systems. Note that this
command doesn't work if called from a Scrollbar's {\em jumpProc}
callback procedure.
\end{semantik}


\subsubsection{StripChart}


The StripChart widget class provides a real time chart of a single
value.  It's functionality is made accessible by the following
command.


\com{scSet}{stripChartWidget value}


\begin{syntax}
\explain{stripChartWidget}{name of a StripChart widget instance}
\explain{value}{string, which contains a double value}
\end{syntax}

\begin{semantik}
This command is used to specify a stripChart widget's current value.
The widget will plot a graph of this value by querying it every {\em
update} seconds. The {\em update} resource can be changed with a call
to \te{setValues}. 
\end{semantik}


\subsubsection{List}


\com{XawListUnhighlight}{listWidget}
\begin{syntax}
\explain{listWidget}{name of a previously created List widget}
\end{syntax}

\begin{semantik}
   This command unhighlights the highlighted element of a List widget.
   Only one element can be highlighted at a time, \te{XawListChange}
   unhighlights automatically the active element before performing the
   change.
\end{semantik}


\com{XawListHighlight}{listWidget index}

\begin{syntax}
\explain{index}{string containing an integer value}
\end{syntax}

\begin{semantik}
	This command highlights the specified element.
\end{semantik}

\returns{val}
\ccom{XawListShowCurrent}{listWidget}

\begin{syntax}
\explain{val}{name of a \Tcl\ array variable, having the elements
{\sf list\_index} and {\sf string}} 
\explain{val({\sf list\_index})}{string containing an integer value}
\explain{val({\sf string})}{string value}
\end{syntax}

	\begin{semantik}
	Use \te{XawListShowCurrent} to get the currently highlighted
	element and its index. Note that within a callback procedure,
	you can use the {\em \%i} and {\em \%s} substitution specifiers.
	\end{semantik}


\com{XawListChange}{listWidget nitems longest resize type arg\hplus}


\begin{syntax}
\explain{listWidget}{name of a previously created List widget}
\explain{nitems}{string containing a signed int}
\explain{longest}{string containing a signed int}
\explain{resize}{{\sf 1 \I\ 0}}
\explain{type}{{\sf Arg \I\ File \I\ List}}
\explain{arg}{string depending on type}
\end{syntax}

\begin{semantik}

   Use \te{XawListChange} to change the contents of \nt{list}. This
   command modifies the {\em list, longest} and {\em nitems}
   attributes.  If \nt{nitems} or \nt{longest} contain a value less
   than one, the List widget will calculate the actual value.
   
   The new contents of the \nt{list} widget can be specified in
   various ways depending on the value of the argument \nt{arg}.
   
   \ccom{XawListChange}{listWidget nitems longest resize \te{File} filename}
   \begin{syntax}
   \explain{filename}{valid Unix filename string}
   \end{syntax}

	\begin{semantik}
	In this case the new contents of \nt{listWidget} are read from the file
	\nt{filename} where each line is taken to be one list element. The
	carriage-returns and line-feeds are discarded!
	\end{semantik}

   \ccom{XawListChange}{listWidget nitems longest resize \te{Arg} element\hplus}
   \begin{syntax}
   \explain{element}{string}
   \end{syntax}

	\begin{semantik}
	Using the \te{Arg} type, the elements of the List widget can be
	specified as arguments to the \te{XawListChange} command. Each 
	argument is regarded as one list element.
	\end{semantik}

   \ccom{XawListChange}{listWidget nitems longest resize \te{List} contents}
   \begin{syntax}
   \explain{contents}{\Tcl\-list}
   \end{syntax}

	\begin{semantik}
	When \te{List} is specified as contents type, 
        the elements of listWidget are specified in a \Tcl\ list. Each 
	element of the \Tcl\ list is regarded as one element of the
        List widget.
	\end{semantik}

   If the execution of a \Tcl\ command is registered with the callback
   attribute called {\em callback}, the current element and it's index
   can be accessed with the \%i and \%s substitution codes (see also
   \te{callback}).

   The contents of a List widget can also be changed via {\em
   setValues}.  Be sure that at any time the {\em numberStrings}
   resource is set to a value equal or lower to the number of strings
   in the list. Otherwise the List widget produces an unfriendly core
   dump.
\end{semantik}


\com{XawListAppend}{listWidget element\hplus}
\begin{semantik}
   This command can be used to append one or more elements to an existing
   list. It is no generic Athena command; the array of strings is merely
   rebuild with the new values appended and afterwards the value of the
   {\em list}  resource is updated.
\end{semantik}


	\begin{example}
	The following program creates an instance of the List widget class, 
	reads in the contents of
	the current directory and sends the name of the chosen file to the
	application.

	The first solution is implemented using the list resource of
        the List widget:
 
\begin{footnotesize}
\begin{verbatim}
#!/usr/bin/X11/wafe --f
List browse topLevel \
   callback {sV topLevel title "Selected: %s"} \
   list [split [exec /bin/ls -1] \n]
realize
\end{verbatim}
\end{footnotesize}

	The second solution is implemented using XawListChange:
 
\begin{footnotesize}
\begin{verbatim}
#!/usr/bin/X11/wafe --f
List browse topLevel \
   callback {sV topLevel title "Selected: %s"} 
XawListChange browse 0 0 1 List [split [exec /bin/ls -1] \n]]
realize
\end{verbatim}
\end{footnotesize}

	Assuming the user selects the file {\tt myprog} with the
        pointer, the window title will change to \T{You selected: myprog}.
	Note that {\tt split} and {\tt exec} are standard \Tcl\
        commands. For further information refer to the \Tcl\ manual 
        \cite{Tcl}. 
        \end{example}



\subsubsection{Text}


One of the most important widget classes is the Text widget class.
Note that a great part of Text's functionality can be accessed via
actions -- if you want them to be triggered by the application rather
then by the user, use
\te{callActionProc}. Note that not all of the functions begin with
"XawText", since some of them are made available by Text's
subparts. All of these command expect as first argument an instance
of the Text widget class (named \nt{textWidget} below).


\com{XawAsciiSaveAsFile}{textWidget filename}


	\begin{semantik}
	This command saves the contents of \nt{textWidget} 
	to the specified
	file, regardless whether a file or a string is edited.
	\end{semantik}


\returns{result}
\ccom{XawAsciiSave}{textWidget}

\begin{syntax}
\explain{result}{1 \I\ 0}
\end{syntax}

	\begin{semantik}
	This command writes out the contents of an Text widget of type {\em
	file}, given that you made any changes since the last save.
	\end{semantik}


\returns{result}
\ccom{XawAsciiSourceChanged}{textWidget}

\begin{syntax}
\explain{result}{1 \I\ 0}
\end{syntax}

	\begin{semantik}
	Use this function to determine whether the source has changed
	since the last save.
	\end{semantik}


\com{XawTextSinkSetTabs}{textWidget tab\hstar}

\begin{syntax}
\explain{tab}{string which contains an integer}
\end{syntax}

	\begin{semantik}
	Use this command to specify the distances between {\em
	Text\/}'s tab\-stops. The unit which is used to measure the
	distance is the width of a figure in the used font.
	\end{semantik}


\com{XawTextSetSelectionArray}{textWidget selectType\hstar~\te{selectNull}}

\begin{syntax}
\explain{selectType}{\te{selectAll} \I\ \te{selectChar} \I\ \te{selectLine} \I\
	\te{selectParagraph} \I\ \te{selectPosition} \I\ \te{selectWord}}
\end{syntax}


\begin{semantik}
This command is used to configure the Text widget's behavior for
multi click text-selections. Each \nt{selectType} argument corresponds
to one click, the last argument must be \te{selectNull}. If an
internal timeout value is exceeded, the widget restarts counting.
\end{semantik}


\returns{textPosition}
\ccom{XawTextSearch}{textWidget scanDir txt}

\begin{syntax}
\explain{textPosition}{string containing a long integer value}
\explain{scanDir}{\te{left} \I\ \te{right}}
\explain{txt}{name of a \Tcl\ array variable having the members 
	\te{firstPos}, \te{ptr} and \te{length}}
\explain{txt(\te{firstPos})}{string containing an integer value}
\explain{txt(\te{length})}{string containing an integer value}
\explain{txt(\te{ptr})}{a string}
\end{syntax}

	\begin{semantik}

	Use \te{XawTextSearch} to search in the text displayed by the text
	widget for the beginning of the specified textBlock. This command
	returns a value less than 0 upon unsuccessful termination, otherwise
	the position of the beginning of the searched block.

		\begin{example}
	
		The following example searches in the text of an 
                Text widget named \te{text} for the word
                \te{example} and moves the insertion Point 
		to this location.

\begin{footnotesize}
\begin{verbatim}
set textBlock(ptr) "example"
set textBlock(length) 7 		
set textBlock(firstPos) 0
textSetInsertPosition text \
   [XawTextSearch text right textBlock]
\end{verbatim}
\end{footnotesize}


		\end{example}

	In most cases, when a C-function takes a structure as an
	argument, we implemented the corresponding \Wafe\ command in
	this style. Usually the members of the \Tcl\ array have
	the same names as the C-language structure members.

	\end{semantik}


\returns{read}
\ccom{XawTextSourceRead}{textWidget begin txt length}

\begin{syntax}
\explain{read}{string containing a long integer value}
\explain{begin}{string containing a long integer value}
\explain{length}{string containing an integer value}
\explain{txt}{name of a \Tcl\ variable to be set as result; it
	will have the following members: \te{firstPos}, \te{length}
	and \te{ptr}} 
\explain{txt(\te{firstPos})}{string containing an integer value}
\explain{txt(\te{length})}{string containing an integer value}
\explain{txt(\te{ptr})}{a string}
\end{syntax}

	\begin{semantik}

	Use \te{XawTextSourceRead} to read the text of the specified
	widget. It may take several calls to this function to read
	the requested amount of text; the number of characters
	actually read is returned and can be compared to the requested
	number.

	\end{semantik}


\returns{found}
\ccom{XawTextSourceScan}{textWidget begin boundary direction count include}
\begin{syntax}
\explain{found}{string containing a long integer}
\explain{begin}{string containing a long integer}
\explain{boundary}{\te{position} \I\ \te{whiteSpace} \I\ \te{EOL} \I\
	\te{paragraph} \I\ \te{all}}
\explain{direction}{\te{left} \I\ \te{right}}
\explain{count}{string containing an integer}
\explain{include}{\te{true} \I\ \te{false}}
\end{syntax}

	\begin{semantik} 

	Use this command to search the widget from \nt{begin} on in
	the specified direction for one of the predefined boundaries.

	\end{semantik}


\com{XawTextInvalidate}{textWidget begin end}
\begin{syntax}
\explain{begin}{string containing a long integer value}
\explain{begin}{string containing a long integer value}
\end{syntax}

	\begin{semantik}
	This function causes the specified range from \nt{begin} to \nt {end}
	to be redisplayed.
	\end{semantik}


\returns{lines}
\ccom{XawTextSinkMaxLines}{textWidget height}
\begin{syntax}
\explain{lines}{string containing an integer value}
\explain{height}{string containing a long integer value}
\end{syntax}

	\begin{semantik}
	This command returns the maximum number of lines that will fit
	in a window with the specified height.
	\end{semantik}

\returns{height}
\ccom{XawTextSinkMaxHeight}{textWidget lines}
\begin{syntax}
\explain{height}{string containing an integer value}
\explain{lines}{string containing an integer value}
\end{syntax}

	\begin{semantik}
	Calculates the height that will taken by the specified number
	of lines.
	\end{semantik}


\com{XawTextEnableRedisplay}{textWidget}

	\begin{semantik}
	This function flushes any changes due to patched updates.
	\end{semantik}


\com{XawTextDisableRedisplay}{textWidget}

\begin{semantik}
To disable redisplay while making several changes use
\te{XawTextDisableRedisplay}. 
\end{semantik}


\com{XawTextDisplay}{textWidget}

	\begin{semantik}
	This function forces redisplay of all accumulated updates.
	\end{semantik}

\returns{topPosition}
\ccom{XawTextTopPosition}{textWidget}

\begin{syntax}
\explain{topPosition}{a string containing a long integer value}
\end{syntax}

	\begin{semantik}
	Obtain the character position of the left-most character of the first
	line displayed.
	\end{semantik}


\com{XawTextSetInsertionPoint}{textWidget insertPosition}

\begin{syntax}
\explain{insertPosition}{string containing a long integer value}
\end{syntax}

	\begin{semantik}
	Use this convenience function to set the value of the 
	\te{insertPosition} resource.
	\end{semantik}	


\returns{insertPosition}
\ccom{XawTextGetInsertionPoint}{textWidget}

	\begin{semantik}
	Use this convenience function to get the value of the
	\te{insertPosition} resource. 
	\end{semantik}		

\com{XawTextDisplayCaret}{textWidget trueFalse}

\begin{syntax}
\explain{trueFalse}{\te{true} \I\ \te{false}}
\end{syntax}

	\begin{semantik}
	This convenience function can be used to modify the value of
	the \te{displayCaret} resource.
	\end{semantik}

\com{textGetSelectionPosition}{textWidget beginVar endVar}

\begin{syntax}
\explain{beginVar}{name of a \Tcl\ variable}
\explain{endVar}{name of a \Tcl\ variable}
\end{syntax}

	\begin{semantik}
	Use this function to retrieve the text, which is currently
	selected. It will set the two \Tcl\ variables as
	specified by the arguments. If the values are equal, nothing
	is currently selected!
	\end{semantik}
 
\com{XawTextSetSelection}{textWidget begin end}

\begin{syntax}
\explain{begin}{string containing a long integer value}
\explain{end}{string containing a long integer value}
\end{syntax}

	\begin{semantik} 
	This function sets the PRIMARY selection
	buffer from character position {\em begin} to position 
	{\em end} and highlights this area.
	\end{semantik}

\com{XawTextUnsetSelection}{textWidget}

\begin{semantik}
To unhighlight a previously highlighted text use \te{XawTextUnsetSelection}.
\end{semantik}

\returns{result}
\ccom{XawTextReplace}{textWidget begin end txt}

\begin{syntax}
\explain{result}{\te{editDone} \I\ \te{positionError} \I\ \te{editError}}
\explain{begin}{string containing a long integer value}
\explain{end}{string containing a long integer value}
\explain{txt}{name of a \Tcl\ array having the members {\sf firstPos, ptr, length}}
\explain{txt(\te{firstPos})}{string containing an integer value}
\explain{txt(\te{length})}{string containing an integer value}
\explain{txt(\te{ptr})}{a string}
\end{syntax}

	\begin{semantik}
	Use this function to replace the text between {\em start} and
	{\em end}. 
	\end{semantik}


\com{XawAsciiSourceFreeString}{textWidget}

\begin{semantik}
  This function frees the memory which is allocated after a getValue
  command in order to build up the string. Note that this memory is
  automatically freed with the next getValue call!
\end{semantik}




\subsubsection{Tree}

\com{XawTreeForceLayout}{treeWidget}

\begin{syntax}
\explain{treeWidget}{name of previously created Tree widget instance}
\end{syntax}

\begin{semantik}
This command will force the Tree widget to recalculate its Layout and
to arrange its children. If the {\em autoReconfigure} resource is set
to false, this provides an efficient way to layout the tree.
\end{semantik}


\subsubsection{Form}


\com{XawFormDoLayout}{formWidget doLayout}

\begin{syntax}
\explain{formWidget}{name of previously created Form widget instance}
\explain{doLayout}{{\sf 1 \I\ 0}}
\end{syntax}

\begin{semantik}
When making several changes to the children of a form, it might be
desirable to set \nt{doLayout} to 0 until after all changes have
been made.
\end{semantik}



\subsubsection{Paned}



\com{XawPanedAllowResize}{panedChild allow}

\begin{syntax}
\explain{panedChild}{name of a Paned widget's child}
\explain{allow}{{\sf 1 \I\ 0}}
\end{syntax}

	\begin{semantik}
	Equivalent to changing the {\em allowResize} constraint resource of the
	specified child.
	\end{semantik}


\com{XawPanedSetMinMax}{panedChild min max}

\begin{syntax}
\explain{min}{string containing an integer}
\explain{max}{string containing an integer}
\end{syntax}

	\begin{semantik}
	Equivalent to setting the {\em min} and {\em max} constraint
	resources of the specified child.
	\end{semantik}


\com{XawPanedGetMinMax}{panedChild minVar maxVar}

\begin{syntax}
\explain{minVar}{name of a \Tcl\ variable}
\explain{maxVar}{name of a \Tcl\ variable}
\end{syntax}

	\begin{semantik}
	Equivalent to querying the {\em min} and {\em max} constraint
	resources of the child. The specified \Tcl\ variables
	will be set by the command.
	\end{semantik}


\com{XawPanedSetRefigureMode}{panedChild mode}

\begin{syntax}
\explain{panedChild}{name of a child widget of a Paned widget}
\explain{mode}{{\sf 1 \I\ 0}}
\end{syntax}

	\begin{semantik}
	Use this command to enable and disable automatic recalculation
	of pane sizes and positions.
	\end{semantik}

\returns{num}
\ccom{XawPanedGetNumSub}{panedWidget}

\begin{syntax}
\explain{num}{string containing an integer value}
\explain{panedWidget}{name of a previously created Paned widget}
\end{syntax}

	\begin{semantik}
	This functions returns the number of children. Note that the
	{\em Grip} widgets are children of the Paned widget as well!
	\end{semantik}


\subsubsection{Toggle}

\com{XawToggleChangeRadioGroup}{toggleWidget radioGroup}

\begin{syntax}
\explain{toggleWidget}{name of a previously created Toggle widget}
\explain{radioGroup}{name of a previously created Toggle widget \I\
	\te{NULL}.}
\end{syntax}

\begin{semantik}
Use this command to add \nt{toggleWidget} to an existing radio group
(\nt{radioGroup} can be any member widget of this group) or to remove
a Toggle from a radio group (by specifying \te{NULL} as
\nt{radioGroup}.
\end{semantik}


\com{XawToggleUnsetCurrent}{radioGroup}

\begin{semantik}
Use this command to un-set all toggles in the specified radio group.
\end{semantik}


\subsubsection{SimpleMenu}

\returns{entry}
\ccom{XawSimpleMenuGetActiveEntry}{simpleMenuWidget}

\begin{syntax}
\explain{entry}{name of an Object}
\explain{simpleMenuWidget}{name of a previously created SimpleMenu widget}
\end{syntax}

	\begin{semantik}
	This function returns the name of the currently active Object
	in the specified SimpleMenu widget
	\end{semantik}


\com{XawSimpleMenuClearActiveEntry}{simpleMenuWidget}

	\begin{semantik}
	This function un-highlights the currently selected entry.
	\end{semantik}




\subsection{Communication, Handlers and Events}


This section explains, how \Wafe's communication mechanism is used to
transfer commands and data between \Wafe\ and the application and how it
can be modified by handlers. Note that an essential part of this topic is the
use of the different command line arguments, which were already
described earlier. 

\subsubsection{The \te{echo} command}

\com{echo}{string\hplus}

\begin{syntax}
\explain{string}{character string}
\end{syntax}

\begin{semantik}

   Communication with the application is primarily facilitated by the
   command {\em echo}. It takes any number of strings as arguments,
   which are send to the application. In {\em direct mode} or {\em
   file mode}, {\em echo} will behave just like an ordinary print
   command, writing its arguments on standard output. (Refer eg to the
   \te{action} command in order to see an example).

\end{semantik}

\subsubsection{Handlers}


Handlers offer the possibility to change \Wafe's communication
mechanism. Normally, three streams are assigned to each application,
which are redirected as described in the introduction. The {\em
stdout\/} stream is echoed to the user, after being searched for
commands (beginning with the {\em prompt-character}), {\em stderr} is
merged with \Wafe's {\em stderr} and afterwards echoed to the user and
the application's {\em stdin} is normally used to receive inputs of
the frontend. An application running in {\em input mode} will
furthermore receive the typed input from the associated terminal.

This standard configuration can be changed by command line arguments
and by using handlers. The latter provide a mean to register a
certain command with \Wafe, which is to be executed whenever input is
pending on the specified stream. The use of handlers is facilitated by
the following commands.


\com{register}{\arg source command}
\begin{syntax}
\explain{source}{\te{stdin} \I\ \te{stdout} \I\ \te{stderr} \I\ \te{xioerr} 
\I\ \te{term} \I\ \te{quit} \I\ \te{int} \I\ \te{hup} \I\ \te{pipe}
\I\ \te{usr1} \I\ \te{usr2}
}
\explain{command}{valid \Wafe\ command string}
\end{syntax}

\begin{semantik}
   Use this command to install handler procedures, which are invoked
   under different conditions, as specified by the argument
   \nt{source}.  

   By specifying \te{stdin}, \te{stdout} or \te{stderr} as first
   argument, \nt{command} will be executed whenever data is pending on
   the corresponding stream. Before executing the command, \Wafe\ will
   update a global \Tcl\ variable called \te{STDIN}, \te{STDOUT} or
   \te{STDERR} according to the handler registered, which will contain
   the pending data. Note that \te{stdout} and \te{stderr} are named
   as they are seen in frontend mode from an application running as an
   subprocess of \Wafe. If the application writes to \te{stdout} or
   \te{stderr} the corresponding handler will be activated. If the
   frontend accepts an additional input from the terminal, a
   \te{stdin} handler can be registered. 

   The \te{stdout} handler is activated, when \Wafe\ is used in
   prompt mode, and \Wafe\ receives a buffer on the channel
   connected with stdout of the subprocess that does not start
   with the prompt character. This type of handler is typically used
   when \Wafe\ is used as a frontend. The following example shows the
   behaviour of this handler.

\begin{footnotesize}
\begin{verbatim}
wafe --d
%echo hi there!
hi there!
%register stdout {echo you typed <$STDOUT>}
asdadasd
you typed <asdadasd
>
%quit
\end{verbatim}
\end{footnotesize}

   The \te{stdin} handler is has to be explicitely turned on by the
   {\tt --i} command line option. Was this argument given, \Wafe\ will
   start listing at stdin and echo per default the incoming data to
   the client application (or to stdout if not running in frontend
   mode). Using the \te{register} command a \Tcl{} handler can be
   specified.

   The \te{stderr} handler can be only used in frontend mode an
   listens to the client programs stderr output.  Note that the
   registration of a handler procedure can change \Wafe's standard
   behavior: Registering an error-handler means that no error messages
   of the application will be echoed to the user's terminal.

   \Wafe\ allows XIO errors to be caught by using the constant
   \te{xioerr} as first argument to the \te{register} command. Note
   that this is a fatal error condition and that \Wafe\ will anyway
   try to kill the application program before exiting afterwards. This
   type of handler procedure facilitates therefore cleanup operations. 

   The remaining handler types refer to signal for which handler can
   be specified as \Tcl\ commands. For signal handlers it is also
   possible to specify {\em IGNORE} or {\em DEFAULT} in the
   \te{command} string which cause either to ignore a signal
   completely or to default to the standard system action (i.e.\ not
   using any \Wafe\ specific signal handler). The command \te{kill}
   (see short reference guide in \shortref) support the same signal types.
\end{semantik}

\com{unregister}{\arg source}
\begin{syntax}
\explain{source}{\te{stdin} \I\ \te{stdout} \I\ \te{stderr} \I\ \te{xioerr}
\I\ \te{term} \I\ \te{quit} \I\ \te{int} \I\ \te{hup} \I\ \te{pipe}
\I\ \te{usr1} \I\ \te{usr2}
}
\end{syntax}

\begin{semantik}
This command is used to unregister the corresponding handler,
which means that the default handler will be reinstalled.
\end{semantik}

Note that a handler procedure is called several times if the message
consists of more than one line (Lines are separated by carriage
returns). If more than one handler for the same input source is
registered, the most recently created one will be used.

\begin{example}
Assuming that the application consists of an Text widget named
{\tt text}, the following code will popup a warning shell,
whenever an error occurs in the application (\Wafe\ operates in
frontend mode).

\begin{footnotesize}
\begin{verbatim}
TransientShell errorShell text
Command errorMessage errorShell \
    callback {popdown errorShell} \
    background red
callback errorShell popupCallback positionCursor 20

register STDERR {
    sV error label $STDERR
    popup errorShell exclusive
}
\end{verbatim}
\end{footnotesize}


Whenever the application writes something on stderr, the popupshell
will pop up -- positioned under the cursor -- and display the error.
Note that the error is displayed in a Command widget, which means that
the shell can be dismissed by a button click.
\end{example}


\returns{inputID}
\ccom{addInput}{fileno handlerType tclVariable tclCommand}

  \begin{syntax}
  \explain{inputID}{handle, can be used to remove the input handler}
  \explain{handlerType}{\te{read}, \te{write}, \te{except} or \te{none}}
  \end{syntax}

\begin{semantik}
            This command can be used to add additional input
            handlers or exception handlers. If used with \te{read} as
            2nd argument, each time when data is ready the data
            is read and APPENDED to the specified \nt{tclVariable}
            and \nt{tclCommand} is executed. \te{addInput} returns an
            \nt{inputId}.

            Note that the ammount of data read might depend on
            the buffering of the operating system. If only the
            newly read data should be kept in the TclVariable,
            TclCommand should set it empty after processing its
            contents.

            If fileno corresponds to an open file, a busy loop
            is likely to occur (see wafe/src/tcl/addInput.tcl
            for an example).

	    As shipped, 16 additional input handlers can be
            added by the application program. Increasing this
            number needs recompilation.
\end{semantik}


\ccom{removeInput}{inputID}
\begin{semantik}
            removes an input added by addInput. inputId is
            returned from addInput.
\end{semantik}

\returns{integer}
\ccom{fileno}{tclFile readOrWrite}

  \begin{syntax}
  \explain{readOrWrite}{\te{read} or \te{write}}
  \end{syntax}

\begin{semantik}
            The function fileno returns for the file opened by
            using \Tcl{}'s open command the file descriptor.  For
            pipes the file descriptor might be different for
            reading or writing.
\end{semantik}


\subsubsection{The additional communication channel}

\Wafe\ provides an additional facility which is used mostly to transfer large
amounts of data from the application to the front end (eg the contents
of an Text widget). When the application process is started,
\Wafe\ creates an additional socket-based communication channel. The
following commands provide access to this feature.

\returns{fd}
\ccom{getChannel}{}

     \begin{syntax}
     \explain{fd}{string containing an integer value}
     \end{syntax}

\begin{semantik}

This command returns the file descriptor to be used by the
application, which is under UNIX a small integer referring to an open
file. Note that this way of communication can only be used if the
application is able to write directly to a file descriptor. This way
how to achieve this depends on the particular interpreter or compiler
of the application programming language.  So before the additional
communication channel is used, the file descriptor should be queried
and the information be sent to the application.

\end{semantik}


\com{setCommunicationVariable}{varName length command}

     \begin{syntax}
     \explain{varName}{Valid \Tcl\ variable name}
     \explain{length}{string containing an integer value}
     \explain{command}{valid \Tcl\ command string}
     \end{syntax}


\begin{semantik}

Use the command \te{setCommunicationVariable} to make the transferred
data availaible for the user interface. As soon as the data with
\nt{length} number of bytes is received, \Wafe\ will create the \Tcl\
variable \nt{varName}, which will contain the transferred data, and
execute \nt{command}. If the variable allready exists, the previous
contents will be deleted. Note that this command does not depend on
the data being allready availaible -- if the transfer is complete,
\nt{command} will be executed immediately, if \nt{length} bytes of
data are not yet received, the execution is delayed until the
transfer is complete. 

\end{semantik}


\subsubsection{Suspending/delaying Execution in  \Wafe, Event Processing}

\Wafe\ provides a simple means for suspending/delaying execution and 
synchronizing the handling of events via the procedure \te{waitForVariable}.

\com{waitForVariable}{varName}

     \begin{syntax}
     \explain{varName}{Valid \Tcl\ variable name}
     \end{syntax}


\begin{semantik}
    This command can be used to ``wait'' in a \Tcl{} command until a
    \Tcl{}-variable is set (eg from a callback or action
    routine). \te{waitForVariable} is commonly used for synchronization
    tasks.

    In a first step, waitForVariable unsets the specified GLOBAL \Tcl{}
    variable and enters a new event loop. This "inner" event loop will
    be left, when the specified variable is set.  The return value of
    waitForVariable is the value of the specified variable.

For example, in a sequence
\begin{verbatim}
                cmd1; waitForVariable x; cmd2; ...
\end{verbatim}
    \Wafe{} suspends until the \Tcl{} variable \verb|x| is set (eg.\ via
    callback procedures, actions or handlers). When the variable
    \verb|x| is set, the \Wafe\ commands \verb|cmd2| is executed.
\end{semantik}



\com{processPendingEvents}{}

\begin{semantik}
    The command \te{processPendingEvents} can be used within in a
    \Tcl{} procedure to process all pending events and to continue
    later in the same point; for example, this can be useful for
    refreshing the screen while computing heavily in \Tcl{}. Another
    application area for this command is wafeperl/mofeperl where the
    use can force screen refresh etc.\ while computing in Perl. 

    Note, that also callback or actions procedures might be triggered
    by \te{processPendingEvents}, which might issue arbitrary \Wafe{}
    commands and alter global variables etc.
\end{semantik}

\subsubsection{Communicating from an Application Program to \Wafe}

If \Wafe\ is used as a frontend, lines which are starting
with the prompt character (usually ``\%'') printed to stdout from
an application program are interpeted as \Wafe\ (\Tcl{}) commands.
Therefore, the remainder of these lines must be valid \Tcl\ statements,
using the appropriate quoting and escaping of literals.

In certain cases, the interpretation of the commands is undesired.
Uninterpreted data transfer can be achieved using the communication
channel explained above. However, for certain interpreted programming
languages, writing to the communication channel hard to achieve, or 
complicated. \Wafe\ provides starting with version 0.95 means for 
uninterpreted assignment from client applications to \Tcl\ variables.

If the application program running under \Wafe\ writes
\begin{verbatim}
%=myvar This will become the contents of myvar
\end{verbatim}
to stdout, the \Tcl\ variable {\tt myvar} is set to the string
starting with 'This' and ending with 'myvar'.

The uninterpeted assignment works as follows:
\begin{itemize}
\item
       If the first character after '\%' (or the character provided
       via the -{}-c option) is '=', the next space terminated token
       is used as a variable name, and the remainder of the line 
       is assigned to the named \Tcl\ variable.

\item
       If the character after the '\%' is a '+' followed by a
       space terminated token for the variable name, then the remainder
       is appended to the specified variable.

\item
       If the character after the '\%' is a '\verb+\+' followed by a
       space terminated token for the variable name, then the remainder
       and a newline character are appended to the specified variable.

\item
       If the character after the '\%' is a '\verb+/+' followed by a
       space terminated token for the variable name, then a newline 
       character and the remainder of the line to the specified variable.
\end{itemize}

Using this mechanism, ``virtual files'' can be implemented, which
write into \Tcl\ variables. An \T{open} command clears the specified
variable, a \T{write} command appends to it, a \T{newline} command appends
a newline and the \T{close} command just flushes stdout.




\subsection{The selection mechanism}


X defines an inter-program communication protocol (called ICCCM),
which allows X-window based applications to exchange data. This
facility is best known when text data is exchanged with the
cut-and-paste mechanism.
\Wafe\ provides simplified access to the exchange of text selections
with the following three commands.

\returns{Boolean}
\ccom{ownSelection}{selection \angs{\te{NULL} \I\ lostCom} \angs{\te{NULL} \I\ doneCom}}

\begin{syntax}
\explain{selection}{character string}
\explain{lostCom}{valid \Wafe\ command string}
\explain{doneCom}{valid \Wafe\ command string}
\end{syntax}

\begin{semantik}
Use the command \te{ownSelection} to claim ownership of the {\em
PRIMARY} selection. The specified string \nt{selection} will be placed
in the buffer and be available for other applications. This means it
can be "pasted" in a window of an application supporting this
communication protocol. 

This command takes two additional arguments, both of them valid
\Wafe-commands. By specifying \nt{lostCom}, a command can be
registered, which will be executed when the application looses
ownership of the {\em PRIMARY} buffer. If {\em doneCom} is specified,
the registered command will be evaluated whenever the selection
transfer process is complete (which normally means a paste action).
Specify the constant \te{NULL} if you do not want to use this feature.
\end{semantik}


\com{getSelectionValue}{selHandler}

\begin{syntax}
\explain{selHandler}{valid \Wafe\ command string}
\end{syntax}

\begin{semantik}
This command is the counterpart of \te{ownSelection}, it is used to
retrieve the current contents of the {\em PRIMARY} buffer. The
registered command string will be ececuted as soon as the selection
data is availaible. The global \Tcl\ variable \te{PRIMARY} will be set to
pass the requested information. This command can only be used if the
application is realized!
\end{semantik}


\com{disownSelection}{}

\begin{semantik}
This command can be used if the application explicitly wants to
disclaim its ownership of the {\em PRIMARY} buffer. Note that the
application automatically looses the ownership, whenever an other
application claims to be the owner.
\end{semantik}

A command registered with \te{getSelectionValue} will be %
invoked with an empty string if no data is currently selected.
Execution will not be postponed until selection data is availaible!
The selection mechanism shall be illustrated by the following example.

\begin{example}
The following \Wafe-script displays the current value of the
primary selection buffer using the label of a Command widget and
allows the user to  
\begin{itemize}
\item 
	set the selection buffer (Btn1) to the value of the label (eg.\
	the user has slected in the meantime another content, and
	wants to set the selection buffer to the old value of the label),
\item
	read again the selection buffer, set the label to the new
	value (Btn2) and to highlight the widget, while the button is
	pressed (this is achieved by the command widget action {\tt
	set()}, or to 
\item
	quit the program (Btn3).
\end{itemize}

\begin{footnotesize}
\begin{verbatim}
#!/usr/bin/X11/wafe --f
sV topLevel allowShellResize true
Command sel topLevel

action sel override  {<Btn1Down>: \
     exec(ownSelection [gV sel label]) set()}
action sel override  {<Btn2Down>: \
     exec(getSelectionValue {sV sel label $PRIMARY})}
action sel override  {<Btn3Down>: exec(quit)}

realize
getSelectionValue {sV sel label $PRIMARY}
\end{verbatim}
\end{footnotesize}


At startup, the program shows whatever is selected at this moment. The
user can make this text again the PRIMARY selection just by pressing
the left pointer button within the window. The application is
terminated by pressing the right button.

\end{example}

Beside of those commands, which are the counterparts of the highlevel Xt
functions, \Wafe\ offers also some of the lower level Xlib functions.
They can be used to modify the {\em primary\/} selection buffer as well as the
seven {\em cut buffers\/}. 

\com{convertSelection}{widget targetBuffer}

\begin{syntax}
\explain{widget}{widget to determine display}
\explain{targetBuffer}{{\sf 0 \I\ 1 \I\ 2 \I\ 3 \I\ 4 \I\ 5 \I\ 6}}
\end{syntax}

	\begin{semantik}
	Use \te{convertSelection} to request the current value of the
	{\em primary\/} selection and place it in cut buffer {\em
	targetBuffer\/} for further use.
	\end{semantik}

\returns{selection}
\ccom{fetchBuffer}{widget cutBuffer} 

\begin{syntax}
\explain{selection}{string value}
\explain{widget}{widget to determine display}
\explain{cutBuffer}{{\sf 0 \I\ 1 \I\ 2 \I\ 3 \I\ 4 \I\ 5 \I\ 6}}
\end{syntax}

	\begin{semantik}
	Use this function to retrieve the value of the specified cut
	buffer. 
	\end{semantik}

\returns{selection}
\ccom{fetchBytes}{widget}
\begin{syntax}
\explain{selection}{string value}
\explain{widget}{widget to determine display}
\end{syntax}

	\begin{semantik}
	Convenience function, which calls \te{convertSelection} and
	\te{fetchBuffer}. The value of the {\em primary} selection is
	returned. Note that the contents of cut-buffer-0 will get
	lost!
	\end{semantik} 


\com{storeBuffer}{widget value cutBuffer}

\begin{syntax}
\explain{widget}{widget to determine display}
\explain{value}{string value}
\explain{cutBuffer}{{\sf 0 \I\ 1 \I\ 2 \I\ 3 \I\ 4 \I\ 5 \I\ 6}}
\end{syntax}

	\begin{semantik}
	Use \te{storeBuffer} to make \nt{value} the content of the
	specified cut buffer.
	\end{semantik}


\subsection{Integration of the XPM image format}


\Wafe\ offers two commands, which provide -- together with Arnaud Le
Hors {\em xpm\/} library -- a mean to include multicolored images in
your application (For details please refer to the xpm documentation
\cite{xpm}). 

First of all, a new string-to-pixmap converter was registered.  Note
that most of the attributes which currently use bitmaps (eg the
resource {\em bitmap\/} of the Label widget) are actually of type {\em
Pixmap\/}. If a bitmap is specified, it is rendered using the {\em
foreground \/} and {\em background\/} colors, which are specified as
seperate resources. The new converter procedure first attempts to
convert the specified filename into a bitmap, using the standard Xt
algorithm. If this conversion fails, it tries to interprete the file
as an {\em xpm} image.

\begin{example}
Assuming that wafe.xpm is a file in valid xpm format located in the
current directory, the following \Wafe-script will generate an instance
of the Label widget class showing the image.

\begin{footnotesize}
\begin{verbatim}
#!/usr/bin/X11/wafe --f
Label image topLevel bitmap wafe.xpm
realize
\end{verbatim}
\end{footnotesize}
\end{example}

Please note that this conversion allocates color cells, which won't be
freed until the application terminates. The allocated resources are
managed by Xt's caching mechanism, which means that a pixmap which is
converted once, will be availaible for the application's lifetime.
Furthermore, if the pixmap file is not located in the current
directory, the filename has to be specified with an absolute path.

\com{changePixmap}{widget attribute filename}

\begin{syntax}
\explain{attribute}{an attribute of type {\em Pixmap}}
\explain{filename}{UNIX filename string \I\ \te{None}}
\end{syntax}

	\begin{semantik} 

	Use \te{changePixmap} to set a resource of type {\em Pixmap\/}
	to the specified image. Obviously, you could achieve the same
	result by using the following command

	\te{setValues} {\em  widget attribute filename}

	The main difference is that \te{changePixmap} keeps track of
	converted pixmaps. A pixmap can be released by setting the
        attribute to another pixmap or to one of the following values:
        \te{None}, \te{ParentRelative}, or \te{Unspecified}. If there
        are no references to a pixmap, all resources (allocated memory
        as well as color cells) of the pixmap are released. So it is
        up to you wether you want the benefits of Xt's caching
        mechanism or wether you prefer having the
	color cells again availaible. 

	\end{semantik}

\com{setIconPixmap}{widget filename}
\begin{syntax}
\explain{widget}{name of a shell widget}
\explain{filename}{UNIX filename string}
\end{syntax}

\begin{semantik}
This command can be used to generate a multicolor XPM-icon for the
specified shell widget. If clip-mask information is available it will
be used correctly.
\end{semantik}

\clearpage

\clearpage
\appendix
\section{Short Reference}\label{short-reference}


\subsection{Tookit Widgets and Commands}\label{xtoolkit}

\begin{itemize}
\input XtGen.tex
\end{itemize}

\subsection{Athena Widgets and Commands}\label{athena}

\begin{itemize}
\input XawGen.tex
\end{itemize}


\subsection{Athena R5 Widgets and Commands}\label{athena5}

\begin{itemize}
\input Xaw5Gen.tex
\end{itemize}


\subsection{Motif 1.1 Widgets and Commands}\label{motif11}

\begin{itemize}
\input XmGen.tex
\end{itemize}

\subsection{Motif 1.2 Widgets and Commands}\label{motif12}

\begin{itemize}
\input Xm12Gen.tex
\end{itemize}

\subsection{XmGraph Extension to Motif Widgets}\label{xmgraph}

\begin{itemize}
\input XmGrGen.tex
\end{itemize}





\subsection{Plotter Widget and Commands}\label{plotter}

\begin{itemize}
\input AtGen.tex
\end{itemize}


\subsection{HyperText (html) Widget and Commands}\label{html}

\begin{itemize}
\input htmlGen.tex
\end{itemize}


\subsection{Drag and Drop Commands}\label{rdd}

\begin{itemize}
\input rddGen.tex
\end{itemize}





\subsection{Miscelaneous Additional Commands}\label{misc}

\begin{itemize}
\input MiscGen.tex
\end{itemize}


\input wafedoc.ind


\begin{thebibliography}{99}

\bibitem{OReillyRM}  David Flanagan, {\em X Toolkit Intrinsics
		     Reference Manual\/}, Third Edition, O'Reilly and
		     Associates Inc., 1990. 

\bibitem{xpm}        Arnaud Le Hors, {\em The X PixMap Format\/},
                     Part of the xpm distribution, 1991.


\bibitem{XtDocu}     Joel McCormack, Paul Asente and Ralph Swick, {\em X
                     Toolkit Intrinsics -- C Language Interface\/}, 
                     Massachusetts Institute of Technology, 1990.

\bibitem{sandiego93} Gustaf Neumann, Stefan Nusser, {\em Wafe - An X
		     Toolkit Based Frontend for Application Programs
		     in Various Programming Languages \/}, Proc.
		     USENIX Winter Conference, January 1993.

\bibitem{OReillyPM}  Adrian Nye -- Tim O'Reilly, {\em X Toolkit Intrinsics
                     Programming Manual\/}, Second Edition, O'Reilly
                     and Associates Inc., 1990.

\bibitem{Tcl}        John K. Ousterhout, {\em Tcl\index{Tcl}: An
                     Embeddable Command 
                     Language\/}, Proc. USENIX Winter Conference, January
                     1990.

\bibitem{AthenaDocu} Ralph Swick -- Terry Weissman, {\em X Toolkit Athena
                     Widgets -- C Language Interface\/}, Massachusetts
                     Institute of Technology, 1990.


\end{thebibliography} 

\end{document}
