= MVC

Model View Controller, or MVC in short, is a software design pattern used to develop [https://en.wikipedia.org/wiki/Graphical_user_interface GUI]s.

The details of the approach are explained well on the [https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller MVC wiki page]. In short, 
* A model contains the data that the user is adjusting. 
* A view shows the data in a GUI to the user (eg, graph, text field, slider position)
* A controller allows the user to change the data (eg dragging sliders, entering text or numbers, clicking check boxes)

A view and controller can, and often are, merged into a single component. For example a slider shows the current value, but the user can also drag the slider; or a checkbox shows the current setting (on or off) while the user can simply click on it to toggle the value.

== Why a toolbox?
This toolbox is to help users develop an MVC based GUI. The tools built into Java lack some functionality: while Java provides a ListModel and a TableModel, it lacks other models such as a StringModel. 

== The Model
The toolbox has a hierarchy of Models. This section describes the various standard models.

=== Model and Compound Models.
At the root is the Model interface. A model basically is an object, which implicitly contains some values that can be adjusted. The interface only specifies that the object broadcasts Event objects whenever something changes in the model.
A Model is called a Compound Model if it contains sub-models. For instance a Person compound model may contain a StringModel containing the name, and a NumberModel containing the age.

=== Event object
All  Event objects are objects containing details of a change that happened in a model. It contains a reference to the source Model of the event, and possibly a child event if the change happened on some sub-model.
There are four types of changes to a model:
* Changed: a sub-model of the model changed
* Added: a model (eg a list) just got extended by addition of a new submodel
* Removed: a model (eg a list) just got shrinked by removal of a submodel
* Selected: a model (eg in a list) just got selected

=== Basic Models
* BasicModel is a generic implementation of Model ment to store primitive objects eg String or numbers. It introduces a getValue and setValue function. There also is a check() function. The intention of the check() function is that a Model throws an exception if the value passed into setValue does not meet additional requirements. 
* StringModel is a BasicModel containing  a String
* NumberModel is a BasicModel containing  a Number. Actually it contains a BigDecimal, which allows arbitrary precision numbers to be entered and manipulated without loss of precision or rounding.

=== ListModel
ListModel contains a list of Models and thus is a compound model.  

=== MapModel
The MapModel contains a Map, or dictionary, of values. Both key and value are a Model so this is a compound model. That key and value are a Model implies that both key and value can be manipulated directly, without calling the MapModel directly. All implementations of MapModel will listen to such changes and notify the change anyway.
MapModel provides a getValue(key) and a put(key,value) function. 

DefaultMapModel is the basic implementation of MapModel. It is implemented using a LinkedHashMap, which helps keeping a fixed order in the elements. This fixed order is important to ensure the display of the elements in the GUI remains fixed. It also allows setting a minimum number of elements in the map

MapFromKeys is a special implementation of MapModel that generates a Map from a ListModel. The ListModel contains the Keys of the Map. MapFromKeys ensures that all keys always have a value. If needed, the create() function is called to automatically generate a new value for a key. When  a key is removed and then later re-added, MapFromKeys may remember the old value, if isRetainValues is set.

=== TypedModel and RealType
A TypedModel extends a Model by adding a RealType and the functions getCurrentValue and setCurrentValue to get/set the RealType contained by the model.
The RealType refers to the actual object contained in the model. This is especially relevant for Compound Models, such as the Person model described above. The getCurrentValue function now returns a Person. 
The reason that the RealType is not included in Model is because we run into typing issues with the MapModel.