Added front-end code information to the design document

3 files changed, 79 insertions, 25 deletions

diff --git a/docs/design.org b/docs/design.org
index be345f2..8bd27e6 100644
--- a/docs/design.org
+++ b/docs/design.org
@@ -1,14 +1,12 @@
 #+TITLE: 7Units Design Document
-#+SUBTITLE: For version 0.3.1
-#+DATE: 2021 August 26
+#+SUBTITLE: For version 0.4.0-alpha.1
+#+DATE: 2022 May 18
 #+LaTeX_HEADER: \usepackage[a4paper, lmargin=25mm, rmargin=25mm, tmargin=25mm, bmargin=25mm]{geometry}
 #+LaTeX_HEADER: \usepackage{xurl}
 #+LaTeX: \newpage
 
 * Introduction
   7Units is a program that can convert between units.  This document details the internal design of 7Units, intended to be used by current and future developers.
-
-  The frontend code is currently subject to change, so it is not included in the current version of this document.
 * Unit System Design
   Any code related to the backend unit system is stored in the ~sevenUnits.unit~ package.
 
@@ -56,6 +54,31 @@
 
     Dimension files are similar, only for dimensions instead of units and prefixes.
 #+LaTeX: \newpage
+* Front-End Design
+  The front-end of 7Units is based on an MVP model.  There are two major frontend classes, the *View* and the *Presenter*.
+** The View
+   The ~View~ is the part of the frontend code that directly interacts with the user.  It handles input and output, but does not do any processing.  Processing is handled by the presenter and the backend code.
+
+   The ~View~ is an interface, not a single class, so that I can easily create multiple views without having to rewrite any processing code.  This allows me to easily prototype changes to the GUI without messing with existing code.
+
+   In addition, I have decided to move some functions of the ~View~ into two subinterfaces, ~UnitConversionView~ and ~ExpressionConversionView~.  This is because 7Units supports two kinds of unit conversion: unit conversion (select two compatible units, specify a value then convert) and expression conversion (enter two expressions and convert the first to a multiple of the second).  Putting these functions into subinterfaces allows a ~View~ to do one type of conversion without forcing it to support the other.
+
+   There are currently two implementations of the ~View~:
+   - TabbedView :: A Swing GUI implementation that uses tabs to separate the two types of conversion.  The default GUI used by 7Units.
+   - ViewBot :: A simulated view that allows programs to set the output of its public methods (i.e. every getter in ~View~ has a setter in ~ViewBot~).  Intended for testing, and is already used by ~PresenterTest~.
+   Both of these ~View~ implementations implement ~UnitConversionView~ and ~ExpressionConversionView~.
+** The Presenter
+   The ~Presenter~ is an intermediary between the ~View~ and the backend code.  It accepts the user's input and passes it to the backend, then accepts the backend's output and passes it to the frontend for user viewing.  Its main functions do not have arguments or return values; instead it takes input from and provides output to the ~View~ via its public methods.
+** Utility Classes
+   The frontend has many miscellaneous utility classes.  Many of them are package-private.  Here is a list of them, with a brief description of what they do and where they are used:
+   - DefaultPrefixRepetitionRule :: An enum containing the available rules determining when you can repeat prefixes.  Used by the ~TabbedView~ for selecting the rule and by the ~Presenter~ for loading it from a file.
+   - DelegateListModel :: A ~javax.swing.ListModel~ implementation that delegates all of its methods to a ~List~.  Implements ~List~ by also delegating to the underlying list.  Used by the ~SearchBoxList~ to create an easily mutable ~ListModel~.
+   - FilterComparator :: A ~Comparator~ that sorts objects according to whether or not they match a filter.  Used by the ~SearchBoxList~ for item sorting.
+   - GridBagBuilder :: A convenience class for generating ~GridBagConstraints~ objects for Swing's ~GridBagLayout~.  Used by ~TabbedView~ for constructing the GUI.
+   - SearchBoxList :: A Swing component that combines a text field and a ~JList~ to create a searchable list.  Used by the ~TabbedView~'s unit conversion mode.
+   - StandardDisplayRules :: A static utility class that allows you to generate display/rounding rules.  Used by ~TabbedView~ for generating these rules and ~Presenter~ for loading them from a file.
+   - UnitConversionRecord :: A record-like object that contains the results of a unit or expression conversion.  Used by ~UnitConversionView~ and ~ExpressionConversionView~ for accepting the results to be displayed.
+#+LaTeX: \newpage
 * Utility Classes
   7Units has a few general "utility" classes.  They aren't directly related to units, but are used in the units system.
 ** ObjectProduct
diff --git a/docs/design.pdf b/docs/design.pdf
index fd1f2f1..0c4bb53 100644
--- a/docs/design.pdf
+++ b/docs/design.pdf
diff --git a/docs/design.tex b/docs/design.tex
index 178a1c8..6523206 100644
--- a/docs/design.tex
+++ b/docs/design.tex
@@ -1,4 +1,4 @@
-% Created 2021-08-26 Thu 11:25
+% Created 2022-05-18 Wed 09:37
 % Intended LaTeX compiler: pdflatex
 \documentclass[11pt]{article}
 \usepackage[utf8]{inputenc}
@@ -16,9 +16,9 @@
 \usepackage{hyperref}
 \usepackage[a4paper, lmargin=25mm, rmargin=25mm, tmargin=25mm, bmargin=25mm]{geometry}
 \usepackage{xurl}
-\date{2021 August 26}
+\date{2022 May 18}
 \title{7Units Design Document\\\medskip
-\large For version 0.3.1}
+\large For version 0.4.0-alpha.1}
 \hypersetup{
  pdfauthor={},
  pdftitle={7Units Design Document},
@@ -34,12 +34,10 @@
 \newpage
 
 \section{Introduction}
-\label{sec:orgc81fddd}
+\label{sec:orgeddaf9e}
 7Units is a program that can convert between units.  This document details the internal design of 7Units, intended to be used by current and future developers.
-
-The frontend code is currently subject to change, so it is not included in the current version of this document.
 \section{Unit System Design}
-\label{sec:org9d0655d}
+\label{sec:org67c461a}
 Any code related to the backend unit system is stored in the \texttt{sevenUnits.unit} package.
 
 Here is a class diagram of the system.  Unimportant methods, methods inherited from Object, getters and setters have been omitted.
@@ -48,11 +46,11 @@ Here is a class diagram of the system.  Unimportant methods, methods inherited f
 \end{center}
 \newpage
 \subsection{Dimensions}
-\label{sec:org1e98dda}
-Dimensions represent what a unit is measuring, such as length, time, or energy.  Dimensions are represented as an \hyperref[sec:orgc7c5740]{ObjectProduct}<BaseDimension>, where \texttt{BaseDimension} is a very simple class (its only properties are a name and a symbol) which represents the dimension of a base unit; these base dimensions can be multiplied to create all other Dimensions.
+\label{sec:org8ff098d}
+Dimensions represent what a unit is measuring, such as length, time, or energy.  Dimensions are represented as an \hyperref[sec:org364a46d]{ObjectProduct}<BaseDimension>, where \texttt{BaseDimension} is a very simple class (its only properties are a name and a symbol) which represents the dimension of a base unit; these base dimensions can be multiplied to create all other Dimensions.
 \subsection{Unit Classes}
-\label{sec:orgd5ff0fb}
-Units are internally represented by the abstract class \texttt{Unit}.  All units have an \hyperref[sec:orgc7c5740]{ObjectProduct}<BaseUnit> (referred to as the base) that they are based on, a dimension (ObjectProduct<BaseDimension>), one or more names and a symbol (these last two bits of data are contained in the \texttt{NameSymbol} class).  The dimension is calculated from the base unit when needed; the variable is just a cache.  It has two constructors: a package-private one used to make \texttt{BaseUnit} instances, and a protected one used to make general units (for other subclasses of \texttt{Unit}).  All unit classes are immutable.
+\label{sec:org8192d2b}
+Units are internally represented by the abstract class \texttt{Unit}.  All units have an \hyperref[sec:org364a46d]{ObjectProduct}<BaseUnit> (referred to as the base) that they are based on, a dimension (ObjectProduct<BaseDimension>), one or more names and a symbol (these last two bits of data are contained in the \texttt{NameSymbol} class).  The dimension is calculated from the base unit when needed; the variable is just a cache.  It has two constructors: a package-private one used to make \texttt{BaseUnit} instances, and a protected one used to make general units (for other subclasses of \texttt{Unit}).  All unit classes are immutable.
 
 Units also have two conversion functions - one which converts from a value expressed in this unit to its base unit, and another which converts from a value expressed in the base unit to this unit.  In \texttt{Unit}, they are defined as two abstract methods.  This allows you to convert from any unit to any other (as long as they have the same base, i.e. you aren't converting metres to pounds).  To convert from A to B, first convert from A to its base, then convert from the base to B.
 
@@ -77,36 +75,69 @@ There are a few more classes which play small roles in the unit system:
 \item[{USCustomary}] A static utility class with instances of common units in the US Customary system (not to be confused with the British Imperial system; it has the same unit names but the values of a few units are different).
 \end{description}
 \subsection{Prefixes}
-\label{sec:org1aaa92c}
+\label{sec:org6469484}
 A \texttt{UnitPrefix} is a simple object that can multiply a \texttt{LinearUnit} by a value.  It can calculate a new name for the unit by combining its name and the unit's name (symbols are done similarly).  It can do multiplication, division and exponentation with a number, as well as multiplication and division with another prefix; all of these work by changing the prefix's multiplier.
 \subsection{The Unit Database}
-\label{sec:org7c6cf6d}
+\label{sec:orgeeef8d3}
 The \texttt{UnitDatabase} class stores all of the unit, prefix and dimension data used by this program.  It is not a representation of an actual database, just a class that stores lots of data.
 
 Units are stored using a custom \texttt{Map} implementation (\texttt{PrefixedUnitMap}) which maps unit names to units.  It is backed by two maps: one for units (without prefixes) and one for prefixes.  It is programmed to include prefixes (so if units includes "metre" and prefixes includes "kilo", this map will include "kilometre", mapping it to a unit representing a kilometre).  It is immutable, but you can modify the underlying maps, which is reflected in the \texttt{PrefixedUnitMap}.  Other than that, it is a normal map implementation.
 
 Prefixes and dimensions are stored in normal maps.
 \subsubsection{Parsing Expressions}
-\label{sec:org8392990}
-Each \texttt{UnitDatabase} instance has four \hyperref[sec:orgb091347]{ExpressionParser} instances associated with it, for four types of expressions: unit, unit value, prefix and dimension.  They are mostly similar, with operators corresponding to each operation of the corresponding class (\texttt{LinearUnit}, \texttt{LinearUnitValue}, \texttt{UnitPrefix}, \texttt{ObjectProduct<BaseDimension>}).  Unit and unit value expressions use linear units; nonlinear units can be used with a special syntax (like "degC(20)") and are immediately converted to a linear unit representing their base (Kelvin in this case) before operating.
+\label{sec:org338b57f}
+Each \texttt{UnitDatabase} instance has four \hyperref[sec:org89370fa]{ExpressionParser} instances associated with it, for four types of expressions: unit, unit value, prefix and dimension.  They are mostly similar, with operators corresponding to each operation of the corresponding class (\texttt{LinearUnit}, \texttt{LinearUnitValue}, \texttt{UnitPrefix}, \texttt{ObjectProduct<BaseDimension>}).  Unit and unit value expressions use linear units; nonlinear units can be used with a special syntax (like "degC(20)") and are immediately converted to a linear unit representing their base (Kelvin in this case) before operating.
 \subsubsection{Parsing Files}
-\label{sec:orgd4ad341}
+\label{sec:org4a8e841}
 There are two types of data files: unit and dimension.
 
 Unit files contain data about units and prefixes.  Each line contains the name of a unit or prefix (prefixes end in a dash, units don't) followed by an expression which defines it, separated by one or more space characters (this behaviour is defined by the static regular expression \texttt{NAME\_EXPRESSION}).  Unit files are parsed line by line, each line being run through the \texttt{addUnitOrPrefixFromLine} method, which splits a line into name and expression, determines whether it's a unit or a prefix, and parses the expression.  Because all units are defined by others, base units need to be defined with a special expression "!"; \textbf{these units should be added to the database before parsing the file}.
 
 Dimension files are similar, only for dimensions instead of units and prefixes.
 \newpage
+\section{Front-End Design}
+\label{sec:orgda7974b}
+The front-end of 7Units is based on an MVP model.  There are two major frontend classes, the \textbf{View} and the \textbf{Presenter}.
+\subsection{The View}
+\label{sec:orgc7df86d}
+The \texttt{View} is the part of the frontend code that directly interacts with the user.  It handles input and output, but does not do any processing.  Processing is handled by the presenter and the backend code.
+
+The \texttt{View} is an interface, not a single class, so that I can easily create multiple views without having to rewrite any processing code.  This allows me to easily prototype changes to the GUI without messing with existing code.
+
+In addition, I have decided to move some functions of the \texttt{View} into two subinterfaces, \texttt{UnitConversionView} and \texttt{ExpressionConversionView}.  This is because 7Units supports two kinds of unit conversion: unit conversion (select two compatible units, specify a value then convert) and expression conversion (enter two expressions and convert the first to a multiple of the second).  Putting these functions into subinterfaces allows a \texttt{View} to do one type of conversion without forcing it to support the other.
+
+There are currently two implementations of the \texttt{View}:
+\begin{description}
+\item[{TabbedView}] A Swing GUI implementation that uses tabs to separate the two types of conversion.  The default GUI used by 7Units.
+\item[{ViewBot}] A simulated view that allows programs to set the output of its public methods (i.e. every getter in \texttt{View} has a setter in \texttt{ViewBot}).  Intended for testing, and is already used by \texttt{PresenterTest}.
+\end{description}
+Both of these \texttt{View} implementations implement \texttt{UnitConversionView} and \texttt{ExpressionConversionView}.
+\subsection{The Presenter}
+\label{sec:org737be7a}
+The \texttt{Presenter} is an intermediary between the \texttt{View} and the backend code.  It accepts the user's input and passes it to the backend, then accepts the backend's output and passes it to the frontend for user viewing.  Its main functions do not have arguments or return values; instead it takes input from and provides output to the \texttt{View} via its public methods.
+\subsection{Utility Classes}
+\label{sec:org81a3701}
+The frontend has many miscellaneous utility classes.  Many of them are package-private.  Here is a list of them, with a brief description of what they do and where they are used:
+\begin{description}
+\item[{DefaultPrefixRepetitionRule}] An enum containing the available rules determining when you can repeat prefixes.  Used by the \texttt{TabbedView} for selecting the rule and by the \texttt{Presenter} for loading it from a file.
+\item[{DelegateListModel}] A \texttt{javax.swing.ListModel} implementation that delegates all of its methods to a \texttt{List}.  Implements \texttt{List} by also delegating to the underlying list.  Used by the \texttt{SearchBoxList} to create an easily mutable \texttt{ListModel}.
+\item[{FilterComparator}] A \texttt{Comparator} that sorts objects according to whether or not they match a filter.  Used by the \texttt{SearchBoxList} for item sorting.
+\item[{GridBagBuilder}] A convenience class for generating \texttt{GridBagConstraints} objects for Swing's \texttt{GridBagLayout}.  Used by \texttt{TabbedView} for constructing the GUI.
+\item[{SearchBoxList}] A Swing component that combines a text field and a \texttt{JList} to create a searchable list.  Used by the \texttt{TabbedView}'s unit conversion mode.
+\item[{StandardDisplayRules}] A static utility class that allows you to generate display/rounding rules.  Used by \texttt{TabbedView} for generating these rules and \texttt{Presenter} for loading them from a file.
+\item[{UnitConversionRecord}] A record-like object that contains the results of a unit or expression conversion.  Used by \texttt{UnitConversionView} and \texttt{ExpressionConversionView} for accepting the results to be displayed.
+\end{description}
+\newpage
 \section{Utility Classes}
-\label{sec:org251cb6a}
+\label{sec:orge44a23f}
 7Units has a few general "utility" classes.  They aren't directly related to units, but are used in the units system.
 \subsection{ObjectProduct}
-\label{sec:orgc7c5740}
+\label{sec:org364a46d}
 An \texttt{ObjectProduct} represents a "product" of elements of some type.  The units system uses them to represent coherent units as a product of base units, and dimensions as a product of base dimensions.
 
 Internally, it is represented using a map mapping objects to their exponents in the product.  For example, the unit "kg m\textsuperscript{2} / s\textsuperscript{2}" (i.e. a Joule) would be represented with a map like \texttt{[kg: 1, m: 2, s: -2]}.
 \subsection{ExpressionParser}
-\label{sec:orgb091347}
+\label{sec:org89370fa}
 The \texttt{ExpressionParser} class is used to parse the unit, prefix and dimension expressions that are used throughout 7Units.  An expression is something like "(2 m + 30 J / N) * 8 s)".  Each instance represents a type of expression, containing a way to obtain values (such as numbers or units) from the text and operations that can be done on these values (such as addition, subtraction or multiplication).  Each operation also has a priority, which controls the order of operations (i.e. multiplication gets a higher priority than addition).
 
 \texttt{ExpressionParser} has a parameterized type \texttt{T}, which represents the type of the value used in the expression.  The expression parser currently only supports one type of value per expression; in the expressions used by 7Units numbers are treated as a kind of unit or prefix.  Operators are represented by internal types; the system distinguishes between unary operators (those that take a single value, like negation) and binary operators (those that take 2 values, like +, -, * or /).
@@ -123,13 +154,13 @@ Expressions are parsed in 2 steps:
 After evaluating the last token, there should be one value left in the stack - the answer.  If there isn't, the original expression was malformed.
 \end{enumerate}
 \subsection{Math Classes}
-\label{sec:orgb4a476a}
+\label{sec:org04a7e76}
 There are two simple math classes in 7Units:
 \begin{description}
 \item[{\texttt{UncertainDouble}}] Like a \texttt{double}, but with an uncertainty (e.g. \(2.0 \pm 0.4\)).  The operations are like those of the regular Double, only they also calculate the uncertainty of the final value.  They also have "exact" versions to help interoperation between \texttt{double} and \texttt{UncertainDouble}.  It is used by the converter's Scientific Precision setting.
 \item[{\texttt{DecimalComparison}}] A static utility class that contains a few alternate equals() methods for \texttt{double} and \texttt{UncertainDouble}.  These methods allow a slight (configurable) difference between values to still be considered equal, to fight roundoff error.
 \end{description}
 \subsection{Collection Classes}
-\label{sec:org4a3e6a1}
+\label{sec:orgb67e633}
 The \texttt{ConditionalExistenceCollections} class contains wrapper implementations of \texttt{Collection}, \texttt{Iterator}, \texttt{Map} and \texttt{Set}.  These implementations ignore elements that do not pass a certain condition - if an element fails the condition, \texttt{contains} will return false, the iterator will skip past it, it won't be counted in \texttt{size}, etc. even if it exists in the original collection.  Effectively, any element of the original collection that fails the test does not exist.
 \end{document}