wiki:BASE_BOUND_CONTROLS_R0
Last modified 11 years ago Last modified on 01/19/09 17:16:33

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.
  • 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:

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.
    • REMEMBER to provide a method to synchronize the model and validation with the corresponding data value.
Example: private void syncInputToModel(Object input) {
	                this.settingModel = true; 
	                String inputValue = (String)input;
	               
	                validation().set(validate(inputValue));
	                if(validation().get().getStatus().shouldSubmit()){
	                        submitData(inputValue);
	                }
	                this.settingModel = false;
	        }

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'. One can also see and test the bound controls manually by running BoundControlsDemoTest as a Java Application.
    • In order to test something that uses a bound control one should emulate a user input. For the different JComponents used methods differ a little.
      • for BoundSpinner - spinner().get().setValue(new Integer(input)) where input is an int value.
      • for BoundTextField - textField().get().setText(value) where value is a String.
      • for BoundComboBox - comboBox().get().setSelectedItem(value) where value is a String.
    • Please provide and explain here similar methods for components implemented after this revision.
  • Bound Controls Source Code
  • Bound Controls Unit Tests and Demo Code

Log

  • Analyzing : Pap - done (35 min)
    • Review: 2 by Tanya - 10min. It is incorrect. The analysis must cover what should be done only through the current revision. This analysis is for the whole task.
  • Analyzing 2: Peko - done (30 mins)
    • Review: 3.5 by Tanya -10m
  • Designing : Peko - 3.5h - done.
    • Review: 4 by Pap - 10m. OK
  • Implementing : Peko 3.5h
  • Implementing 2 : Peko 4h - done.
    • Review: 3.5 by Pavlina - 30 mins
  • Testing :

Comments

  • Bound Controls are satisfying for the time being.
  • BoundSpinner is not easily controllable and not automatically updated on user input. It inputs into the model when the UI control leaves its focus. Should be fixed in next revision by extending the BoundTextField to provide incrementing and decrementing buttons. This way we will have a fully customizable BoundSpinner.
  • We need a bound control that does not input directly into the model. For position field of a frame for example it will be annoying for the frame to move around the page while the user inputs data. --peko