% run this through LaTeX with the appropriate wrapper

\chapter {WIDGET}

WIDGET (Window Interface Developed at GEc hirsT)
is a simple Directory User Agent for X.500 Directory Services.
It is included only as an example of an X.500 interface, and how to
use the procedural interface, it is not considered to be fully developed.

WIDGET supports the following Directory operations:-
\begin{itemize}
\item bind
\item read
\item list
\item search
\item modify
\end{itemize}

WIDGET uses only a subset of these operations.  If you want to
use the full power of X.500 you should use the DISH interface described in
Chapter~\ref{dish}.

WIDGET is curses based, and splits the users screen up into a number of
small areas called ``widgets''.  Each widget is used to enter information.

\section {Types of Widget}

There are various types of ``widget'' used by the WIDGET program, these are
described in the following sections.

Each widget (except label widgets) have an identification
``letter'' associated with them,
this is indicated by the left most character in the widget, for example,
the widget below is identified by the letter ``\tt b\rm ''.

\begin{tabular}{|l|}
\hline
\tt b: bind\ \ \\
\hline
\end{tabular}

\subsection {Label Widgets}
Label widgets are used to simply write information to the screen, they do not accept
any form of input.

\subsection {Command Widgets}
A command widget is used to make the program take some kind of action, such as
send a {\em read} operation to the directory,
or to change the set of widgets displayed.
  
To issue the command type the letter indicated in
the widget. 

\subsection {Dialog Widgets}

Dialog widgets are used to get information from the user.
To use a dialog widget, press the letter associated with the widget.
Any further input from the keyboard will be entered into the widget,
a ``return'' character is used to end the input.

\subsection {Toggle Widgets}

Toggle widgets are used to select one of a set of pre-determined values.
Simply enter the widget letter, and the value will change the next value in
the circular list.

\section {Using WIDGET}

The WIDGET interface is invoked with the \pgm{widget} command.  

Help is given at any stage by typing `\tt ?\rm ', type `\tt q\rm ' to quit.

\subsection {Binding}

When run, the first set of widgets display are used to connect to a DSA.
You are allowed to change the name of the DSA you want to contact, the user
name and password.

The are also two widgets to select and read the cache file.  Caching is
described in section \ref {dua_cache}.

You can not proceed until you have successfully connected to a DSA, once
connected, the main options set of widgets will be displayed.

\subsection {Main Options}
The ``main options'' set of widgets, allow you to modify your 
current position in
the DIT, and select the {\em read, list, search} and {\em modify} set of
widgets.

The current position is entered into the ``goto'' dialog widget.  The QUIPU
format
for a distinguished name, described in many other places, is used.
The initial setting of this value is defined by your ``quipurc'' file. 
See section~\ref{quipurc}.

\subsection {Read}

The {\em read} set of widgets, allow you specify the node of the DIT you want to
read (Enter the name of the node in the ``base'' widget).
To read the node, activate the ``start'' command widget.
The result will be displayed in the text window at the bottom of the screen.
All results are cached, so future reads will be quicker.

\subsection {List}

The {\em list} set of widgets are used to list the children below the specified
node.
The default sizelimit parameter can be changed with the ``limit'' dialog
widget, a value of -1 specifies no size limit.

List results are cached.

\subsection {Search}

The {\em search} set of widgets are used to create a simple search filter to apply
to the directory.

Only a single filter item can be specified, and only string types can be
searched for.

The attribute type is selected with the ``type'' toggle widget, and the type
of match with the ``match'' toggle widget.
The search value is entered into the ``value'' dialog
(If a value is specified with a {\em present} match, the value is ignored).

The Distinguished names of entries found to match the filter are
displayed. The attribute data form the is cached, so that it can be looked at using the
read set of widgets.  


\subsection {Modify}

Modify is similar to search !!! That is you specify the type and value
required, and the type of operation.  With modify, the type widget is a
dialog widget, not a toggle widget.

The operations recognised are: {\em modify}, {\em add}, {\em remove}, {\em add value} and 
{\em remove value}.  
The {\em add value} and {\em remove value} options 
are used to manipulate multi valued
attributes, attempts to remove the last value, or add a value to a
non-existing attribute result in an error (as defined by the standards)

\subsection {Quitting}

There are a final set of widgets to quit the program.
They give you the option of saving the cache, then quitting, or just quitting.

When you leave the program, an ``unbind'' operation will be sent to the DSA
on your behalf.

