% -*- Mode:TeX -*-
%%% 
%%% TEXAS INSTRUMENTS INCORPORATED, P.O. BOX 149149, AUSTIN, TX 78714-9149
%%% Copyright (C) 1989, 1990 Texas Instruments Incorporated.  All Rights Reserved.
%%% 
%%%     Permission is granted to any individual or institution to use,
%%%     copy, modify and distribute this document, provided that  this
%%%     complete  copyright  and   permission  notice   is maintained,
%%%     intact, in  all  copies  and  supporting documentation.  Texas
%%%     Instruments Incorporated  makes  no  representations about the
%%%     suitability of the software described herein for any  purpose.
%%%     It is provided "as is" without express or implied warranty.
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                 %
%                            Preamble                             %
%                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentstyle[twoside,11pt]{report}
\pagestyle{headings}
%%
%% Inserted from home:/usr/local/hacks/tex/setmargins.tex:
%%
%%    Original: Glenn Manuel 12-17-86
%%    Added optional [printer-offset]: Glenn Manuel 2-27-87
%% Sets the margins, taking into account the fact that LaTex
%% likes to start the left margin 1.0 inch from the left edge
%% of the paper.
%%   This macro prints on the screen and in the log file
%%   the values it sets for:
%%     Textwidth, Odd Page Left Margin, Even Page Left Margin,
%%     Marginparwidth, Printer Offset
%%     (the values are in points: 72.27 pts/inch).
%%     The Odd and Even Page Left Margins include LaTeX's
%%     built-in 1.0in offset, but NOT the [printer-offset],
%%     so these values always indicate what the actual
%%     printout SHOULD measure.
%%
%% USAGE:  Place the following between the
%%         \documentstyle   and  \begin{document} commands:
%% \input{this-file's-name}
%% \setmargins[printer-offset]{line-length}{inside-margin-width}
%%
%%   where ALL arguments to \setmargins are DIMENSIONS
%%           like {6.5in}, {65pt}, {23cm}, etc.
%%   The units MUST BE SUPPLIED, even if the dimension is zero {0in}.
%%
%%   [printer-offset] is optional.  Default is zero.
%%
%%   Examples:
%% \setmargins{0in}{0in}         % default line length & default margins
%% \setmargins[-.12in]{0in}{0in} % compensate for printer offset
%% \setmargins{0in}{1in}         % default line length, 1 inch inner margin
%% \setmargins{6.5in}{0in}       % 6.5 inch line length & default margins
%% \setmargins{5in}{1.5in}       % 5 inch line length & 1.5 inch inner margin
%%
%%   {inside-margin-width} is defined as follows:
%%       For 1-sided printing: left margin for all pages.
%%       For 2-sided printing: left  margin for odd pages,
%%                             right margin for even pages.
%%
%%   Defaults:
%%   Each argument has a default if {0in} is used as the argument:
%%      line-length default = 6.0in
%%      inside-margin-width default:
%%         For 1-sided printing, text is centered on the page
%%                     (each margin = [1/2]*[8.5in - line length]);
%%         For 2-sided printing, inside margin is twice the outside margin
%%                     (inside  margin = [2/3]*[8.5in - line length],
%%                      outside margin = [1/3]*[8.5in - line length]).
%%      printer-offset default = 0in
%%
%%  For all cases, the outside margin (and marginparwidth, the
%%  width of margin notes) is just whatever is left over after
%%  accounting for the inside margin and the line length.
%%
%% Note: LaTeX's built-in offset of 1.0 inch can vary somewhat,
%%       depending upon the alignment of the Laser printer.
%%       If you need it to be EXACT, you will have to supply
%%       the optional [printer-offset] argument.
%%       Subtract the actual measured left margin on an
%%       odd-numbered page from the printed Odd Page Left Margin
%%       value, and use the result as the [printer-offset].
%%       Positive values shift everything to the right,
%%       negative values shift everything to the left.
%%
\makeatletter
\def\setmargins{\@ifnextchar[{\@setmargins}{\@setmargins[0in]}}
\def\@setmargins[#1]#2#3{
%%%  Uses temporary dimension registers \dimen0, \dimen2, \dimen3, \dimen1
    \dimen1=#1                         % 1st argument [printer offset]
    \dimen2=#2                         % 2nd argument (line length)
    \dimen3=#3                         % 3rd argument (inner margin)
     \advance\dimen1 by -1.0in         % for LaTeX built-in offset
    \ifdim\dimen2=0in 
        \textwidth=6in  \dimen2=6in
    \else \textwidth=\dimen2
    \fi
    \dimen0=8.5in
    \advance\dimen0 by -\dimen2         % 8.5in - line length
    \if@twoside
       \ifdim\dimen3=0in  % use defaults: 2/3 inside, 1/3 outside
          \divide\dimen0 by 3           % (8.5in-line length)/3
          \dimen2=2\dimen0              % (2/3)*(8.5in-line length)
          \oddsidemargin=\dimen2
          \advance\oddsidemargin by \dimen1   % add in offset
          \dimen2=\dimen0               % (8.5in-line length)/3
          \evensidemargin=\dimen2
          \advance\evensidemargin by \dimen1  % add in offset
%  allow for space on each side of marginal note
          \advance\dimen0 by -2\marginparsep
          \marginparwidth=\dimen0
       \else            % use supplied 2-sided value
          \oddsidemargin=\dimen3             % inside-margin-width
          \advance\oddsidemargin by \dimen1  % add in offset
          \advance\dimen0 by -\dimen3   % 8.5in-line length-inside margin
          \evensidemargin=\dimen0
          \advance\evensidemargin by \dimen1 % add in offset
%  allow for space on each side of marginal note
          \advance\dimen0 by -2\marginparsep
          \marginparwidth=\dimen0
       \fi
%  one-sided
    \else \ifdim\dimen3=0in  % use defaults: center text 
              \divide\dimen0 by 2         % (8.5in-line length)/2
              \oddsidemargin=\dimen0      % (8.5in-line length)/2
              \advance\oddsidemargin by \dimen1   % add in offset
              \evensidemargin=\dimen0     % (8.5in-line length)/2
              \advance\evensidemargin by \dimen1  % add in offset
%  allow for space on each side of marginal note
              \advance\dimen0 by -2\marginparsep
              \marginparwidth=\dimen0
          \else  % use supplied values
              \advance\dimen0 by -\dimen3  % 8.5in-line length-left margin
%  allow for space on each side of marginal note
              \advance\dimen0 by -2\marginparsep
              \marginparwidth=\dimen0
              \advance\dimen3 by \dimen1   % add in offset
              \oddsidemargin=\dimen3
              \evensidemargin=\dimen3
          \fi
    \fi
  \immediate\write16{Textwidth = \the\textwidth}
  \dimen0=1.0in
  \advance\dimen0 by \oddsidemargin
  \immediate\write16{Odd Page Left Margin = \the\dimen0}
  \dimen0=1.0in
  \advance\dimen0 by \evensidemargin
  \immediate\write16{Even Page Left Margin = \the\dimen0}
  \immediate\write16{Marginparwidth = \the\marginparwidth}
  \dimen0=#1
  \immediate\write16{Printer Offset = \the\dimen0}
 }
%
\def\@outputpage{\begingroup\catcode`\ =10 \if@specialpage 
     \global\@specialpagefalse\@nameuse{ps@\@specialstyle}\fi
     \if@twoside 
       \ifodd\count\z@ \let\@thehead\@oddhead \let\@thefoot\@oddfoot
                       \let\@themargin\oddsidemargin
% treat page 0 (title page) as if it is an odd-numbered page
        \else \ifnum\count\z@=0 \let\@thehead\@oddhead \let\@thefoot\@oddfoot
                                \let\@themargin\oddsidemargin
              \else \let\@thehead\@evenhead
                    \let\@thefoot\@evenfoot \let\@themargin\evensidemargin
     \fi\fi\fi
     \shipout
     \vbox{\normalsize \baselineskip\z@ \lineskip\z@
           \vskip \topmargin \moveright\@themargin
           \vbox{\setbox\@tempboxa
                   \vbox to\headheight{\vfil \hbox to\textwidth{\@thehead}}
                 \dp\@tempboxa\z@
                 \box\@tempboxa
                 \vskip \headsep
                 \box\@outputbox
                 \baselineskip\footskip
                 \hbox to\textwidth{\@thefoot}}}\global\@colht\textheight
           \endgroup\stepcounter{page}\let\firstmark\botmark}
%
\makeatother
%%
%% End of home:/usr/local/hacks/tex/setmargins.tex:
%%
\setmargins{6.5in}{1in}
\topmargin = 0in
\headheight = 5mm
\headsep = 3mm
\textheight = 9in
%\textwidth = 5.9in
\makeindex
\begin{document}
% Simple command to generate the index.
\newcommand{\outputindex}[1]{{
\begin{theindex}
\input{#1}
\end{theindex}
}}
%%
%% Inserted from home:/u3/ekberg/tex/pretxt.tex
%%
% Define the old PRETXT SAME/HIGHER/LOWER commands.
% These let one move up and down in the dot level numbering
% system without having to know the current level.  Note that the L
% version of the macro exists to allow one to specify a label for the
% section information.
%
% If you didn't understand the above, then read on.  PRETXT is the
% name of a preprocessor for another word processor which added some
% interesting features.  The feature implemented here, is an improved
% numbering scheme based upon the existing numbering scheme available
% in LaTeX.  The improvement is that one need not remember which level
% you are at when defining a new section, one only need remember the
% relative ordering.  For example:
%   LaTeX input                          LaTeX output
%   \CHAPTER{Foo}                          1
%   \LOWER{Foo Bar}                        1.1
%   \LOWER{Foo Bar Baz}                    1.1.1
%   \SAME{More Foo Bar}                    1.1.2
%   \SAME{Even More Foo Bar}               1.1.3
%   \HIGHER{More Foo}                      1.2
%   \SAME{Even More Foo}                   1.3
%   \LOWER{Even More Even more Foo}        1.3.1
% The advantage here is that one can reorganize entire sections of
% text and only have to change one of the section numbering commands
% (the first one).  With the original LaTeX method, one would have to
% change every section numbering command if one moved to a different
% level in the hierarchy.
%
% These four commands have alternates which allow one to specify a
% label for the section number and its page.  This allows one to refer
% to that number elsewhere in the document.  The alternates are
% CHAPTERL, LOWERL, SAMEL and HIGHERL.
%
\countdef\sectionlevel=100
\global\sectionlevel=0
\newcommand{\CHAPTER}[1]{\global\sectionlevel=0 \chapter{#1}
}
\newcommand{\CHAPTERL}[2]{\global\sectionlevel=0 \chapter{#1} \label{#2}
}
\newcommand{\SAME}[1]{
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1}}
           \else {\bigskip \subsubsection{#1}}
           \fi
      \fi
 \fi}
\newcommand{\SAMEL}[2]{
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1} \label{#2}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1} \label{#2}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1} \label{#2}}
           \else {\bigskip \subsubsection{#1} \label{#2}}
           \fi
      \fi
 \fi}
\newcommand{\LOWER}[1]{{\global\advance\sectionlevel by1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1}}
           \else {\bigskip \subsubsection{#1}}
           \fi
      \fi
 \fi}
\newcommand{\LOWERL}[2]{{\global\advance\sectionlevel by1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1} \label{#2}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1} \label{#2}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1} \label{#2}}
           \else {\bigskip \subsubsection{#1} \label{#2}}
           \fi
      \fi
 \fi}
\newcommand{\HIGHER}[1]{{\global\advance\sectionlevel by-1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1}}
           \else {\bigskip \subsubsection{#1}}
           \fi
      \fi
 \fi}
\newcommand{\HIGHERL}[2]{{\global\advance\sectionlevel by-1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1} \label{#2}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1} \label{#2}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1} \label{#2}}
           \else {\bigskip \subsubsection{#1} \label{#2}}
           \fi
      \fi
 \fi}


\newcommand{\SAMEF}[1]{
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter[#1]{#1\protect\footnotemark}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section[#1]{#1\protect\footnotemark}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection[#1]{#1\protect\footnotemark}}
           \else {\bigskip \subsubsection[#1]{#1\protect\footnotemark}}
           \fi
      \fi
 \fi}
\newcommand{\LOWERF}[1]{{\global\advance\sectionlevel by1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter[#1]{#1\protect\footnotemark}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section[#1]{#1\protect\footnotemark}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection[#1]{#1\protect\footnotemark}}
           \else {\bigskip \subsubsection[#1]{#1\protect\footnotemark}}
           \fi
      \fi
 \fi}
\newcommand{\HIGHERF}[1]{{\global\advance\sectionlevel by-1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter[#1]{#1\protect\footnotemark}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section[#1]{#1\protect\footnotemark}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection[#1]{#1\protect\footnotemark}}
           \else {\bigskip \subsubsection[#1]{#1\protect\footnotemark}}
           \fi
      \fi
 \fi}


%%
%% End of home:/u3/ekberg/tex/pretxt.tex
%%
\setlength{\parskip}{5 mm}
\setlength{\parindent}{0 in}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                 %
%                            Document                             %
%                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%
\title{Common Lisp Interactive Objects} 

\author{Kerry Kimbrough \\
Suzanne McBride \\ 
Lars Greninger \\ \\
Texas Instruments Incorporated} 
\date{Version 1.0\\
July, 1990
%\\[2 in]
\vfill
\copyright 1989, 1990\  Texas Instruments Incorporated
\\[.5in]
\parbox{3.5in}{
     Permission is granted to any individual or institution to use,
     copy, modify and distribute this document, provided that  this
     complete  copyright  and   permission  notice   is maintained,
     intact, in  all  copies  and  supporting documentation.  Texas
     Instruments Incorporated  makes  no  representations about the
     suitability of the software described herein for any  purpose.
     It is provided ``as is'' without express or implied warranty.
}}
\maketitle
%
\setcounter{page}{1}
\pagenumbering{roman}
\tableofcontents
%\clearpage\listoffigures
\clearpage
\setcounter{page}{0}
\pagenumbering{arabic}


\CHAPTER{Introduction} 

\LOWER{Overview} 

Common Lisp Interactive Objects (CLIO) is a set of CLOS classes that represent the
standard components of an object-oriented user interface --- such as text, menus,
buttons, scroller, and dialogs.  CLIO is designed to be a portable system written
in Common Lisp and is based on other standard Common Lisp interfaces:

\begin{itemize}
\item CLX\cite{clx}, the Common
Lisp interface to the
X Window System; 

\item CLUE\cite{clue}, a portable Common Lisp user interface toolkit; and

\item  CLOS\cite{clos}, the ANSI-standard Common Lisp Object
System.\index{CLUE} \index{CLX}\index{CLOS}

\end{itemize}

CLIO  not only provides the basic components commonly used in
constructing graphical user interfaces, but also  specifies an application
progam interface that is {\bf look-and-feel independent}.  \index{look-and-feel,
independence} That is, an application program can rely on the functional
behavior of CLIO components without depending on the details of visual
appearance and event handling.  

CLIO components are those whose ``look-and-feel'' is typically specified by a
comprehensive user interface {\bf style guide}.\index{style guide}
A style guide describes a consistent, identifiable style shared by all application
programs.  OPEN LOOK\footnotemark\footnotetext{OPEN LOOK is a trademark of AT\&T}
and Motif\footnotemark\footnotetext{Motif is a trademark of the Open Software
Foundation} are examples of such look-and-feel style guides.  The CLIO interface
is designed to support implementations that conform to these and other style
guides.

The concept of look-and-feel independence means that the look-and-feel of CLIO
components is encapsulated within the implementation of the CLIO interface. An
application program can be ported to a different style guide simply by using
a different implementation of the CLIO ``library.''

\SAME{Summary of Features}

The toolkit ``intrinsics'' used by CLIO are defined by CLUE.\index{CLUE} Thus,
CLIO defines the application programmer interface to a set of {\bf contact}
\index{contact} classes --- constructor functions, accessor functions, {\bf
resources},\index{resources} and {\bf callback}\index{callback} interfaces.  See
\cite{clue} for a complete description of contacts, callbacks, and resources.

CLIO does {\em not} define functions or mechanisms that control the handling of
user input events.  Such functions are related to the ``feel'' of a specific style
guide\index{style guide} and are thus implementation-dependent.\index{event
handling}

The types of classes defined by CLIO include text, images, controls, dialogs,
and containers.  All CLIO classes are subclass of a common base class --- the
{\tt core}\index{classes, core}\index{core} class.

\LOWER{Text} 

The {\tt display-text} class\index{display-text} represents text that is
displayed but cannot be modified interactively.  The text displayed is given by
a source string, which may contain \verb+#\newline+ characters to indicate multiple
lines.
A {\tt display-text} has a number of attributes --- such as font, alignment, and
margins --- that control its presentation.  A {\tt display-text} also supplies
operations which allow a user to select portions of the source string.  The
standard conventions specified by the X Window System Inter-Client
Communications Convention Manual (ICCCM)\cite{icccm} are used to support
interchange of selected text.

The {\tt edit-text}\index{edit-text} class represents text that can be
interactively selected, deleted, or modified by a user. An {\tt edit-text}
shares the same presentation attributes as a {\tt display-text}.

Additional classes --- {\tt display-text-field}\index{display-text-field} and
{\tt edit-text-field}\index{edit-text-field} --- are defined to provide
efficient support for the common cases of single-line text fields.

\SAME{Images}

A {\bf display-image}\index{display-image} presents an array of pixels for
viewing.  The source array of a {\tt display-image} may be either a {\tt pixmap}
or an {\tt image} object.  A {\tt display-image} has several attributes --- such
as margins and gravity --- that control its presentation.


\SAME{Controls}

CLIO {\bf controls}\index{controls} are used to select or modify values
that control the application or other parts of its user interface. CLIO contains
four different types of controls: buttons, scales, items, and choices.

{\bf Buttons}\index{buttons} represent ``switches'' used to initate actions or
modify values.  An {\bf action-button}\index{action-button} allows a user to
immediately invoke an action.  A {\bf toggle-button}\index{toggle-button}
represents a two-state switch which a user may turn ``on'' or ``off.'' A button
has a label which may be either a text string or a {\tt pixmap}.  A {\bf
dialog-button}\index{dialog-button} is a specialized {\tt action-button} which
allows a user to immediately present a dialog, such as a menu.

A {\bf scale}\index{scale} is used to present a numerical value for viewing and
modification.  CLIO scales include sliders and scrollers.  A {\bf
scroller}\index{scroller} is a scale which plays a specific user interface role
--- changing the viewing position of another user interface object.  A {\tt
slider} has the same functional interface as a {\tt scroller}, but it has a less
specific role and typically has a different appearance and behavior.  Sliders
and scrollers may have either a horizontal or a vertical orientation.

{\bf Item}\index{menu, item} classes represent objects which can appear as
selectable items in menus.  The item types defined by CLIO include {\bf
action-items}\index{action-item}, which invoke an immediate action, and {\bf
dialog-items}\index{dialog-item}, which display another menu or another type
of dialog.

A {\bf choice} contact\index{choice} is a composite contact used to contain a
set of {\bf choice items}\index{choice, items}.  A choice contact allows a user
to choose zero or more of the choice items which are its children.
In order to operate correctly as a choice item, a child contact need not belong
to any specific class, but it must obey a certain {\bf choice item
protocol}\index{choice item, protocol}.  Choice classes in CLIO include {\bf
choices}\index{choices} and {\bf multiple-choices}\index{multiple-choices}.

\SAME{Dialogs}

{\bf Dialog}\index{dialog} classes are {\tt shell}\footnotemark\footnotetext{For
a complete discussion of shells, see \cite{clue}.} subclasses used to display a
set of application data and \index{shell} to report a user's response.  CLIO
defines dialogs for various types of user interactions.  A {\bf
confirm}\index{confirm} is a simple dialog which presents a message and allows a
user to enter a ``yes or no'' response.  A {\bf menu}\index{menu} allows a user
to select from a set of choice items.  A {\bf
property-sheet}\index{property-sheet} presents a set of related values for
editing and allows a user to accept or cancel any changes.  The most general
type of dialog is a {\bf command}\index{command}, which presents not only a set
of related value controls but also a set of application-defined controls which
operate on the values.


\SAME{Containers} 

A {\bf container}\index{container} is a composite contact used
to manage a set of child contacts.  For example, a {\bf
scroll-frame}\index{scroll-frame} is a CLIO container which contains a child
called the ``content'' and which allows a user to view different parts of the
content by manipulating horizontal and/or vertical scrolling controls.  The
scrolling controls are implemented by {\tt scroller} contacts and are created
automatically.


Some container classes are referred to as {\bf layouts}.
\index{layouts} A layout is a type of container whose purpose is limited to
providing a specific style of geometry management.  Examples of CLIO layouts
include forms and tables.
A {\bf form}\index{form} manages the geometry of a set of children (or {\bf
members}\index{form, members}) according to a set of constraints.  Geometrical
constraints are used to define the minimum/maximum size for each member, as well
as the ideal/maximum/minimum space between members.
A {\bf table}\index{table} arranges its members into an array of rows and columns.
Row/column positions are defined as constraint resources of individual members



\HIGHER{Packages}
All CLIO function symbols are assumed to be exported from a single package that
represents an implementation of CLIO for a specific style guide. However, the
name of the package which exports CLIO symbols is implementation-dependent. 

\SAME{Core Contacts}\index{classes, core}


 
All CLIO contact classes are subclasses of the {\tt core} class.  The {\tt core}
class represents exactly those features common to the all CLIO classes. In
general, the implementation of the {\tt core} class also represents the
characteristics shared by all component in a specific style guide.
\index{style guide}
Functionally, the {\tt core} class is defined by the accessor methods described
below.  In addition, {\tt core} defines initargs which may be given to any of
the CLIO constructor functions.\index{constructor functions}

{\samepage
{\large {\bf contact-foreground \hfill Method, core}}
\index{core, contact-foreground method}
\index{contact-foreground method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & contact-foreground & \\
& ((core  core)) \\
(declare & (values pixel)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf contact-foreground) & \\
         & (foreground \\
         & (core core)) \\
(declare & (values pixel)))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Return or change the foreground pixel used for output to a {\tt core}
contact. When changing the foreground pixel, {\tt convert}
is called to convert the new value to a pixel value, if necessary.

The {\tt :foreground} initarg can be given to any CLIO constructor
function to initialize the foreground pixel.  By default, the initial
foreground pixel for a {\tt core} object is the same as its parent's.
If the parent is not a {\tt core} contact (for example, if the parent is
a {\tt root}), then the default initial foreground pixel is given by
{\tt \index{variables, *default-contact-foreground*}
*default-contact-foreground*}.

}\end{flushright}

{\samepage
{\large {\bf contact-border \hfill Method, core}}
\index{core, contact-border method}
\index{contact-border method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & contact-border & \\
& ((core  core)) \\
(declare & (values (or (member :copy) pixel pixmap))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf contact-border) & \\
         & (border \\
         & (core core)) \\
(declare & (values (or (member :copy) pixel pixmap))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}
{Return or change the contents of the border of a {\tt core} contact.
When changing the border, {\tt convert} is called to
convert the new value to a valid value, if necessary.

The {\tt :border} initarg can be given to any CLIO constructor function to
initialize the contact border.
By default, the border for a {\tt core} object is given by {\tt
\index{variables, *default-contact-border*}
*default-contact-border*}. 


}\end{flushright}




\CHAPTER{Text}

\LOWER{Display Text}\index{display-text}                                  

\index{classes, display-text}

A {\tt display-text} presents multiple lines of text for viewing.


The source of a {\tt display-text} is a text string. The following functions may be
used to control the presentation of the displayed string.

\begin{itemize}    
\item {\tt display-gravity} 
\item {\tt display-text-alignment} 
%\item {\tt display-text-character-set} 
\item {\tt display-text-font} 
\end{itemize}

The following functions may be used to set the margins surrounding the displayed
text.

\begin{itemize}
 \item {\tt display-bottom-margin}
 \item {\tt display-left-margin}
 \item {\tt display-right-margin}
 \item {\tt display-top-margin}
\end{itemize}




\LOWER{Selecting and Copying Text} \index{display-text, selecting text} 
A {\tt display-text} allows a user to interactively select source text and to transfer
selected text strings using standard conventions for interclient communication
(see Section~\ref{sec:selections}).  The specific interactive operations used to
select and transfer text are implementation-dependent.

Selecting text causes a {\tt display-text} to become the owner of the {\tt
:primary} selection, which then contains the selected text.\index{selections,
:primary} 
The {\tt display-text-selection} function may be used to return the
currently-selected text.
Copying selected text --- accomplished by user interaction or by
calling the {\tt display-text-copy} function --- causes the selected text to
become the value of the {\tt :clipboard} selection.

A {\tt display-text} can handle requests from other clients to convert the {\tt
:primary} and {\tt :clipboard} selections to the target types defined by the
following atoms.\index{display-text, converting selections} (See \cite{icccm}
for a complete description of conventions for text target atoms.)

\begin{itemize}
\item The font character encoding atom. This is an atom identifying the character
encoding used by the {\tt display-text-font}. 
\item {\tt :text}. This is equivalent to using the font character encoding
atom. 
\item All other target atoms required by ICCCM. See Section~\ref{sec:selections}.
\end{itemize}


\SAME{Functional Definition}

{\samepage
{\large {\bf make-display-text \hfill Function}} 
\index{constructor functions, display-text}
\index{make-display-text function}
\index{display-text, make-display-text function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-display-text \\
       & (\&rest initargs \\
       & \&key  \\
       &   (alignment           & :left)\\
       &   (border              & *default-contact-border*) \\ 
       &   (bottom-margin       & :default) \\ 
%       &   (character-set       & :string) \\ 
       &   (display-gravity             & :center) \\
       &   (font                & *default-display-text-font*) \\ 
       &   foreground \\
       &   (left-margin         & :default) \\ 
       &   (right-margin        & :default) \\ 
       &   (top-margin          & :default) \\
       &   (source              & "")\\ 
       &   \&allow-other-keys) \\
(declare & (values   display-text)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt display-text} contact.
The resource specification list of the {\tt display-text} class defines
a resource for each of the initargs above.\index{display-text,
resources}
}\end{flushright}




{\samepage
{\large {\bf display-bottom-margin \hfill Method, display-text}}
\index{display-text, display-bottom-margin method}
\index{display-bottom-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-bottom-margin & \\
& ((display-text  display-text)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-bottom-margin) & \\
& (bottom-margin \\
& (display-text  display-text)) \\
(declare &(type (or (integer 0 *) :default)  bottom-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns or changes the pixel size of the
bottom margin.  The height of the contact minus the bottom margin size defines
the bottom edge of the clipping rectangle used when displaying the source.
Setting the bottom margin to {\tt :default} causes the value of {\tt
*default-display-bottom-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-bottom-margin*}
  
}\end{flushright}



{\samepage  
{\large {\bf display-text-alignment \hfill Method, display-text}}
\index{display-text, display-text-alignment method}
\index{display-text-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-alignment & \\
& ((display-text  display-text)) \\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-alignment) & \\
         & (alignment \\
         & (display-text  display-text)) \\
(declare &(type (member :left :center :right)  alignment))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the horizontal alignment of text lines with respect to the
bounding rectangle of the source.

\begin{center}
\begin{tabular}{ll}
{\tt :left} & Lines are left-justified within the source bounding rectangle.\\ \\
{\tt :right} & Lines are right-justified within the source bounding rectangle.\\ \\
{\tt :center} & Lines are centered within the source bounding rectangle.\\
\end{tabular}
\end{center}}
\end{flushright}


%{\samepage  
%{\large {\bf display-text-character-set \hfill Method, display-text}}
%\index{display-text, display-text-character-set method}
%\index{display-text-character-set method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & display-text-character-set & \\
%& ((display-text  display-text)) \\
%(declare & (values keyword)))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf display-text-character-set) & \\
%         & (character-set \\
%         & (display-text  display-text)) \\
%(declare &(type keyword  character-set))\\
%(declare & (values keyword)))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns or changes the keyword symbol indicating the character set encoding of
%the source. Together with the {\tt display-text-font}, the character set
%determines the {\tt font} object used to display source characters.
%The default  --- {\tt :string} --- is equivalent to {\tt :latin-1} (see
%\cite{icccm}). 
%} \end{flushright}
%

{\samepage
{\large {\bf display-text-copy \hfill Method, display-text}}
\index{display-text, display-text-copy method}
\index{display-text-copy method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-copy & \\
           & ((display-text  display-text)) \\
(declare   & (values (or null sequence))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Causes the currently selected text to become the
current value of the {\tt :clipboard} selection\index{display-text, copying
text}. The currently selected text is returned. 

}\end{flushright}


{\samepage  
{\large {\bf display-gravity \hfill Method, display-text}}
\index{display-text, display-gravity method}
\index{display-gravity method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-gravity & \\
& ((display-text  display-text)) \\
(declare & (values gravity)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-gravity) & \\
         & (gravity \\
         & (display-text  display-text)) \\
(declare &(type gravity  gravity))\\
(declare & (values gravity)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the display gravity of the contact.\index{gravity
type}
See Section~\ref{sec:globals}. Display gravity controls the alignment of the
source bounding rectangle with respect to the clipping rectangle formed by the
top, left, bottom, and right margins. The display gravity determines the source
position that is aligned with the corresponding position of the margin
rectangle.  
} \end{flushright}

{\samepage  
{\large {\bf display-left-margin \hfill Method, display-text}}
\index{display-text, display-left-margin method}
\index{display-left-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-left-margin & \\
& ((display-text  display-text)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-left-margin) & \\
         & (left-margin \\
         & (display-text  display-text)) \\
(declare &(type (or (integer 0 *) :default)  left-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
left margin.  The left margin size defines
the left edge of the clipping rectangle used when displaying the source.
Setting the left margin to {\tt :default} causes the value of {\tt
*default-display-left-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-left-margin*}
}
\end{flushright}




{\samepage  
{\large {\bf display-right-margin \hfill Method, display-text}}
\index{display-text, display-right-margin method}
\index{display-right-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-right-margin & \\
& ((display-text  display-text)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-right-margin) & \\
         & (right-margin \\
         & (display-text  display-text)) \\
(declare &(type (or (integer 0 *) :default)  right-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
right margin.  The width of the contact minus the right margin size defines
the right edge of the clipping rectangle used when displaying the source.
Setting the right margin to {\tt :default} causes the value of {\tt
*default-display-right-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-right-margin*}
}
\end{flushright}




{\samepage  
{\large {\bf display-text-font \hfill Method, display-text}}
\index{display-text, display-text-font method}
\index{display-text-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-font & \\
& ((display-text  display-text)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-font) & \\
         & (font \\
         & (display-text  display-text)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification. Together
with the {\tt display-text-source}, this determines the {\tt font}
object used to display source characters.
} 
\end{flushright}

{\samepage  
{\large {\bf display-text-selection \hfill Method, display-text}}
\index{display-text, display-text-selection method}
\index{display-text-selection method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-selection & \\
& ((display-text  display-text)) \\
(declare & (values (or null sequence))))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns a string containing the currently selected text (or {\tt nil} if no text
is selected).} \end{flushright}


{\samepage  
{\large {\bf display-text-source \hfill Method, display-text}}
\index{display-text, display-text-source method}
\index{display-text-source method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-source & \\
& ((display-text  display-text)\\
&  \&key \\
&   (start 0)\\
&   end) \\
(declare &(type (integer 0 *) & start)\\
         &(type (or (integer 0 *) null) & end))\\
(declare & (values string)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-source) & \\
         & (new-source \\
         & (display-text  display-text)\\
&  \&key \\
&   (start 0)\\
&   end\\
&   (from-start 0)\\
&   from-end) \\
(declare &(type stringable  new-source)\\
        &(type (integer 0 *) & start from-start)\\
         &(type (or (integer 0 *) null) & end from-end))\\
(declare & (values string)))
\end{tabular}
\rm}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the string displayed. As in {\tt common-lisp:subseq}, the {\tt
start} and {\tt end} arguments specify the substring returned or
changed.

When changing the displayed string, the {\tt from-start} and {\tt
from-end} arguments specify the substring of the {\tt new-source}
argument that replaces the source substring given by {\tt start} and
{\tt end}.}
 \end{flushright}



{\samepage  
{\large {\bf display-top-margin \hfill Method, display-text}}
\index{display-text, display-top-margin method}
\index{display-top-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-top-margin & \\
& ((display-text  display-text)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-top-margin) & \\
         & (top-margin \\
         & (display-text  display-text)) \\
(declare &(type (or (integer 0 *) :default)  top-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
top margin.  The top margin size defines
the top edge of the clipping rectangle used when displaying the source.
Setting the top margin to {\tt :default} causes the value of {\tt
*default-display-top-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-top-margin*}
}
\end{flushright}

\vfill
\pagebreak

\HIGHER{Display Text Field}\index{display-text-field}                                  

\index{classes, display-text-field}

A {\tt display-text-field} presents a single line of text for viewing.  The
functional interface for {\tt display-text-field} objects is much the same as
that for {\tt display-text} objects.  However, some presentation attributes are
not appropriate for single-line text ({\tt display-text-alignment}, for
example).  Also, the implementation of a {\tt display-text-field} may be simpler
and more efficient.


\LOWER{Functional Definition}

{\samepage
{\large {\bf make-display-text-field \hfill Function}} 
\index{constructor functions, display-text-field}
\index{make-display-text-field function}
\index{display-text-field, make-display-text-field function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-display-text-field \\
       & (\&rest initargs \\
       & \&key  \\
%       &   (alignment           & :left)\\
       &   (border              & *default-contact-border*) \\ 
       &   (bottom-margin       & :default) \\ 
%       &   (character-set       & :string) \\ 
       &   (display-gravity             & :center) \\
       &   (font                & *default-display-text-font*) \\ 
       &   foreground \\
       &   (left-margin         & :default) \\ 
       &   (right-margin        & :default) \\ 
       &   (top-margin          & :default) \\
       &   (source              & "")\\ 
       &   \&allow-other-keys) \\
(declare & (values   display-text-field)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt display-text-field} contact.
The resource specification list of the {\tt display-text-field} class defines
a resource for each of the initargs above.\index{display-text-field,
resources}
}\end{flushright}




{\samepage
{\large {\bf display-bottom-margin \hfill Method, display-text-field}}
\index{display-text-field, display-bottom-margin method}
\index{display-bottom-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-bottom-margin & \\
& ((display-text-field  display-text-field)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-bottom-margin) & \\
& (bottom-margin \\
& (display-text-field  display-text-field)) \\
(declare &(type (or (integer 0 *) :default)  bottom-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns or changes the pixel size of the
bottom margin.  The height of the contact minus the bottom margin size defines
the bottom edge of the clipping rectangle used when displaying the source.
Setting the bottom margin to {\tt :default} causes the value of {\tt
*default-display-bottom-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-bottom-margin*}
  
}\end{flushright}





%{\samepage  
%{\large {\bf display-text-character-set \hfill Method, display-text-field}}
%\index{display-text-field, display-text-character-set method}
%\index{display-text-character-set method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & display-text-character-set & \\
%& ((display-text-field  display-text-field)) \\
%(declare & (values keyword)))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf display-text-character-set) & \\
%         & (character-set \\
%         & (display-text-field  display-text-field)) \\
%(declare &(type keyword  character-set))\\
%(declare & (values keyword)))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns or changes the keyword symbol indicating the character set encoding of
%the source. Together with the {\tt display-text-font}, the character set
%determines the {\tt font} object used to display source characters.
%The default  --- {\tt :string} --- is equivalent to {\tt :latin-1} (see
%\cite{icccm}). 
%} \end{flushright}
%



{\samepage  
{\large {\bf display-gravity \hfill Method, display-text-field}}
\index{display-text-field, display-gravity method}
\index{display-gravity method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-gravity & \\
& ((display-text-field  display-text-field)) \\
(declare & (values gravity)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-gravity) & \\
         & (gravity \\
         & (display-text-field  display-text-field)) \\
(declare &(type gravity  gravity))\\
(declare & (values gravity)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the display gravity of the contact.\index{gravity
type}
See Section~\ref{sec:globals}. Display gravity controls the alignment of the
source bounding rectangle with respect to the clipping rectangle formed by the
top, left, bottom, and right margins. The display gravity determines the source
position that is aligned with the corresponding position of the margin
rectangle.  
} \end{flushright}

{\samepage  
{\large {\bf display-left-margin \hfill Method, display-text-field}}
\index{display-text-field, display-left-margin method}
\index{display-left-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-left-margin & \\
& ((display-text-field  display-text-field)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-left-margin) & \\
         & (left-margin \\
         & (display-text-field  display-text-field)) \\
(declare &(type (or (integer 0 *) :default)  left-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
left margin.  The left margin size defines
the left edge of the clipping rectangle used when displaying the source.
Setting the left margin to {\tt :default} causes the value of {\tt
*default-display-left-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-left-margin*}
}
\end{flushright}




{\samepage  
{\large {\bf display-right-margin \hfill Method, display-text-field}}
\index{display-text-field, display-right-margin method}
\index{display-right-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-right-margin & \\
& ((display-text-field  display-text-field)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-right-margin) & \\
         & (right-margin \\
         & (display-text-field  display-text-field)) \\
(declare &(type (or (integer 0 *) :default)  right-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
right margin.  The width of the contact minus the right margin size defines
the right edge of the clipping rectangle used when displaying the source.
Setting the right margin to {\tt :default} causes the value of {\tt
*default-display-right-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-right-margin*}
}
\end{flushright}




{\samepage  
{\large {\bf display-text-font \hfill Method, display-text-field}}
\index{display-text-field, display-text-font method}
\index{display-text-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-font & \\
& ((display-text-field  display-text-field)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-font) & \\
         & (font \\
         & (display-text-field  display-text-field)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification. Together
with the {\tt display-text-source}, this determines the {\tt font}
object used to display source characters.
} 
\end{flushright}



{\samepage  
{\large {\bf display-text-source \hfill Method, display-text-field}}
\index{display-text-field, display-text-source method}
\index{display-text-source method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-source & \\
& ((display-text-field  display-text-field)\\
&  \&key \\
&   (start 0)\\
&   end) \\
(declare &(type (integer 0 *) & start)\\
         &(type (or (integer 0 *) null) & end))\\
(declare & (values string)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-source) & \\
         & (new-source \\
         & (display-text-field  display-text-field)\\
&  \&key \\
&   (start 0)\\
&   end\\
&   (from-start 0)\\
&   from-end) \\
(declare &(type stringable  new-source)\\
        &(type (integer 0 *) & start from-start)\\
         &(type (or (integer 0 *) null) & end from-end))\\
(declare & (values string)))
\end{tabular}
\rm}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the string displayed. As in {\tt common-lisp:subseq}, the {\tt
start} and {\tt end} arguments specify the substring returned or
changed.

When changing the displayed string, the {\tt from-start} and {\tt
from-end} arguments specify the substring of the {\tt new-source}
argument that replaces the source substring given by {\tt start} and
{\tt end}.}
 \end{flushright}



{\samepage  
{\large {\bf display-top-margin \hfill Method, display-text-field}}
\index{display-text-field, display-top-margin method}
\index{display-top-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-top-margin & \\
& ((display-text-field  display-text-field)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-top-margin) & \\
         & (top-margin \\
         & (display-text-field  display-text-field)) \\
(declare &(type (or (integer 0 *) :default)  top-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
top margin.  The top margin size defines
the top edge of the clipping rectangle used when displaying the source.
Setting the top margin to {\tt :default} causes the value of {\tt
*default-display-top-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-top-margin*}
}
\end{flushright}


\vfill
\pagebreak

\HIGHER{Edit Text}\index{edit-text}                                    

\index{classes, edit-text}

An {\tt edit-text} presents multiple lines of text for viewing and editing.

The source of an {\tt edit-text} is a text string.  The {\bf
point}\index{edit-text, point} defines the index in the
source where characters entered by a user will be inserted.  The {\tt
edit-text-clear} function may be used to make the source empty.

The {\tt :complete} callback is invoked when a user signals that text editing is
complete.  The {\tt :point} callback is invoked whenever a user
changes the insert point.  {\tt :insert} and {\tt :delete} callbacks may be
defined to
validate each change to the source made by the user.  The {\tt :verify} callback
is called before completion to validate the final source string. 
{\tt :suspend} and {\tt :resume} callbacks are invoked when user text editing is
suspended and resumed.

Displayed source text may be selected by a user for interclient data transfer.
The {\tt display-text-selection} function may be used to return the
currently-selected text.  The current text selection is defined to be the source
(sub)string between the point and the {\bf mark}.  \index{edit-text, mark} An
application program may change the point and the mark to change the current text
selection.  An {\tt edit-text} provides methods that allow a user to transfer
selected text using standard conventions for interclient communication.

The following functions may be used to control the presentation of the text
source.

\begin{itemize}
\item {\tt display-gravity} 
\item {\tt display-text-alignment} 
%\item {\tt display-text-character-set} 
\item {\tt display-text-font} 
\end{itemize}

The following functions may be used to set the margins surrounding the text
source.

\begin{itemize}
 \item {\tt display-bottom-margin}
 \item {\tt display-left-margin}
 \item {\tt display-right-margin}
 \item {\tt display-top-margin}
\end{itemize}

\LOWERL{Selecting, Copying, Cutting, and Pasting Text}{sec:select-text}
\index{edit-text, selecting text}
An {\tt edit-text} 
allows a user to interactively select source text and to transfer
selected text strings using standard conventions for interclient communication  (see
Section~\ref{sec:selections}).  The specific interactive operations used to
select and transfer text are implementation-dependent.

Selecting text causes an {\tt edit-text} to become the owner of the {\tt
:primary} selection, which then contains the selected text.\index{selections,
:primary} 
The {\tt display-text-selection} function may be used to return the
currently-selected text.
Copying or cutting selected text causes the selected text to become
the value of the {\tt :clipboard} selection.

The {\tt display-text-copy} function causes the selected text to become the
current value of the {\tt :clipboard} selection\index{edit-text, copying text}.
The {\tt edit-text-cut} function causes the selected text to be deleted and the
deleted text to become the value of the {\tt :clipboard}
selection.\index{selections, :clipboard}\index{edit-text, cutting text} The {\tt
edit-text-paste} function causes the current contents of the {\tt :clipboard}
selection to be inserted into the source.\index{selections,
:clipboard}\index{edit-text, pasting text}

An {\tt edit-text} can handle requests from other clients to convert the {\tt
:primary} and {\tt :clipboard} selections to the target types defined by the
following atoms.\index{edit-text, converting selections} (See \cite{icccm} for a
complete description of conventions for text target atoms.)

\begin{itemize}
\item The font character encoding atom. This is an atom identifying the character
encoding used by the {\tt display-text-font}. 
\item {\tt :text}. This is equivalent to using the font character encoding
atom. 
\item All other target atoms required by ICCCM. See Section~\ref{sec:selections}.
\end{itemize}



\SAME{Functional Definition}

{\samepage
{\large {\bf make-edit-text \hfill Function}} 
\index{constructor functions, edit-text}
\index{make-edit-text function}
\index{edit-text, make-edit-text function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-edit-text \\
       & (\&rest initargs \\
       & \&key  \\
       & (alignment           & :left)\\
       & (border              & *default-contact-border*) \\ 
       & (bottom-margin       & :default) \\ 
%       & (character-set       & :string) \\ 
       & (display-gravity             & :north-west) \\
       & (font                & *default-display-text-font*) \\ 
       & foreground \\
%      & (grow                  & :off) \\ 
       & (left-margin         & :default) \\ 
       & mark                &  \\ 
       & point               &\\ 
       & (right-margin        & :default) \\ 
       & (source              & "")\\ 
       & (top-margin          & :default) \\
       &   \&allow-other-keys) \\
(declare & (values   edit-text)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt edit-text} contact.
The resource specification list of the {\tt edit-text} class defines
a resource for each of the initargs above.\index{edit-text,
resources}

}\end{flushright}




{\samepage  
{\large {\bf display-text-alignment \hfill Method, edit-text}}
\index{edit-text, display-text-alignment method}
\index{display-text-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-alignment & \\
& ((edit-text  edit-text)) \\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-alignment) & \\
         & (alignment \\
         & (edit-text  edit-text)) \\
(declare &(type (member :left :center :right)  alignment))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the horizontal alignment of text lines with respect to the
bounding rectangle of the source.

\begin{center}
\begin{tabular}{ll}
{\tt :left} & Lines are left-justified within the source bounding rectangle.\\ \\
{\tt :right} & Lines are right-justified within the source bounding rectangle.\\ \\
{\tt :center} & Lines are centered within the source bounding rectangle.\\
\end{tabular}
\end{center}}
\end{flushright}


{\samepage  
{\large {\bf display-bottom-margin \hfill Method, edit-text}}
\index{edit-text, display-bottom-margin method}
\index{display-bottom-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-bottom-margin & \\
& ((edit-text  edit-text)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-bottom-margin) & \\
         & (bottom-margin \\
         & (edit-text  edit-text)) \\
(declare &(type (or (integer 0 *) :default)  bottom-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
bottom margin.  The height of the contact minus the bottom margin size defines
the bottom edge of the clipping rectangle used when displaying the source.
Setting the bottom margin to {\tt :default} causes the value of {\tt
*default-display-bottom-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-bottom-margin*}
}
\end{flushright}




%{\samepage  
%{\large {\bf display-text-character-set \hfill Method, edit-text}}
%\index{edit-text, display-text-character-set method}
%\index{display-text-character-set method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & display-text-character-set & \\
%& ((edit-text  edit-text)) \\
%(declare & (values keyword)))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf display-text-character-set) & \\
%         & (character-set \\
%         & (edit-text  edit-text)) \\
%(declare &(type keyword  character-set))\\
%(declare & (values keyword)))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns or changes the keyword symbol indicating the character set encoding of
%the source. Together with the {\tt display-text-font}, the character set
%determines the {\tt font} object used to display source characters.
%The default  --- {\tt :string} --- is equivalent to {\tt :latin-1} (see
%\cite{icccm}). 
%}
%\end{flushright}
%
%
%


{\samepage  
{\large {\bf display-gravity \hfill Method, edit-text}}
\index{edit-text, display-gravity method}
\index{display-gravity method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-gravity & \\
& ((edit-text  edit-text)) \\
(declare & (values gravity)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-gravity) & \\
         & (gravity \\
         & (edit-text  edit-text)) \\
(declare &(type gravity  gravity))\\
(declare & (values gravity)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the display gravity of the contact.\index{gravity
type}
See Section~\ref{sec:globals}. Display gravity controls the alignment of the
source bounding rectangle with respect to the clipping rectangle formed by the
top, left, bottom, and right margins. The display gravity determines the source
position that is aligned with the corresponding position of the margin
rectangle.  
}
\end{flushright}




{\samepage  
{\large {\bf display-left-margin \hfill Method, edit-text}}
\index{edit-text, display-left-margin method}
\index{display-left-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-left-margin & \\
& ((edit-text  edit-text)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-left-margin) & \\
         & (left-margin \\
         & (edit-text  edit-text)) \\
(declare &(type (or (integer 0 *) :default)  left-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
left margin.  The left margin size defines
the left edge of the clipping rectangle used when displaying the source.
Setting the left margin to {\tt :default} causes the value of {\tt
*default-display-left-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-left-margin*}
}
\end{flushright}




{\samepage  
{\large {\bf display-right-margin \hfill Method, edit-text}}
\index{edit-text, display-right-margin method}
\index{display-right-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-right-margin & \\
& ((edit-text  edit-text)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-right-margin) & \\
         & (right-margin \\
         & (edit-text  edit-text)) \\
(declare &(type (or (integer 0 *) :default)  right-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
right margin.  The width of the contact minus the right margin size defines
the right edge of the clipping rectangle used when displaying the source.
Setting the right margin to {\tt :default} causes the value of {\tt
*default-display-right-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-right-margin*}
}
\end{flushright}


{\samepage
{\large {\bf display-text-copy \hfill Method, edit-text}}
\index{edit-text, display-text-copy method}
\index{display-text-copy method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-copy & \\
           & ((edit-text  edit-text)) \\
(declare   & (values (or null string))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Causes the currently selected text to become the
current value of the {\tt :clipboard} selection\index{edit-text, copying
text}. The currently selected text is returned. 

}\end{flushright}



{\samepage  
{\large {\bf display-text-font \hfill Method, edit-text}}
\index{edit-text, display-text-font method}
\index{display-text-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-font & \\
& ((edit-text  edit-text)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-font) & \\
         & (font \\
         & (edit-text  edit-text)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification. Together
with the {\tt display-text-source}, this determines the {\tt font}
object used to display source characters.
}
\end{flushright}


{\samepage  
{\large {\bf display-text-selection \hfill Method, edit-text}}
\index{edit-text, display-text-selection method}
\index{display-text-selection method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-selection & \\
& ((edit-text  edit-text)) \\
(declare & (values (or null string))))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns a string containing the currently selected text (or {\tt nil} if no text
is selected).} \end{flushright}

        
{\samepage  
{\large {\bf display-text-source \hfill Method, edit-text}}
\index{edit-text, display-text-source method}
\index{display-text-source method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-source & \\
& ((edit-text  edit-text)\\
&  \&key \\
&   (start 0)\\
&   end) \\
(declare &(type (integer 0 *) & start)\\
         &(type (or (integer 0 *) null) & end))\\
(declare & (values string)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-source) & \\
         & (new-source \\
         & (edit-text  edit-text)\\
&  \&key \\
&   (start 0)\\
&   end\\
&   (from-start 0)\\
&   from-end) \\
(declare &(type stringable  new-source)\\
        &(type (integer 0 *) & start from-start)\\
         &(type (or (integer 0 *) null) & end from-end))\\
(declare & (values string)))
\end{tabular}
\rm}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the string displayed. As in {\tt common-lisp:subseq}, the {\tt
start} and {\tt end} arguments specify the substring returned or
changed.

When changing the displayed string, the {\tt from-start} and {\tt
from-end} arguments specify the substring of the {\tt new-source}
argument that replaces the source substring given by {\tt start} and
{\tt end}.}
 \end{flushright}





{\samepage  
{\large {\bf display-top-margin \hfill Method, edit-text}}
\index{edit-text, display-top-margin method}
\index{display-top-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-top-margin & \\
& ((edit-text  edit-text)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-top-margin) & \\
         & (top-margin \\
         & (edit-text  edit-text)) \\
(declare &(type (or (integer 0 *) :default)  top-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
top margin.  The top margin size defines
the top edge of the clipping rectangle used when displaying the source.
Setting the top margin to {\tt :default} causes the value of {\tt
*default-display-top-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-top-margin*}
}
\end{flushright}


{\samepage  
{\large {\bf edit-text-clear \hfill Method, edit-text}}
\index{edit-text, edit-text-clear method}
\index{edit-text-clear method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-clear & \\
& ((edit-text  edit-text)))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Sets the source to the empty string.}
\end{flushright}

{\samepage
{\large {\bf edit-text-cut \hfill Method, edit-text}}
\index{edit-text, edit-text-cut method}
\index{edit-text-cut method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-cut & \\
           & ((edit-text  edit-text)) \\
(declare   & (values (or null string))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Causes the selected text to be deleted and the deleted text to become the value
of the {\tt :clipboard} selection.\index{selections,
:clipboard}\index{edit-text, cutting text}
Returns the deleted text, if any. 

}\end{flushright}


%{\samepage  
%{\large {\bf edit-text-grow \hfill Method, edit-text}}
%\index{edit-text, edit-text-grow method}
%\index{edit-text-grow method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & edit-text-grow & \\
%& ((edit-text  edit-text)) \\
%(declare & (values (member :on :off))))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf edit-text-grow) & \\
%         & (grow \\
%         & (edit-text  edit-text)) \\
%(declare &(type (member :on :off)  grow))\\
%(declare & (values (member :on :off))))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns or changes the way the {\tt edit-text} changes size when
%the length of the source increases. If {\tt :on}, then the {\tt edit-text}
%will grow longer when
%the length of the source increases.} \end{flushright}


{\samepage  
{\large {\bf edit-text-mark \hfill Method, edit-text}}
\index{edit-text, edit-text-mark method}
\index{edit-text-mark method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-mark & \\
& ((edit-text  edit-text)) \\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf edit-text-mark) & \\
         & (mark \\
         & (edit-text  edit-text)) \\
(declare &(type (or null (integer 0 *))  mark))\\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes an index in the
source used to access the currently-selected text. If {\tt nil}, no text is
selected. Otherwise, the selected text is defined to be the source substring
between the mark and the point. In order to
avoid surprising the user, an application program should change the mark only in
response to some user action.}\index{edit-text, mark} 
\end{flushright}

{\samepage
{\large {\bf edit-text-paste \hfill Method, edit-text}}
\index{edit-text, edit-text-paste method}
\index{edit-text-paste method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-paste & \\
           & ((edit-text  edit-text)) \\
(declare   & (values (or null string))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Causes the current contents of the {\tt :clipboard} selection to be
inserted into the source.\index{selections,
:clipboard}\index{edit-text, pasting text}
Returns the inserted text, if any.

}\end{flushright}


        
{\samepage  
{\large {\bf edit-text-point \hfill Method, edit-text}}
\index{edit-text, edit-text-point method}
\index{edit-text-point method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-point & \\
& ((edit-text  edit-text)) \\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf edit-text-point) & \\
         & (point \\
         & (edit-text  edit-text)\\
         & \&key\\
         & clear-p) \\
(declare &(type (or null (integer 0 *)) & point)\\
         &(type boolean &  clear-p))\\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the index in the
source where characters entered by a user will be inserted. When
changing the point, if {\tt
clear-p} is true, then the current text selection is cleared --- that
is, the mark is also
set to the new point position. In order to avoid
surprising the user, an application program should change the point only in
response to some user action.
\index{edit-text, point} } 
\end{flushright}











\SAME{Callbacks}\index{edit-text, callbacks}

{\samepage
{\large {\bf :complete \hfill Callback, edit-text}} 
\index{edit-text, :complete callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & complete-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user indicates that all source modifications are complete.
The {\tt :verify} callback
is always invoked before invoking the {\tt :complete} callback. The {\tt
:complete} callback is called only if 
{\tt :verify} returns true.


}\end{flushright}


{\samepage
{\large {\bf :delete \hfill Callback, edit-text}} 
\index{edit-text, :delete callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & delete-function & \\
       & (edit-text\\
       & start\\
       & end)\\
(declare & (type  edit-text  edit-text)\\
         & (type (or null (integer 0 *))  start end))\\
(declare & (values (or null (integer 0 *)) (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{Invoked when the user deletes one or more
source characters.  The deleted substring is defined
by the {\tt start} and {\tt end} indices.  This callback allows an application
to protect source fields from deletion or adjust the deleted text.  The return
values indicate the start and end indices of the source characters that should
actually be deleted.

}\end{flushright}


{\samepage
{\large {\bf :insert \hfill Callback, edit-text}} 
\index{edit-text, :insert callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & insert-function & \\
       & (edit-text\\
       & start\\
       & inserted)\\
(declare & (type  edit-text  edit-text)\\
         & (type (integer 0 *)  start)\\
         & (type (or character string)  inserted))\\
(declare & (values (or null (integer 0 *)) (or character string))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user inserts one or more source
characters.  The inserted
substring is defined by the {\tt start} index and the {\tt inserted} string or character.  This callback
allows an application to protect source fields from insertion or to adjust the
inserted text. The return values indicate the start index and characters of the
string actually inserted. If a {\tt nil} start index is returned, then the
insertion is not allowed.

}\end{flushright}

        
{\samepage
{\large {\bf :point \hfill Callback, edit-text}} 
\index{edit-text, :point callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & point-function & \\ 
& (edit-text\\
& new-position) \\
(declare & (type  edit-text  edit-text)\\
         & (type  (or null (integer 0 *))  new-position)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user explicitly changes the position of the
point.\index{edit-text, point}
This does not include implicit changes caused by inserting or deleting text.

}\end{flushright}


{\samepage
{\large {\bf :resume \hfill Callback, edit-text}} 
\index{edit-text, :resume callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & resume-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user resumes editing on the {\tt edit-text}. For
example, this callback is usually invoked when the {\tt edit-text} becomes
the keyboard focus. 

}\end{flushright}

{\samepage
{\large {\bf :suspend \hfill Callback, edit-text}} 
\index{edit-text, :suspend callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & suspend-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user suspends editing on the {\tt edit-text}. For
example, this callback is usually invoked when the {\tt edit-text} ceases
to be the keyboard focus. 

}\end{flushright}


{\samepage
{\large {\bf :verify \hfill Callback, edit-text}} 
\index{edit-text, :verify callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & verify-function \\
& (edit-text)\\
(declare & (type  edit-text  edit-text))\\
(declare   & (values boolean string)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
Invoked when the user requests validation of the modified source. 
This callback allows an application to enforce constraints on the contents of
the source. If the first return value is true, then the source satisfies
application constraints. Otherwise, the second value is a string containing an
error message to be displayed.

This callback
is always invoked before invoking the {\tt :complete} callback. The {\tt
:complete} callback is called only if 
{\tt :verify} returns true.
}\end{flushright}

%\SAMEF{Edit Text Commands}\index{edit text, commands}
%\footnotetext{Not yet implemented}\index{NOT IMPLEMENTED!, edit
%text commands}
%
%{\em [This section will describe the programmer interface for using buffers and
%command tables to implement text editing commands.]}


\vfill
\pagebreak

\HIGHER{Edit Text Field}\index{edit-text-field}                                    

\index{classes, edit-text-field}

An {\tt edit-text-field} presents a single line of text for viewing and editing.
An {\tt edit-text-field} may optionally define a maximum number of characters
for its source string.

Displayed source text may be selected by a user for interclient data transfer.
An {\tt edit-text-field} provides the same functions as an {\tt edit-text} for
selecting, copying, cutting, and pasting text (see
Section~\ref{sec:select-text}).

The functional interface for {\tt edit-text-field} objects is much the same as
that for {\tt edit-text} objects.  However, some attributes are not appropriate
for single-line text ({\tt display-text-alignment}, for example).  Also, the
implementation of a {\tt edit-text-field} may be simpler and more efficient.

\LOWER{Functional Definition}

{\samepage
{\large {\bf make-edit-text-field \hfill Function}} 
\index{constructor functions, edit-text-field}
\index{make-edit-text-field function}
\index{edit-text-field, make-edit-text-field function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-edit-text-field \\
       & (\&rest initargs \\
       & \&key  \\
%       & (alignment           & :left)\\
       & (border              & *default-contact-border*) \\ 
       & (bottom-margin       & :default) \\ 
%       & (character-set       & :string) \\
       & (display-gravity             & :west) \\ 
       & (font                & *default-display-text-font*) \\ 
       & foreground \\
%      & (grow                  & :off) \\ 
       & (left-margin         & :default) \\ 
       & length \\ 
       & mark                &  \\ 
       & point               &  \\ 
       & (right-margin        & :default) \\ 
       & (source              & "")\\ 
       & (top-margin          & :default) \\
       &   \&allow-other-keys) \\
(declare & (values   edit-text-field)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt edit-text-field} contact.
The resource specification list of the {\tt edit-text-field} class defines
a resource for each of the initargs above.\index{edit-text-field,
resources}

}\end{flushright}





{\samepage  
{\large {\bf display-bottom-margin \hfill Method, edit-text-field}}
\index{edit-text-field, display-bottom-margin method}
\index{display-bottom-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-bottom-margin & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-bottom-margin) & \\
         & (bottom-margin \\
         & (edit-text-field  edit-text-field)) \\
(declare &(type (or (integer 0 *) :default)  bottom-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
bottom margin.  The height of the contact minus the bottom margin size defines
the bottom edge of the clipping rectangle used when displaying the source.
Setting the bottom margin to {\tt :default} causes the value of {\tt
*default-display-bottom-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-bottom-margin*}
}
\end{flushright}




%{\samepage  
%{\large {\bf display-text-character-set \hfill Method, edit-text-field}}
%\index{edit-text-field, display-text-character-set method}
%\index{display-text-character-set method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & display-text-character-set & \\
%& ((edit-text-field  edit-text-field)) \\
%(declare & (values keyword)))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf display-text-character-set) & \\
%         & (character-set \\
%         & (edit-text-field  edit-text-field)) \\
%(declare &(type keyword  character-set))\\
%(declare & (values keyword)))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns or changes the keyword symbol indicating the character set encoding of
%the source. Together with the {\tt display-text-font}, the character set
%determines the {\tt font} object used to display source characters.
%The default  --- {\tt :string} --- is equivalent to {\tt :latin-1} (see
%\cite{icccm}). 
%}
%\end{flushright}
%
%
%


{\samepage  
{\large {\bf display-gravity \hfill Method, edit-text-field}}
\index{edit-text-field, display-gravity method}
\index{display-gravity method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-gravity & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values gravity)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-gravity) & \\
         & (gravity \\
         & (edit-text-field  edit-text-field)) \\
(declare &(type gravity  gravity))\\
(declare & (values gravity)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the display gravity of the contact.\index{gravity
type}
See Section~\ref{sec:globals}. Display gravity controls the alignment of the
source bounding rectangle with respect to the clipping rectangle formed by the
top, left, bottom, and right margins. The display gravity determines the source
position that is aligned with the corresponding position of the margin
rectangle.  
}
\end{flushright}




{\samepage  
{\large {\bf display-left-margin \hfill Method, edit-text-field}}
\index{edit-text-field, display-left-margin method}
\index{display-left-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-left-margin & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-left-margin) & \\
         & (left-margin \\
         & (edit-text-field  edit-text-field)) \\
(declare &(type (or (integer 0 *) :default)  left-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
left margin.  The left margin size defines
the left edge of the clipping rectangle used when displaying the source.
Setting the left margin to {\tt :default} causes the value of {\tt
*default-display-left-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-left-margin*}
}
\end{flushright}




{\samepage  
{\large {\bf display-right-margin \hfill Method, edit-text-field}}
\index{edit-text-field, display-right-margin method}
\index{display-right-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-right-margin & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-right-margin) & \\
         & (right-margin \\
         & (edit-text-field  edit-text-field)) \\
(declare &(type (or (integer 0 *) :default)  right-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
right margin.  The width of the contact minus the right margin size defines
the right edge of the clipping rectangle used when displaying the source.
Setting the right margin to {\tt :default} causes the value of {\tt
*default-display-right-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-right-margin*}
}
\end{flushright}


{\samepage
{\large {\bf display-text-copy \hfill Method, edit-text-field}}
\index{edit-text-field, display-text-copy method}
\index{display-text-copy method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-copy & \\
           & ((edit-text-field  edit-text-field)) \\
(declare   & (values (or null string))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Causes the currently selected text to become the
current value of the {\tt :clipboard} selection\index{edit-text-field, copying
text}. The currently selected text is returned. 

}\end{flushright}


{\samepage  
{\large {\bf display-text-font \hfill Method, edit-text-field}}
\index{edit-text-field, display-text-font method}
\index{display-text-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-font & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-font) & \\
         & (font \\
         & (edit-text-field  edit-text-field)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification. Together
with the {\tt display-text-source}, this determines the {\tt font}
object used to display source characters.
}
\end{flushright}


{\samepage  
{\large {\bf display-text-selection \hfill Method, edit-text-field}}
\index{edit-text-field, display-text-selection method}
\index{display-text-selection method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-selection & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (or null string))))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns a string containing the currently selected text (or {\tt nil} if no text
is selected).} \end{flushright}

        
{\samepage  
{\large {\bf display-text-source \hfill Method, edit-text-field}}
\index{edit-text-field, display-text-source method}
\index{display-text-source method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-text-source & \\
& ((edit-text-field  edit-text-field)\\
&  \&key \\
&   (start 0)\\
&   end) \\
(declare &(type (integer 0 *) & start)\\
         &(type (or (integer 0 *) null) & end))\\
(declare & (values string)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-text-source) & \\
         & (new-source \\
         & (edit-text-field  edit-text-field)\\
&  \&key \\
&   (start 0)\\
&   end\\
&   (from-start 0)\\
&   from-end) \\
(declare &(type stringable  new-source)\\
        &(type (integer 0 *) & start from-start)\\
         &(type (or (integer 0 *) null) & end from-end))\\
(declare & (values string)))
\end{tabular}
\rm}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the string displayed. As in {\tt common-lisp:subseq}, the {\tt
start} and {\tt end} arguments specify the substring returned or
changed.

When changing the displayed string, the {\tt from-start} and {\tt
from-end} arguments specify the substring of the {\tt new-source}
argument that replaces the source substring given by {\tt start} and
{\tt end}.}
 \end{flushright}





{\samepage  
{\large {\bf display-top-margin \hfill Method, edit-text-field}}
\index{edit-text-field, display-top-margin method}
\index{display-top-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-top-margin & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-top-margin) & \\
         & (top-margin \\
         & (edit-text-field  edit-text-field)) \\
(declare &(type (or (integer 0 *) :default)  top-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
top margin.  The top margin size defines
the top edge of the clipping rectangle used when displaying the source.
Setting the top margin to {\tt :default} causes the value of {\tt
*default-display-top-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-top-margin*}
}
\end{flushright}


{\samepage  
{\large {\bf edit-text-clear \hfill Method, edit-text-field}}
\index{edit-text-field, edit-text-clear method}
\index{edit-text-clear method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-clear & \\
& ((edit-text-field  edit-text-field)))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Sets the source to the empty string.}
\end{flushright}

{\samepage
{\large {\bf edit-text-cut \hfill Method, edit-text-field}}
\index{edit-text-field, edit-text-cut method}
\index{edit-text-cut method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-cut & \\
           & ((edit-text-field  edit-text-field)) \\
(declare   & (values (or null string))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Causes the selected text to be deleted and the deleted text to become the value
of the {\tt :clipboard} selection.\index{selections,
:clipboard}\index{edit-text-field, cutting text}
Returns the deleted text, if any.

}\end{flushright}



%{\samepage  
%{\large {\bf edit-text-grow \hfill Method, edit-text-field}}
%\index{edit-text-field, edit-text-grow method}
%\index{edit-text-grow method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & edit-text-grow & \\
%& ((edit-text-field  edit-text-field)) \\
%(declare & (values (member :on :off))))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf edit-text-grow) & \\
%         & (grow \\
%         & (edit-text-field  edit-text-field)) \\
%(declare &(type (member :on :off)  grow))\\
%(declare & (values (member :on :off))))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns or changes the way the {\tt edit-text-field} changes size when
%the length of the source increases. If {\tt :on}, then the {\tt edit-text-field}
%will grow longer when
%the length of the source increases.} \end{flushright}


{\samepage  
{\large {\bf edit-text-field-length \hfill Method, edit-text-field}}
\index{edit-text-field, edit-text-field-length method}
\index{edit-text-field-length method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-field-length & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf edit-text-field-length) & \\
         & (length \\
         & (edit-text-field  edit-text-field)) \\
(declare &(type (or null (integer 0 *))  length))\\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the maximum number of characters allowed in the source string
of the {\tt edit-text-field}. If {\tt nil}, then the source can be any length.}
\end{flushright}

{\samepage  
{\large {\bf edit-text-mark \hfill Method, edit-text-field}}
\index{edit-text-field, edit-text-mark method}
\index{edit-text-mark method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-mark & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf edit-text-mark) & \\
         & (mark \\
         & (edit-text-field  edit-text-field)) \\
(declare &(type (or null (integer 0 *))  mark))\\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes an index in the
source used to access the currently-selected text. If {\tt nil}, no text is
selected. Otherwise, the selected text is defined to be the source substring
between the mark and the point. In order to
avoid surprising the user, an application program should change the mark only in
response to some user action.}\index{edit-text-field, mark} 
\end{flushright}

{\samepage
{\large {\bf edit-text-paste \hfill Method, edit-text-field}}
\index{edit-text-field, edit-text-paste method}
\index{edit-text-paste method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-paste & \\
           & ((edit-text-field  edit-text-field)) \\
(declare   & (values (or null string))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Causes the current contents of the {\tt :clipboard} selection to be
inserted into the source.\index{selections,
:clipboard}\index{edit-text-field, pasting text}
Returns the inserted text, if any.

}\end{flushright}



        
{\samepage  
{\large {\bf edit-text-point \hfill Method, edit-text-field}}
\index{edit-text-field, edit-text-point method}
\index{edit-text-point method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-point & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage  
{\large {\bf edit-text-point \hfill Method, edit-text-field}}
\index{edit-text-field, edit-text-point method}
\index{edit-text-point method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & edit-text-point & \\
& ((edit-text-field  edit-text-field)) \\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf edit-text-point) & \\
         & (point \\
         & (edit-text-field  edit-text-field)\\
         & \&key\\
         & clear-p) \\
(declare &(type (or null (integer 0 *)) & point)\\
         &(type boolean &  clear-p))\\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the index in the
source where characters entered by a user will be inserted. When
changing the point, if {\tt
clear-p} is true, then the current text selection is cleared --- that
is, the mark is also
set to the new point position. In order to avoid
surprising the user, an application program should change the point only in
response to some user action.
\index{edit-text-field, point} } 
\end{flushright}










\SAME{Callbacks}\index{edit-text-field, callbacks}

{\samepage
{\large {\bf :complete \hfill Callback, edit-text-field}} 
\index{edit-text-field, :complete callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & complete-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user indicates that all source modifications are complete.
The {\tt :verify} callback
is always invoked before invoking the {\tt :complete} callback. The {\tt
:complete} callback is called only if 
{\tt :verify} returns true.

}\end{flushright}


{\samepage
{\large {\bf :delete \hfill Callback, edit-text-field}} 
\index{edit-text-field, :delete callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & delete-function & \\
       & (edit-text-field\\
       & start\\
       & end)\\
(declare & (type  edit-text-field  edit-text-field)\\
         & (type (or null (integer 0 *))  start end))\\
(declare & (values (or null (integer 0 *)) (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ Invoked when the user deletes one or more
source characters.  The deleted substring is defined
by the {\tt start} and {\tt end} indices.  This callback allows an application
to protect source fields from deletion or adjust the deleted text.  The return
values indicate the start and end indices of the source characters that should
actually be deleted.

}\end{flushright}


{\samepage
{\large {\bf :insert \hfill Callback, edit-text-field}} 
\index{edit-text-field, :insert callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & insert-function & \\
       & (edit-text-field\\
       & start\\
       & inserted)\\
(declare & (type  edit-text-field  edit-text-field)\\
         & (type (integer 0 *)  start)\\
         & (type (or character string)  inserted))\\
(declare & (values (or null (integer 0 *)) (or character string))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user inserts one or more source
characters.  The inserted
substring is defined by the {\tt start} index and the {\tt inserted} string or character.  This callback
allows an application to protect source fields from insertion or to adjust the
inserted text. The return values indicate the start index and characters of the
string actually inserted. If a {\tt nil} start index is returned, then the
insertion is not allowed.

}\end{flushright}

        
{\samepage
{\large {\bf :point \hfill Callback, edit-text-field}} 
\index{edit-text-field, :point callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & point-function & \\ 
& (edit-text-field\\
& new-position) \\
(declare & (type  edit-text-field  edit-text-field)\\
         & (type  (or null (integer 0 *))  new-position)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user explicitly changes the position of the
point.\index{edit-text-field, point}
This does not include implicit changes caused by inserting or deleting text.

}\end{flushright}


{\samepage
{\large {\bf :resume \hfill Callback, edit-text-field}} 
\index{edit-text-field, :resume callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & resume-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user resumes editing on the {\tt edit-text-field}. For
example, this callback is usually invoked when the {\tt edit-text-field} becomes
the keyboard focus. 

}\end{flushright}

{\samepage
{\large {\bf :suspend \hfill Callback, edit-text-field}} 
\index{edit-text-field, :suspend callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & suspend-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user suspends editing on the {\tt edit-text-field}. For
example, this callback is usually invoked when the {\tt edit-text-field} ceases
to be the keyboard focus. 

}\end{flushright}


{\samepage
{\large {\bf :verify \hfill Callback, edit-text-field}} 
\index{edit-text-field, :verify callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & verify-function \\
& (edit-text-field)\\
(declare & (type  edit-text-field  edit-text-field))\\
(declare   & (values boolean string)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
Invoked when the user requests validation of the modified source. 
This callback allows an application to enforce constraints on the contents of
the source. If the first return value is true, then the source satisfies
application constraints. Otherwise, the second value is a string containing an
error message to be displayed.

This callback
is always invoked before invoking the {\tt :complete} callback. The {\tt
:complete} callback is called only if 
{\tt :verify} returns true.
}\end{flushright}


\CHAPTER{Images}

\LOWER{Display Image}\index{display-image} 

\index{classes, display-image}

A {\tt display-image} presents an array of pixels  for viewing.


The source of a {\tt display-image} is a {\tt pixmap} or an {\tt image}.  The
following functions may be used to control the presentation of the displayed pixel
array.

\begin{itemize}    
\item {\tt display-gravity} 
\end{itemize}

The following functions may be used to set the margins surrounding the displayed
pixel array.

\begin{itemize}
 \item {\tt display-bottom-margin}
 \item {\tt display-left-margin}
 \item {\tt display-right-margin}
 \item {\tt display-top-margin}
\end{itemize}

\pagebreak

\LOWER{Functional Definition}

{\samepage
{\large {\bf make-display-image \hfill Function}} 
\index{constructor functions, display-image}
\index{make-display-image function}
\index{display-image, make-display-image function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-display-image \\
       & (\&rest initargs \\
       & \&key  \\
       &   (border              & *default-contact-border*) \\ 
       &   (bottom-margin       & :default) \\ 
       &   (display-gravity     & :tiled) \\
       &   foreground \\
       &   (left-margin         & :default) \\ 
       &   (right-margin        & :default) \\ 
       &   (top-margin          & :default) \\
       &   source              & \\ 
       &   \&allow-other-keys) \\
(declare & (values   display-image)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt display-image} contact.
The resource specification list of the {\tt display-image} class defines
a resource for each of the initargs above.\index{display-image,
resources}
}\end{flushright}




{\samepage
{\large {\bf display-bottom-margin \hfill Method, display-image}}
\index{display-image, display-bottom-margin method}
\index{display-bottom-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-bottom-margin & \\
& ((display-image  display-image)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-bottom-margin) & \\
& (bottom-margin \\
& (display-image  display-image)) \\
(declare &(type (or (integer 0 *) :default)  bottom-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns or changes the pixel size of the
bottom margin.  The height of the contact minus the bottom margin size defines
the bottom edge of the clipping rectangle used when displaying the source.
Setting the bottom margin to {\tt :default} causes the value of {\tt
*default-display-bottom-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-bottom-margin*}
  
}\end{flushright}



{\samepage  
{\large {\bf display-gravity \hfill Method, display-image}}
\index{display-image, display-gravity method}
\index{display-gravity method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-gravity & \\
& ((display-image  display-image)) \\
(declare & (values (or (member :tiled) gravity))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-gravity) & \\
         & (gravity \\
         & (display-image  display-image)) \\
(declare &(type (or (member :tiled) gravity)  gravity))\\
(declare & (values (or (member :tiled) gravity))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the display gravity of the contact.\index{gravity
type}
See Section~\ref{sec:globals}. Display gravity controls the alignment of the
source bounding rectangle with respect to the clipping rectangle formed by the
top, left, bottom, and right margins. The display gravity determines the source
position that is aligned with the corresponding position of the margin
rectangle. 

If the display gravity is {\tt :tiled}, then the image is tiled to fill the entire
margin clipping rectangle. } \end{flushright}

{\samepage  
{\large {\bf display-left-margin \hfill Method, display-image}}
\index{display-image, display-left-margin method}
\index{display-left-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-left-margin & \\
& ((display-image  display-image)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-left-margin) & \\
         & (left-margin \\
         & (display-image  display-image)) \\
(declare &(type (or (integer 0 *) :default)  left-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
left margin.  The left margin size defines
the left edge of the clipping rectangle used when displaying the source.
Setting the left margin to {\tt :default} causes the value of {\tt
*default-display-left-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-left-margin*}
}
\end{flushright}




{\samepage  
{\large {\bf display-right-margin \hfill Method, display-image}}
\index{display-image, display-right-margin method}
\index{display-right-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-right-margin & \\
& ((display-image  display-image)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-right-margin) & \\
         & (right-margin \\
         & (display-image  display-image)) \\
(declare &(type (or (integer 0 *) :default)  right-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
right margin.  The width of the contact minus the right margin size defines
the right edge of the clipping rectangle used when displaying the source.
Setting the right margin to {\tt :default} causes the value of {\tt
*default-display-right-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-right-margin*}
}
\end{flushright}




{\samepage  
{\large {\bf display-image-source \hfill Method, display-image}}
\index{display-image, display-image-source method}
\index{display-image-source method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-image-source & \\
& ((display-image  display-image))\\
(declare & (values (or pixmap image))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-image-source) & \\
         & (source \\
         & (display-image  display-image)) \\
(declare &(type (or pixmap image)  source))\\
(declare & (values (or pixmap image))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the image displayed. }
\end{flushright}



{\samepage  
{\large {\bf display-top-margin \hfill Method, display-image}}
\index{display-image, display-top-margin method}
\index{display-top-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-top-margin & \\
& ((display-image  display-image)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-top-margin) & \\
         & (top-margin \\
         & (display-image  display-image)) \\
(declare &(type (or (integer 0 *) :default)  top-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
top margin.  The top margin size defines
the top edge of the clipping rectangle used when displaying the source.
Setting the top margin to {\tt :default} causes the value of {\tt
*default-display-top-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-top-margin*}
}
\end{flushright}


                                 


\CHAPTER{Control}\index{controls}

\LOWER{Action Button}\index{action-button}                                  

\index{classes, action-button}

An {\tt action-button} allows a user to immediately invoke an action.


An {\tt action-button} label may be either a text string or a {\tt pixmap}. The
{\tt action-button} font is used to display a text label.
The {\tt :press} callback is invoked when a user initiates operation of the {\tt
action-button}.  The {\tt :release} callback is invoked when a user terminates
operation of the {\tt action-button}.  Typically, only a {\tt :release} callback
needs to be defined.  Both {\tt :press} and {\tt :release} callbacks may be used
to control a continuous action.

\LOWER{Functional Definition}

{\samepage
{\large {\bf make-action-button \hfill Function}} 
\index{constructor functions, action-button}
\index{make-action-button function}
\index{action-button, make-action-button function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-action-button \\
       & (\&rest initargs \\
       & \&key  \\
       & (border                & *default-contact-border*) \\ 
%       & (character-set         & :string) \\ 
       & (font                  & *default-display-text-font*) \\ 
       & foreground \\
       & (label                 & "") \\  
       & (label-alignment       & :center) \\  
       &   \&allow-other-keys) \\
(declare & (values   action-button)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt action-button} contact.
The resource specification list of the {\tt action-button} class defines
a resource for each of the initargs above.\index{action-button,
resources}


}\end{flushright}


%{\samepage  
%{\large {\bf button-character-set \hfill Method, action-button}}
%\index{action-button, button-character-set method}
%\index{button-character-set method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & button-character-set & \\
%& ((action-button  action-button)) \\
%(declare & (values keyword)))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf button-character-set) & \\
%         & (character-set \\
%         & (action-button  action-button)) \\
%(declare &(type keyword  character-set))\\
%(declare & (values keyword)))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns the keyword symbol indicating the character set encoding of
%an {\tt action-button} text label. Together with either the {\tt
%button-font}, the character set
%determines the {\tt font} object used to display label characters.
%The default  --- {\tt :string} --- is equivalent to {\tt :latin-1} (see
%\cite{icccm}). {\tt button-character-set} should return {\tt nil} if and only
%if the item label is an {\tt image} or an {\tt pixmap}.
%}
%\end{flushright}



{\samepage  
{\large {\bf button-font \hfill Method, action-button}}
\index{action-button, button-font method}
\index{button-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-font & \\
& ((action-button  action-button)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-font) & \\
         & (font \\
         & (action-button  action-button)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification for a text label. Together
with the {\tt button-label}, this determines the {\tt font}
object used to display label characters.
}
\end{flushright}




{\samepage  
{\large {\bf button-label \hfill Method, action-button}}
\index{action-button, button-label method}
\index{button-label method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label & \\
& ((action-button  action-button)) \\
(declare & (values (or string pixmap))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label) & \\
         & (label \\
         & (action-button  action-button)) \\
(declare &(type (or stringable pixmap image)  label))\\
(declare & (values (or string pixmap))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the label contents. If a symbol is given for the label, it is
converted to a string. If an {\tt image} is given for the label, it is converted
to a {\tt pixmap}.} \end{flushright}

{\samepage  
{\large {\bf button-label-alignment \hfill Method, action-button}}
\index{action-button, button-label-alignment method}
\index{button-label-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label-alignment & \\
& ((action-button  action-button)) \\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label-alignment) & \\
         & (alignment \\
         & (action-button  action-button)) \\
(declare &(type (member :left :center :right)  alignment))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the alignment of the label within the {\tt action-button}.}
\end{flushright}

%\SAME{Action Button Choice Items}\index{action-button, as choice item}
%{\tt action-button} contacts may be used as choice items. The {\tt action-button} class
%implements the accessor methods and callbacks used in the choice item protocol (see
%Section~\ref{sec:choice-item-protocol}).
%
%Operating an {\tt action-button} is intended to produce an immediate effect.
%Therefore, as a choice item, an {\tt action-button} does not retain its
%``selected'' state. When it is created, an {\tt action-button} is unselected.
%After an {\tt action-button} is selected and its {\tt :on} callback is invoked, then
%it is immediately (and  automatically) unselected and its {\tt :off} callback is
%invoked. This means that it is seldom useful to define an {\tt :off} callback
%for an {\tt action-button} choice item.
%For this same reason, a choice contact
%containing only {\tt action-button} choice items should not use the {\tt
%:always-one} choice policy.


\SAME{Callbacks}\index{action-button, callbacks}

{\samepage
{\large {\bf :press \hfill Callback, action-button}} 
\index{action-button, :press callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & press-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user initiates the action represented by the {\tt
action-button}.

}\end{flushright}

 
{\samepage
{\large {\bf :release \hfill Callback, action-button}} 
\index{action-button, :release callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & release-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user terminates the action represented by the {\tt
action-button}.


}\end{flushright}

  





\vfill\pagebreak

\HIGHER{Action Item}\index{action-item}                                  

\index{classes, action-item}

An {\tt action-item} is a menu item which is functionally equivalent to an
{\tt action-button}. However, an {\tt action-item} is intended to be used as a
member of a menu and therefore may have a different appearance and
operation.  Selecting an {\tt action-item} in a menu allows a user to
immediately invoke an action.\index{menu, item}\index{menu, action item}

An {\tt action-item} label may be either a text string or a {\tt pixmap}. The
{\tt action-item} font is used to display a text label.
The {\tt :press} callback is invoked when a user initiates operation of the {\tt
action-item}.  The {\tt :release} callback is invoked when a user terminates
operation of the {\tt action-item}.  Typically, only a {\tt :release} callback
needs to be defined.  Both {\tt :press} and {\tt :release} callbacks may be used
to control a continuous action.

\LOWER{Functional Definition}

{\samepage
{\large {\bf make-action-item \hfill Function}} 
\index{constructor functions, action-item}
\index{make-action-item function}
\index{action-item, make-action-item function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-action-item \\
       & (\&rest initargs \\
       & \&key  \\
       & (border                & *default-contact-border*) \\ 
%       & (character-set         & :string) \\ 
       & (font                  & *default-display-text-font*) \\ 
       & foreground \\
       & (label                 & "") \\  
       & (label-alignment       & :left) \\  
       &   \&allow-other-keys) \\
(declare & (values   action-item)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt action-item} contact.
The resource specification list of the {\tt action-item} class defines
a resource for each of the initargs above.\index{action-item,
resources}


}\end{flushright}


%{\samepage  
%{\large {\bf button-character-set \hfill Method, action-item}}
%\index{action-item, button-character-set method}
%\index{button-character-set method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & button-character-set & \\
%& ((action-item  action-item)) \\
%(declare & (values keyword)))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf button-character-set) & \\
%         & (character-set \\
%         & (action-item  action-item)) \\
%(declare &(type keyword  character-set))\\
%(declare & (values keyword)))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns the keyword symbol indicating the character set encoding of
%an {\tt action-item} text label. Together with either the {\tt
%button-font}, the character set
%determines the {\tt font} object used to display label characters.
%The default  --- {\tt :string} --- is equivalent to {\tt :latin-1} (see
%\cite{icccm}). {\tt button-character-set} should return {\tt nil} if and only
%if the item label is an {\tt image} or an {\tt pixmap}.
%}
%\end{flushright}



{\samepage  
{\large {\bf button-font \hfill Method, action-item}}
\index{action-item, button-font method}
\index{button-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-font & \\
& ((action-item  action-item)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-font) & \\
         & (font \\
         & (action-item  action-item)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification for a text label. Together
with the {\tt button-label}, this determines the {\tt font}
object used to display label characters.
}
\end{flushright}




{\samepage  
{\large {\bf button-label \hfill Method, action-item}}
\index{action-item, button-label method}
\index{button-label method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label & \\
& ((action-item  action-item)) \\
(declare & (values (or string pixmap))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label) & \\
         & (label \\
         & (action-item  action-item)) \\
(declare &(type (or stringable pixmap image)  label))\\
(declare & (values (or string pixmap))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the label contents. If a symbol is given for the label, it is
converted to a string. If an {\tt image} is given for the label, it is converted
to a {\tt pixmap}.} \end{flushright}

{\samepage  
{\large {\bf button-label-alignment \hfill Method, action-item}}
\index{action-item, button-label-alignment method}
\index{button-label-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label-alignment & \\
& ((action-item  action-item)) \\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label-alignment) & \\
         & (alignment \\
         & (action-item  action-item)) \\
(declare &(type (member :left :center :right)  alignment))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the alignment of the label within the {\tt action-item}.}
\end{flushright}

\SAME{Action Item Choice Items}\index{action-item, as choice item}
{\tt action-item} contacts may be used as choice items. The {\tt action-item} class
implements the accessor methods and callbacks used in the choice item protocol (see
Section~\ref{sec:choice-item-protocol}).

Operating an {\tt action-item} is intended to produce an immediate effect.
Therefore, as a choice item, an {\tt action-item} does not retain its
``selected'' state. When it is created, an {\tt action-item} is unselected.
After an {\tt action-item} is selected and its {\tt :on} callback is invoked, then
it is immediately (and  automatically) unselected and its {\tt :off} callback is
invoked. This means that it is seldom useful to define an {\tt :off} callback
for an {\tt action-item} choice item. For this same reason, a choice contact
containing only {\tt action-item} choice items should not use the {\tt
:always-one} choice policy.

\SAME{Callbacks}\index{action-item, callbacks}

{\samepage
{\large {\bf :press \hfill Callback, action-item}} 
\index{action-item, :press callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & press-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user initiates the action represented by the {\tt
action-item}.

}\end{flushright}

 
{\samepage
{\large {\bf :release \hfill Callback, action-item}} 
\index{action-item, :release callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & release-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user terminates the action represented by the {\tt
action-item}.


}\end{flushright}


\vfill\pagebreak

\HIGHER{Dialog Button}\index{dialog-button}                                  

\index{classes, dialog-button}

A {\tt dialog-button} allows a user to immediately present a dialog --- for
example, a {\tt menu} or a {\tt property-sheet}, etc.  See
Chapter~\ref{sec:dialogs} for a description of CLIO dialog classes.\index{dialog}

A {\tt dialog-button} is essentially a specialized type of {\tt action-button},
for which {\tt :press}/{\tt :release} semantics (i.e.  presenting a dialog) are
defined automatically , not by the application programmer.  Details of dialog
presentation --- for example, the position where the dialog appears --- are thus
implementation-dependent.

A {\tt dialog-button} label may be either a text string or a {\tt pixmap}.
The {\tt dialog-button} font is used to display a text label.

\LOWER{Functional Definition}

{\samepage
{\large {\bf make-dialog-button \hfill Function}} 
\index{constructor functions, dialog-button}
\index{make-dialog-button function}
\index{dialog-button, make-dialog-button function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-dialog-button \\
       & (\&rest initargs \\
       & \&key  \\
       & (border                & *default-contact-border*) \\ 
%       & (character-set         & :string) \\ 
       & dialog       &  \\   
       & (font                  & *default-display-text-font*) \\ 
       & foreground \\
       & (label                 & "") \\ 
       & (label-alignment       & :left) \\   
       &   \&allow-other-keys) \\
(declare &(type (or null contact function list) dialog))\\
(declare & (values   dialog-button)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt dialog-button} contact.
The resource specification list of the {\tt dialog-button} class defines
a resource for each of the initargs above.\index{dialog-button,
resources}

The {\tt dialog} argument specifies the dialog contact to be presented by the {\tt
dialog-button}. The value can be a {\tt contact} instance for an existing dialog
or (by default) {\tt nil}, if the dialog will be defined later. Otherwise, the
dialog contact is created automatically, according to the type of {\tt dialog}
argument given.  

\begin{itemize}
\item A constructor function object. This function is called to create the dialog.

\item A list of the form {\tt ({\em constructor} .  {\em
initargs})}, where {\em constructor} is a function and {\em initargs}
is a list of initargs used by the {\em
constructor}. A dialog is created using the given constructor and initargs.

\end{itemize}


}\end{flushright}

{\samepage  
{\large {\bf button-dialog \hfill Method, dialog-button}}
\index{dialog-button, button-dialog method}
\index{button-dialog method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-dialog & \\
& ((dialog-button  dialog-button)) \\
(declare & (values contact)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-dialog) & \\
         & (dialog \\
         & (dialog-button dialog-button)) \\
(declare &(type contact & dialog))\\
(declare &(values contact)))
\end{tabular}
\rm
}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the dialog presented by the {\tt dialog-button}.
Typically, this is an instance one of the CLIO dialog classes described in
Chapter~\ref{sec:dialogs}.}
\end{flushright}

{\samepage  
{\large {\bf button-font \hfill Method, dialog-button}}
\index{dialog-button, button-font method}
\index{button-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-font & \\
& ((dialog-button  dialog-button)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-font) & \\
         & (font \\
         & (dialog-button  dialog-button)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification for a text label. Together
with the {\tt button-label}, this determines the {\tt font}
object used to display label characters.
}
\end{flushright}




{\samepage  
{\large {\bf button-label \hfill Method, dialog-button}}
\index{dialog-button, button-label method}
\index{button-label method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label & \\
& ((dialog-button  dialog-button)) \\
(declare & (values (or string pixmap))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label) & \\
         & (label \\
         & (dialog-button  dialog-button)) \\
(declare &(type (or stringable pixmap image)  label))\\
(declare & (values (or string pixmap))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the label contents. If a symbol is given for the label, it is
converted to a string. If an {\tt image} is given for the label, it is converted
to a {\tt pixmap}.} \end{flushright}

{\samepage  
{\large {\bf button-label-alignment \hfill Method, dialog-button}}
\index{dialog-button, button-label-alignment method}
\index{button-label-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label-alignment & \\
& ((dialog-button  dialog-button)) \\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label-alignment) & \\
         & (alignment \\
         & (dialog-button  dialog-button)) \\
(declare &(type (member :left :center :right)  alignment))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the alignment of the label within the {\tt dialog-button}.}
\end{flushright}





\vfill\pagebreak
  
\HIGHER{Dialog Item}\index{dialog-item}                                 

\index{classes, dialog-item}

A {\tt dialog-item} is a menu item used to present another dialog --- for
example, another {\tt menu} or a {\tt property-sheet}, etc.\index{menu, item} 
A {\tt dialog-item} allows an application programmer to construct a multi-level
hierarchy of menus. See Chapter~\ref{sec:dialogs} for a description of CLIO dialog
classes.\index{dialog}

A {\tt dialog-item} is essentially a specialized type of {\tt action-item}, for
which {\tt :press}/{\tt :release} semantics (i.e. presenting a dialog) are defined
automatically , not by the application programmer.  Details of dialog presentation
--- for example, the position where the dialog appears --- are thus
implementation-dependent.

A {\tt dialog-item} label may be either a text string or a {\tt pixmap}.
The {\tt dialog-item} font is used to display a text label.

\LOWER{Functional Definition}

{\samepage
{\large {\bf make-dialog-item \hfill Function}} 
\index{constructor functions, dialog-item}
\index{make-dialog-item function}
\index{dialog-item, make-dialog-item function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-dialog-item \\
       & (\&rest initargs \\
       & \&key  \\
       & (border                & *default-contact-border*) \\ 
%       & (character-set         & :string) \\ 
       & dialog       &  \\   
       & (font                  & *default-display-text-font*) \\ 
       & foreground \\
       & (label                 & "") \\ 
       & (label-alignment       & :left) \\   
       &   \&allow-other-keys) \\
(declare &(type (or null contact function list) dialog))\\
(declare & (values   dialog-item)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt dialog-item} contact.
The resource specification list of the {\tt dialog-item} class defines
a resource for each of the initargs above.\index{dialog-item,
resources}

The {\tt dialog} argument specifies the dialog contact to be presented by the {\tt
dialog-item}. The value can be a {\tt contact} instance for an existing dialog
or (by default) {\tt nil}, if the dialog will be defined later. Otherwise, the
dialog contact is created automatically, according to the type of {\tt dialog}
argument given.  

\begin{itemize}
\item A constructor function object. This function is called to create the dialog.

\item A list of the form {\tt ({\em constructor} .  {\em
initargs})}, where {\em constructor} is a function and {\em initargs}
is a list of initargs used by the {\em
constructor}. A dialog is created using the given constructor and initargs.

\end{itemize}

}\end{flushright}

{\samepage  
{\large {\bf button-dialog \hfill Method, dialog-item}}
\index{dialog-item, button-dialog method}
\index{button-dialog method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-dialog & \\
& ((dialog-item  dialog-item)) \\
(declare & (values contact)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-dialog) & \\
         & (dialog\\
         & (dialog-item dialog-item)) \\
(declare &(type contact & dialog))\\
(declare &(values contact)))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns the dialog presented by the {\tt dialog-item}. 
Typically, this is an instance one of the CLIO dialog classes described in
Chapter~\ref{sec:dialogs}.} \end{flushright}

{\samepage  
{\large {\bf button-font \hfill Method, dialog-item}}
\index{dialog-item, button-font method}
\index{button-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-font & \\
& ((dialog-item  dialog-item)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-font) & \\
         & (font \\
         & (dialog-item  dialog-item)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification for a text label. Together
with the {\tt button-label}, this determines the {\tt font}
object used to display label characters.
}
\end{flushright}




{\samepage  
{\large {\bf button-label \hfill Method, dialog-item}}
\index{dialog-item, button-label method}
\index{button-label method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label & \\
& ((dialog-item  dialog-item)) \\
(declare & (values (or string pixmap))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label) & \\
         & (label \\
         & (dialog-item  dialog-item)) \\
(declare &(type (or stringable pixmap image)  label))\\
(declare & (values (or string pixmap))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the label contents. If a symbol is given for the label, it is
converted to a string. If an {\tt image} is given for the label, it is converted
to a {\tt pixmap}.} \end{flushright}

{\samepage  
{\large {\bf button-label-alignment \hfill Method, dialog-item}}
\index{dialog-item, button-label-alignment method}
\index{button-label-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label-alignment & \\
& ((dialog-item  dialog-item)) \\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label-alignment) & \\
         & (alignment \\
         & (dialog-item  dialog-item)) \\
(declare &(type (member :left :center :right)  alignment))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the alignment of the label within the {\tt dialog-item}.}
\end{flushright}




\vfill\pagebreak



\HIGHER{Scroller}\index{scroller}                                     

\index{classes, scroller}

The {\tt scroller} class represents a particular form of a general type of user
interface object known as a {\bf scale}\index{scale}.  A scale is used to
present a numerical value for viewing and modification.  A {\tt scroller} is a
scale which plays a specific user interface role --- changing the viewing
position of another user interface object --- and therefore typically has a
distinctive style of appearance and operation.

A {\tt scroller} may have either a horizontal or a vertical orientation.  The
range of possible {\tt scroller} values is given by its maximum and minimum.
The current value of a {\tt scroller} is always in this range of {\bf value
units}\index{scroller, value units}.  The {\tt :new-value} callback is invoked
whenever a user changes the {\tt scroller} value interactively.  A {\tt
scroller} displays an indicator whose size is defined in the same value units
as the minimum and maximum.  Programmers typically change the indicator size to
reflect the proportion of some other quantity to the total value range.


\LOWER{Functional Definition}

{\samepage
{\large {\bf make-scroller \hfill Function}} 
\index{constructor functions, scroller}
\index{make-scroller function}
\index{scroller, make-scroller function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-scroller \\
       & (\&rest initargs \\
       & \&key  \\
       & (border                & *default-contact-border*) \\ 
       & foreground \\
       & (increment             & 1) \\ 
       & (indicator-size        & 0) \\ 
       & (maximum               & 1) \\ 
       & (minimum               & 0) \\ 
       & (orientation           & :vertical) \\ 
       & (update-delay          & 0) \\
       & (value                 & 0) \\  
       &   \&allow-other-keys) \\
(declare & (values   scroller)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt scroller} contact.
The resource specification list of the {\tt scroller} class defines
a resource for each of the initargs above.\index{scroller,
resources}


}\end{flushright}





{\samepage  
{\large {\bf scale-increment \hfill Method, scroller}}
\index{scroller, scale-increment method}
\index{scale-increment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-increment & \\
& ((scroller  scroller)) \\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-increment) & \\
         & (increment \\
         & (scroller  scroller)) \\
(declare &(type number  increment))\\
(declare & (values number)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the number of value units added to/subtracted from the
current value when the user performs an increment/decrement operation.}
\end{flushright}




{\samepage  
{\large {\bf scale-indicator-size \hfill Method, scroller}}
\index{scroller, scale-indicator-size method}
\index{scale-indicator-size method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-indicator-size & \\
& ((scroller  scroller)) \\
(declare & (values (or number (member :off)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-indicator-size) & \\
         & (indicator-size \\
         & (scroller  scroller)) \\
(declare &(type number  indicator-size))\\
(declare & (values (or number (member :off)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the indicator size in value units. The exact interpretation
of the indicator size value is implementation-dependent.

A {\tt scroller} typically displays the indicator size relative to total value
range. A {\tt scroll-frame}\index{scroll-frame} sets the indicator size to the
number of value units currently visible in the scroll area.
If the indicator size is {\tt :off}, then no indicator is displayed.
}
\end{flushright}




{\samepage  
{\large {\bf scale-maximum \hfill Method, scroller}}
\index{scroller, scale-maximum method}
\index{scale-maximum method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-maximum & \\
& ((scroller  scroller)) \\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-maximum) & \\
         & (maximum \\
         & (scroller  scroller)) \\
(declare &(type number  maximum))\\
(declare & (values number)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the maximum value.}
\end{flushright}




{\samepage  
{\large {\bf scale-minimum \hfill Method, scroller}}
\index{scroller, scale-minimum method}
\index{scale-minimum method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-minimum & \\
& ((scroller  scroller)) \\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-minimum) & \\
         & (minimum \\
         & (scroller  scroller)) \\
(declare &(type number  minimum))\\
(declare & (values number)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the minimum value.}
\end{flushright}




{\samepage  
{\large {\bf scale-orientation \hfill Method, scroller}}
\index{scroller, scale-orientation method}
\index{scale-orientation method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-orientation & \\
& ((scroller  scroller)) \\
(declare & (values (member :horizontal :vertical))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-orientation) & \\
         & (orientation \\
         & (scroller  scroller)) \\
(declare &(type (member :horizontal :vertical)  orientation))\\
(declare & (values (member :horizontal :vertical))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the orientation used to display the value range.}
\end{flushright}

{\samepage  
{\large {\bf scale-update \hfill Method, scroller}}
\index{scroller, scale-update method}
\index{scale-update method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-update & \\
& ((scroller  scroller) \\
& \&key \\
& increment \\
& indicator-size \\
& maximum \\
& minimum \\
& value)\\
(declare & (type number increment indicator-size maximum minimum value)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Changes one or more {\tt scroller} attributes simultaneously. This method causes
the updated {\tt scroller} to be redisplayed only once and thus is more efficient
than changing each attribute individually.} \end{flushright}


{\samepage  
{\large {\bf scale-update-delay \hfill Method, scroller}}
\index{scroller, scale-update-delay method}
\index{scale-update-delay method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-update-delay & \\
& ((scroller  scroller)) \\
(declare & (values (or number (member :until-done)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-update-delay) & \\
         & (update-delay \\
         & (scroller  scroller)) \\
(declare &(type (or number (member :until-done))  update-delay))\\
(declare & (values (or number (member :until-done)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ Returns or changes the current
incremental update delay time interval.  The update delay is meaningful only for
{\tt
scroller} objects that present user controls for continuous update of the {\tt
scroller} value. The update delay specifies the time interval (in seconds) that
must elapse during continuous updating before the {\tt :new-value} callback is
invoked to report a new value. If the update delay is {\tt :until-done}, then the {\tt
:new-value} callback is invoked only when continuous updating ceases.}
\end{flushright}

{\samepage  
{\large {\bf scale-value \hfill Method, scroller}}
\index{scroller, scale-value method}
\index{scale-value method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-value & \\
& ((scroller  scroller)) \\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-value) & \\
         & (value \\
         & (scroller  scroller)) \\
(declare &(type number  value))\\
(declare & (values number)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the current value.}
\end{flushright}






\SAME{Callbacks}\index{scroller, callbacks}

{\samepage
{\large {\bf :new-value \hfill Callback, scroller}} 
\index{scroller, :new-value callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & new-value-function & \\ 
& (value) \\
(declare &(type  number  value)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the value is changed by the user (but {\em not} when it is changed
by the application program) in order to report the new value to the application.

}\end{flushright}



{\samepage
{\large {\bf :adjust-value \hfill Callback, scroller}} 
\index{scroller, :adjust-value callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & adjust-value-function & \\ 
& (value) \\
(declare &(type  number  value))\\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked before {\tt :new-value} each time the value is changed by the user. This
callback allows an application to modify a user value before it is actually
used. 

}\end{flushright}

{\samepage
{\large {\bf :begin-continuous \hfill Callback, scroller}} 
\index{scroller, :begin-continuous callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & begin-continuous-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user begins continuous update of the {\tt scroller} value. This
callback is not used if the {\tt scroller} does not present controls for
continuous update. 

An application {\tt :new-value} callback may choose to respond differently to new
values that occur during continuous update --- that is, after the {\tt
:begin-continuous} callback is invoked and before the {\tt :end-continuous}
callback is invoked. For example, a faster method of displaying the new value
might be used during continuous update.

}\end{flushright}


{\samepage
{\large {\bf :end-continuous \hfill Callback, scroller}} 
\index{scroller, :end-continuous callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & end-continuous-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user ends continuous update of the {\tt scroller} value. This
callback is not used if the {\tt scroller} does not present controls for
continuous update.

}\end{flushright}








\vfill\pagebreak

\HIGHER{Slider}\index{slider}                                     

\index{classes, slider}

The {\tt slider} class represents a particular form of a general type of user
interface object known as a {\bf scale}\index{scale}.  A scale is used to
present a numerical value for viewing and modification.  A {\tt slider} has the
same functional interface as a {\tt scroller}, but it plays
a different  user interface role and typically has a different appearance and
behavior.

A {\tt slider} may have either a horizontal or a vertical orientation.  The
range of possible {\tt slider} values is given by its maximum and minimum.  The
current value of a {\tt slider} is always in this range of {\bf value
units}\index{slider, value units}.  The {\tt :new-value} callback is invoked
whenever a user changes the {\tt slider} value interactively.  The indicator
size of a {\tt slider} may specify the distance in value units between
``ticks,'' or other fixed labels used to show the value at various indicator
positions.


\LOWER{Functional Definition}

{\samepage
{\large {\bf make-slider \hfill Function}} 
\index{constructor functions, slider}
\index{make-slider function}
\index{slider, make-slider function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-slider \\
       & (\&rest initargs \\
       & \&key  \\
       & (border                & *default-contact-border*) \\ 
       & foreground \\
       & (increment             & 1) \\ 
       & (indicator-size        & 0) \\ 
       & (maximum               & 1) \\ 
       & (minimum               & 0) \\ 
       & (orientation           & :horizontal) \\ 
       & (update-delay          & 0) \\
       & (value                 & 0) \\  
       &   \&allow-other-keys) \\
(declare & (values   slider)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt slider} contact.
The resource specification list of the {\tt slider} class defines
a resource for each of the initargs above.\index{slider,
resources}


}\end{flushright}





{\samepage  
{\large {\bf scale-increment \hfill Method, slider}}
\index{slider, scale-increment method}
\index{scale-increment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-increment & \\
& ((slider  slider)) \\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-increment) & \\
         & (increment \\
         & (slider  slider)) \\
(declare &(type number  increment))\\
(declare & (values number)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the number of value units added to/subtracted from the
current value when the user performs an increment/decrement operation.}

\end{flushright}


{\samepage  
{\large {\bf scale-indicator-size \hfill Method, slider}}
\index{slider, scale-indicator-size method}
\index{scale-indicator-size method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-indicator-size & \\
& ((slider  slider)) \\
(declare & (values (or number (member :off)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-indicator-size) & \\
         & (indicator-size \\
         & (slider  slider)) \\
(declare &(type number  indicator-size))\\
(declare & (values (or number (member :off)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the indicator size in value units. The exact interpretation
of the indicator size value is implementation-dependent.

A {\tt slider} typically interprets the indicator size as the distance in value
units between ``ticks,'' or other fixed labels used to show the value at various
indicator positions.  If the indicator size is zero, then the spacing of
indicator labels is determined automatically and may change, depending on the
size of the {\tt slider} and its minimum/maximum value.  If the indicator size
is {\tt :off}, then no indicator labels are displayed.

}
\end{flushright}



{\samepage  
{\large {\bf scale-maximum \hfill Method, slider}}
\index{slider, scale-maximum method}
\index{scale-maximum method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-maximum & \\
& ((slider  slider)) \\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-maximum) & \\
         & (maximum \\
         & (slider  slider)) \\
(declare &(type number  maximum))\\
(declare & (values number)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the maximum value.}
\end{flushright}




{\samepage  
{\large {\bf scale-minimum \hfill Method, slider}}
\index{slider, scale-minimum method}
\index{scale-minimum method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-minimum & \\
& ((slider  slider)) \\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-minimum) & \\
         & (minimum \\
         & (slider  slider)) \\
(declare &(type number  minimum))\\
(declare & (values number)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the minimum value.}
\end{flushright}




{\samepage  
{\large {\bf scale-orientation \hfill Method, slider}}
\index{slider, scale-orientation method}
\index{scale-orientation method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-orientation & \\
& ((slider  slider)) \\
(declare & (values (member :horizontal :vertical))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-orientation) & \\
         & (orientation \\
         & (slider  slider)) \\
(declare &(type (member :horizontal :vertical)  orientation))\\
(declare & (values (member :horizontal :vertical))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the orientation used to display the value range.}
\end{flushright}

{\samepage  
{\large {\bf scale-update \hfill Method, slider}}
\index{slider, scale-update method}
\index{scale-update method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-update & \\
& ((slider  slider) \\
& \&key \\
& increment \\
& indicator-size \\
& maximum \\
& minimum \\
& value)\\
(declare & (type number increment indicator-size maximum minimum value)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Changes one or more {\tt slider} attributes simultaneously. This method causes
the updated {\tt slider} to be redisplayed only once and thus is more efficient
than changing each attribute individually.} \end{flushright}



{\samepage  
{\large {\bf scale-update-delay \hfill Method, slider}}
\index{slider, scale-update-delay method}
\index{scale-update-delay method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-update-delay & \\
& ((slider  slider)) \\
(declare & (values (or number (member :until-done)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-update-delay) & \\
         & (update-delay \\
         & (slider  slider)) \\
(declare &(type (or number (member :until-done))  update-delay))\\
(declare & (values (or number (member :until-done)))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ Returns or changes the current
incremental update delay time interval.  The update delay is meaningful only for
{\tt
slider} objects that present user controls for continuous update of the {\tt
slider} value. The update delay specifies the time interval (in seconds) that
must elapse during continuous updating before the {\tt :new-value} callback is
invoked to report a new value. If the update delay is {\tt :until-done}, then the {\tt
:new-value} callback is invoked only when continuous updating ceases.}
\end{flushright}



{\samepage  
{\large {\bf scale-value \hfill Method, slider}}
\index{slider, scale-value method}
\index{scale-value method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scale-value & \\
& ((slider  slider)) \\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scale-value) & \\
         & (value \\
         & (slider  slider)) \\
(declare &(type number  value))\\
(declare & (values number)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the current value.}
\end{flushright}


\pagebreak



\SAME{Callbacks}\index{slider, callbacks}

{\samepage
{\large {\bf :new-value \hfill Callback, slider}} 
\index{slider, :new-value callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & new-value-function & \\ 
& (value) \\
(declare &(type  number  value)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the value is changed by the user (but {\em not} when it is changed
by the application program) in order to report the new value to the application.


}\end{flushright}



{\samepage
{\large {\bf :adjust-value \hfill Callback, slider}} 
\index{slider, :adjust-value callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & adjust-value-function & \\ 
& (value) \\
(declare &(type  number  value))\\
(declare & (values number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked before {\tt :new-value} each time the value is changed by the user. This
callback allows an application to modify a user value before it is actually
used. 


}\end{flushright}

{\samepage
{\large {\bf :begin-continuous \hfill Callback, slider}} 
\index{slider, :begin-continuous callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & begin-continuous-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user begins continuous update of the {\tt slider} value. This
callback is not used if the {\tt slider} does not present controls for
continuous update. 

An application {\tt :new-value} callback may choose to respond differently to new
values that occur during continuous update --- that is, after the {\tt
:begin-continuous} callback is invoked and before the {\tt :end-continuous}
callback is invoked. For example, a faster method of displaying the new value
might be used during continuous update.

}\end{flushright}


{\samepage
{\large {\bf :end-continuous \hfill Callback, slider}} 
\index{slider, :end-continuous callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & end-continuous-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the user ends continuous update of the {\tt slider} value. This
callback is not used if the {\tt slider} does not present controls for
continuous update.

}\end{flushright}


\vfill\pagebreak




\HIGHER{Toggle Button}\index{toggle-button}                                  

\index{classes, toggle-button}

A {\tt toggle-button} represents a two-state switch which a user may turn
``on'' or ``off.'' 

A {\tt toggle-button} label may be either a text string or a {\tt pixmap}.
The {\tt toggle-button} font is used to display a text label.

\LOWER{Functional Definition}

{\samepage
{\large {\bf make-toggle-button \hfill Function}} 
\index{constructor functions, toggle-button}
\index{make-toggle-button function}
\index{toggle-button, make-toggle-button function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-toggle-button \\
       & (\&rest initargs \\
       & \&key  \\
       & (border                & *default-contact-border*) \\ 
%       & (character-set         & :string) \\ 
       & (font                  & *default-display-text-font*) \\ 
       & foreground \\
       & (label                 & "") \\  
       & (label-alignment       & :center) \\  
       & (switch                & :off) \\  
       &   \&allow-other-keys) \\
(declare & (values   toggle-button)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt toggle-button} contact.
The resource specification list of the {\tt toggle-button} class defines
a resource for each of the initargs above.\index{toggle-button,
resources}


}\end{flushright}


%{\samepage  
%{\large {\bf button-character-set \hfill Method, toggle-button}}
%\index{toggle-button, button-character-set method}
%\index{button-character-set method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & button-character-set & \\
%& ((toggle-button  toggle-button)) \\
%(declare & (values keyword)))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf button-character-set) & \\
%         & (character-set \\
%         & (toggle-button  toggle-button)) \\
%(declare &(type keyword  character-set))\\
%(declare & (values keyword)))
%\end{tabular}
%\rm}
%\end{flushright}
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns the keyword symbol indicating the character set encoding of
%a {\tt toggle-button} text label. Together with either the {\tt
%button-font}, the character set
%determines the {\tt font} object used to display label characters.
%The default  --- {\tt :string} --- is equivalent to {\tt :latin-1} (see
%\cite{icccm}). {\tt button-character-set} should return {\tt nil} if and only
%if the item label is an {\tt image} or an {\tt pixmap}.
%}
%\end{flushright}
%


{\samepage  
{\large {\bf button-font \hfill Method, toggle-button}}
\index{toggle-button, button-font method}
\index{button-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-font & \\
& ((toggle-button  toggle-button)) \\
(declare & (values font)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-font) & \\
         & (font \\
         & (toggle-button  toggle-button)) \\
(declare &(type fontable  font))\\
(declare & (values font)))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification for a text label. Together
with the {\tt button-label}, this determines the {\tt font}
object used to display label characters.
}
\end{flushright}




{\samepage  
{\large {\bf button-label \hfill Method, toggle-button}}
\index{toggle-button, button-label method}
\index{button-label method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label & \\
& ((toggle-button  toggle-button)) \\
(declare & (values (or string pixmap))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label) & \\
         & (label \\
         & (toggle-button  toggle-button)) \\
(declare &(type (or stringable pixmap image)  label))\\
(declare & (values (or string pixmap))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the label contents. If a symbol is given for the label, it is
converted to a string. If an {\tt image} is given for the label, it is converted
to a {\tt pixmap}.}
\end{flushright}

{\samepage  
{\large {\bf button-label-alignment \hfill Method, toggle-button}}
\index{toggle-button, button-label-alignment method}
\index{button-label-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-label-alignment & \\
& ((toggle-button  toggle-button)) \\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-label-alignment) & \\
         & (alignment \\
         & (toggle-button  toggle-button)) \\
(declare &(type (member :left :center :right)  alignment))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the alignment of the label within the {\tt toggle-button}.}
\end{flushright}


{\samepage  
{\large {\bf button-switch \hfill Method, toggle-button}}
\index{toggle-button, button-switch method}
\index{button-switch method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & button-switch & \\
& ((toggle-button  toggle-button)) \\
(declare & (values (member :on :off))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf button-switch) & \\
         & (switch \\
         & (toggle-button  toggle-button)) \\
(declare &(type (member :on :off)  switch))\\
(declare & (values (member :on :off))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the state of the {\tt toggle-button} switch. }
\end{flushright}

\SAME{Toggle Button Choice Items}\index{toggle-button, as choice item}
{\tt toggle-button} contacts may be used as choice items. The {\tt toggle-button} class
implements the accessor methods and callbacks used in the choice item protocol (see
Section~\ref{sec:choice-item-protocol}).

\SAME{Callbacks}\index{toggle-button, callbacks}

The callbacks used by a {\tt toggle-button} are defined by the choice item
protocol.
\index{choice item, protocol}
See Section~\ref{sec:choice-item-protocol}.



\vfill\pagebreak


\CHAPTERL{Choice}{sec:choice}

A {\bf choice} contact\index{choice} is a composite contact used to contain a
set of {\bf choice items}\index{choice, items}.  A choice contact allows a user
to choose one or more of the choice items which are its children.
In order to operate correctly as a choice item, a child contact need not belong
to any specific class, but it must obey a certain {\bf choice item
protocol}\index{choice item, protocol}.  

\LOWERL{Choice Item Protocol}{sec:choice-item-protocol}\index{choice item, protocol}

The choice item protocol is a set of accessor functions and callbacks
that are used by choice contacts to control the selection of choice
items.  The choice item protocol is {\em not} an application programmer
interface.  Rather, it is an interface used by a contact programmer to
implement a choice contact.  The choice item protocol allows any choice
contact to accomodate a variety of choice item classes.  In CLIO, {\tt
toggle-button} and {\tt action-item} contacts are examples of choice
item classes that implement this choice item protocol.

\LOWERL{Methods}{sec:choice-item-methods}\index{choice item,
methods}
The following generic accessor functions, which accept a choice
item argument, must have an applicable method for each choice item.\index{choice,
items}

%{\samepage  
%{\large {\bf choice-item-character-set \hfill Method, choice item protocol}}
%\index{choice item, choice-item-character-set method}
%\index{choice-item-character-set method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & choice-item-character-set & \\
%& (choice-item) \\
%(declare & (values keyword)))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns the keyword symbol indicating the character set encoding of
%a choice item text label. Together with either the {\tt choice-font} or the {\tt
%choice-item-font}, the character set
%determines the {\tt font} object used to display label characters.
%The default  --- {\tt :string} --- is equivalent to {\tt :latin-1} (see
%\cite{icccm}). {\tt choice-item-character-set} should return {\tt nil} if and only
%if the item label is an {\tt image} or an {\tt pixmap}.
%}
%\end{flushright}


{\samepage
{\large {\bf choice-item-font \hfill Method, choice item protocol}}
\index{choice item, choice-item-font method}
\index{choice-item-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-item-font & \\
& (choice-item) \\
(declare &(type contact & choice-item))\\
(declare & (values &font)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-item-font) & \\
         & (font \\
         & choice-item) \\
(declare &(type fontable  font)\\
         &(type contact & choice-item))\\
(declare & (values font)))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{ Returns and changes the font
specification of a choice
item text label.  
Together
with the {\tt choice-item-label}, this determines the {\tt font}
object used to display label characters.
{\tt choice-item-font} should return {\tt nil} if and only if
the item label is a {\tt pixmap}.

If a {\tt choices} or {\tt multiple-choices} parent has a non-{\tt nil} font,
then {\tt (setf choice-item-font)} will be used to make all choice item labels
use the parent font.

}\end{flushright}
 
{\samepage
{\large {\bf choice-item-highlight-default-p \hfill Method, choice item protocol}}
\index{choice item, choice-item-highlight-default-p method}
\index{choice-item-highlight-default-p method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-item-highlight-default-p & \\
& (choice-item) \\
(declare &(type contact & choice-item))\\
(declare & (values boolean)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-item-highlight-default-p) & \\
         & (highlight-default-p \\
         & choice-item) \\
(declare &(type boolean  highlight-default-p)\\
         &(type contact & choice-item))\\
(declare & (values boolean)))
\end{tabular}
\rm
}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the visual state used by a choice item when it is a
member of the default selection. When this state is true, a choice item should
be displayed
differently to indicate that it is a default selection; otherwise, a choice
item should be displayed normally.

}\end{flushright}

{\samepage
{\large {\bf choice-item-highlight-selected-p \hfill Method, choice item protocol}}
\index{choice item, choice-item-highlight-selected-p method}
\index{choice-item-highlight-selected-p method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-item-highlight-selected-p & \\
& (choice-item) \\
(declare &(type contact & choice-item))\\
(declare & (values boolean)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-item-highlight-selected-p) & \\
         & (highlight-selected-p \\
         & choice-item) \\
(declare &(type boolean  highlight-selected-p)\\
         &(type contact & choice-item))\\
(declare & (values boolean)))
\end{tabular}
\rm
}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the visual state used by a choice item when it is
selected. When this state is true, a choice item should be displayed
differently to indicate that it is selected; otherwise, a choice
item should be displayed normally.

Note that these functions are related only to the visual highlighting of
selection. It is possible for this state to be true, even if the choice item
has not actually been selected.

}\end{flushright}

{\samepage
{\large {\bf choice-item-label \hfill Method, choice item protocol}}
\index{choice item, choice-item-label method}
\index{choice-item-label method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-item-label & \\
& (choice-item) \\
(declare &(type contact & choice-item))\\
(declare & (values(or string pixmap))))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{ Returns the {\tt pixmap} or string
object used to label the choice item.

}\end{flushright}


{\samepage  
{\large {\bf choice-item-label-alignment \hfill Method, choice item protocol}}
\index{choice item, choice-item-label-alignment method}
\index{choice-item-label-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-item-label-alignment & \\
& (choice-item) \\
(declare &(type contact & choice-item))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-item-label-alignment) & \\
         & (alignment \\
         & choice-item) \\
(declare &(type (member :left :center :right)  alignment)\\
         &(type contact & choice-item))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the alignment of the label within the {\tt choice-item}.}
\end{flushright}


{\samepage
{\large {\bf choice-item-selected-p \hfill Method, choice item protocol}}
\index{choice item, choice-item-selected-p method}
\index{choice-item-selected-p method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-item-selected-p & \\
& (choice-item) \\
(declare &(type contact & choice-item))\\
(declare & (values boolean)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-item-selected-p) & \\
         & (selected-p \\
         & choice-item) \\
(declare &(type boolean  selected-p)\\
         &(type contact & choice-item))\\
(declare & (values boolean)))
\end{tabular}
\rm
}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the selected state of a choice item. 

{\tt (setf choice-item-selected-p)} is called when the current selection is
changed by the application program, i.e.  when the application program calls
{\tt (setf choice-selection)}.  Calling this method should have the same
effect as (un)selecting the choice item interactively by a user.}\end{flushright}

\SAMEL{Application Callbacks}{sec:choice-item-app-callbacks}\index{choice item, application callbacks}

The application semantics of (un)selecting a choice item are implemented
primarily by the
callbacks of the choice item, {\em not} by callbacks of its parent. An
application determines the semantics of (un)selecting a choice item by defining
the following callbacks for it. 

{\samepage
{\large {\bf :off \hfill Callback, choice item protocol}} 
\index{choice item, :off callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & off-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked on the current selection item when the selection changes.

}\end{flushright}


{\samepage
{\large {\bf :on \hfill Callback, choice item protocol}} 
\index{choice item, :on callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & on-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the choice item is selected.

}\end{flushright}

\SAMEL{Control Callbacks}{sec:choice-item-ctrl-callbacks}\index{choice item, control callbacks}

Depending on its behavior, a choice contact may need to respond to
certain user operations on an individual choice item. For example, if a choice
contact allows at most one choice item to be selected, then it should respond to
a new user selection by unselecting the previously-selected choice item. Thus, a
choice item must invoke certain control callbacks to allow its containing
choices contact to control its selection interaction properly.

A choice item should invoke the following callbacks at the appropriate times in
order inform its choice parent about important user actions.  A choice contact
will associate with these callback names the functions that implement its
response to these user actions.

{\samepage
{\large {\bf :change-allowed-p \hfill Callback, choice item protocol}} 
\index{choice item, :change-allowed-p callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & change-allowed-p-function \\
& (to-selected-p)\\
(declare & (type boolean to-selected-p))\\
(declare & (values boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the choice item is about to be selected or unselected. The {\tt to-selected-p}
argument is true if and only if the choice item is about to be selected. If no
{\tt
:change-allowed-p} function is defined or if this  callback function  returns
true, then choice item highlighting may change and the
{\tt :changing} callback may be invoked and, ultimately, the {\tt :on}/{\tt :off}
callback may be invoked. However, if {\tt :change-allowed-p} returns {\tt nil},
then the choice item is not allowed to change state, and none of these operations
should be performed.

}\end{flushright}


{\samepage
{\large {\bf :changing \hfill Callback, choice item protocol}} 
\index{choice item, :changing callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & changing-function \\
 & (to-selected-p) \\
(declare & (type boolean to-selected-p)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ A sequence of user actions may be
required to (un)select a choice item (for example, a {\tt :button-press} event
followed by a {\tt :button-release} event).  The {\tt :changing} callback is
invoked when the user begins to (un)select the choice item; the {\tt to-selected-p}
argument is true if and only if the user is beginning to select the choice item.
In this case, the choice item may have changed its visual
appearance to indicate the anticipated transition to the new state.  A choice
contact may respond to this callback by changing the highlighting of other
choice items.

}\end{flushright}


{\samepage
{\large {\bf :canceling-change \hfill Callback, choice item protocol}} 
\index{choice item, :canceling-change callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & canceling-change-function \\
 & (to-selected-p) \\
(declare & (type boolean to-selected-p)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ A sequence of user actions may be
required
to (un)select a choice item (for example, a {\tt :button-press} event followed
by a {\tt :button-release} event).  The {\tt :canceling-change} callback is
invoked when the user cancels his (un)selection without completing the full
sequence; the {\tt to-selected-p}
argument is true if the user is canceling a selection operation and {\tt nil}
otherwise. In this case, the choice item is no longer about to be (un)selected
and may have removed any visual feedback of the previously-anticipated change in
state.  A choice contact may respond to this callback by changing the
highlighting of other choice items.

}\end{flushright}

\vfill
\pagebreak

\HIGHER{Choices}\index{choices}                                      

\index{classes, choices}

A {\tt choices} contact is a composite that allows a user to choose at most one
of its children.  The members of a {\tt choices} children list are referred to
as {\bf choice items}\index{choices, items}.  A {\tt choices} composite uses the
geometry management of a {\tt table} to arrange its items in rows and columns
(see Section~\ref{sec:table}).\index{choice item}

The item of a {\tt choices} chosen by a user is referred to as the {\bf
selection}\index{choices, selection}\footnotemark\footnotetext{Note that this
meaning of
``selection'' is completely different from the concept of the selection
mechanism for interclient communication discussed in
Section~\ref{sec:selections}.}.  An application program can initialize both
the current selection and the default selection.  {\tt choices} behavior depends
on its choice policy, which can be either {\tt :always-one} (the current
selection can be changed only by choosing another item) or {\tt :one-or-none}
(the current selection may be {\tt nil}).

The following functions may be used to specify the layout of {\tt choices}
members.

\begin{itemize}
\item {\tt table-column-alignment}
\item {\tt table-column-width}
\item {\tt table-columns}
\item {\tt table-row-alignment}
\item {\tt table-row-height}
\item {\tt table-same-height-in-row}
\item {\tt table-same-width-in-column}
\end{itemize}


The following functions may be used to set the margins surrounding the {\tt
choices}.

\begin{itemize}
\item {\tt display-bottom-margin}
\item {\tt display-left-margin}
\item {\tt display-right-margin}
\item {\tt display-top-margin}
\end{itemize}

\pagebreak
The following functions may be used to set the spacing between  {\tt choices} rows
and columns.

\begin{itemize}
\item {\tt display-horizontal-space}
\item {\tt display-vertical-space}
\end{itemize}



\LOWER{Functional Definition}

A {\tt choices} composite uses the
geometry management of a {\tt table} to arrange its items in rows and columns.
All accessors, initargs, and constraint resources defined in
Section~\ref{sec:table} are applicable to a {\tt choices} composite.


{\samepage
{\large {\bf make-choices \hfill Function}} 
\index{constructor functions, choices}
\label{page:make-choices}
\index{make-choices function}
\index{choices, make-choices function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-choices \\
       & (\&rest initargs \\
       & \&key  \\ 
       & (border                & *default-contact-border*) \\ 
       & (bottom-margin         & :default) \\
       & (choice-policy         & :one-or-none)\\
       & (column-alignment      & :left)\\
       & (column-width          & :maximum)\\
       & (columns               & 0)\\
       & default-selection & \\
       & (font                  & *default-choice-font*)\\       
       & foreground \\
       & (horizontal-space      & :default) \\
       & (left-margin           & :default) \\
       & (right-margin          & :default) \\
       & (row-alignment         & :bottom)\\
       & (row-height            & :maximum)\\
       & (same-height-in-row    & :off)\\
       & (same-width-in-column  & :off)\\
       & separators  & \\
       & (top-margin            & :default) \\
       & (vertical-space        & :default) \\
       & \&allow-other-keys) \\
(declare & (values   choices)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt choices} contact.
The resource specification list of the {\tt choices} class defines
a resource for each of the initargs above.\index{choices,
resources}

The {\tt default-selection} initarg is the contact name symbol for the choice item
that is the initial default selection.

}\end{flushright}

{\samepage
{\large {\bf choice-default \hfill Method, choices}}
\index{choices, choice-default method}
\index{choice-default method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-default & \\
& ((choices  choices)) \\
(declare & (values (or null contact))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-default) & \\
         & (default \\
         & (choices choices)) \\
(declare &(type (or null contact)  default))\\
(declare & (values (or null contact))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the default selection.

}\end{flushright}

{\samepage
{\large {\bf choice-font \hfill Method, choices}}
\index{choices, choice-font method}
\index{choice-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-font & \\
& ((choices  choices)) \\
(declare & (values (or null font))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-font) & \\
         & (font \\
         & (choices choices)) \\
(declare &(type (or null fontable)  font))\\
(declare & (values (or null font))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification for all choice item text labels.
Together
with the {\tt choice-item-label}, this determines the {\tt font}
object used to display label characters. If {\tt nil}, then choice items are
allowed to use different fonts.

}\end{flushright}

{\samepage
{\large {\bf choice-policy \hfill Method, choices}}
\index{choices, choice-policy method}
\index{choice-policy method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-policy & \\
& ((choices  choices)) \\
(declare & (values (member :always-one :one-or-none))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-policy) & \\
         & (policy \\
         & (choices choices)) \\
(declare &(type (member :always-one :one-or-none)  policy))\\
(declare & (values (member :always-one :one-or-none))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the choice policy. If {\tt :always-one}, then the current
selection can be changed only by choosing another item. If {\tt :one-or-none}, then
the current selection may be {\tt nil}.

}\end{flushright}

{\samepage
{\large {\bf choice-selection \hfill Method, choices}}
\index{choices, choice-selection method}
\index{choice-selection method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-selection & \\
& ((choices  choices)) \\
(declare & (values (or null contact))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-selection) & \\
         & (selection \\
         & (choices choices)) \\
(declare &(type (or null contact)  selection))\\
(declare & (values (or null contact))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the currently-selected choice item. In order to
avoid surprising the user, an application program should change the selection only in
response to some user action.

}\end{flushright}


\vfill
\pagebreak

\HIGHER{Multiple Choices}\index{multiple-choices}                                      


\index{classes, multiple-choices}

A {\tt multiple-choices} contact is a composite that allows a user to choose any subset
of its children.  The members of a {\tt multiple-choices} children list are referred to
as {\bf choice items}\index{multiple-choices, items}.  A {\tt multiple-choices}
composite uses the
geometry management of a {\tt table} to arrange its items in rows and columns
(see Section~\ref{sec:table}).\index{choice item}

The items of a {\tt multiple-choices} chosen by a user are referred to as the {\bf
selection}\index{multiple-choices, selection}\footnotemark\footnotetext{Note
that this meaning of
``selection'' is completely different from the concept of the selection
mechanism for interclient communication discussed
in Section~\ref{sec:selections}.}.  An application program can initialize both
the current selection and the default selection.  

The following functions may be used to specify the layout of {\tt table}
members.

\begin{itemize}
\item {\tt table-column-alignment}
\item {\tt table-column-width}
\item {\tt table-columns}
\item {\tt table-row-alignment}
\item {\tt table-row-height}
\item {\tt table-same-height-in-row}
\item {\tt table-same-width-in-column}
\end{itemize}


The following functions may be used to set the margins surrounding the {\tt
multiple-choices}.

\begin{itemize}
\item {\tt display-bottom-margin}
\item {\tt display-left-margin}
\item {\tt display-right-margin}
\item {\tt display-top-margin}
\end{itemize}

\pagebreak
The following functions may be used to set the spacing between  {\tt multiple-choices} rows
and columns.

\begin{itemize}
\item {\tt display-horizontal-space}
\item {\tt display-vertical-space}
\end{itemize}


\LOWER{Functional Definition}

A {\tt multiple-choices} composite uses the
geometry management of a {\tt table} to arrange its items in rows and columns.
All accessors, initargs, and constraint resources defined in
Section~\ref{sec:table} are applicable to a {\tt multiple-choices} composite.


{\samepage

{\large {\bf make-multiple-choices \hfill Function}}
\label{page:make-multiple-choices} 
\index{constructor functions, multiple-choices}
\index{make-multiple-choices function}
\index{multiple-choices, make-multiple-choices function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-multiple-choices \\
       & (\&rest initargs \\
       & \&key  \\ 
       & (border                & *default-contact-border*) \\ 
       & (bottom-margin         & :default) \\
       & (column-alignment      & :left)\\
       & (column-width          & :maximum)\\
       & (columns               & 0)\\
       & default-selection & \\
       & (font                  & *default-choice-font*)\\       
       & foreground \\
       & (horizontal-space      & :default) \\
       & (left-margin           & :default) \\
       & (right-margin          & :default) \\
       & (row-alignment         & :bottom)\\
       & (row-height            & :maximum)\\
       & (same-height-in-row    & :off)\\
       & (same-width-in-column  & :off)\\
       & separators  & \\
       & (top-margin            & :default) \\
       & (vertical-space        & :default) \\
       & \&allow-other-keys) \\
(declare & (values   multiple-choices)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt multiple-choices} contact.
The resource specification list of the {\tt multiple-choices} class defines
a resource for each of the initargs above.\index{multiple-choices,
resources}

The {\tt default-selection} initarg is a list of contact name symbols for the
choice items that are the initial default selection.


}\end{flushright}

{\samepage
{\large {\bf choice-default \hfill Method, multiple-choices}}
\index{multiple-choices, choice-default method}
\index{choice-default method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-default & \\
& ((multiple-choices  multiple-choices)) \\
(declare &(values list)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-default) & \\
         & (default \\
         & (multiple-choices multiple-choices)) \\
(declare &(type list  default))\\
(declare & (values list)))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the default selection.

}\end{flushright}

{\samepage
{\large {\bf choice-font \hfill Method, multiple-choices}}
\index{multiple-choices, choice-font method}
\index{choice-font method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-font & \\
& ((multiple-choices  multiple-choices)) \\
(declare & (values(or null font))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-font) & \\
         & (font \\
         & (multiple-choices multiple-choices)) \\
(declare &(type (or null fontable)  font))\\
(declare & (values (or null font))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the font specification for all choice item text labels.
Together
with the {\tt choice-item-label}, this determines the {\tt font}
object used to display label characters. If {\tt nil}, then choice items are
allowed to use different fonts.


}\end{flushright}


{\samepage
{\large {\bf choice-selection \hfill Method, multiple-choices}}
\index{multiple-choices, choice-selection method}
\index{choice-selection method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & choice-selection & \\
& ((multiple-choices  multiple-choices)) \\
(declare &(values list)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf choice-selection) & \\
         & (selection \\
         & (multiple-choices multiple-choices)) \\
(declare &(type list  selection))\\
(declare & (values list)))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the currently-selected choice items. In order to
avoid surprising the user, an application program should change the selection only in
response to some user action.


}\end{flushright}





\CHAPTER{Containers}

A {\bf container}\index{container} is a composite contact used to manage a set
of child contacts.  Some container classes are referred to as {\bf layouts}.
\index{layouts} A layout is a type of container whose purpose is limited to
providing a specific style of geometry management.  Examples of CLIO layouts
include {\tt form} and {\tt table}.

\LOWER{Form}\index{form}                                      

\index{classes, form}

A {\tt form} is a layout contact \index{layouts} which manages the geometry of a
set of children (or {\bf members}\index{form, members}) according to a set of
constraints.  Geometrical constraints are defined by constraint
resources\footnotemark\footnotetext{See \cite{clue} for a complete description of
constraint resources.} of individual members and by the {\bf links}\index{link}
between members.  Links are used to specify the ideal/minimum/maximum spacing
between two members or between a member and the form itself.\index{form,
constraints} Member constraints are used to define the minimum/maximum for each
member's size.

\LOWER{Form Layout Policy}\index{form, layout policy}

A {\tt form} is said to satisfy its layout constraints if the size of each member
and the length of each link lies between its requested minimum and maximum.  The
basic {\tt form} layout policy is to satisfy its constraints and keep all members
completely visible within the current size of the form.  Therefore, changing the
size of a {\tt form} will usually result in changes to the size or position of its
members or to the length of the links that define the spaces between members.
Similarly, any changes to the member constraints or to the links of a {\tt form}
may cause the form to change its layout to satisfy the new constraints.  Note that
members may be clipped by the edges of a {\tt form}, if its constraints cannot be
satisfied otherwise.

When a {\tt form} is first created or when it is resized or when its set of
members and links is changed, then the {\tt form} must ensure that its constraints
remain satisfied.  In doing so, a {\tt form} first determines its own ``ideal''
size, defined by the current sizes of all members and links.  A {\tt form} will
then negotiate with its geometry manager to change to the ``best'' approximation
of the ideal size.  If this best size differs from the current size of the {\tt
form}, then the resulting ``stretch'' or ``shrink'' is distributed over all
members and links, in proportion to the ``stretchability'' or ``shrinkability'' of
each individual member and link.  The stretchability of a member or link is the
difference between its current size and its maximum size.  Similarly, the
shrinkability of a member or link is the difference between its current size and
its minimum size.

The maximum size of a member or the length of a link may be {\tt :infinite},
indicating that the member or link can grow to any size.  The {\tt form} layout
policy treats {\tt :infinite} values specially.  Within a chain of linked members,
any extra ``stretch'' in the layout is distributed equally among the {\tt
:infinite} members and links, leaving other members and links unchanged.

\SAME{Functional Definition}

{\samepage
{\large {\bf make-form \hfill Function}} 
\index{constructor functions, form}
\index{make-form function}
\index{form, make-form function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-form \\
       & (\&rest initargs \\
       & \&key  \\ 
       & (border                & *default-contact-border*) \\ 
       & foreground \\
       & horizontal-links \\
       & vertical-links \\
       & \&allow-other-keys) \\
(declare &(type list& horizontal-links vertical-links))\\
(declare & (values   form)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt form} contact.
The resource specification list of the {\tt form} class defines
a resource for each of the initargs above.\index{form,
resources}

The {\tt horizontal-links} and {\tt vertical-links} arguments initialize the links
between form members (see Section~\ref{sec:links}).  Each argument is a list of
the form {\tt ({\em link-init-list}*)}, where each {\em link-init-list} is a list
of keyword/value pairs.  The keywords allowed for {\tt horizontal-links} and {\tt
vertical-links} are the same as those for {\tt make-horizontal-link} and {\tt
make-vertical-link}, respectively. However, initial values of {\tt :from} and {\tt
:to} keywords must be specified by contact name symbols, rather than contact
instances.

}\end{flushright}





\SAME{Constraint Resources}
The
following functions may be used to return or change
the constraint resources of {\tt form} members.
\index{form, changing constraints}
\index{form, constraints}


{\samepage  
{\large {\bf form-max-height \hfill Function}}
\index{form, form-max-height function}
\index{form-max-height function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & form-max-height & \\
& (member) \\
(declare &(type contact & member))\\
(declare & (values (or card16 (member :infinite)))))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the maximum
            height allowed for the member.  A {\tt form} is allowed to change the
            height of the member to any value between its minimum/maximum height
in order to satisfy
            its layout constraints.

The maximum height of a member may be initialized by specifying a {\tt
:max-height} initarg to the constructor function which creates the member.
 
}
\end{flushright}



 

{\samepage  
{\large {\bf form-max-width \hfill Function}}
\index{form, form-max-width function}
\index{form-max-width function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & form-max-width & \\
& (member) \\
(declare &(type contact & member))\\
(declare & (values (or card16 (member :infinite)))))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the maximum
            width allowed for the member.  A {\tt form} is allowed to change the
            width of the member to any value between its minimum/maximum width
in order to satisfy
            its layout constraints.

The maximum width of a member may be initialized by specifying a {\tt
:max-width} initarg to the constructor function which creates the member.
}
\end{flushright}



 
{\samepage  
{\large {\bf form-min-height \hfill Function}}
\index{form, form-min-height function}
\index{form-min-height function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & form-min-height & \\
& (member) \\
(declare &(type contact & member))\\
(declare & (values card16)))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the minimum
            height allowed for the member.  A {\tt form} is allowed to change the
            height of the member to any value between its minimum/maximum height
in order to satisfy
            its layout constraints.

The minimum height of a member may be initialized by specifying a {\tt
:min-height} initarg to the constructor function which creates the member.
}
\end{flushright}



 

{\samepage  
{\large {\bf form-min-width \hfill Function}}
\index{form, form-min-width function}
\index{form-min-width function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & form-min-width & \\
& (member) \\
(declare &(type contact & member))\\
(declare & (values card16)))
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the minimum
            width allowed for the member.  A {\tt form} is allowed to change the
            width of the member to any value between its minimum/maximum width
in order to satisfy
            its layout constraints.

The minimum width of a member may be initialized by specifying a {\tt
:min-width} initarg to the constructor function which creates the member.
}
\end{flushright}



 

\SAMEL{Link Functions}{sec:links}\index{link}

A {\tt link} represents the space between two members of a {\tt form} layout.  A
{\tt link} has a specific orientation, either horizontal or vertical.
The {\bf length} of a {\tt
link} specifies the distance in pixels from its {\bf
from-member}\index{link, from-member} to its {\bf to-member},\index{link,
to-member}. The length of a {\tt link} is also directional, where a
positive length is to the right or downward, depending on the
orientation of the {\tt link}.  The space represented by the length of a {\tt
link} is always measured between specific {\bf attach points}\index{link, attach
points} on its to-member and from-member.  An attach point can be either the center
of the member or one of its edges --- the left or right edge for horizontal links,
the top or bottom edge for vertical links.
Either the to-member or the from-member of a {\tt link} can be the {\tt form}
itself; in this case, the other member must be a member of the {\tt form}.

In general, between any two members, there can be at most one horizontal
link and at most one vertical link.  However, there can be multiple
links between a {\tt form} and one of its members.  For a given
orientation, a member can have a distinct link to each possible attach
point on the {\tt form}.  For example, a single member could define
horizontal links to both the left and right edges of its {\tt form}.

The following functions are used to create, destroy, look up, and modify {\tt link}
objects.

\pagebreak

{\samepage
{\large {\bf make-horizontal-link \hfill Function}} 
\index{make-horizontal-link function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-horizontal-link & \\
&	  (\&key \\
&	   (attach-from & :right) \\
&	   (attach-to   & :left) \\
&	   from \\
&	   length      &  \\
&	   (maximum     & :infinite) \\
&	   (minimum     & 0) \\
&	   to) \\
(declare & (type contact &                        from to)\\
&	    (type (member :left :center :right) & attach-from attach-to) \\
&	    (type int16	&			 length minimum) \\
&	    (type (or int16 (member :infinite))	& maximum)) \\
(declare &(values link)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 

Creates and returns a horizontal link between {\tt from} and {\tt to}.  The {\tt
from} and {\tt to} contacts may either be members of the same {\tt form} or a
member and its parent {\tt form}.  The {\tt length} is measured from {\tt from}
to {\tt to}, so a positive {\tt length} indicates that {\tt to} is to the right
of {\tt from};  by default, the {\tt length} is equal to the {\tt minimum}. {\tt
attach-from} and {\tt attach-to}
indicate where the link attaches to {\tt from} and {\tt to}, respectively.  


}\end{flushright}


{\samepage
{\large {\bf make-vertical-link \hfill Function}} 
\index{make-vertical-link function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-vertical-link & \\
&	  (\&key \\
&	   (attach-from & :bottom) \\
&	   (attach-to   & :top) \\
&	   from \\
&	   length      &  \\
&	   (maximum     & :infinite) \\
&	   (minimum     & 0) \\
&	   to) \\
(declare & (type contact &                        from to)\\
&	    (type (member :top :center :bottom) & attach-from attach-to) \\
&	    (type int16	&			 length minimum) \\
&	    (type (or int16 (member :infinite))	& maximum)) \\
(declare &(values link)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 

Creates and returns a vertical link between {\tt from} and {\tt to}.  The {\tt
from} and {\tt to} contacts may either be members of the same {\tt form} or a
member and its parent {\tt form}.  The {\tt length} is measured from {\tt from}
to {\tt to}, so a positive {\tt length} indicates that {\tt to} is below {\tt
from};  by default, the {\tt length} is equal to the {\tt minimum}.  {\tt
attach-from} and {\tt attach-to} indicate where the link
attaches to {\tt from} and {\tt to}, respectively.  


}\end{flushright}

{\samepage
{\large {\bf destroy \hfill Method, link}} 
\index{destroy method}
\index{link, destroy method}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & destroy & \\ 
& ((link & link))) \\
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{Destroys the {\tt link}, removing
its layout constraints between its {\tt from} and {\tt to} contacts.
}\end{flushright}

{\samepage
{\large {\bf find-link \hfill Function}} 
\index{find-link function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & find-link & \\ 
& (contact-1 \\
&  contact-2 \\
&  orientation\\
& \&optional \\
&  form-attach-point)\\ 
(declare &(type contact &                       contact-1 contact-2)\\
	 &(type (member :horizontal :vertical)& orientation)\\
         &(type (member :left :right :top :bottom :center)& form-attach-point))\\
(declare &(values (or link null)))) \\
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{ Returns the link of the given
{\tt orientation} between {\tt contact-1} and {\tt contact-2}.  If
either {\tt contact-1} or {\tt contact-2} is a {\tt form}, then the {\tt
form-attach-point} argument may be given to specify the {\tt form} link
desired; the {\tt form-attach-point} may be omitted if there is only one
link of the given {\tt orientation} between the {\tt form} and the
member.

}\end{flushright}


{\samepage
{\large {\bf link-attach-from \hfill Method, link}}
\index{link, link-attach-from method}
\index{link-attach-from method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & link-attach-from & \\
           & ((link  link)) \\
(declare   & (values (member :left :right :top :bottom :center))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf link-attach-from) & \\
         & (attach-from \\
         & (link link)) \\
(declare &(type (member :left :right :top :bottom :center) & attach-from))\\
(declare &(values (member :left :right :top :bottom :center))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and (with {\tt setf}) changes the attach point of the {\tt link} on
its from-member. For a horizontal link, the attach point is one of {\tt
:left}, {\tt :center}, or {\tt :right}. For a vertical link, the attach point is one of {\tt
:top}, {\tt :center}, or {\tt :bottom}.

}\end{flushright}


{\samepage
{\large {\bf link-attach-to \hfill Method, link}}
\index{link, link-attach-to method}
\index{link-attach-to method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & link-attach-to & \\
           & ((link  link)) \\
(declare   & (values (member :left :right :top :bottom :center))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf link-attach-to) & \\
         & (attach-to \\
         & (link link)) \\
(declare &(type (member :left :right :top :bottom :center) & attach-to))\\
(declare &(values (member :left :right :top :bottom :center))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and (with {\tt setf}) changes the attach point of the {\tt link} on
its to-member. For a horizontal link, the attach point is one of {\tt
:left}, {\tt :center}, or {\tt :right}. For a vertical link, the attach point is one of {\tt
:top}, {\tt :center}, or {\tt :bottom}.

}\end{flushright}

{\samepage
{\large {\bf link-from \hfill Method, link}}
\index{link, link-from method}
\index{link-from method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & link-from & \\
           & ((link  link)) \\
(declare   & (values contact)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the from-member of the {\tt link}.

}\end{flushright}


{\samepage
{\large {\bf link-length \hfill Method, link}}
\index{link, link-length method}
\index{link-length method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & link-length & \\
           & ((link  link)) \\
(declare   & (values int16)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf link-length) & \\
         & (length \\
         & (link link)) \\
(declare &(type int16 & length))\\
(declare &(values int16)))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns and (with {\tt setf}) changes the current length of the {\tt link}.

}\end{flushright}

{\samepage
{\large {\bf link-maximum \hfill Method, link}}
\index{link, link-maximum method}
\index{link-maximum method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & link-maximum & \\
           & ((link  link)) \\
(declare   & (values (or int16 (member :infinite)))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf link-maximum) & \\
         & (maximum \\
         & (link link)) \\
(declare &(type (or int16 (member :infinite)) & maximum))\\
(declare &(values (or int16 (member :infinite)))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns and (with {\tt setf}) changes the maximum length of the {\tt link}.

}\end{flushright}


{\samepage
{\large {\bf link-minimum \hfill Method, link}}
\index{link, link-minimum method}
\index{link-minimum method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & link-minimum & \\
           & ((link  link)) \\
(declare   & (values int16)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf link-minimum) & \\
         & (minimum \\
         & (link link)) \\
(declare &(type int16 & minimum))\\
(declare &(values int16)))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns and (with {\tt setf}) changes the minimum length of the {\tt link}.

}\end{flushright}

{\samepage
{\large {\bf link-orientation \hfill Method, link}}
\index{link, link-orientation method}
\index{link-orientation method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & link-orientation & \\
           & ((link  link)) \\
(declare   & (values (member :horizontal :vertical))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the orientation of the {\tt link}.

}\end{flushright}



{\samepage
{\large {\bf link-to \hfill Method, link}}
\index{link, link-to method}
\index{link-to method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & link-to & \\
           & ((link  link)) \\
(declare   & (values contact)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the to-member of the {\tt link}.

}\end{flushright}


{\samepage
{\large {\bf link-update \hfill Method, link}} 
\index{link-update method}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & link-update & \\
&	  ((link link) \\
&          \&key \\
&	   attach-from &  \\
&	   attach-to   &  \\
&	   length      &  \\
&	   minimum     &  \\
&	   maximum)     &  \\
(declare & (type (member :left :right :top :center :bottom) & attach-from attach-to) \\ 
&	    (type int16	&			 length minimum) \\
&	    (type (or int16 (member :infinite))	& maximum))) \\

\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 

Changes one or more {\tt link} attributes simultaneously. This method causes form
constraints to be reevaluated only once and thus is more efficient than changing
each attribute individually.

}\end{flushright}






\vfill\pagebreak

\HIGHER{Scroll Frame}\index{scroll-frame}                                      
\index{classes, scroll-frame}

A {\tt scroll-frame} is a {\tt composite} contact which contains a contact
called the {\bf content}
\index{scroll-frame, content}
and which allows a user to view different parts of the content
by manipulating horizontal and/or vertical scrolling controls.  The
scrolling controls are implemented by {\tt scroller} contacts and are
created automatically.  

The content is displayed in an area of the {\tt scroll-frame} represented by a
contact called the {\bf scroll area}.\index{scroll-frame, scroll area} The
scroll area is the parent contact for the content.  An application programmer
initializes a {\tt scroll-frame} by defining its content as a child of the
scroll area.  A {\tt scroll-frame} can contain at most one contact as its
content.

Scrolling is performed by callback functions defined on the content.  An
application programmer may define {\tt :horizontal-calibrate} and
{\tt :vertical-calibrate} callbacks, which are called to initialize the
{\tt scroll-frame.}  The content's {\tt :scroll-to} callback is called to
redisplay the content at a new position.  The {\tt :horizontal-calibrate}
and {\tt :vertical-calibrate}
callbacks allow the application programmer to define the ranges and units
for scroll position values.  All scrolling is performed in these
{\bf content units}. 
\index{scroll-frame, content units}
A {\tt scroll-frame} uses defaults for the
{\tt :horizontal-calibrate}, {\tt :vertical-calibrate}, and {\tt :scroll-to}
callback functions, if they are not given by the application programmer.

A {\tt scroll-frame} also defines {\tt :horizontal-update} and {\tt
:vertical-update} callback functions on its content.  These functions may be
called to inform the {\tt scroll-frame} about changes in content size, position,
etc.  caused by the application program.


\LOWER{Functional Definition}


{\samepage
{\large {\bf make-scroll-frame \hfill Function}} 
\index{constructor functions, scroll-frame}
\index{make-scroll-frame function}
\index{scroll-frame, make-scroll-frame function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-scroll-frame \\
       & (\&rest initargs \\
       & \&key  \\ 
       & (border                & *default-contact-border*) \\ 
       & content                &  \\ 
       & foreground \\
       & (horizontal    & :on)\\
       & (left          & 0)\\
       & (top           & 0)\\
       & (vertical      & :on) \\      
       & \&allow-other-keys) \\
(declare & (values   scroll-frame)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt scroll-frame} contact.
The resource specification list of the {\tt scroll-frame} class defines
a resource for each of the initargs above.\index{scroll-frame,
resources}

The {\tt content} initarg, if given, causes the content contact to be created
automatically with a specific constructor function and an optional list of
initargs.\index{scroll-frame, content} The value of the {\tt content} argument is
either a constructor function or a list of the form {\tt ({\em constructor} .
{\em content-initargs})}, where {\em constructor} is a function that creates and
returns the content and {\em content-initargs} is a list of keyword/value pairs
used by the {\em constructor}.

}\end{flushright}

{\samepage
{\large {\bf scroll-frame-area \hfill Method, scroll-frame}}
\index{scroll-frame, scroll-frame-area method}
\index{scroll-frame-area method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scroll-frame-area & \\
& ((scroll-frame  scroll-frame)) \\
(declare & (values contact)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the  scroll area of the {\tt scroll-frame}. The content of the
{\tt scroll-frame}  may be set by creating a contact whose parent is the
scroll area.   }\end{flushright}

{\samepage
{\large {\bf scroll-frame-content \hfill Method, scroll-frame}}
\index{scroll-frame, scroll-frame-content method}
\index{scroll-frame-content method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scroll-frame-content & \\
& ((scroll-frame  scroll-frame)) \\
(declare & (values contact)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the  content of the {\tt scroll-frame}. The content of the
{\tt scroll-frame}  is set by creating a contact whose parent is the scroll
area, or by using the {\tt content} initarg with {\tt
make-scroll-frame}. \index{scroll-frame, content}
}\end{flushright}


{\samepage
{\large {\bf scroll-frame-horizontal \hfill Method, scroll-frame}}
\index{scroll-frame, scroll-frame-horizontal method}
\index{scroll-frame-horizontal method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scroll-frame-horizontal & \\
& ((scroll-frame  scroll-frame)) \\
(declare & (values (member :on :off))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scroll-frame-horizontal) & \\
         & (switch \\
         & (scroll-frame scroll-frame)) \\
(declare &(type (member :on :off)  switch))\\
(declare & (values (member :on :off))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Enables or disables the user control for horizontal scrolling. 
}\end{flushright}


{\samepage
{\large {\bf scroll-frame-vertical \hfill Method, scroll-frame}}
\index{scroll-frame, scroll-frame-vertical method}
\index{scroll-frame-vertical method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scroll-frame-vertical & \\
& ((scroll-frame  scroll-frame)) \\
(declare & (values (member :on :off))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf scroll-frame-vertical) & \\
         & (switch \\
         & (scroll-frame scroll-frame)) \\
(declare &(type (member :on :off)  switch))\\
(declare & (values (member :on :off))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Enables or disables the user control for vertical scrolling. 
}\end{flushright}



{\samepage
{\large {\bf scroll-frame-position \hfill Method, scroll-frame}}
\index{scroll-frame, scroll-frame-position method}
\index{scroll-frame-position method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scroll-frame-position & \\
& ((scroll-frame  scroll-frame)) \\
(declare & (values left top)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the current horizontal/vertical position of the content (in content
units) which appears at the left/top edge of the scroll area.
}\end{flushright}

{\samepage
{\large {\bf scroll-frame-reposition \hfill Method, scroll-frame}}
\index{scroll-frame, scroll-frame-reposition method}
\index{scroll-frame-reposition method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & scroll-frame-reposition & \\
& ((scroll-frame  scroll-frame)\\
& \&key left top) \\
(declare &(type number left top))\\
(declare & (values left top)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
Changes the horizontal/vertical position
of the content (in content units) which appears at the left/top edge of the
scroll area.  The (possibly adjusted) final content position  (see
{\tt :horizontal-adjust} and {\tt :vertical-adjust}
callbacks, Section~\ref{sec:scroll-frame-callbacks}) is returned.

}\end{flushright}

	




              
\SAMEL{Content Callbacks}{sec:scroll-frame-callbacks}

\index{scroll-frame, callbacks}
A {\tt scroll-frame} does not use any
callbacks of its own.  Instead, an application programmer controls scrolling by
defining the following callbacks for the content.

{\samepage
{\large {\bf :horizontal-adjust \hfill Callback}} 
\index{scroll-frame, :horizontal-adjust callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & horizontal-adjust-function & \\ 
& (left) \\
(declare &(type  number  left))\\
(declare & (values   number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns an adjusted new left position.
Called when the horizontal position of the content is changed.  The given left
position is guaranteed to be a valid value.  The default function for this
callback returns the given position unchanged.

}\end{flushright}


{\samepage
{\large {\bf :horizontal-calibrate \hfill Callback}} 
\index{scroll-frame, :horizontal-calibrate callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & horizontal-calibrate-function () \\
(declare & (values   minimum maximum pixels-per-unit)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns values needed to initialize
horizontal scrolling for the {\tt scroll-frame.}  The current minimum and
maximum for the horizontal position are returned in content units.
The pixels-per-unit returned is used for two purposes. First, pixels-per-unit
is used to set the indicator size of the horizontal {\tt
scroller} to show the number of units visible in the scroll area. Also, 
if the default {\tt :scroll-to} callback is used, pixels-per-unit defines the
size of the content units used for scrolling.  

The default
function for this callback returns the following values.  
\begin{center}
\begin{tabular}[t]{ll}
minimum: &	0 \\ 
maximum: &	 {\tt (max 0 (- (contact-width content) (contact-width scroll-area)))}\\
pixels-per-unit: & 1\\ 
\end{tabular}
\end{center}
}\end{flushright}


	

		


{\samepage
{\large {\bf :horizontal-update \hfill Callback}} 
\index{scroll-frame, :horizontal-update callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & horizontal-update-function & \\  
& (\&key \\
&  position \\
&  minimum \\
&  maximum \\
&  pixels-per-unit) \\
(declare &(type  number  position minimum maximum pixels-per-unit)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
This callback is added to the content
automatically by the {\tt scroll-frame,} not by the application programmer.  May
be called to inform the {\tt scroll-frame} about changes made by the program in
the content's horizontal calibration data. See {\tt :horizontal-calibrate}
callback.

}\end{flushright}

{\samepage
{\large {\bf :vertical-adjust \hfill Callback}} 
\index{scroll-frame, :vertical-adjust callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & vertical-adjust-function & \\ 
& (top) \\
(declare &(type  number  top))\\
(declare & (values   number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns an adjusted new top position.
Called when the vertical position of the content is changed.  The given top
position is guaranteed to be a valid value.  The default function for this
callback returns the given position unchanged.

}\end{flushright}


{\samepage
{\large {\bf :vertical-calibrate \hfill Callback}} 
\index{scroll-frame, :vertical-calibrate callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & vertical-calibrate-function () \\
(declare & (values   minimum maximum pixels-per-unit)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns values needed to initialize
vertical scrolling for the {\tt scroll-frame.}  The current minimum and
maximum for the vertical position are returned in content units.
The pixels-per-unit returned is used for two purposes. First, pixels-per-unit
is used to set the indicator size of the vertical {\tt
scroller} to show the number of units visible in the scroll area. Also, 
if the default {\tt :scroll-to} callback is used, pixels-per-unit defines the
size of the content units used for scrolling.  

The default function for this callback returns the following values.
\begin{center}
\begin{tabular}[t]{ll}
minimum: &	0 \\ 
maximum: &	{\tt (max 0 (- (contact-height content) (contact-height scroll-area)))}\\ 
pixels-per-unit: & 1\\
\end{tabular}
\end{center}
}\end{flushright}


			
{\samepage
{\large {\bf :vertical-update \hfill Callback}} 
\index{scroll-frame, :vertical-update callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & vertical-update-function & \\  
& (\&key \\
&  position \\
&  minimum \\
&  maximum \\
&  pixels-per-unit) \\
(declare &(type  number  position minimum maximum pixels-per-unit)))
\end{tabular}
\rm
}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ 
This callback is added to the content
automatically by the {\tt scroll-frame,} not by the application programmer.  May
be called to inform the {\tt scroll-frame} about changes made by the program in
the content's vertical calibration data. See {\tt :vertical-calibrate} callback.

}\end{flushright}


{\samepage
{\large {\bf :scroll-to \hfill Callback}} 
\index{scroll-frame, :scroll-to callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & scroll-to-function & \\ 
& (left top) \\
(declare &(type  number  left top)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Redisplays the content so that the given
position (in content units) appears at the upper-left of the scroll-frame.  The
default function for this callback assumes that content units are pixels and
scrolls the content by moving it with respect to the {\tt scroll-frame} parent.
}\end{flushright}

	


\vfill\pagebreak


\HIGHERL{Table}{sec:table}\index{table}                                      

\index{classes, table}

A {\tt table} is a layout contact \index{layouts} which arranges its children
(or {\bf members}\index{table, members}) into an array of rows and columns.
Row/column positions are defined as constraint resources of individual members
(see \cite{clue} for a complete description of constraint
resources).\index{table, constraints}

\LOWER{Table Layout Policy}\index{table, layout policy}

The layout of a {\tt table} is governed by table constraints, spacing constraints,
and member constraints.  Table constraints are attributes which describe the rows
and columns.  The following functions may be used to return or change table constraints.

\begin{itemize}
\item {\tt table-column-alignment}
\item {\tt table-column-width}
\item {\tt table-columns}
\item {\tt table-row-alignment}
\item {\tt table-row-height}
\item {\tt table-same-height-in-row}
\item {\tt table-same-width-in-column}
\end{itemize}

Spacing contraints control the amount of space surrounding rows and columns.
The following functions may be used to return or change spacing constraints for a {\tt
table}.

\begin{itemize}
\item {\tt display-bottom-margin}
\item {\tt display-left-margin}
\item {\tt display-right-margin}
\item {\tt display-top-margin}
\item {\tt display-horizontal-space}
\item {\tt display-vertical-space}
\item {\tt table-separator}
\end{itemize}

Member constraints may be used to specify the row/column position of an individual
member.  An application programmer must ensure that member constraints do not
conflict with table constraints.  In case of such a conflict, table constraints
will override member constraints.  For example, suppose table constraints specify
that a {\tt table} has two columns, but member constraints specify that a member
should appear in the third column.  In this case, the member column constraint
will be ignored and the member will be placed in another column.  The following
functions may be used to return or change member constraints.

\begin{itemize}
\item {\tt table-column}
\item {\tt table-row}
\end{itemize}


\SAME{Functional Definition}
	 
{\samepage
{\large {\bf make-table \hfill Function}} 
\index{constructor functions, table}
\index{make-table function}
\index{table, make-table function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-table \\
       & (\&rest initargs \\
       & \&key  \\ 
       & (border                & *default-contact-border*) \\ 
       & (bottom-margin         & :default) \\
       & (column-alignment      & :left)\\
       & (column-width          & :maximum)\\
       & (columns               & :maximum)\\
       & foreground \\
       & (horizontal-space      & :default) \\
       & (left-margin           & :default) \\
       & (right-margin          & :default) \\
       & (row-alignment         & :bottom)\\
       & (row-height            & :maximum)\\
       & (same-height-in-row    & :off)\\
       & (same-width-in-column  & :off)\\
       & separators  & \\
       & (top-margin            & :default) \\
       & (vertical-space        & :default) \\
       & \&allow-other-keys) \\
(declare & (values   table)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt table} contact.
The resource specification list of the {\tt table} class defines
a resource for each of the initargs above.\index{table,
resources}

The {\tt separators} initarg is a list of row indexes indicating the rows of the
{\tt table} that are followed by separators.\index{table, separator}
See {\tt table-separator}, page~\pageref{page:table-separator}.

 }\end{flushright}

{\samepage
{\large {\bf display-bottom-margin \hfill Method, table}}
\index{table, display-bottom-margin method}
\index{display-bottom-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-bottom-margin & \\
& ((table  table)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-bottom-margin) & \\
& (bottom-margin \\
& (table  table)) \\
(declare &(type (or (integer 0 *) :default)  bottom-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns or changes the pixel size of the
bottom margin.  The height of the contact minus the bottom margin size defines
the bottom edge of the clipping rectangle used when displaying the source.
Setting the bottom margin to {\tt :default} causes the value of {\tt
*default-display-bottom-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-bottom-margin*}
  
}\end{flushright}


{\samepage
{\large {\bf display-horizontal-space \hfill Method, table}}
\index{table, display-horizontal-space method}
\index{display-horizontal-space method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-horizontal-space & \\
& ((table  table)) \\
(declare & (values integer)))
\end{tabular}
\rm}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-horizontal-space) & \\
& (horizontal-space \\
& (table  table)) \\
(declare &(type (or integer :default)  horizontal-space))\\
(declare & (values integer)))
\end{tabular}
\rm}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns or changes the pixel size of the space between columns in the {\tt table}.  
Setting the horizontal space to {\tt :default} causes the value of {\tt
*default-display-horizontal-space*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-horizontal-space*}
  
}\end{flushright}


{\samepage  
{\large {\bf display-left-margin \hfill Method, table}}
\index{table, display-left-margin method}
\index{display-left-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-left-margin & \\
& ((table  table)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-left-margin) & \\
         & (left-margin \\
         & (table  table)) \\
(declare &(type (or (integer 0 *) :default)  left-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
left margin.  The left margin size defines
the left edge of the clipping rectangle used when displaying the source.
Setting the left margin to {\tt :default} causes the value of {\tt
*default-display-left-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-left-margin*}
}
\end{flushright}


{\samepage  
{\large {\bf display-right-margin \hfill Method, table}}
\index{table, display-right-margin method}
\index{display-right-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-right-margin & \\
& ((table  table)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-right-margin) & \\
         & (right-margin \\
         & (table  table)) \\
(declare &(type (or (integer 0 *) :default)  right-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
right margin.  The width of the contact minus the right margin size defines
the right edge of the clipping rectangle used when displaying the source.
Setting the right margin to {\tt :default} causes the value of {\tt
*default-display-right-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-right-margin*}
}
\end{flushright}


{\samepage  
{\large {\bf display-top-margin \hfill Method, table}}
\index{table, display-top-margin method}
\index{display-top-margin method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-top-margin & \\
& ((table  table)) \\
(declare & (values (integer 0 *))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-top-margin) & \\
         & (top-margin \\
         & (table  table)) \\
(declare &(type (or (integer 0 *) :default)  top-margin))\\
(declare & (values (integer 0 *))))
\end{tabular}
\rm}
\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the pixel size of the
top margin.  The top margin size defines
the top edge of the clipping rectangle used when displaying the source.
Setting the top margin to {\tt :default} causes the value of {\tt
*default-display-top-margin*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-top-margin*}
}
\end{flushright}
	  

{\samepage
{\large {\bf display-vertical-space \hfill Method, table}}
\index{table, display-vertical-space method}
\index{display-vertical-space method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display-vertical-space & \\
& ((table  table)) \\
(declare & (values integer)))
\end{tabular}
\rm}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf display-vertical-space) & \\
& (vertical-space \\
& (table  table)) \\
(declare &(type (or integer :default)  vertical-space))\\
(declare & (values integer)))
\end{tabular}
\rm}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ 
Returns or changes the pixel size of the space between rows in the {\tt table}.  
Setting the vertical space to {\tt :default} causes the value of {\tt
*default-display-vertical-space*} (converted from points to the number of pixels
appropriate for the contact screen) to be used.
\index{variables, *default-display-vertical-space*}
  
}\end{flushright}



{\samepage
{\large {\bf table-column-alignment \hfill Method, table}}
\index{table, table-column-alignment method}
\index{table-column-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-column-alignment & \\
& ((table  table)) \\
(declare & (values(member :left :center :right))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf table-column-alignment) & \\
         & (alignment \\
         & (table table)) \\
(declare &(type (member :left :center :right)  alignment))\\
(declare & (values (member :left :center :right))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the horizontal alignment of members in each column.

}\end{flushright}

	  
{\samepage
{\large {\bf table-column-width \hfill Method, table}}
\index{table, table-column-width method}
\index{table-column-width method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-column-width & \\
& ((table  table)) \\
(declare & (values (or (member :maximum) (integer 1 *) list))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf table-column-width) & \\
         & (width \\
         & (table table)) \\
(declare &(type (or (member :maximum) (integer 1 *) list)  width))\\
(declare & (values (or (member :maximum) (integer 1 *) list))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the width of columns in the {\tt table}. An integer column
width gives the pixel width used for each column.  A {\tt
:maximum} column width means that each column will be as wide as its widest member,
and thus may differ in width. Column widths may also be specified by a
list of the form {\tt ({\em column-width*})}, where the {\tt i}-th element of
the list is the {\em column-width} for the {\tt i}-th column. A {\em
column-width} element may be either an integer pixel column width or {\tt nil}
(meaning {\tt :maximum} column width).

}\end{flushright}

	  
{\samepage
{\large {\bf table-columns \hfill Method, table}}
\index{table, table-columns method}
\index{table-columns method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-columns & \\
& ((table  table)) \\
(declare & (values(or (integer 1 *) (member :none :maximum)))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf table-columns) & \\
         & (columns \\
         & (table table)) \\
(declare &(type (or (integer 1 *) (member :none :maximum))  columns))\\
(declare & (values (or (integer 1 *) (member :none :maximum)))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the number of columns in the {\tt table}. A {\tt :none} value
means that rows are filled without aligning members into columns. A {\tt :maximum}
value means that as many columns as possible will be formed.

}\end{flushright}

	  
%
% Feature removed; may reappear when it is better understood.
%
%{\samepage
%{\large {\bf table-delete-policy \hfill Method, table}}
%\index{table, table-delete-policy method}
%\index{table-delete-policy method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & table-delete-policy & \\
%& ((table  table)) \\
%(declare & (values(member :shrink-column :shrink-list :shrink-none))))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%{\samepage
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf table-delete-policy) & \\
%         & (policy \\
%         & (table table)) \\
%(declare &(type (member :shrink-column :shrink-list :shrink-none)  policy))\\
%(declare & (values (member :shrink-column :shrink-list :shrink-none))))
%\end{tabular}
%\rm
%}
%\end{flushright}}
%
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns and changes the policy used to adjust the {\tt table} layout when a
%member is destroyed or unmanaged. {\tt :shrink-column} means that members which
%appear in the same column as the deleted member but in higher rows will move up
%a row.
%{\tt :shrink-list} means all members following the deleted member move left
%and/or up. {\tt :shrink-none} means that no members move and the space occupied
%by the deleted member remains empty.
%
%}\end{flushright}

	  
{\samepage
{\large {\bf table-member \hfill Method, table}}
\index{table, table-member method}
\index{table-member method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-member & \\
& ((table  table)\\
& row \\
& column) \\
(declare &(type (integer 0 *)  row column))\\
(declare & (values (or null contact))))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns the member, if any, at the given row/column position.

}\end{flushright}

	  
{\samepage
{\large {\bf table-row-alignment \hfill Method, table}}
\index{table, table-row-alignment method}
\index{table-row-alignment method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-row-alignment & \\
& ((table  table)) \\
(declare & (values(member :top :center :bottom))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf table-row-alignment) & \\
         & (alignment \\
         & (table table)) \\
(declare &(type (member :top :center :bottom)  alignment))\\
(declare & (values (member :top :center :bottom))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the vertical alignment of members in each row.

}\end{flushright}

	  
{\samepage
{\large {\bf table-row-height \hfill Method, table}}
\index{table, table-row-height method}
\index{table-row-height method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-row-height & \\
& ((table  table)) \\
(declare & (values(or (member :maximum) (integer 1 *) list))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf table-row-height) & \\
         & (height \\
         & (table table)) \\
(declare &(type (or (member :maximum) (integer 1 *) list)  height))\\
(declare & (values (or (member :maximum) (integer 1 *) list))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the height of rows in the {\tt table}. An integer row
height gives the pixel height used for each row.  A {\tt
:maximum} row height means that each row will be as high as its highest member,
and thus may differ in height. Row heights may also be specified by a
list of the form {\tt ({\em row-height*})}, where the {\tt i}-th element of
the list is the {\em row-height} for the {\tt i}-th row. A {\em
row-height} element may be either an integer pixel row height or {\tt nil}
(meaning {\tt :maximum} row height).

}\end{flushright}

	  
{\samepage
{\large {\bf table-same-height-in-row \hfill Method, table}}
\index{table, table-same-height-in-row method}
\index{table-same-height-in-row method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-same-height-in-row & \\
& ((table  table)) \\
(declare & (values(member :on :off))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf table-same-height-in-row) & \\
         & (switch \\
         & (table table)) \\
(declare &(type (member :on :off)  switch))\\
(declare & (values (member :on :off))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and changes whether the members in a row will be
set to have the same height.

}\end{flushright}

	  
{\samepage
{\large {\bf table-same-width-in-column \hfill Method, table}}
\index{table, table-same-width-in-column method}
\index{table-same-width-in-column method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-same-width-in-column & \\
& ((table  table)) \\
(declare & (values(member :on :off))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf table-same-width-in-column) & \\
         & (switch \\
         & (table table)) \\
(declare &(type (member :on :off)  switch))\\
(declare & (values (member :on :off))))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns and changes whether the members in a column will be
set to have the same width.


}\end{flushright}

{\samepage
{\large {\bf table-separator \hfill Method, table}}
\index{table, table-separator method}
\label{page:table-separator}
\index{table-separator method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & table-separator & \\
           & ((table  table)\\
           & row) \\
(declare &(type (integer 0 *) & row))\\
(declare   & (values (member :on :off))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf table-separator) & \\
         & (switch \\
         & (table table)\\
         & row) \\
(declare &(type (member :on :off) & switch)\\
         &(type (integer 0 *) & row))\\
(declare &(values (member :on :off))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns and changes the presence of a separator after the given {\tt row} of the
{\tt table}. For example, {\tt (setf (table-separator table 0) :on)} causes a
separator to appear between rows 0 and 1 of the {\tt table}.

A separator is some kind of visual separation between adjacent table
rows. For example, a separator could be represented by a thin line or by extra
space. However, the exact visual form of a separator is
implementation-dependent.\index{table, separator}

}\end{flushright}
	  

\SAME{Constraint Resources}
The
following functions may be used to return or (with {\tt setf}) to change
the constraint resources of the members of a {\tt table} contact.
\index{table, changing constraints}
\index{table, constraints}


{\samepage
{\large {\bf table-column \hfill Function}}
\index{table, table-column function}
\index{table-column function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & table-column & \\
& (member) \\
(declare &(type contact & member))\\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the column position of the table member.
A {\tt nil} value means that the {\tt table} may choose any
convenient column.}\end{flushright}

{\samepage
{\large {\bf table-row \hfill Function}}
\index{table, table-row function}
\index{table-row function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & table-row & \\
& (member) \\
(declare &(type contact & member))\\
(declare & (values (or null (integer 0 *)))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the row position of the table member.
A {\tt nil} value means that the {\tt table} may choose any
convenient row.}\end{flushright}




\CHAPTERL{Dialogs}{sec:dialogs} 
\index{dialog} The term {\bf dialog}\index{dialog}
refers generally to a type of composite which presents several application data
items for interaction and \index{shell} reports a user's response.  In some cases,
a user can respond by modifying the presented data. In CLIO, dialogs are {\tt
shell} subclasses that represent top-level contacts.

CLIO defines dialogs for the following types of user interactions.
\begin{center}
\begin{tabular}[t]{lp{5in}}
{\tt command} & Presents a set of related value controls and a set of command
controls which operate on the values. This is the most general type of dialog.\\ 
\\
{\tt confirm} & A simple dialog which presents a message and allows a user to
enter a ``yes or no'' response.\\
\\
{\tt menu} & Allows a user to select from a set of choice items.\\
\\
{\tt property-sheet} & Presents a set of related
values for editing and allows a user to accept or cancel any changes.\\

\end{tabular}
\end{center}

\LOWERL{Accepting, Canceling, and Initializing Dialogs}{sec:dialog-accept-cancel}
 
When a user terminates
interaction with a dialog, he is said to {\bf exit} the dialog.
\index{dialog, exiting} In general, the application program determines the
visual effect of exiting a dialog.  Applications often use dialogs as
``pop-ups,'' in which case exiting the dialog causes it to be ``popped down''
(i.e.  its state becomes {\tt :withdrawn}).  \index{dialog, pop-up}
\index{dialog, popping down}

A dialog often contains one or more controls that allow a user to indicate a
positive (or ``accept'') response and a negative (or ``cancel'') response.
Most CLIO dialogs automatically create accept and cancel controls that use
the generic functions {\tt dialog-accept} and {\tt dialog-cancel}.  An accept
response causes the {\tt dialog-accept} function to be invoked and exits the
dialog.  A cancel response causes the {\tt dialog-cancel} function to be
invoked and exits the dialog.
\index{dialog, accept control}
\index{dialog, cancel control}
\index{dialog-accept method}
\index{dialog-cancel method}

\index{dialog, callbacks}
In general, dialogs use the following callbacks for handling
user responses and for initialization.

\begin{center}
\begin{tabular}[t]{lp{5in}}
{\tt :accept} & Invoked by the {\tt dialog-accept} function when a user accepts and
exits the dialog. \\
\\	
{\tt :cancel} & Invoked by the {\tt dialog-cancel} function when a user
cancels and exits the dialog.\\ 
\\
{\tt :initialize} & Invoked by the {\tt shell-mapped} function when the dialog
becomes {\tt :mapped} (see \cite{clue}, shell contacts).\\
\\
{\tt :verify} & Invoked when a user accepts the dialog. This callback is used
only when the dialog presents data which the user may change. This
callback can be used to enforce validity constraints on user changes. By
default, this callback is undefined.\\

\end{tabular}
\end{center}

For dialogs that contain values to be changed, an application programmer may
also define the following callbacks for each value.  These optional callbacks
may be used to control the effect of user changes on individual values and are
invoked only if the corresponding callback is not defined for the dialog
itself.

\begin{center}
\begin{tabular}[t]{lp{5in}}
{\tt :accept} & Invoked by the {\tt dialog-accept} function if no {\tt
:accept} callback is defined for the dialog. \\
\\	
{\tt :cancel} & Invoked by the {\tt dialog-cancel} function if no {\tt
:cancel} callback is defined for the dialog.\\ 
\\
{\tt :initialize} & Invoked by the {\tt shell-mapped} function if no {\tt
:initialize} callback is defined for the dialog.\\
\end{tabular}
\end{center}


Note that the application programmer has several options for controlling a
dialog: 
\begin{itemize}
\item Implement accept semantics via callbacks for individual members or
        via callbacks for the dialog or both (or neither).

\item Implement cancel recovery semantics for edited values via
        ``change-immediately-then-undo-later'' or via ``postpone-changes-until-accept.''

\item Implement the (re)initialization of a value via its {\tt :initialize}
callback or via its  {\tt :cancel} callback or not at all.

\end{itemize}
 
\SAME{Presenting Dialogs} 
An application program should call the {\tt
present-dialog} function \index{present-dialog method} to present a {\tt
command} dialog at a specific location, in response to a user or program event.
The {\tt present-dialog} for each dialog class encapsulates all
implementation-dependent rules for positioning the dialog and initializing its
interaction.

\SAME{Command}\index{command}
\index{classes, command}

A {\tt command} is a {\tt transient-shell} which presents a set of related
values to be viewed or changed by the user.  Also presented are a set of
controls which represent commands that operate on the values.  In general, the
application programmer is responsible for programming command controls to exit
the dialog appropriately.  For convenience, optional default accept and cancel
controls can be created automatically, although their exact appearance and
behavior are implementation-dependent. 

The application programmer may also also identify a {\bf default
control}\index{command, default control}. A {\tt command} may highlight the
default control or otherwise expedite its selection by the user, although the
exact treatment of the default control is implementation-dependent.

A {\tt command} contains two children representing different regions.  Values
to be viewed or modified appear in the region called the {\bf command
area}\index{command, command area}.  The command area is a layout
contact\index{layouts}, such as a {\tt form}, which controls the layout of
values.  Command controls appear in the region called the {\bf control
area}\index{command, control area}.  The control area is also a layout, such
as a {\tt table}.  Command controls are presented by children of the control
area.  Typically, command controls are {\tt action-button} objects.

A {\tt command} uses the {\tt :initialize} callback for initialization.  If
the default accept control is specified, then the {\tt :accept} and {\tt
:verify} callbacks are used.  If the default cancel control is specified, then
the {\tt :cancel} callback is used. See Section~\ref{sec:dialog-accept-cancel}.



\LOWER{Functional Definition}

The {\tt command} class is a subclass of the {\tt transient-shell} class.
All {\tt transient-shell} accessors and initargs may be used to operate on a
{\tt command}.  See \cite{clue}, {\tt shell}
contacts.\index{transient-shell}

\pagebreak

{\samepage
{\large {\bf make-command \hfill Function}} 
\index{constructor functions, command}
\index{make-command function}
\index{command, make-command function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-command \\
       & (\&rest initargs \\
       & \&key  \\ 
       & (border                & *default-contact-border*) \\ 
       & (command-area          & 'make-table)\\    
       & (control-area          & 'make-table)\\    
       & (default-accept        & :on)\\    
       & (default-cancel        & :on)\\    
       & default-control \\
       & foreground \\
       & \&allow-other-keys) \\
(declare & (type (or function list)& command-area control-area))\\
(declare & (values   command)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt command} contact.
The resource specification list of the {\tt command} class defines
a resource for each of the initargs above.\index{command,
resources}

The {\tt command-area} and {\tt control-area} arguments specify the constructor
function and (optionally) initial attributes for the command area and the
control area,
respectively.  Each of these arguments may be either a function or a
list of the form {\tt ({\em constructor} .  {\em initargs})}, where {\em
initargs} is a list of keyword/value pairs allowed by the {\em constructor} function.
\index{command, control area}\index{command, command area}
}\end{flushright}


{\samepage
{\large {\bf command-area \hfill Method, command}}
\index{command, command-area method}
\index{command-area method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & command-area & \\
           & ((command  command)) \\
(declare   & (values composite)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the command area composite. Values to be presented or edited are
represented by children of the command area.

}\end{flushright}


{\samepage
{\large {\bf command-control-area \hfill Method, command}}
\index{command, command-control-area method}
\index{command-control-area method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & command-control-area & \\
           & ((command  command)) \\
(declare   & (values composite)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ Returns the control area composite.
Command controls are represented by children of the control area.

}\end{flushright}


{\samepage
{\large {\bf command-default-accept \hfill Method, command}}
\index{command, command-default-accept method}
\index{command-default-accept method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & command-default-accept & \\
           & ((command  command)) \\
(declare   & (values (or (member :on :off) string))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf command-default-accept) & \\
         & (switch \\
         & (command command)) \\
(declare &(type (or (member :on :off) stringable) & switch))\\
(declare &(values (or (member :on :off) string))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns  (and with {\tt setf}) changes whether the default accept control is
used. If {\tt :on}, then the default accept control is used with an
implementation-dependent label. If a string, then the default accept control
is used and labelled with the given string. If {\tt :off}, then the default
accept control is not used.

}\end{flushright}

{\samepage
{\large {\bf command-default-cancel \hfill Method, command}}
\index{command, command-default-cancel method}
\index{command-default-cancel method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & command-default-cancel & \\
           & ((command  command)) \\
(declare   & (values (or (member :on :off) string))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf command-default-cancel) & \\
         & (switch \\
         & (command command)) \\
(declare &(type (or (member :on :off) stringable) & switch))\\
(declare &(values (or (member :on :off) string))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns and (with {\tt setf}) changes whether the default cancel control is
used. If {\tt :on}, then the default cancel control is used with an
implementation-dependent label. If a string, then the default cancel control
is used and labelled with the given string. If {\tt :off}, then the default
cancel control is not used.

}\end{flushright}



{\samepage
{\large {\bf dialog-accept \hfill Method, command}}
\index{command, dialog-accept method}
\index{dialog-accept method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-accept & \\
& ((command  command)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{Called when the user accepts and exits the
{\tt command}, using the default accept control. The primary method invokes the {\tt
:accept} callback
for the {\tt command}, if defined; otherwise, the {\tt :accept} callback is invoked
for each member of the command area.  }\end{flushright}



{\samepage
{\large {\bf dialog-cancel \hfill Method, command}}
\index{command, dialog-cancel method}
\index{dialog-cancel method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-cancel & \\
& ((command  command)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{Called when the user cancels and exits the
{\tt command}, using the default cancel control. The primary method invokes the {\tt
:cancel} callback
for the {\tt command}, if defined; otherwise, the {\tt :cancel} callback is invoked
for each member of the command area. }\end{flushright}

{\samepage
{\large {\bf dialog-default-control \hfill Method, command}}
\index{command, dialog-default-control method}
\index{dialog-default-control method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-default-control & \\
& ((command  command))\\
(declare &(values symbol)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf dialog-default-control) & \\
         & (control \\
         & (command command)) \\
(declare &(type symbol  control))\\
(declare &(values symbol)))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{Returns and (with {\tt setf}) changes
the name of the default control. \index{command, default control}
By default, the name of the default control is either {\tt :accept} (if a
default accept control exists) or the name of the first member of the control
area.} \end{flushright}

{\samepage
{\large {\bf present-dialog \hfill Method, command}}
\index{command, present-dialog method}
\index{present-dialog method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & present-dialog & \\
           & ((command  command)\\
        & \&key \\
        & x \\
        & y\\
        & button\\
        & state)\\
(declare & (type (or int16 null)  & x)\\
         & (type (or int16 null)  & y)\\
        & (type (or button-name null) & button)\\ 
        & (type (or mask16 null)  & state)))\\ 
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{ Presents the {\tt command} at the
position given by {\tt x} and {\tt y}.  The values of {\tt x} and {\tt y} are
treated as hints, and the exact position where the {\tt command} will appear is
implementation-dependent.  By default, {\tt x} and {\tt y} are determined by the
current pointer position.
 
If the {\tt command} is presented in response to a pointer button event, then
{\tt button} should specify the button pressed or released. Valid button names
are {\tt :button-1}, {\tt :button-2}, {\tt :button-3}, {\tt :button-4}, and {\tt
:button-5}. If given, {\tt
state} specifies the current state of the pointer buttons and modifier keys.

}\end{flushright}


{\samepage
{\large {\bf shell-mapped \hfill Method, command}}
\index{command, shell-mapped method}
\index{shell-mapped method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & shell-mapped & \\
& ((command  command)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{ Called before {\tt command} becomes
{\tt :mapped} (See \cite{clue}, {\tt shell} contacts).  The primary
method
invokes the {\tt :initialize} callback for the {\tt command}, if defined;
otherwise, the {\tt :initialize} callback is invoked for each member of the
command area.  }\end{flushright}


\SAMEL{Callbacks}{sec:command-callbacks}\index{command, callbacks}

An application programmer may define the following callbacks for
a {\tt command}.

{\samepage
{\large {\bf :accept \hfill Callback, command}} 
\index{command, :accept callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & accept-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when a user accepts and exits the {\tt command}, using the default
accept control. 
This function should implement the application response to any user changes to
the {\tt command}.
This callback is used if the default accept control is specified. However, if no
default accept control is specified, then use of the {\tt :accept} callback is
implementation-dependent.
  }\end{flushright}

{\samepage
{\large {\bf :cancel \hfill Callback, command}} 
\index{command, :cancel callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & cancel-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when a user cancels and exits the {\tt command}, using the default
cancel control. 
This function should implement the application response to cancelling any user
changes to the {\tt command}. This callback is used if the default cancel control
is specified. However, if no
default cancel control is specified, then use of the {\tt :cancel} callback is
implementation-dependent.


}\end{flushright}

{\samepage
{\large {\bf :initialize \hfill Callback, command}} 
\index{command, :initialize callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & initialize-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the {\tt command} becomes {\tt :mapped}.
This function should implement any initialization needed for the {\tt
command} before it becomes {\tt :mapped}.
}\end{flushright}


{\samepage
{\large {\bf :verify \hfill Callback, command}} 
\index{command, :verify callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & verify-function \\
& (command)\\
(declare & (type  command  command))\\
(declare & (values   boolean string (or null contact))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ If defined, this callback is invoked
when a user accepts the {\tt command}.  This callback can be used to
enforce validity constraints on user changes.  If all user changes are valid,
then the first return value is true and the {\tt command} is accepted and
exited.  Otherwise, the first return value is {\tt nil} and the {\tt command} is
not exited. If the first return value is {\tt nil}, then two other values are
returned. The second return value is an error message string to be displayed by
the {\tt command}. The third value is the member contact reporting the error, or
{\tt nil}.
}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ If no {\tt :verify} callback is defined,
then the {\tt command} is accepted and exited
immediately.

This callback is used if the default accept control is specified. However, if no
default accept control is specified, then use of the {\tt :verify} callback is
implementation-dependent.
}\end{flushright}

\SAME{Member Callbacks}\index{command, callbacks}
An application programmer may define the following callbacks for
members of the command area. These callbacks may or may not be used, depending on
the 
functions for the {\tt command} callbacks described in
Section~\ref{sec:command-callbacks}. See also the description for the {\tt
dialog-accept} and {\tt dialog-cancel} methods. 

{\samepage
{\large {\bf :accept \hfill Callback}} 
\index{command, :accept callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & accept-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked by the {\tt dialog-accept} function if no {\tt
:accept} callback is defined for the {\tt command}.
This function should implement the application response to any user changes to
the individual member.
}\end{flushright}

{\samepage
{\large {\bf :cancel \hfill Callback}} 
\index{command, :cancel callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & cancel-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked by the {\tt dialog-cancel} function if no {\tt
:cancel} callback is defined for the {\tt command}.
This function should implement the application response to cancelling any user
changes to the individual member.

}\end{flushright}

{\samepage
{\large {\bf :initialize \hfill Callback}} 
\index{command, :initialize callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & initialize-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked by the {\tt shell-mapped} function if no {\tt
:initialize} callback is defined for the {\tt command}.
This function should implement any initialization needed for the individual
member before the {\tt command} becomes {\tt :mapped}.

}\end{flushright}



\vfill
\pagebreak

\HIGHERL{Confirm}{sec:confirm}\index{confirm}
\index{classes, confirm}

A {\tt confirm} is an {\tt override-shell} which presents a message and allows
a user to enter a ``yes or no'' response. 

A {\tt confirm} contains an accept control and, optionally, a cancel control.
If only an accept control is specified, then a {\tt confirm} accepts only a
single response, indicating that a user has seen the message.  The accept and
cancel controls are created automatically, and their exact appearance and
behavior are implementation-dependent. However, the application programmer can
specify text labels to be displayed by the accept and cancel controls.

The application programmer may also also identify a {\bf default
control}\index{confirm, default control}. A {\tt confirm} may highlight the
default control or otherwise expedite its selection by the user, although the
exact treatment of the default control is implementation-dependent.

A {\tt confirm} uses the {\tt :initialize}, {\tt :accept}, and {\tt :cancel}
callbacks. See Section~\ref{sec:dialog-accept-cancel}.

The {\tt confirm-p} function is a simplified interface for presenting a {\tt
confirm} dialog and returning the user response as a boolean value. 
\index{confirm-p function}

\LOWER{Functional Definition}

The {\tt confirm} class is a subclass of the {\tt override-shell} class. All
{\tt transient-shell} accessors and initargs may be used to operate on a {\tt
confirm}. See \cite{clue}, {\tt shell} contacts.\index{transient-shell}

{\samepage
{\large {\bf make-confirm \hfill Function}} 
\index{constructor functions, confirm}
\index{make-confirm function}
\index{confirm, make-confirm function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-confirm \\
       & (\&rest initargs \\
       & \&key  \\ 
       & accept-label         &  \\ 
       & (accept-only         & :off) \\ 
       & (border                & *default-contact-border*) \\ 
       & cancel-label         &  \\ 
       & (default-control & :accept)\\
       & foreground \\
       & message               & \\
       & near                   & \\
       & \&allow-other-keys) \\
(declare & (values   confirm)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt confirm} contact.
The resource specification list of the {\tt confirm} class defines
a resource for each of the initargs above.\index{confirm,
resources}

}\end{flushright}

{\samepage
{\large {\bf confirm-accept-label \hfill Method, confirm}}
\index{confirm, confirm-accept-label method}
\index{confirm-accept-label method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & confirm-accept-label & \\
           & ((confirm  confirm)) \\
(declare & (values string)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf confirm-accept-label) & \\
         & (accept-label \\
         & (confirm confirm)) \\
(declare &(type stringable  accept-label))\\
(declare & (values string)))
\end{tabular}
\rm
}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the label displayed by the accept control. The default accept
label is implementation-dependent.

}\end{flushright}


{\samepage
{\large {\bf confirm-accept-only \hfill Method, confirm}}
\index{confirm, confirm-accept-only method}
\index{confirm-accept-only method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & confirm-accept-only & \\
           & ((confirm  confirm)) \\
(declare & (values (member :on :off))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf confirm-accept-only) & \\
         & (accept-only \\
         & (confirm confirm)) \\
(declare &(type (member :on :off)  accept-only))\\
(declare & (values (member :on :off))))
\end{tabular}
\rm
}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the presence of the cancel control. If {\tt :on}, then no
cancel control is presented.

}\end{flushright}

{\samepage
{\large {\bf confirm-cancel-label \hfill Method, confirm}}
\index{confirm, confirm-cancel-label method}
\index{confirm-cancel-label method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & confirm-cancel-label & \\
           & ((confirm  confirm)) \\
(declare & (values string)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf confirm-cancel-label) & \\
         & (cancel-label \\
         & (confirm confirm)) \\
(declare &(type stringable  cancel-label))\\
(declare & (values string)))
\end{tabular}
\rm
}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the label displayed by the cancel control. The default cancel
label is implementation-dependent.

}\end{flushright}



{\samepage
{\large {\bf confirm-message \hfill Method, confirm}}
\index{confirm, confirm-message method}
\index{confirm-message method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & confirm-message & \\
           & ((confirm  confirm)) \\
(declare & (values string)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf confirm-message) & \\
         & (message \\
         & (confirm confirm)) \\
(declare &(type string  message))\\
(declare & (values string)))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the message displayed by the {\tt confirm}.

}\end{flushright}

{\samepage
{\large {\bf confirm-near \hfill Method, confirm}}
\index{confirm, confirm-near method}
\index{confirm-near method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & confirm-near & \\
           & ((confirm  confirm)) \\
(declare & (values window)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf confirm-near) & \\
         & (near \\
         & (confirm confirm)) \\
(declare &(type window  near))\\
(declare & (values window)))
\end{tabular}
\rm
}
\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns or changes the position where the {\tt confirm} is displayed.
When it is {\tt :mapped}, the {\tt confirm} appears near the given {\tt
window}; the exact meaning of ``near'' is implementation-dependent. 
In general, the ``near window'' should be the one receiving the user input that
caused the {\tt confirm} to become {\tt :mapped}. Typically,
changing the
``near window''  changes the values of {\tt x} and {\tt y} for the {\tt
confirm}.

By default, the ``near window'' of a {\tt confirm} is itself. This
is a special case indicating that the position of the {\tt confirm} is
determined normally, by its {\tt x} and {\tt y} position 

}\end{flushright}

{\samepage
{\large {\bf confirm-p \hfill Function}} 
\index{confirm-p function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & confirm-p & \\ 
&  (\&rest initargs \\
&  \&key near  \\
&  \&allow-other-keys)\\
(declare &(type contact & near))\\
(declare & (values boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ Presents a {\tt confirm} and
waits for a user to exit the dialog.  Returns true if the user accepts
and {\tt nil} if the user cancels.  

The attributes of the {\tt confirm} are specified by the {\tt initargs}, which can
contain any initarg allowed by {\tt make-confirm} (except {\tt
:callbacks}).\index{make-confirm function} The {\tt :callbacks} initarg is not
allowed because {\tt :accept} and {\tt :cancel} callbacks are defined by {\tt
confirm-p}.  The {\tt near} argument is required.

}\end{flushright}


{\samepage
{\large {\bf dialog-accept \hfill Method, confirm}}
\index{confirm, dialog-accept method}
\index{dialog-accept method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-accept & \\
& ((confirm  confirm)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{Called when the user accepts and exits the
{\tt confirm}. The primary method invokes the {\tt :accept} callback
for the {\tt confirm}.  }\end{flushright}



{\samepage
{\large {\bf dialog-cancel \hfill Method, confirm}}
\index{confirm, dialog-cancel method}
\index{dialog-cancel method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-cancel & \\
& ((confirm  confirm)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{ Called when the user cancels and exits the
{\tt confirm}. The primary method invokes the {\tt :cancel} callback
for the {\tt confirm}.}\end{flushright}

{\samepage
{\large {\bf dialog-default-control \hfill Method, confirm}}
\index{confirm, dialog-default-control method}
\index{dialog-default-control method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-default-control & \\
& ((confirm  confirm))\\
(declare &(values (member :accept :cancel))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf dialog-default-control) & \\
         & (control \\
         & (confirm confirm)) \\
(declare &(type (member :accept :cancel) & control))\\
(declare &(values (member :accept :cancel))))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{Returns and (with {\tt setf}) changes
the name of the default control. \index{confirm, default control}
}\end{flushright}

{\samepage
{\large {\bf present-dialog \hfill Method, confirm}}
\index{confirm, present-dialog method}
\index{present-dialog method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & present-dialog & \\
           & ((confirm  confirm)\\
        & \&key \\
        & x \\
        & y\\
        & button\\
        & state)\\
(declare & (type (or int16 null)  & x)\\
         & (type (or int16 null)  & y)\\
        & (type (or button-name null) & button)\\ 
        & (type (or mask16 null)  & state)))\\ 
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{ Presents the {\tt confirm} at the
position given by {\tt x} and {\tt y}.  The values of {\tt x} and {\tt y} are
treated as hints, and the exact position where the {\tt confirm} will appear is
implementation-dependent.  By default, {\tt x} and {\tt y} are determined by the
current pointer position.
 
If the {\tt confirm} is presented in response to a pointer button event, then
{\tt button} should specify the button pressed or released. Valid button names
are {\tt :button-1}, {\tt :button-2}, {\tt :button-3}, {\tt :button-4}, and {\tt
:button-5}. If given, {\tt
state} specifies the current state of the pointer buttons and modifier keys.

}\end{flushright}


{\samepage
{\large {\bf shell-mapped \hfill Method, confirm}}
\index{confirm, shell-mapped method}
\index{shell-mapped method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & shell-mapped & \\
& ((confirm  confirm)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{ Called before {\tt confirm} becomes
{\tt :mapped} (See \cite{clue}, {\tt shell} contacts).  The primary
method
invokes the {\tt :initialize} callback for the {\tt confirm}.
}\end{flushright}






\SAMEL{Callbacks}{sec:confirm-callbacks}\index{confirm, callbacks}

An application programmer may define the following callbacks for
a {\tt confirm}.

{\samepage
{\large {\bf :accept \hfill Callback, confirm}} 
\index{confirm, :accept callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & accept-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when a user accepts and exits the {\tt confirm}. 
This function should implement the application effect of a user's accept
response.

}\end{flushright}

{\samepage
{\large {\bf :cancel \hfill Callback, confirm}} 
\index{confirm, :cancel callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & cancel-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when a user cancels and exits the {\tt confirm}. 
This function should implement the application effect of a user's cancel
response.

}\end{flushright}

{\samepage
{\large {\bf :initialize \hfill Callback, confirm}} 
\index{confirm, :initialize callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & initialize-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the {\tt confirm} becomes {\tt :mapped}.
This function should implement any initialization needed for the {\tt
confirm} before it becomes {\tt :mapped}.
}\end{flushright}

\vfill
\pagebreak

\HIGHERL{Menu}{sec:menu}\index{menu}
\index{classes, menu}

A {\tt menu} is an {\tt override-shell} which presents a choice
contact\index{choice} and allows a user to select from a set of choice items.
Menu items are added as choice items of this choice contact, which is created
automatically.  An application programmer can define the class and initial
attributes for this choice contact when the {\tt menu} is created.  See
Chapter~\ref{sec:choice} for a description of choice contact classes.

A {\tt menu} has a title defined by a text string. 

The choice item controls that appear in menus are called {\bf menu
items}\index{menu items}. Menu items may exhibit a distinctive appearance and
operation which reflect their special role as parts of menus. CLIO defines two
classes of menu items  --- {\tt action-item} and {\tt menu-item}.

A {\tt menu} uses the {\tt :initialize} callback for initialization.


\LOWER{Functional Definition}

The {\tt menu} class is a subclass of the {\tt override-shell} class. All
{\tt override-shell} accessors and initargs may be used to operate on a {\tt
menu}. See \cite{clue}, {\tt shell} contacts.\index{override-shell}

{\samepage
{\large {\bf make-menu \hfill Function}} 
\index{constructor functions, menu}
\index{make-menu function}
\index{menu, make-menu function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-menu \\
       & (\&rest initargs \\
       & \&key  \\ 
       & (border                & *default-contact-border*) \\ 
       & (choice                & 'make-choices)\\    
       & foreground \\
       & (title                 & "")\\    
       & \&allow-other-keys) \\
(declare & (type (or function list)& choice))\\
(declare & (values   menu)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt menu} contact.
The resource specification list of the {\tt menu} class defines
a resource for each of the initargs above.\index{menu,
resources}

The {\tt choice} argument specifies the constructor and (optionally) initial
attributes for the choice contact of the new {\tt menu}.  This argument may be
either a constructor function or a list of the form {\tt ({\em constructor} .
{\em initargs})}, where {\em initargs} is a list of keyword/value pairs allowed by
the {\em constructor} function.

}\end{flushright}

{\samepage
{\large {\bf menu-choice \hfill Method, menu}}
\index{menu, menu-choice method}
\index{menu-choice method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & menu-choice & \\
& ((menu  menu)) \\
(declare & (values choice-contact)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Returns the choice contact for the {\tt menu}. This choice contact is created
automatically and its class can be set only by {\tt make-menu}.  Menu items are
defined by creating choice items for this choice contact.}\end{flushright}

{\samepage
{\large {\bf menu-title \hfill Method, menu}}
\index{menu, menu-title method}
\index{menu-title method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & menu-title & \\
& ((menu  menu)) \\
(declare & (values title-contact)))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf menu-title) & \\
         & (title \\
         & (menu menu)) \\
(declare &(type stringable & title))\\
(declare &(values string)))
\end{tabular}
\rm
}
\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the title string of the {\tt
menu}.} 
\end{flushright}

{\samepage
{\large {\bf present-dialog \hfill Method, menu}}
\index{menu, present-dialog method}
\index{present-dialog method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & present-dialog & \\
           & ((menu  menu)\\
        & \&key \\
        & x \\
        & y\\
        & button\\
        & state)\\
(declare & (type (or int16 null)  & x)\\
         & (type (or int16 null)  & y)\\
        & (type (or button-name null) & button)\\ 
        & (type (or mask16 null)  & state)))\\ 
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{ Presents the {\tt menu} at the
position given by {\tt x} and {\tt y}.  The values of {\tt x} and {\tt y} are
treated as hints, and the exact position where the {\tt menu} will appear is
implementation-dependent.  By default, {\tt x} and {\tt y} are determined by the
current pointer position.
 
If the {\tt menu} is presented in response to a pointer button event, then
{\tt button} should specify the button pressed or released. Valid button names
are {\tt :button-1}, {\tt :button-2}, {\tt :button-3}, {\tt :button-4}, and {\tt
:button-5}. If given, {\tt
state} specifies the current state of the pointer buttons and modifier keys.

}\end{flushright}

{\samepage
{\large {\bf shell-mapped \hfill Method, menu}}
\index{menu, shell-mapped method}
\index{shell-mapped method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & shell-mapped & \\
& ((menu  menu)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{ Called before {\tt menu} becomes
{\tt :mapped} (See \cite{clue}, {\tt shell} contacts).  The primary
method
invokes the {\tt :initialize} callback for the {\tt menu}, if defined;
otherwise, the {\tt :initialize} callback is invoked for each menu
item.}\end{flushright}


\SAMEL{Callbacks}{sec:menu-callbacks}\index{menu, callbacks}

An application programmer may define the following callback for
a {\tt menu}.

{\samepage
{\large {\bf :initialize \hfill Callback}} 
\index{menu, :initialize callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & initialize-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the {\tt menu} becomes {\tt :mapped}.
This function should implement any initialization needed for the {\tt
menu} before it becomes {\tt :mapped}.

}\end{flushright}

\SAMEL{Item Callbacks}{sec:menu-item-callbacks}\index{menu, callbacks}

An application programmer may define the following callback for
each item in a {\tt menu}.

{\samepage
{\large {\bf :initialize \hfill Callback}} 
\index{menu, :initialize callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & initialize-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked by the {\tt shell-mapped} function if no {\tt
:initialize} callback is defined for the {\tt menu}.
This function should implement any initialization needed for the individual
item before the {\tt menu} becomes {\tt :mapped}.

}\end{flushright}


\vfill
\pagebreak
\HIGHER{Property Sheet}\index{property-sheet}                                      

\index{classes, property-sheet}
A {\tt property-sheet} is a {\tt transient-shell} which presents a set of
related values that can be changed
by a user.  Typically, a
{\tt property-sheet} allows a user to modify the properties, or attributes, of a
specific application object. A {\tt property-sheet} contains controls which
allow a user either to accept or to cancel any changes to the values. Accept
and cancel controls are created automatically, and their exact appearance and
behavior are implementation-dependent.

The application programmer may also also identify a {\bf default
control}\index{property-sheet, default control}. A {\tt property-sheet} may highlight the
default control or otherwise expedite its selection by the user, although the
exact treatment of the default control is implementation-dependent.


The content of a {\tt property-sheet} is called the {\bf property area}.
\index{property-sheet, property area} The property area is a layout
contact\index{layouts}, such as a {\tt form}.  Property values are
presented by contacts which are children (or {\bf members})
\index{property-sheet, members} of the property area.

A {\tt property-sheet} uses the {\tt :initialize}, {\tt :accept}, {\tt
:cancel}, and {\tt :verify} callbacks.  See
Section~\ref{sec:dialog-accept-cancel}.



\LOWER{Functional Definition}

The {\tt property-sheet} class is a subclass of the {\tt transient-shell} class.
All {\tt transient-shell} accessors and initargs may be used to operate on a
{\tt property-sheet}.  See \cite{clue}, {\tt shell}
contacts.\index{transient-shell}


{\samepage
{\large {\bf make-property-sheet \hfill Function}} 
\index{constructor functions, property-sheet}
\index{make-property-sheet function}
\index{property-sheet, make-property-sheet function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-property-sheet \\
       & (\&rest initargs \\
       & \&key  \\ 
       & (border                & *default-contact-border*) \\ 
       & (default-control       & :accept)\\
       & foreground \\
       & (property-area         & 'make-table)\\    
       & \&allow-other-keys) \\
(declare & (type (or symbol list)& property-area))\\
(declare & (values   property-sheet)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns a {\tt property-sheet} contact.
The resource specification list of the {\tt property-sheet} class defines
a resource for each of the initargs above.\index{property-sheet,
resources}

The {\tt property-area} argument specifies the constructor and (optionally)
initial attributes for the property area.  This argument
may be either a constructor function or a list of the form {\tt ({\em constructor}
.  {\em initargs})}, where {\em initargs} is a list of keyword/value pairs allowed
by the {\em constructor} function.

}\end{flushright}

{\samepage
{\large {\bf dialog-accept \hfill Method, property-sheet}}
\index{property-sheet, dialog-accept method}
\index{dialog-accept method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-accept & \\
& ((property-sheet  property-sheet)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{Called when the user accepts and exits the
{\tt property-sheet}. The primary method invokes the {\tt :accept} callback
for the {\tt property-sheet}, if defined; otherwise, the {\tt :accept} callback is invoked
for each member of the property area.  }\end{flushright}



{\samepage
{\large {\bf dialog-cancel \hfill Method, property-sheet}}
\index{property-sheet, dialog-cancel method}
\index{dialog-cancel method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-cancel & \\
& ((property-sheet  property-sheet)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{Called when the user cancels and exits the
{\tt property-sheet}. The primary method invokes the {\tt :cancel} callback
for the {\tt property-sheet}, if defined; otherwise, the {\tt :cancel} callback is invoked
for each member of the property area. }\end{flushright}

{\samepage
{\large {\bf dialog-default-control \hfill Method, property-sheet}}
\index{property-sheet, dialog-default-control method}
\index{dialog-default-control method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & dialog-default-control & \\
& ((property-sheet  property-sheet))\\
(declare &(values (member :accept :cancel))))
\end{tabular}
\rm

}\end{flushright}}

{\samepage
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf dialog-default-control) & \\
         & (control \\
         & (property-sheet property-sheet)) \\
(declare &(type (member :accept :cancel) & control))\\
(declare &(values (member :accept :cancel))))
\end{tabular}
\rm
}
\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{Returns and (with {\tt setf}) changes
the name of the default control. \index{property-sheet, default control}
By default, the name of the default control is either {\tt :accept} (if a
default accept control exists) or the name of the first member of the control
area.} \end{flushright}

{\samepage
{\large {\bf present-dialog \hfill Method, property-sheet}}
\index{property-sheet, present-dialog method}
\index{present-dialog method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & present-dialog & \\
           & ((property-sheet  property-sheet)\\
        & \&key \\
        & x \\
        & y\\
        & button\\
        & state)\\
(declare & (type (or int16 null)  & x)\\
         & (type (or int16 null)  & y)\\
        & (type (or button-name null) & button)\\ 
        & (type (or mask16 null)  & state)))\\ 
\end{tabular}
\rm

}\end{flushright}}



\begin{flushright} \parbox[t]{6.125in}{ Presents the {\tt property-sheet} at the
position given by {\tt x} and {\tt y}.  The values of {\tt x} and {\tt y} are
treated as hints, and the exact position where the {\tt property-sheet} will
appear is
implementation-dependent.  By default, {\tt x} and {\tt y} are determined by the
current pointer position.
 
If the {\tt property-sheet} is presented in response to a pointer button event, then
{\tt button} should specify the button pressed or released. Valid button names
are {\tt :button-1}, {\tt :button-2}, {\tt :button-3}, {\tt :button-4}, and {\tt
:button-5}. If given, {\tt
state} specifies the current state of the pointer buttons and modifier keys.

}\end{flushright}


{\samepage
{\large {\bf shell-mapped \hfill Method, property-sheet}}
\index{property-sheet, shell-mapped method}
\index{shell-mapped method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & shell-mapped & \\
& ((property-sheet  property-sheet)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{ Called before {\tt property-sheet} becomes
{\tt :mapped} (See \cite{clue}, {\tt shell} contacts).  The primary
method
invokes the {\tt :initialize} callback for the {\tt property-sheet}, if defined;
otherwise, the {\tt :initialize} callback is invoked for each member of the
property area.  }\end{flushright}




{\samepage
{\large {\bf property-sheet-area \hfill Method, property-sheet}}
\index{property-sheet, property-sheet-area method}
\index{property-sheet-area method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & property-sheet-area & \\
& ((property-sheet  property-sheet))\\
(declare & (values contact)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{Returns the property area
contact.}\end{flushright}







\SAMEL{Callbacks}{sec:property-sheet-callbacks}\index{property-sheet, callbacks}

An application programmer may define the following callbacks for
a {\tt property-sheet}.

{\samepage
{\large {\bf :accept \hfill Callback, property-sheet}} 
\index{property-sheet, :accept callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & accept-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when a user accepts and exits the {\tt property-sheet}. 
This function should implement the application response to any user changes to
the {\tt property-sheet}.

}\end{flushright}

{\samepage
{\large {\bf :cancel \hfill Callback, property-sheet}} 
\index{property-sheet, :cancel callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & cancel-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when a user cancels and exits the {\tt property-sheet}. 
This function should implement the application response to cancelling any user
changes to the {\tt property-sheet}.

}\end{flushright}

{\samepage
{\large {\bf :initialize \hfill Callback, property-sheet}} 
\index{property-sheet, :initialize callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & initialize-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked when the {\tt property-sheet} becomes {\tt :mapped}.
This function should implement any initialization needed for the {\tt
property-sheet} before it becomes {\tt :mapped}.
}\end{flushright}


{\samepage
{\large {\bf :verify \hfill Callback, property-sheet}} 
\index{property-sheet, :verify callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & verify-function \\
& (property-sheet)\\
(declare & (type  property-sheet  property-sheet))\\
(declare & (values   boolean string (or null contact))))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{ If defined, this callback is invoked
when a user accepts the {\tt property-sheet}.  This callback can be used to
enforce validity constraints on user changes.  If all user changes are valid,
then the first return value is true and the {\tt property-sheet} is accepted and
exited.  Otherwise, the first return value is {\tt nil} and the {\tt property-sheet} is
not exited. If the first return value is {\tt nil}, then two other values are
returned. The second return value is an error message string to be displayed by
the {\tt property-sheet}. The third value is the member contact reporting the error, or
{\tt nil}.
}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{ If no {\tt :verify} callback is defined,
then the {\tt property-sheet} is accepted and exited
immediately.}\end{flushright}

\SAME{Member Callbacks}\index{property-sheet, callbacks}
An application programmer may define the following callbacks for
members of the property area. 
These callbacks may or may not be used, depending on
the 
functions for the {\tt property-sheet} callbacks described in
Section~\ref{sec:property-sheet-callbacks}. 

{\samepage
{\large {\bf :accept \hfill Callback}} 
\index{property-sheet, :accept callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & accept-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked by the {\tt dialog-accept} function if no {\tt
:accept} callback is defined for the {\tt property-sheet}.
This function should implement the application response to any user changes to
the individual member.
}\end{flushright}

{\samepage
{\large {\bf :cancel \hfill Callback}} 
\index{property-sheet, :cancel callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & cancel-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked by the {\tt dialog-cancel} function if no {\tt
:cancel} callback is defined for the {\tt property-sheet}.
This function should implement the application response to cancelling any user
changes to the individual member.

}\end{flushright}

{\samepage
{\large {\bf :initialize \hfill Callback}} 
\index{property-sheet, :initialize callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & initialize-function & () )
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked by the {\tt shell-mapped} function if no {\tt
:initialize} callback is defined for the {\tt property-sheet}.
This function should implement any initialization needed for the individual
member before the {\tt property-sheet} becomes {\tt :mapped}.

}\end{flushright}



\CHAPTER{General Features}

\LOWER{Utilities}

This section describes various utility functions defined by CLIO.

%\LOWER{Converting Size Units}
\index{size units}

{\samepage
{\large {\bf point-pixels \hfill Function}} 
\index{point-pixels function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & point-pixels \\
       & (screen \\
       & \&optional \\
       & (number 1) \\
       & (dimension :vertical))\\
(declare & (type screen  screen)\\
	   &(type number  number)\\
	   &(type (member :horizontal :vertical)  dimension)) \\ 
(declare & (values (integer 0 *))))
\end{tabular}
\rm
}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the number of pixels represented by the given {\tt number} of points, in
either the {\tt :vertical} or {\tt :horizontal} dimension of the {\tt screen}.
}\end{flushright}


{\samepage
{\large {\bf pixel-points \hfill Function}} 
\index{pixel-points function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & pixel-points \\
       & (screen \\
       & \&optional \\
       & (number 1) \\
       & (dimension :vertical))\\
(declare & (type screen  screen)\\
	  &(type number  number)\\
	  &(type (member :horizontal :vertical)  dimension)) \\ 
(declare & (values number)))
\end{tabular}
\rm
}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the number of points represented by the given {\tt number} of pixels, in
either the {\tt :vertical} or {\tt :horizontal} dimension of the {\tt screen}.
}\end{flushright}


{\samepage
{\large {\bf inch-pixels \hfill Function}} 
\index{inch-pixels function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & inch-pixels \\
       & (screen \\
       & \&optional \\
       & (number 1) \\
       & (dimension :vertical))\\
(declare & (type screen  screen)\\
	  &(type number  number)\\
	  &(type (member :horizontal :vertical)  dimension)) \\ 
(declare & (values (integer 0 *))))
\end{tabular}
\rm
}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the number of pixels represented by the given {\tt number} of inches, in
either the {\tt :vertical} or {\tt :horizontal} dimension of the {\tt screen}.
}\end{flushright}


{\samepage
{\large {\bf pixel-inches \hfill Function}} 
\index{pixel-inches function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & pixel-inches \\
       & (screen \\
       & \&optional \\
       & (number 1) \\
       & (dimension :vertical))\\
(declare & (type screen  screen)\\
	  &(type number  number)\\
	  &(type (member :horizontal :vertical)  dimension)) \\ 
(declare & (values number)))
\end{tabular}
\rm
}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the number of inches represented by the given {\tt number} of pixels, in
either the {\tt :vertical} or {\tt :horizontal} dimension of the {\tt screen}.
}\end{flushright}


{\samepage
{\large {\bf millimeter-pixels \hfill Function}} 
\index{millimeter-pixels function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & millimeter-pixels \\
       & (screen \\
       & \&optional \\
       & (number 1) \\
       & (dimension :vertical))\\
(declare & (type screen  screen)\\
	  &(type number  number)\\
	  &(type (member :horizontal :vertical)  dimension)) \\ 
(declare & (values (integer 0 *))))
\end{tabular}
\rm
}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the number of pixels represented by the given {\tt number} of millimeters, in
either the {\tt :vertical} or {\tt :horizontal} dimension of the {\tt screen}.
}\end{flushright}


{\samepage
{\large {\bf pixel-millimeters \hfill Function}} 
\index{pixel-millimeters function}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & pixel-millimeters \\
       & (screen \\
       & \&optional \\
       & (number 1) \\
       & (dimension :vertical))\\
(declare & (type screen  screen)\\
	  &(type number  number)\\
	  &(type (member :horizontal :vertical)  dimension)) \\ 
(declare & (values number)))
\end{tabular}
\rm
}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the number of millimeters represented by the given {\tt number} of pixels, in
either the {\tt :vertical} or {\tt :horizontal} dimension of the {\tt screen}.
}\end{flushright}

\SAMEL{Global Variables and Type Specifiers}{sec:globals}

{\samepage
{\large {\bf gravity \hfill Type}} 
\index{types, gravity}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{llll}
\raggedright
(deftype  & gravity & () \\
          &'(member & :north-west :north  :north-east\\
          &         & :west       :center :east\\
          &         & :south-west :south  :south-east))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Describes an alignment position used to display contact contents.
}\end{flushright}


{\samepage
{\large {\bf *default-choice-font* \hfill Variable}} 
\index{variables, *default-choice-font*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-choice-font* \\
& "*-*-*-*-r-*--12-*-*-*-p-*-iso8859-1")
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default font used for text labels in choice items.\index{choice item}

}\end{flushright}
 
{\samepage
{\large {\bf *default-contact-border* \hfill Variable}} 
\index{variables, *default-contact-border*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-contact-border* & :black)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default border color for CLIO contacts.

}\end{flushright}

{\samepage
{\large {\bf *default-contact-foreground* \hfill Variable}} 
\index{variables, *default-contact-foreground*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-contact-foreground* & :black)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default initial foreground color for CLIO contacts.

}\end{flushright}

{\samepage
{\large {\bf *default-display-bottom-margin* \hfill Variable}} 
\index{variables, *default-display-bottom-margin*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-display-bottom-margin* & 0)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default bottom margin for CLIO  contacts, given in
points. This value must be converted into pixel units appropriate for the given
display.

}\end{flushright}

{\samepage
{\large {\bf *default-display-left-margin* \hfill Variable}} 
\index{variables, *default-display-left-margin*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-display-left-margin* & 0)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default left margin for CLIO  contacts, given in
points. This value must be converted into pixel units appropriate for the given
display.

}\end{flushright}

{\samepage
{\large {\bf *default-display-right-margin* \hfill Variable}} 
\index{variables, *default-display-right-margin*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-display-right-margin* & 0)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default right margin for CLIO  contacts, given in
points. This value must be converted into pixel units appropriate for the given
display.

}\end{flushright}



{\samepage
{\large {\bf *default-display-top-margin* \hfill Variable}} 
\index{variables, *default-display-top-margin*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-display-top-margin* & 0)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default top margin for CLIO  contacts, given in
points. This value must be converted into pixel units appropriate for the given
display.

}\end{flushright}

{\samepage
{\large {\bf *default-display-horizontal-space* \hfill Variable}} 
\index{variables, *default-display-horizontal-space*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-display-horizontal-space* & 0)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default horizontal spacing for CLIO layout contacts, given in
points. This value must be converted into pixel units appropriate for the given
display.

}\end{flushright}


{\samepage
{\large {\bf *default-display-vertical-space* \hfill Variable}} 
\index{variables, *default-display-vertical-space*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-display-vertical-space* & 0)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default vertical spacing for CLIO layout contacts, given in
points. This value must be converted into pixel units appropriate for the given
display.

}\end{flushright}


{\samepage
{\large {\bf *default-display-text-font* \hfill Variable}} 
\index{variables, *default-display-text-font*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defparameter & *default-display-text-font* \\
              & "*-*-*-*-r-*--12-*-*-*-p-*-iso8859-1")
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default font used by CLIO contacts.

}\end{flushright}


\SAMEL{Selections for Interclient Communication}{sec:selections}

Certain CLIO contacts for display and editing support the interchange of data
among different clients via {\bf selections}\index{selections}.  The X selection
mechanism is defined by the X Window System Protocol\cite{protocol}.  The use of
selections by CLIO contacts conforms to the conventions described by the X
Window System Inter-Client Communications Convention Manual (ICCCM)\cite{icccm}.

In general, display and editing contacts supply user operations which set the
value of certain standard selections to contact data.  That is, a user can make a
display/editing contact the owner of a standard selection and can cause the
contact then to return selected contact data in response to SelectionRequest
events.  The specific user operations which control selections depend on the
contact class.

In order to conform to ICCCM, display and editing contacts support the following
targets for all supported selections (see \cite{icccm} for a complete
description of these required targets).

\begin{center}
\begin{tabular}{lp{4in}} 
{\tt :multiple} &
                Return a list containing the selection value in multiple target
                formats.\\
\\ 
{\tt :targets} &
                Return a list of supported target formats.\\
\\ 
{\tt :timestamp} &
                Return a timestamp giving the time when selection ownership
                was acquired.\\
\end{tabular}
\end{center}

\CHAPTER{Acknowledgements}

Major contributions to the CLIO design came from the other members of the team
responsible for its initial implementation:

\begin{center}
\begin{tabular}{ll}
Javier Arellano &       Texas Instruments \\
William Cohagan &       William Cohagan Inc.\\
Paul Fuqua      &       Texas Instruments \\
Eric Mielke     &       Texas Instruments \\
Mark Young      &       Texas Instruments \\
\end{tabular}
\end{center}

In addition, we wish to thank the following individuals, who were among
our first users and who suggested many significant improvements.
\begin{center}
\begin{tabular}{ll}
Patrick Hogan    &       Texas Instruments \\
Aaron Larson     &       Honywell Systems Research Center \\
Jill Nicola      &       Texas Instruments \\
\end{tabular}
\end{center}

%\appendix
%\CHAPTER{CLIO for OPEN LOOK} 
%\index{OPEN LOOK}\index{look and feel} 
%
%This chapter describes the ``look and feel'' of CLIO/OL, an implementation of
%CLIO for the OPEN LOOK user interface
%environment\footnotemark\footnotetext{OPEN LOOK is a trademark of AT\&T.}.
%CLIO/OL is the implementation of CLIO which accompanies the public
%distribution of CLUE software.  The following sections describe, for each CLIO
%class, the user
%operations and actions  that are specific to the OPEN LOOK Graphical User
%Interface\cite{open-look-gui}. Other CLIO/OL functions and accessors which are
%related strictly to the OPEN LOOK implementation are also defined.
%
%\LOWER{Packages}
%
%\SAME{Core Contacts}
%\LOWER{Functions}
%{\samepage
%{\large {\bf contact-scale \hfill Method, core}}
%\index{core, contact-scale method}
%\index{contact-scale method}
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & contact-scale & \\
%& ((core  core)) \\
%(declare & (values (member :small :medium :large :extra-large))))
%\end{tabular}
%\rm
%
%}\end{flushright}}
%
%{\samepage
%\begin{flushright} \parbox[t]{6.125in}{
%\tt
%\begin{tabular}{lll}
%\raggedright
%(defmethod & (setf contact-scale) & \\
%         & (scale \\
%         & (core core)) \\
%(declare &(type (member :small :medium :large :extra-large) scale))\\
%(declare & (values (member :small :medium :large :extra)
%\end{tabular}
%\rm
%}
%\end{flushright}}
%
%
%
%\begin{flushright} \parbox[t]{6.125in}{
%Returns or changes the contact scale. The actual effect of changing scale is
%determined by methods defined by {\tt core} subclasses. When creating a {\tt
%core} instance, the {\tt :scale} initarg may be used to specify an initial
%scale; by default, a {\tt core} contact has the same scale as its parent. 
%
%}\end{flushright}
%
%
%\HIGHER{Action Button}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Choices}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Display Text Field}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Edit Text Field}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Form}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Multiple Choices}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Property Sheet}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Scroll Frame}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Scroller}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Slider}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Table}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.
%
%\HIGHER{Toggle Button}
%\LOWER{Actions}
%{\em ?}\index{INCOMPLETE!}
%\SAME{User Operations}
%See \cite{open-look-gui}, Section {\em ?}\index{INCOMPLETE!}.




\begin{thebibliography}{9}

\bibitem{clos} Bobrow, Daniel G., et al. The Common Lisp Object System
Specification (X3J13-88-002). American National Standards Institute, June,
1988.

\bibitem{clue} Kimbrough, Kerry and Oren, LaMott. Common Lisp User
Interface Environment, Version 7.1 (November, 1989).

%\bibitem{open-look-gui} OPEN LOOK Graphical User Interface, Release 1.0. Sun
%Microsystems Inc. (May 1, 1989).

\bibitem{icccm} Rosenthal, David S. H. X11 Inter-Client Communication Conventions
Manual, Version 1 (January, 1990).

\bibitem{protocol} Scheifler, Robert W. The X Window System Protocol, Version
11, Revision 3.

\bibitem{clx} Scheifler, Robert W., et al. CLX --- Common Lisp X Interface,
Release 4 (January 1990).

\end{thebibliography}



\begin{theindex}
\input{clio.index}
\end{theindex}

\end{document}


