manual/specs/BigBookOfOperationsAndModes.tex

\documentclass[10pt]{article}
\textwidth 160mm
\textheight 220mm
\topmargin 0mm
\headheight=0mm
\headsep=5mm
\evensidemargin -0.4mm
\oddsidemargin -0.4mm
\pagestyle{headings}

\title{Zap Brannagans's Big Book of Operations \& Modes}
\author{Dominik G\"oddeke}
\date{July 13th, 2001}

\begin{document}

\maketitle

This document describes all operations available in the \textbf{DeViSoRGriD 2} application, and the corresponding mode changes invoked by them.
For more details about the implementation and how we put these rules into code, see the programmer's guide.

\tableofcontents


\section{The Main Modes}
As outlined in the documentation, there are eight major modes the
application can be in. Each mode strictly determines what happens if
the user clicks on the central drawing area. Of course, the
application is in only one mode at all times and the current mode is
never unspecified.
\begin{itemize}
\item \texttt{NO MODE} This is the default mode. Only selecting is allowed by throwing a lasso on the drawing area. There is no explicit one-click button to switch back to NO MODE, however, if all additional dialogs are closed, if zooming is disabled, the addType is set to NOTHING and Rectifying is disabled too, the application sure returns to NO MODE. As there can be only one mode at at time, usually one click on the button that toggles the current mode will suffice to go back to NO MODE.
\item \texttt{ZOOM MODE} In this mode, zoom operations are available. If the zoomType submode is set to SET, rectangle-drawing results in zooming into the enclosed area so that it fits the current main frame size. If the zoomType is set to IN, single-clicking results in zooming into the domain by a constant factor, centering the view to the event point.
\item \texttt{DRAW MODE} In this mode, depending on the current addType selected, multiple elements and segments can be inserted in the drawing area. See below for a brief description of the input of every item.
\item \texttt{EDGE STATUS MODE} This mode is activated only by the according dialog. Clicking on an edge with the left button sets the edge's values to the ones set in the dialog, clicking on an edge with the right button displays the edge's values in the dialog. This also works with selections of edges. In the dialog, clicking APPLY has the same effect as a left click (for the selection), clicking close closes the dialog and switches back to normal mode.
\item \texttt{PARALLELBLOCK MODE} This mode is activated only by the according dialog. Clicking APPLY sets the values from the dialog to the currently selected macro elements, clicking on macro elements updates the values in the dialog. CLOSE and AUTOMATIC work respectively. Lasso-throwing for selections has the same effect.
\item \texttt{REFINE MODE} This mode is also only activated by the corresponding dialog. Clicking REFINE in the dialog calls the TriGen tool with the parameters set in the dialog to work on the current selection of elements. selecting is also allowed. Clicking CANCEL closes the dialog and switches back to NO MODE.
\item \texttt{PROPERTY MODE} This mode allows to change the properties of any
  item of the domain. Clicking on an item pops up a modal dialog where the user can change certain properties of the selected item. The dialog differs for
  various items, however, not all item types are supported. In that case, an
  error message is displayed.
\item \texttt{RECTIFYELEMENT MODE} This mode allows to transform quads
and macros to rectangular shape with several left clicks on the
element (all possible rectifications are cycled through). A
right-click on the same element perfoms an undo operation of the last
transformation. Clicking on other items on the drawing area has no
effect.
\item \texttt{MIRROR MODE} This mode is only used for indirect
mirroring. Basically, it allows the user to draw a line against which
mirroring is performed on the drawing area. as soon as the line is
finished, the selected items will be mirrored and the application will
automatically return to NO MODE.

\end{itemize}

\section{Modes and Operations}
In this section, for all operations the pre-condition (what mode the application must be in to have a discernable effect) and the post-condition (what mode the application is in after performing the operation) are once and for all defined. As all operations are available through the menu (Toolbar and keyboard access is just additional to some of them), the definition is structured according to the submenus.\\
There are three different types of operations available, single-action operations, toggle operations and multiple toggle operations.

\subsection{The Default Setting}
This short section just lists the default submode entries. It is used in every mode change to update the GUI. For easier reference, it is explicitly outlined here:
\begin{itemize}
\item All submode mask buttons remain in their previous setting, so
does the directInput toggle and the copyMode.
\item The current addType is set to ``Nothing'', therefore all ''add...'' checkbox-menu-entries and toolbar buttons are deselected.
\item For the modes that are valid only when the appropriate dialog is visible
  (PROPERTY, PARALLELBLOCK and EDGE STATUS), the according dialog is closed.
\item The Zoom toggle buttons are disabled.
\end{itemize}

\subsection{Operations in the FILE menu}
\begin{itemize}
\item NEW:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] A confirmation dialog is brought up if the user has unchanged data.
\item[Postcondition:] If the user approves the confirmation, the application
  goes back to default settings, additionally selecting the select mask
  buttons. It then switches to NO MODE. Otherwise nothing is changed.
\end{description}
\item OPEN:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] A confirmation dialog is brought up if the user has unchanged data.
\item[Postcondition:] If the user approves the confirmation, the FileLoader
  dialog is brought up. If the user makes a valid selection in this dialog, the
  application goes back to default settings, additionally selecting the select
  mask buttons, and the domain is loaded. It then switches to NO MODE. If the user exits either of the dialogs non-applovingly, nothing is changed.
\end{description}
\item SAVE:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] If the domain has not been saved before, the saveAs dialog is displayed, otherwise the domain is saved using the most recently used filename and file type.
\item[Postcondition:] In any case, nothing is changed.
\end{description}
\item SAVE AS (UCD, FEAT, FEAST):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The saveAs dialog is displayed.
\item[Postcondition:] If the user approves the dialog, the domain is saved in the specified format to the specified file. Otherwise, nothing is changed.
\end{description}
\item MERGE DOMAIN:
\begin{description}
\item same as load, the newly loaded domain is merged with the existing domain, the boundary container numbering is updated to make sure all boundary containers have different, subsequent numbers.
\end{description}
\item PRINT:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The print dialog is displayed.
\item[Postcondition:]  If the user approves the dialog, the specified part of the domain is printed on the selected printer. Otherwise, nothing is changed.
\end{description}
\item EXIT:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] If the user has unchanged data, a confirmation dialog is displayed.
\item[Postcondition:] if the user approves, the application is shut down, otherwise, nothing is changed.
\end{description}
\end{itemize}


\subsection{Operations in the EDIT menu}
\begin{itemize}
\item UNDO:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The most recent change is reverted.
\item[Postcondition:] Due to our undo model, the application is in the mode it was in before the last action (see the UndoFunctionality paper).
\end{description}
\item CUT:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] If the current selection is empty, nothing happens. Otherwise, the selected elements are removed from both the internal data structure and the drawing area and stored in the clipboard.
\item[Postcondition:] The previous mode is kept.
\end{description}
\item COPY:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] If the current selection is empty, nothing happens. Otherwise, the selected elements are copied to the clipboard.
\item[Postcondition:] The mode is not changed.
\end{description}
\item PASTE (Toggle operation)
\begin{description}
\item[Precondition:] This operation can be performed if the current selection is
  not empty.
\item[Actions:] The application first restores the default setting (without mode changes of course. This is done to deselect all sub-modes that might have been activated before).The application switches to DRAW mode, and the addType is set to CLIPBOARD.
\item[Postcondition:] DRAW mode and CLIPBOARD addType. Clicks on the drawing area result in pasting the contents of the clipboard, with the upper left corner of the selection being the point the click occurred at. This means the same items can be pasted to the domain multiple times.
\end{description}
\item SCALE:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] If the current selection is empty, nothing happens. Otherwise, a dialog pops up asking for the scale factor (a positive or negative nonzero percent value). The selected elements are then scaled by the given factor.
\item[Postcondition:] The mode is not changed.
\end{description}
\item ROTATE:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] If the current selection is empty, nothing happens. Otherwise, a dialog pops up asking for the rotating angle (a positive or negative double value in the range of -360 to 360 degrees). The selected elements are then rotated by the given angle.
\item[Postcondition:] The mode is not changed.
\end{description}
\item MIRROR (Toggle Operation):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] If the current selection is empty, nothing
happens. Otherwise, if direct input is active, a dialog is shown. In
indirect input mode, the application switches to MIRROR MODE.
\item[Postcondition:] When the dialog is closed or when the line is
finished, the application jumps back to NO MODE.
\end{description}
\item SELECT CURRENT BOUNDARY:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The application displays a dialog. After selecting a boundary there, its number is set as currentBoundary in the ControlCenter.
\item[Postcondition:] No mode change.
\end{description}

\end{itemize}

\subsection{Operations in the VIEW menu}
\begin{itemize}
\item SET ZOOM (Toggle Operation):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] No iminent action.
\item[Postcondition:] After restoring default submode settings, the application switches to ZOOM MODE, zoomType is set to SET. In this mode, rectangle-drawing on the drawing area results in zooming into the enclosed area so that the rectangle fits the screen. This is a toggle mode, so the application stays in this mode until the next mode change.
\end{description}
\item RESET ZOOM:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] This is a single operation, the whole domain is zoomed back to default zoom level.
\item[Postcondition:] The previous mode is kept.
\end{description}
\item ZOOM IN (Toggle Operation):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring default sub-modes, the application switches to ZOOM MODE with zoomType IN. Clicking on the drawing area results in zooming in on the domain by a constant factor (+20\%), centering the view on the event point.
\item[Postcondition:] This is a toggle mode, the application stays in that mode
\end{description}
\item ZOOM OUT:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The last ''set zoom'' or ''zoom in'' operation is taken back, in other words, this is a one-step undo for zooming.
\item[Postcondition:] The previous mode is kept.
\end{description}
\item SELECT NODES (Multiple Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] No iminent action.
\item[Postcondition:] No mode change, only the selection flag for
nodes is updated.
\end{description}
\item SELECT ELEMENTS (Multiple Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] No iminent action.
\item[Postcondition:] No mode change, only the selection flag for
elements is updated.
\end{description}
\item SELECT SEGMENTS (Multiple Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] No iminent action.
\item[Postcondition:] No mode change, only the selction flag for
segments is updated.
\end{description}
\item SELECT EDGES (Multiple Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] No iminent action.
\item[Postcondition:] No mode change, only the selction flag for
edges is updated.
\end{description}
\item PROPERTIES (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] No iminent action.
\item[Postcondition:] After restoring default sub-modes, the application switches to PROPERTY MODE.
\end{description}
\end{itemize}


\subsection{Operations in the DOMAIN menu}
\begin{itemize}
\item NEW BOUNDARY CONTAINER
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] A new empty boundary container is added to the domain, the boundary counter is incremented.
\item[Postcondition:] The mode is not changed.
\end{description}
\item ANALYTIC DOMAIN DESCRIPTION:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] If the current domain contains non-analytic segments, a warning dialog pops up. If the user confirms that dialog, a new empty domain is created. A modal dialog box is brought up allowing the user to enter a parametric or analytic description of the domain. An analyticly defined domain must not contain any other segments.
\item[Postcondition:] The mode is not changed.
\end{description}
\item DIRECT INPUT  (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The direct flag is set to \texttt{true} if it has been set to false before, to false otherwise.
\item[Postcondition:] The mode is not changed.
\end{description}
\item NEW LINE (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring defaults except for the direct input mode, the application switches to DRAW MODE with addType LINE. If that has been the previous mode, it switches to NO MODE with addType NOTHING.
If the direct flag is enabled, single-clicking on the domain brings up a modal dialog asking for the startpoint and endpoint coordinates. The event point is the pre-set startpoint. Selecting APPLY in that dialog adds the newly defined line to the currently selected boundary container if the user input has been successfully validated. If validation is not successful, an error message is brought up. Selecting OK closes the dialog afterwards. Selecting CANCEL in that dialog closes the dialog without adding a new line. \\
Otherwise, Left-clicking marks the startpoint, moving the mouse cursor draws a direct line from the startpoint to the current cursor position, and a second left-click marks the endpoint, thus adding the new line to the current boundary container.
\item[Postcondition:] This mode is a toggle mode.
\end{description}
\item NEW MULTILINE (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring defaults for all other submodes except the direct input mode, the application switches to DRAW MODE with addType MULTILINE. If that has been the previous mode, it switches to NO MODE with addType NOTHING. For this segment type, the direct flag is ignored. Left-clicking marks the startpoint of a new line element, moving the mouse cursor draws a direct line from the startpoint to the current cursor position, and another left-click marks the an endpoint of the line element, which is also considered the startpoint for the next line segment. Right-Clicking marks the current endpoint as the final endpoint, the application then returns to the state before the first click, allowing for adding more multiline items directly afterwards.
\item[Postcondition:] This mode is a toggle mode.
\end{description}
 \item NEW CIRCLE+ (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring defaults for all other submodes except the direct input mode, the application switches to DRAW MODE with addType CIRCLEP. If that has been the previous mode, it switches to NO MODE with addType NOTHING. If the direct flag is enabled, single-clicking on the domain brings up a modal dialog asking for the midpoint coordinates, radius and angle. The event point is the pre-set midpoint. Selecting OK in that dialog adds the newly defined arc to the currently selected boundary if the user input has been successfully validated. If validation is not successful, an error message is brought up. Selecting CANCEL in that dialog closes the dialog without adding a new line.\\
Otherwise, Left-clicking marks the midpoint, dragging (with still pressed left button) draws a direct line from the startpoint to the current cursor position, and releasing the button marks the radius. After that, two input formats are supported: Right-Clicking results in drawing a full circle (with mathematical positive orientation) and adding it to the currently selected boundary, just moving the mouse pointer allows for drawing semi-circles or any arc. Once the desired angle has been reached, left-clicking adds the arc to the currently selected boundary.
\item[Postcondition:] This mode is a toggle mode.
\end{description}
\item NEW CIRCLE- (Toggle Mode):\\
Analogously to positively-oriented circles.
\item NEW TRI (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring defaults for all other submodes except the direct input mode, the application switches to DRAW MODE with addType TRI. If that has been the previous mode, it switches to NO MODE with addType NOTHING. If direct input is disabled, Tris are added just like multilines, despite the fact that tris always form a closed triangle, and all three points must be nodes. Therefore, if there is no node at the desired points (modulo the snap value of course), a new node is added. If direct input is enabled, a modal dialog pops up asking for three nodes (by their number, therefore these nodes have to exist already). Selecting apply adds a new Tri element to the domain (after validation of course), selecting OK closes the dialog afterwards, selecting CANCEL closes the dialog without adding anything.
\item[Postcondition:] This mode is a toggle mode.
\end{description}
\item NEW QUAD (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring defaults for all other submodes except the direct input mode, the application switches to DRAW MODE with addType QUAD. If that has been the previous mode, it switches to NO MODE with addType NOTHING. If direct input is disabled, Quads are added just like multilines, despite the fact that they always have four sides, forming a closed rectangle,  and all four corners must be nodes. Therefore, if there is no node at the desired points (modulo the snap value of course), a new node is added. The direct input works exactly the same as for Tris, except that four nodes are required.
\item[Postcondition:] This mode is a toggle mode.
\end{description}
\item NEW MACRO (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] Macros are added just like quads, the local refinement is not part of the drawing process and can be invoked by selecting PARALLELBLOCK from the GRID menu.
\item[Postcondition:] This mode is a toggle mode.
\end{description}
\item ADJUST ALL BOUNDARIES:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] All boundary parts are processed to make them continous. If this is not possible, the application automatically selects the malformed boundary and displayes a warning message.
\item[Postcondition:] The mode is not changed.
\end{description}
\item LINK BOUNDARIES:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] All boundaries are processed. If two boundaries share one or more segments (full segments, not only segment parts, share implies visual sharing, both boundaries have to be continous on their own), they are merged into one boundary, which means the shared segments are removed. One boundary number is removed, the boundary numbering is updated.
\item[Postcondition:] The mode is not changed.
\end{description}
\item SWAP BOUNDARY ORIENTATION:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The orientation of the (parametric description of the) selected boundary is swapped.
\item[Postcondition:] The mode is not changed.
\end{description}
\item DOMAIN STATISTICS:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] A non-modal dialog pops up displaying the domain statistics.
\item[Postcondition:] The mode is not changed.
\end{description}
\end{itemize}


\subsection{Operations in the GRID menu}
\begin{itemize}
\item ADD MULTIPLE BOUNDARY NODES:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] A modal dialog pops up asking for details (number of nodes to create, the boundary number on which nodes are to ne added etc.). Clicking APPLY adds boundary nodes to the boundary specified in the dialog, OK closes the dialog afterwards, CANCEL doesn't add any nodes and closes the dialog.
\item[Postcondition:] The mode is not changed.
\end{description}
\item SET EDGE STATUS (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring default submodes, the application switches to EDGE STATUS MODE. The non-modal (additional toolbar-like) dialog pops up at the reserved position. If that has been the previous mode, it switches to NO MODE, closing the dialog.
\item[Postcondition:] This is a toggle mode.
\end{description}
\item SET PARALLEL BLOCK (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring default submodes, the application switches to PARALLELBLOCK MODE. The non-modal (additional toolbar-like) dialog pops up at the reserved position. If that has been the previous mode, it switches to NO MODE, closing the dialog.
\item[Postcondition:] This is a toggle mode.
\end{description}
\item LOADBALANCING:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] A modal dialog pops up asking for details.
\item[Postcondition:] The previous mode is kept.
\end{description}
\item RECTIFY ELEMENTS (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring default submodes, the application switches to RECTIFYELEMENT MODE. If that has been the previous mode, it switches to NO MODE.
\end{description}
\item REFINE (Toggle Mode):
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] After restoring default submodes, the application switches to REFINE MODE. If that has been the previous mode, it switches to NO MODE.
\end{description}
\end{itemize}


\subsection{Operations in the OPTIONS menu}
The Options menu's only entries are shortcuts to the according tab sheet in the Options Dialog. So the mode changes are the same for all these entries.
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The modal Options Dialog pops up displaying the corresponding tab sheet.
\item[Postcondition:] The application resets itself to default mode.
\end{description}


\subsection{Operations in the HELP menu}
\begin{itemize}
\item MANUAL:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The help screen is displayed (non-modally).
\item[Postcondition:] The mode is not changed.
\end{description}
\item ABOUT:
\begin{description}
\item[Precondition:] This operation can be performed in any mode.
\item[Actions:] The modal ABOUT dialog is displayed.
\item[Postcondition:] The mode is not changed.
\end{description}
\end{itemize}

\end{document}