% -*- Mode: LaTeX; Package: CLIM-USER -*-

\chapter {Panes}
\label {panes}

CLIM panes are similar to the gadgets or widgets of other toolkits.  They can be
used by application builders to compose the top-level user interface of their
applications as well as auxiliary dialogues.  The application programmer
provides an abstract specification of the pane hierarchy, which CLIM uses in
conjunction with user preferences and other factors to select a specific ``look
and feel'' for the application.  In some environments a CLIM application can use
the facilities of the host window system toolkit via a set of \concept{adaptive
panes}, allowing a portable CLIM application to take on the look and feel of a
native application user interface.

Panes are rectangular objects that are implemented as special sheet types.  An
application will typically construct a tree of panes that will divide up the
screen space allocated to the application.  The various CLIM pane types can be
characterized by whether they have children panes or not: panes that can have
other panes as children are called \concept{composite panes}, and those that
don't are called \concept{leaf panes}.  Composite panes are used to provide a
mechanism for spatially organizing (``laying out'') other panes.  Leaf panes
implement gadgets that have some appearance and react to user input by invoking
application code.  Another kind of leaf pane provides an area of the
application's screen real estate that can be used by the application to present
application specific information.  CLIM provides a number of these
\concept{application pane} types that allow the application to use CLIM's
graphics, input, stream, and extended stream facilities.

\section {Abstract Panes}

\concept{Abstract panes} are panes that are defined only in terms of their
programmer interface, or behavior.  The protocol for an abstract pane (that is,
the specified set of initialization options, accessors and callbacks) is
designed to specify the pane in terms of its overall purpose, rather then in
terms of its specific appearance or particular interactive details.  The purpose
of this abstract definition is to allow multiple implementations of the abstract
pane, each defining its own specific look and feel.  CLIM can then select the
appropriate pane implementation based on factors outside the control of the
application, such as user preferences or the look and feel of the host operating
environment.  A subset of the abstract panes, the \term{adaptive panes}, have
been defined to integrate well across all CLIM operating platforms.

CLIM provides a general mechanism for automatically selecting the particular
implementation of an abstract pane selected by an application based on the
current frame manager.  The application programmer can override the selection
mechanism by using the name of a specific pane implementation in place of the
abstract pane name when specifying the application frame's layout.  By
convention, the name of the basic, portable implementation of an abstract pane
class can be determined by adding the suffix ``-PANE'' to the abstract name.


\section {Pane Construction and Uses}

Applications typically define the hierarchy of panes used in their frames using
the \cl{:pane} or \cl{:panes} options of \cl{define-application-frame}.  These
options generate the body of methods on functions that are invoked when the
frame is being adopted into a particular frame manager, so the frame manager can
select the specific implementations of the abstract panes.

There are two basic interfaces to constructing a pane: \cl{make-instance} of a
known pane type, and \cl{realize-pane} of an abstract pane protocol name.  The
\cl{make-instance} approach requires the application to know the name of the
specific pane implementation class that is desired; all pane class names,
including those of the implementations of abstract pane protocol specifications,
end in ``-PANE''.  Using \cl{make-instance} directly circumvents the abstract
pane selection mechanism, which is appropriate for some cases. For example, the
programmer may want to use particular layout panes like \cl{vbox-pane} and
\cl{hbox-pane} and avoid the costs and uncertainty of going through the
realization mechanism.

The second approach, \cl{realize-pane}, invokes the ``look and feel''
realization process to select and construct a pane.  Normally this process is
implemented by the frame manager, but other realizers are possible.  The
\cl{realize-pane} function is typically invoked using an abstract pane name,
which is always a symbol in the CLIM package that doesn't include the ``-PANE''
suffix.  This naming convention distinguish the names of the abstract pane
protocols from the names of classes that implement them.  Programmers, however,
are allowed to pass any pane class name to \cl{realize-pane}, in which case the
frame manager will in general instantiate that specific class.

\issue {SWM} {We surely want a \cl{pane} protocol class, which is probably a
subclass of \cl{sheet}.  The instantiable pane classes to which you can do
output should also be a subclass of \cl{medium}.}


\Defun {realize-pane} {abstract-pane-protocol-name \rest initargs}

Selects a class that implements abstract pane protocol specified by
\arg{abstract-pane-protocol-name} and constructs a pane of that class.  It must
be used within the dynamic scope of either a \cl{with-look-and-feel-realization}
or the \cl{:pane} or \cl{:panes} options of a \cl{define-application-frame}
(which sets up an implicit \cl{with-look-and-feel-realization}).

\Defgeneric {realize-pane-internal} {realizer frame abstract-name \rest initargs}

This is the generic function that is actually invoked by a call to
\cl{realize-pane}.  The extant \arg{realizer} is established by
\cl{with-look-and-feel-realization}.  Frame managers (and other realizers)
define a method on this generic function to implement their realization policy.

\Defmacro {with-look-and-feel-realization} {(realizer frame) \body forms}

Establishes a dynamic context that installs \arg{realizer} as the entity
responsible for realizing panes.  All calls to \cl{realize-pane} within this
context result in \cl{realize-pane-internal} being invoked on \arg{realizer}.
This macro can be nested dynamically; inner uses shadow outer uses.
\arg{body} may have zero or more declarations as its first forms.

Typically \arg{realizer} is a frame manager, but in some cases \arg{realizer}
may be some other object. For example, within the implementation of pane that is
uses its own subpanes to achieve its function, this form might be used with
\arg{realizer} being the pane itself.


\subsection {Pane Initialization Options}

Client code should be particularly cautious about passing values for these pane
options, since the desktop's look and feel or the user's preferences should
usually determine these values.

\defoption {:foreground}
\Defoption {:background}

These options specify the default foreground and background inks for a pane.

\Defoption {:text-style}

This option specifies the default text style that should be used for any sort of
pane that supports text output.  Panes that do not support text output ignore
this option.


\subsection {Pane Queries}


\Defgeneric {pane-frame} {pane}

This function returns the frame that ``owns'' the pane.  \cl{pane-frame} can be
invoked on any pane in a frame's pane hierarchy, not just its single root pane,
but it can only be invoked on ``active'' panes, those that are currently adopted
into the frame's pane hierarchy.

\defgeneric {pane-foreground} {pane}
\Defgeneric {pane-background} {pane}

Return the current foreground and background inks of the pane, respectively.

\issue {SWM} {Why aren't these \cl{medium-foreground} and {medium-background},
since panes obey the medium protocol to this extent?}


\section {Layout and Layout Panes}
\label {basic-layout}

In this section, the aspects of the CLIM pane layout protocol that most
application builder need to understand are described.  A more detailed account
of this protocol is presented in Section~\ref{detailed-layout}.  Programmers who
need to build their own pane types, particularly, composite pane types, will
probably need the more detailed account.


\subsection {The Basics of the Layout Protocol}

The layout protocol is triggered by \cl{layout-frame}, which is automatically
called when a frame is adopted.

CLIM uses a two pass algorithm to lay out a pane hierarchy.  In the first pass,
called space composition, the top-level pane is asked how much space it
requires.  This may in turn lead to the question being asked recursively of all
the panes in the hierarchy, with the answers being composed to produce the
top-level pane's answer.  Each pane answers the query by returning a
\concept{space requirement} (or \cl{space-requirement}) object, which specifies
the pane's desired width and height as well as its willingness to shrink or grow
along the width and height axis.

In the second pass, called space allocation, the frame manager attempts to
obtain the required amount of space from the host window system (of course, this
may not be possible).  The top-level pane is allocated the space that is
actually available.  Each pane, in turn, allocates space recursively to each of
its descendants in the hierarchy according to the pane's rules of composition.

For many types of pane, the application programmer can indicate the space
requirements of the pane at creation time using initialization arguments, as
well as, dynamically using the \cl{change-space-requirement} function described
below.  For example, application panes are used to display application-specific
information, so the application can determine how much space should normally be
given to them.

Other pane types automatically calculate how much space they need based on the
information they need to display.  For example, label panes, can automatically
calculate their space requirement based on the text they need to display.

A composite pane calculates its space requirement based on the requirements of
its children and its own particular rule for arranging them.  For example, a
pane that arranges its children in a vertical stack would return as its desired
height the sum of the heights of its children.  Note, however, a composite is
not required by the layout protocol to respect the space requests of its
children; in fact, composite panes aren't even required to ask their children.

Space requirements are expressed for each of the two dimensions as a preferred
size, a mininum size below which the pane cannot be shrunk, and a maxium size
above which the pane cannot be grown.  (The minimum and maximum sizes can also
be specified as relative amounts.)  All sizes are specified as a real number
indicating the number of device units (such as pixels).

The following pane initialization options control the space request parameters
for the pane:

\defoption {:width}
\defoption {:max-width}
\defoption {:min-width}
\defoption {:height}
\defoption {:max-height}
\Defoption {:min-height}

These options control space layout.  The \cl{:width} and \cl{:height} options
specify the preferred horizontal and vertical sizes.  The \cl{:max-width} and
\cl{:max-height} options specify the maximum amount of space that may be
consumed by the pane, and give CLIM's pane layout engine permission to grow the
pane beyond the preferred size.  The \cl{:min-width} and \cl{:min-height}
options specify the minimum amount of space that may be consumed by the pane,
and give CLIM's pane layout engine permission to shrink the pane below the
preferred size.

If either of the \cl{:max-width} or \cl{:min-width} options is not supplied, it
defaults to \cl{:width}.  If either of the \cl{:max-height} or \cl{:min-height}
options is not supplied, it defaults to \cl{:height}.

\cl{:max-width}, \cl{:min-width}, \cl{:max-height}, and \cl{:min-height} can
also be specified as a relative size by supplying a list of the form
\cl{(\arg{number} :relative)}.  In this case, the number indicates the number
of device units that the pane is willing to stretch or shrink.

The values of these options are specified in the same way as the \cl{:x-spacing}
and \cl{:y-spacing} options to \cl{formatting-table}.  (Note that
\cl{:character} and \cl{:line} may only be used on those panes that display
text, such as a \cl{message-pane}.)

\Defconst {+fill+}

This constant can be used as a value to any of the relative size options.  It
indicates that pane's willingness to adjust an arbitrary amount in the specified
direction.

\Defgeneric {change-space-requirement} {pane \key resize-frame \rest space-req-keys} 

This function can be invoked to indicate that the space requirements for
\arg{pane} have changed.  Any of the options that applied to the pane at
creation time can be passed into this function as well.

\arg{resize-frame} determines whether the frame should be resized to accommodate
the new space requirement of the hierarchy.  If \arg{resize-frame} is
\term{true}, then \cl{layout-frame} will be invoked on the frame.  If
\arg{resize-frame} is \term{false}, then the frame may or may not get resized
depending on the pane hierarchy and the \cl{:resize-frame} option that was
supplied to \cl{define-application-framework}.

\Defmacro {changing-space-requirements} {(\key resize-frame) \body body}

This macro supports batching the invocation of the layout protocol by calls
to \cl{change-space-requirement}.  Within the body, all calls to
\cl{change-space-requirement} change the internal structures of the pane and
are recorded.  When the body is exited, the layout protocol is invoked
appropriately.  \arg{body} may have zero or more declarations as its first
forms.

\issue {ILA} {There is still work to do in defining what this means exactly.}

\issue {ILA} {The protocol for handling space allocation failures (such as a
layout that cannot fit in the available space) needs to be specified.  The
working proposal is that an error will be signalled when the constraints can't
be satisfied.  If the application chooses, it can establish a condition handler.
Otherwise the panes will fall where they may.  The \cl{define-frame-application}
macro should provide an option that allows programmers to conveniently specify a
condition handler.}


\subsection {Layout Panes}

\issue {ILA} {We need to achieve some consensus on what the exact set of layout
panes should be and what they should be called.}

The layout panes describe in this section are all composite panes that are
responsible for positioning their children according to various layout rules.
All of these panes accept the initialization argument \cl{:contents}, the value
of which is a list of the children to be laid out.

Layout panes can be selected in the same way as other panes using
\cl{make-instance} or \cl{realize-pane}.  For convenience and readability of
application pane layouts, some of these panes provides a macro that expands into
a \cl{make-instance} form, passing a list of the panes created in the body of
the macro as the \cl{:contents} argument.  For example, you can express a layout
of a vertical column of two label panes either as:

\begin{verbatim}
(make-instance 'vbox-pane
               :contents (list (make-instance 'label-pane :text "One")
                               (make-instance 'label-pane :text "Two")))
\end{verbatim}

or

\begin{verbatim}
(vertically ()
  (make-instance 'label-pane :text "One")
  (make-instance 'label-pane :text "Two"))
\end{verbatim}

\issue {SWM} {I think that we should flush layout panes from the spec, and leave
only the layout macros.  Legislating panes overly constrains the implementation,
since they are not really necessary to proper laying-out of a frame.}

\deflpane {hbox-pane}
\defmacro {horizontally} {(\rest options) \body contents}
\deflpane {vbox-pane}
\Defmacro {vertically}   {(\rest options) \body contents}

These panes horizontally and vertically organize their children, which are the
panes created by \arg{contents}.

\cl{hbox-pane} allocates space to its contents from left to right.
\cl{vbox-pane} allocates space to its contents from top to bottom.
\arg{contents} is list that contains any the following elements:

\begin{itemize}
\item A pane.  The pane is inserted at this point and its space requirements are
used to compute the size.

\item A number.  The specified number of pixels should be allocated.

\item The symbol \cl{+fill+}.  This means that an arbitrary amount of space can
be absorbed at this point in the layout.

\item A list whose first element is a number and whose second element evaluates
to a pane.  If the number is below 1 then it means that that percentage of
excess space or deficit should be allocated to the pane.  If the number is
greater than 1, then that much space is allocated to the pane.  For example:

\begin{verbatim}
(horizontally ()
   (1/3 (realize-pane 'label-button-pane))
   (2/3 (realize-pane 'label-button-pane)))
\end{verbatim}
would create a horizontal stack of two button panes.
\end{itemize}

\deflpane {hrack-pane}
\Deflpane {vrack-pane}

Similar to the box panes, except that they ensure that all children are the same
size in the minor dimension.  In other words, these panes are used to create
stacks of same-sized items, such as menu items.

\deflpane {table-pane}
\Defmacro {tabling} {(\rest options) \body contents}

This pane allows laying panes out in a two-dimensional table arrangement.  Each
row in \arg{contents} is itself specified as a list of panes.

\Deflpane {grid-pane}

A table where each of the cells are the same size in each of the two dimensions.

\deflpane {spacer-pane}
\Defmacro {spacing} {(\rest options) \body contents}

This layout pane reserves some margin space around a single child pane.  The
space requirement keys that are passed in indicate the requirements for the
surrounding space, not including the requirements of the child.

\deflpane {border-pane}
\Defmacro {bordering} {(\rest options) \body contents}

This layout pane puts a border around its contents.

The \cl{:background} option can be used to control the ink used to draw the
background.

\deflpane {restraining-pane}
\Defmacro {restraining} {(\rest options) \body contents}

Wraps the pane with a pane that prevents changes to the space requirements for
contents from causing relayout of panes outside of the restraining context.  In
other words, it prevents the size constraints of the child from propagating up
beyond this point.

\Deflpane {bboard-pane}

A pane that allows its children to be any size and lays them out wherever they
want to be (for example, a desktop manager).

\subsection {Layout Pane Options}

\defoption {:align-x}
\Defoption {:align-y}

The \cl{:align-x} option is one of \cl{:right}, \cl{:center}, or \cl{:left}.
The \cl{:align-y} option is one of \cl{:top}, \cl{:center}, or \cl{:bottom}.
These have the same semantics as for \cl{formatting-cell}.

\defoption {:x-spacing}
\defoption {:y-spacing}
\Defoption {:spacing}

These spacing options apply to the \cl{vbox}, \cl{hbox}, and \cl{table} panes,
and indicate the amount of horizontal and vertical spacing (respectively) to
leave between the items in boxes or rows and columns in table.  The values of
these options are specified in the same way as the \cl{:x-spacing} and
\cl{:y-spacing} options to \cl{formatting-table}.  \cl{:spacing} specifies both
the $x$ and $y$ spacing simultaneously.


\keepout{
\deflpane {outlined-pane}
\Defmacro {bordering}  {(option) \body contents}

\deflpane {shadow-pane}
\defmacro {raising}    {(option) \body contents}
\Defmacro {depressing} {(option) \body contents}
}


\section {Application Panes}

In addition to the various widgets and controls, and application usually needs
some space to display application-specific output and receive
application-specific input from the user.  For example, a paint program needs a
``canvas'' pane on which to display the picture and handle the ``mouse
strokes''.  A frame can use the basic CLIM input and output services in an
application-specific way through use of an \concept{application pane}.

This section describes the existing application pane types.  In addition, an
application programmer can customize pane behavior by defining a subclass of
one of these pane types and writing methods to change the repaint or
event-handling behavior.

\Defspane {basic-clim-pane}

This pane implements the CLIM graphics protocol and basic event-level protocol.
These protocols are documented in earlier chapters of the spec.  An application
can use this pane type as a ``canvas'' on which to draw application output.

\Defspane {basic-stream-pane}

This pane implements the basic Common Lisp stream protocol for the frame.  That
is, it implements the basic character stream protocol as described in the Gray
proposal to X3J13.

\Defspane {extended-stream-pane}

This pane implements the CLIM extended stream protocol.  This includes the basic
stream protocol plus the extended input and output protocols that support output
recording and presentations.

\subsection {Making Application Panes}

An application frequently uses application panes to display more information
than will fit in the space allocated to the pane.  CLIM provides panes that can
be used to add scrolling behavior to the application pane.  Since this is a
rather common need, a standard macro is provided to package this functionality.

\Defmacro {making-application-pane} {(\rest options) \body contents}

This macro embeds the contents pane in a collection of composite and leaf panes
designed to implement scrolling behavior.  These panes can include a viewport
pane, which provides a ``window'' into the application pane's contents and
manages the coordinate transformation that determines which part of the contents
are visible, two scroll bar gadget panes to provide a user interface to
scrolling, and a overseer pane to manage it all.  The options are:

\begin{itemize}
\item \cl{:scroll-bars}---can be \cl{nil} (no scroll bars), \cl{:horizontal},
\cl{:vertical}, \cl{:both} or \cl{:auto}, which will include scroll bars if the
contents pane has more information to display than the viewport can hold.

\item \cl{:label}---can be \cl{nil} or a string that will be displayed as a
label for the application pane.

\item \cl{:text-style}---controls the text style of the label.
\end{itemize}

Also, the various space-request options (such as \cl{:width} and \cl{:height})
are accepted, controlling the layout of the viewport pane.

\subsection {CLIM Stream Pane Options}

The following are init options to CLIM stream panes.

\begin{itemize}
\item \cl{:display-function} specifies a function for CLIM to call to display
the contents of a CLIM stream pane.  The standard \cl{clim-top-level} top-level
function will invoke the pane's display function at the appropriate time (see
the \cl{:display-after-commands} option).  The value of this option should be
either the name of a function to invoke or a cons whose car is the name of a
function and whose cdr is additional arguments to the function.  The function
will be invoked on the frame, the pane, and the additional function arguments,
if any.

\item \cl{:display-time} tells CLIM when to run the display function.  If it is
\cl{t}, CLIM will erase the pane's contents and run the display function the
next time a frame command is executed.  If it is \cl{nil}, CLIM will only run
the display function when it is explicitly necessary (when the pane is initially
exposed, for example).  If it is \cl{:command-loop} the display will be run
after any command is executed.
\end{itemize}

\section {Pane Options}

Panes use a uniform set of initargs to specify their layout and appearance
parameters.

\defoption {:align-x}
\Defoption {:align-y}

The \cl{:align-x} option is one of \cl{:right}, \cl{:center}, or \cl{:left}.
The \cl{:align-y} option is one of \cl{:top}, \cl{:center}, or \cl{:bottom}.  In
addition, \cl{:align-y} may be \cl{:baseline} for panes that place text.  These
have the same semantics as for \cl{formatting-cell}.

\defoption {:trigger}
\defoption {:wire}
\Defoption {:value}

These options define how an abstract pane notifies the application frame (or
some other pane that is using it to build a more complex pane) that some action
(for example, a button has been selected) has occurred.  Wires and triggers are
describe more completely below.  Currently, a client should specify only one of
wire (an object that is described below) or trigger (a funcallable object).  In
addition, value is an object that is passed back to the client via the trigger
or the wire according to the definition of the abstract pane.


\section{Abstract Panes}

CLIM defines the following additional abstract panes, each having at least one
implementation.

\issue {ILA} {The full behavior of each pane will be defined after the set of
defined panes is finalized.}

\defgadget {scrollable-pane}
\Defmacro {scrolling} {(\rest options) \body contents}

\Defgadget {one-of-pane}

\Defgadget {list-pane}

\Defgadget {text-stream-pane}

\defgadget {label-pane}
\Defmacro {labelled} {(\rest options) \body contents}

\Defgadget {line-editor-pane}

\Defgadget {label-button-pane}

\Defgadget {radio-button-pane}
 
\Deflpane {horizontal-divider}

\Deflpane {vertical-divider}