% -*- TeX-master: "finaler" -*-
\label{sec:ui-design}

The user interface for the \Gizmoball game is implemented in the
\texttt{gizmoball.ui} package. It is a generalized design that allows
for multiple renderers to draw the game board state, and uses a shared
interface framework with \emph{interaction modes} for the game player
and editor in order to achieve code reuse.

\begin{figure}[htbp]
  \centering
  \includegraphics[scale=0.55]{mddui}
  \caption{User interface module dependency diagram}
  \label{fig:ui-mdd}
\end{figure}

The root of the interface is the \texttt{gizmoball.ui.GizmoBallFrame}
class. This class handles the initial bootstrapping of the system, and
displays the main window. It contains two rows of option buttons: a
universal set that handles system-level functions such as loading, 
saving, and switching between editing and playing modes; and a 
mode-specific set with controls that are only relevant to one mode or
the other (e.g. for playing mode, a start/pause button; for editing
mode, connection display options). It also contains a 
\texttt{GameBoardComponent} that draws a gameboard on the screen. 
It also contains a \texttt{PropertyTable} that displays information 
about the selected gizmo, and an editor toolbar that selects gizmos 
to be placed.

The actual drawing of the gameboard is performed by a
\emph{renderer}. We separate the renderer from the UI package in order
to make the design more general; by abstracting away the renderer, we
can drop in a new renderer that provides different
features. Initially, we intend to implement the $\R^2$ renderer
(described in detail in Section~\ref{sec:r2-renderer}), which
draws a two-dimensional representation of the game board using
the Swing API. If time permits, we may implement an $\R^3$ renderer
using the Java3D APIs.

Each renderer has a \texttt{GameBoardComponent} class (e.g.
\texttt{R2GameBoardComponent}) that extends the
\texttt{gizmoball.ui.AbstractGameBoardComponent} abstract base class.
This class handles all things related to the gameboard and its display
on the screen. It contains the \texttt{GameBoard} object that
represents the game board (see
Section~\ref{sec:game-system-architecture}). It accesses the game
board's state, and displays it in a renderer-specific manner.

Key presses and mouse clicks on the game board are also handled by the
\texttt{GameBoardComponent}. However, we maintain only a single
\texttt{GameBoardComponent}, regardless of whether the game is in the
editor or player mode. This decision eliminates the need to
simultaneously maintain or update state in two different game boards,
and facilitates code reuse. Since \Gizmoball obviously behaves very
differently depending on whether the user is currently editing or
playing, we use \emph{interaction modes}, which derive from
\texttt{gizmoball.ui.AbstractInteractionMode} and encapsulate how the
game reacts to user input (see Section~\ref{sec:ui-design-interaction}). 
The \texttt{GameBoardComponent} selects either the playing or editing 
interaction mode (for the $\R^2$ renderer, 
\texttt{R2PlayingInteractionMode} and \texttt{R2EditingInteractionMode}). 
The \texttt{GameBoardComponent} harnesses the power of dynamic 
polymorphism by passing click and keypress events to the interaction 
mode object, which chooses the correct action for that mode and invokes 
the appropriate method of the \texttt{GameBoardComponent}.

\subsubsection{Interaction Modes}
\label{sec:ui-design-interaction}

Interaction modes provide a pluggable system of user control handlers
that interface between events in the user interface and input domain
and the internal game systems.  The decision to adopt such a system
stems from a need for different strategies of handling user 
interactions depending on both the current mode (playing or editing)
and the current renderer ($\R^2$ or others).  One can easily see how 
editing would require different functionality than playing: keypresses
may be shortcuts rather than key triggers, and the gameboard component
would need to handle mouse events to deal with gizmo placement and
selection.  Similarly, a 2d renderer would not require camera angle
user controls that users of a 3d renderer would appreciate.  The
choice of an interaction mode system is also consistent with the
overall emphasis on designing a system that is as general and 
expandable as possible.

Implementations of interaction modes act as the keyboard and mouse
event listeners for the \texttt{GameBoardComponent}.  As such, the
interaction modes can handle user interactions from these input
devices correctly.  In addition, implementations of interaction
modes have various methods that serve as relays from the GUI's
components to the representation systems for the gameboard and 
display.  This design allows the interface and the internal systems 
to be completely isolated; the interface and devices are unaware of
underlying systems it controls, and the internal systems are 
unaware of buttons and input devices (or even a user).

\subsubsection{Editing Interaction Mode}
\label{sec:ui-design-editing}

The editing interaction mode is designed in accordance with
the philosophy of generality guiding the other aspects of the design.
The enhanced display required for the editor is achieved by a system
of editing artifacts that can be fluidly added to the gameboard
component and updated.  The editor's functionality is separated into
submodes corresponding to different realms of user interaction:
building gizmos, selecting gizmos, and modifying gizmo properties.  To
support the discrete interval placement of gizmos, a pluggable system
of snap modes was implemented that could be expanded to handle a wide
range of user-input discretizations.

Editing interaction mode is further divided into three submodes.  The
first mode activates when a user selects a gizmo type from the gizmo
palette.  Through this mode, the user must be able to define gizmos
and place them on the gameboard.  However, gizmos of different types
may vary significantly in how they are defined.  Simple gizmos like
the standard set can just be stamped at positions, but more complex
ones like poly gizmos require schemes such as a series of clicks that
define a closed polygon.  To support a most general set of possible
gizmo types, the build mode must be able to poll arbitrary volumes
of information from the user, from a single click to an unpredictably
long sequence.  However, the mode must also be aware of when enough
input has been collected that is sufficient for building a gizmo.  To
meet these requirements, a probe system was created.

Probes are temporary monitors of the user input channels--mouse and
keyboard.  As input is received, the probes cache the information,
checking each time new input arrives whether sufficient input has
been collected.  Each type of probe is task-specific and will wrap
a specific pattern of input sequence, signaling success when the
pattern has been achieved and returning an atomic set of data
representing the input sequence.  For example, a simple probe would 
have sessions consisting of monitoring a single mouse click, messaging 
the submode when this has fired.  Other probes could monitor for 
click-drag-release patterns and then notify a build mode for sizable
gizmos to operate only after this pattern has been observed.

In conjunction with probes, submodes become adaptible so that a single
submode can handle a class of actions.  All gizmos can be built through
a general submode design that reflects on the gizmo's properties,
determines the user-definition scheme, selects the appropriate probe,
and builds after the probe has finished its session.  Similarly, the
other two submodes assume a simple structure: the selection submode
probes for mouse click collisions with frobber menus and other gizmos,
and the property setting submode reflects on the property being set to
figure out the input pattern.

Supporting the submode system is a system of editing artifacts that
portray transient images and editing elements like connection arrows,
snap grids, and frobbers.  Artifacts are, however, not separate 
components that only exist for display purposes; any object can be used 
as an artifact, so long as the renderer has support for displaying it.  
For example, while building positionable gizmos, the transient artifact 
is an actual gizmo whose position is being refreshed in real time.  
The advantages of managing editing artifacts in this way are many: 
there is no redundancy, there are no synchrony issues, and the same 
mechanism used to draw the gizmo while in the gameboard can be reused 
to draw the gizmo in this transitional state.  These artifacts are used
to indicate modality and represent information.

Through this system, any editor-side task is divided into three 
components.  On the user side is the probe that interfaces between
the user input and the editing system.  On the system side is the
editing artifact that uses information gathered by the probe and
translates it into visual feedback for the user.  Combining these two
aspects is the submode, responsible for carrying about the actual
edits controlled by the user's input and portrayed by the editing 
artifacts.


\subsubsection{Property Table}
\label{sec:property-table}

A property table is displayed at the bottom of the editor
interface. It allows the user to browse through a tree view of the
property system, viewing and editing the values of each property. If a
gizmo is selected, it appears as the root of the property hierarchy;
if no gizmo is selected, the \texttt{GameBoard} is the root.

The property table is implemented in the
\texttt{gizmoball.ui.propertytable} package. The external interface is
a \texttt{PropertyTable} class that, given a root node, traverses the
property hierarchy to generate and display a tree-table. Changes in
the table are translated into changes in game state by parsing the
text values and translating them into \texttt{setProperty} calls. The
\texttt{PropertyTable} has \texttt{startListening} and \texttt{stopListening}
calls that allow it to be registered as a \texttt{PropertyObserver} to
receive notifications when properties change. This can be disabled
during gameplay for speed.

We will not describe the internal workings of the
\texttt{PropertyTable} and its associated package in great detail, as
they are neither especially interesting nor easy to understand. No
sane person should be subjected to the
\texttt{gizmoball.ui.propertytable} package source. Part of the reason
for the complexity is Swing's lack of a \text{TreeTable} class. Thus
we were forced to implement our own \texttt{TreeTable} by using a
\texttt{JTree} as a renderer for a \texttt{JTable}. The remainder of
the code is a data model which builds the property tree, providing
implementations of the required accessor and mutator functions for the
\texttt{JTree} and \texttt{JTable}. To accomplish this, layers upon
layers of abstractions wrapping other abstractions and being swaddled
themselves in still more abstractions were required. We can only quote
Thompson and Ritchie's infamous quote from the Unix source: ``You are
not expected to understand this.'' \cite{ritchie}. It will be better
for your sanity if you don't.