= Analysis =

== Overview ==
 * Bound controls are used to provide a way for data validation on user input. We need to define and create some base  classes to serve as a mainframe and some base bound controls.
== Task requirements ==
 * Bound controls provide a way for user input. They differ from standard controls in their behavior.
  * Bound controls should act like a View-Controller and you can consider them a Model-View-Controller pattern.
   * View is represented by a field, spinner or a drop-down menu plus a sign whether the current data input is valid or not. 
   * The Controller is the part that validates the data and inputs it in the model or rejects it.
  * As the user inputs data in a bound control it is automatically validated. 
  * If the data is correct it is put in the undo/redo mechanism.
  * If the data is correct the information in the bound control is sent to the bound data-holder(the control model).
  * This transition is two-way. 
  * They allow to attach a model and a verification mechanism. 
 * Bound controls are composed of:
  * a standard control
  * a notification sign. It shows the verification status. 
   Example - icon: It can be either correct (a green tick) or incorrect (a red cross.) Both the tick and the cross should have an explanation in its tool-tip what is wrong with the input of the user.
  * a label (optionally). 
 * We have:
  * !BoundTextField, which contains:
   * icon - green tick, red cross.
   * label - what the input is.
   * text field - for the input itself.
 * We need:
  * Some base bound control which eases bound controls creation.
  * Some Bound controls to use as a start:
   * Spinner with the minimum and maximum value set and a label to say what it is.
 * We should:
  * Design the base classes
  * Polish the !BoundTextField class and fix what is to be fixed.
  * Create a class containing a spinner.
   * When inputing data the tool-tip of the spinner should containing a understandable explanation about its correctness and validity.
   * The spinner bound control should also contain a label, so that the user understands what it is used for.
  *Create a class containing a combo box. Apply same things like the spinner.

== Task result ==
The result of this task must be code.

== Implementation idea ==
- Use a JPanel, with other panels for input field(spinner, text field etc.), notification icons and other.

== Related ==
- !BoundTextField class in sophie.

== How to demo ==
 * Show working controls. 
 * Try to input invalid data. 
 * Try to input valid data, that must result to expected change.
 * Open Eclipse and run => net.asteasolutions.veda.gui.util.demo.!BoundControlsDemo


= Design =
 * A base class for bound controls. Different classes extending it and providing different UI for input of data.
 * !BoundBaseControl:
  * A base class for bound controls.
  * A JLabel to tell the user what the input is about.
  * A JPanel with an Icon - to inform about the validity of the input.
  * When mouse is over the Icon - a tool-tip is displayed to tell what the current status of the validation is.
 * Three classes that extend !BoundBaseControl:
  * !BoundSpinner - contains a JSpinner for the input of the user.
  * !BoundTextField - contains a JTextField for the input of the user.
  * !BoundComboBox - contains a JComboBox for the input of the user.
 * The only difference in the tree classes is the GUI used for input of data. One should extend these classes and implement the corresponding methods. 
 * All of the four classes mentioned above are abstract. If one wants to have a different UI for input of data they should extend the !BoundBaseControl class. Otherwise extend one of the other three.
 * UML: 
[[Image(source:/trunk/sophie2-platform/doc/uml-design-diagrams/Bound-Controls.png)]]
 * Usage:
  * In order to have a bound control one should implement one of the three !BoundSpinner, !BoundTextField or !BoundComboBox.
  * Implement the methods:
   * protected abstract String computeContents(); - this method should return the String representation of the data value stored in the 'model'.
   * protected abstract void submitData(String input); - this method should assign the new data value for the model.
   * protected abstract Validation validate(String fieldString); - this method should validate the user input represented by 'fieldString'.
   * NOTE: Since the JComboBox uses an array of Objects to display and choose from, for the implementation of !BoundComboBox one should also implement 'protected abstract String[] computeModelItems()' which should return the items in the combo box.
  * In order to create a bound control different from these described above, one should also implement  'protected abstract JComponent computeDataInputUI()' to return the graphical representation of the component which is used for user input.


= Implementation =
 
 * For more information see documentation and classes locate at: 'net.asteasolutions.veda.gui.util.boundcontrols'
 * For Unit tests and Demo see 'net.asteasolutions.veda.gui.util.boundcontrols' and 'net.asteasolutions.veda.gui.util.demo'

= Log =
[[Include(wiki:BASE_BOUND_CONTROLS_R0_LOG)]]