Merge branch 'release-0.4.0' into stable

1 files changed, 70 insertions, 5 deletions

diff --git a/docs/design.org b/docs/design.org
index be345f2..0e3a477 100644
--- a/docs/design.org
+++ b/docs/design.org
@@ -1,20 +1,53 @@
 #+TITLE: 7Units Design Document
-#+SUBTITLE: For version 0.3.1
-#+DATE: 2021 August 26
+#+SUBTITLE: For version 0.4.0
+#+DATE: 2022 July 8
 #+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.
+* System Overview
+  #+CAPTION: A big-picture diagram of 7Units, containing all of the major classes.
+  #+attr_latex: :height 144px
+  [[./diagrams/overview-diagram.plantuml.png]]
+** Packages of 7Units
+   7Units splits its code into three main packages:
+   - ~sevenUnits.unit~ :: The [[*Unit System Design][unit system]]
+   - ~sevenUnits.utils~ :: Extra classes that aid the unit system.
+   - ~sevenUnitsGUI~ :: The [[*Front-End Design][front end]] code
+   ~sevenUnits.unit~ depends on ~sevenUnits.utils~, while ~sevenUnitsGUI~ depends on both ~sevenUnits~ packages.  There is only one class that isn't in any of these packages, ~sevenUnits.VersionInfo~.
+** Major Classes of 7Units
+   - [[*Unit Classes][sevenUnits.unit.Unit]] :: The class representing a unit
+   - [[*The Unit Database][sevenUnits.unit.UnitDatabase]] :: A class that stores collections of units, prefixes and dimensions.
+   - [[*The View][sevenUnitsGUI.View]] :: The class that handles interaction between the user and the program.
+   - [[*The Presenter][sevenUnitsGUI.Presenter]] :: The class that handles communication between the ~View~ and the unit system.
+#+LaTeX: \newpage
+** Process of Unit Conversion
+   #+CAPTION: The process of converting units
+   [[./diagrams/convert-units.plantuml.png]]
+   1. The ~View~ triggers a unit conversion method from the ~Presenter~.
+   2. The ~Presenter~ gets raw input data from the ~View~'s public methods (from unit, to unit, from value).
+   3. The ~Presenter~ uses the ~UnitDatabase~'s methods to convert the raw data from the ~View~ into actual units.
+   4. The ~Presenter~ performs the unit conversion using the provided unit objects.
+   5. The ~Presenter~ calls the ~View~'s methods to show the result of the conversion.
+#+LaTeX: \newpage
+** Process of Expression Conversion
+   The process of expression conversion is similar to that of unit conversion.
+   #+CAPTION: The process of converting expressions
+   [[./diagrams/convert-expressions.plantuml.png]]
+   1. The ~View~ triggers a unit conversion method from the ~Presenter~.
+   2. The ~Presenter~ gets raw input data from the ~View~'s public methods (unit conversion: from unit, to unit, from value; expression conversion: input expression, output expression).
+   3. The ~Presenter~ uses the ~UnitDatabase~'s methods to parse the expressions, converting the input into a ~LinearUnitValue~ and the output into a ~Unit~.
+   4. The ~Presenter~ converts the provided value into the provided unit.
+   5. The ~Presenter~ calls the ~View~'s methods to show the result of the conversion.
+#+LaTeX: \newpage
 * Unit System Design
   Any code related to the backend unit system is stored in the ~sevenUnits.unit~ package.
 
   Here is a class diagram of the system.  Unimportant methods, methods inherited from Object, getters and setters have been omitted.
-  [[./diagrams/units-class-diagram.plantuml.png]]
   #+CAPTION: Class diagram of sevenUnits.unit
+  [[./diagrams/units-class-diagram.plantuml.png]]
   #+LaTeX: \newpage
 ** Dimensions
    Dimensions represent what a unit is measuring, such as length, time, or energy.  Dimensions are represented as an [[*ObjectProduct][ObjectProduct]]<BaseDimension>, where ~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.
@@ -56,6 +89,38 @@
 
     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.
+*** Rules
+    The ~Presenter~ has a set of function-object rules that determine some of its behaviours.  Each corresponds to a setting in the ~View~, but they can be set to other values via the ~Presenter~'s setters (although nonstandard rules cannot be saved and loaded):
+    - numberDisplayRule :: A function that determines how numbers are displayed.  This controls the rounding rules.
+    - prefixRepetitionRule :: A function that determines which combinations of prefixes are valid in unit expressions.  This controls the unit prefix rules.
+    - searchRule :: A function that determines which prefixes are shown in the unit lists in unit conversion (which prefixed units are searchable).
+
+    These rules have been made this way to enable an incredible level of customization of these behaviours.  Because any function object with the correct arguments and return type is accepted, these rules (especially the number display rule) can do much more than the default behaviours.
+** 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