OpenSwing Framework

# OpenSwing Components

SourceForge.net Home page JAllinOne More documentation

Inserisci i termini di ricerca Invia modulo di ricerca

### 5. Presentation tier development

Presentation layer includes gui development, presentation logic and data retrieval logic. In this chapter all this topics will be described.

## 5.1 Frame/Internal Frame development

OpenSwing allows gui development based on several solutions: thare are no constraints on graphics controls usage inside the applications. It can be possible to create applications based on javax.swing.JFrame and/or javax.swing.JInternalFrame classes.

In addition, OpenSwing framework provides some generic components that can be adopted to realize applications based on an MDI front-end (Multiple Document Interface).

# 5.1.1 MDI Environment

An MDI environment is available with OpenSwing; this feature is based on org.openswing.swing.mdi. client.MDIFrame class. This class represents the main application window (derived form JFrame); inside it user can show internal frames, based on org.openswing.swing.mdi.client.InternalFrame class (derived from JInternalFrame).

The interface org.openswing.swing.mdi.client.MDIController is passed as argument to MDIFrame class and it is used to define the MDI frame behaviour; the interface declares the following methods:

- public void afterMDIcreation(MDIFrame frame) callback called after MDI frame creation; it can be overrided to customize the MDI frame content
- public String getMDIFrameTitle() define the application title
- public int getExtendedState() define if the application must be maximized at startup time
- public String getAboutText() text showed in the About window; it can contain HTML based text: in this case it must begin with "<html>" text
- public String getAboutImage() image name used to show an image in the About window; this method will show the image only if it returns a not null value; window size is autoset according to the imahe dimensions. By clicking over the image, the About window will be closed..

- public void stopApplication() callback called when the application must be closed
- public boolean viewChangeLanguageInMenuBar() define if a "change language" menu item must be showed in the "File" menu
- public ArrayList getLanguages() define the list of languages supported by the application, expressed as a list of org.openswing.swing.internationalization.java.Language objects
- public boolean viewLoginInMenuBar() define if a "change user" menu item must be showed in the "File" menu; the method returns false if the application does not require any login
- public JDialog viewLoginDialog(JFrame parentFrame) return a dialog window for user login; the method can return null if the application does not require any login. OpenSwing provides a default login window, based on LoginDialog class, that optionally allows to: store account in local file system ("Store Account" check-box), select language to use, specify each label/button show in login dialog and manage encrypt password.

- public boolean viewFunctionsInTreePanel() define if the application menu must be showed as a tree in an internal frame anchored to the left side of the MDI frame. The tree contains on the top a find input field to search an application feature in the tree menu. To set focus inside this input field user can press F3 key from any place
- public boolean viewFunctionsInMenuBar() define if the application menu must be showed in the menu bar in the top of the MDI frame. Menu items will be inserted between "File" menu and "Window" and "Help" menu, which are always visible
- public ClientFacade getClientFacade() return an instance of ClientFacade interface, that contains all methods that can be called from the application menu items: when user select an item from the application menu, the framework will call via reflection the corrisponding method defined in ClientFacade implementation class. The corrisponding method must be public and must be without any argument or with one String argument that represents the function identifier.
- public DefaultTreeModel getApplicationFunctions() list of application functions, represented as a tree model. This items will be reported as is in the tree menu and in the menubar. Each tree node must be an object of type org.openswing.swing.mdi.java.ApplicationFunction
- public boolean viewOpenedWindowIcons() define if a buttons panel must be showed in the bottom of the MDI frame; the buttons are related to internal frames currently opened; user can switch an internal frame to front by clicking into the corresponding button. By clicking with the right mouse button, a popup menu is showed; by means of this popup menu user can reduce to icon the corresponding internal frame or close it.

MDIFrame class is a singleton class: it can be directly called from any client-side place, by means of MDIFrame.getInstance() static method.

To access to ClientFacade implementation class there exist a method in MDIFrame: getClientFacade() ; this method can be invoked from any client-side place.

To add internal frames to the MDI frame there exist a method in MDIFrame: add() ; this method is available in two versions: the first requires only one argument, the internal frame; the last requires the internal frame and a flag indicating if the internal frame must be maximized.

All internal frames added to MDI frame must extend org.openswing.swing.mdi.client.InternalFrame class.

Each time ad internal frame is added to MDIFrame class, its name is also added to "Window" menu and a button is added also to buttons panel in the bottom of the MDI frame (if this showing setting is enabled); by means of the menu item in "Window" menu related to the internal frame, used can move to front the internal frame or by clicking on the corresponding button in the buttons panel.

There are many properties in InternalFrame class: using them it i possible to create for instance modal internal frames, a unique instance of an internal frame, adding automatic save changes checking before closing it, etc.

# 5.1.2 Non MDI Frames

All base graphics controls, grid, tree, Form, lookup provided with OpenSwing can be used also without the MDI frame, i.e. without org.openswing.swing.mdi.client package usage. In this case all features linked to the MDIFrame class cannot be used (tree menu, menu bar, window menu, buttons panel, progress bar, etc).

## 5.2 Base graphics controls

OpenSwing provides many base graphics controls. All these graphics controls implements the same interface: org.openswing.swing.client.InputControl that declares some common properties:

- "attributeName" i.e. the attribute name of the value object related to the Form object connected to this graphics control (see Form paragraph); if a value object contains inner value objects, then it is possible to bind the controls to an attribute of an inner value object, by specifing the complete path from the outside attribute to the most inner attribute (e.g. "taskVO.taskCode", if the Form value object contains getTaskVO() method that returns the inner value object TaskVO and this one contains getTaskCode() method)
- "linkedLabel" label that can be linked to the graphics control whose text will be showed by the framework on saving form data when the graphics controls is declared mandatory and has no value inside it (see Form paragraph)
- "value" value currently showed inside the graphics control; data type differs according to graphics control type
- "canCopy" define if graphics control must preserve the value inside it when user is pressing copy button (se Form paragraph)
- "enabled" define if graphics control is currently enabled (this property is evaluated only if graphics control is not bind to a Form)
- "enabledOnInsert" define if graphics control must be enabled when Form binded to the control is switched to insert mode (see Form paragraph)
- "enabledOnEdit" define if graphics control must be enabled when Form binded to the control is switched to edit mode (see Form paragraph)
- "required" define if graphics control is mandatory, i.e. on saving Form content, each mandatory control is checked: if there exist a mandatory graphics control not filled then saving operation is interrrupted and a warning dialog is showed, indicating the list of mandatory controls (the list of linked labels text) not filled (see Form paragraph); if a graphics control is declared as mandatory and the control property ClientSettings.VIEW_MANDATORY_SYMBOL is set to "true" then a red "*" symbol is shoed on the right of the control, to represent that the graphics control is mandatory.
- "toolTipText" - define the tooltip text to set for the graphics control; this text will be automatically translated according to internationalization settings.
- textAlignment define the horizontal alignment of the text inside an input control (left, center or right)

In the following table are reported all base graphics controls.

Graphics control | Description
Text label | org.openswing.swing.client.LabelControl Text label is automatically translate according to internationalizatin settings currently setted.
Multi-line text label | org.openswing.swing.client.MultiLineLabelControl Multi-line text label, whose text is automatically translated according to internationalizatin settings currently setted.

Text input field

org.openswing.swing.client.TextControl

Text input field has several additional properties:

• "maxCharacters" maximum number of characters allowed

• "trimText" define if text must be trimmed, i.e. if spaces characters at the left and on the right of text must be removed

• "upperCase" define if text is always expressed in uppercase

• "rpadding" define if must be applied right padding on the text (additional spaces added on the right of the text until the text length is exactly uquals to "maxCharacters"); this property is useful when the graphics control is linked to a database field of type CHAR.

Multi-line text input field | org.openswing.swing.client.TextAreaControl This input field has one additional property: "maxCharactes" that defines the maximum number of characters allowed.

Numeric field

org.openswing.swing.client.NumericControl

Numeric input field has several additional properties:

• "maxCharacters" - maximum number of characters allowed

• "maxValue" maximum number allowed

• "minValue" minimum number allowed

• "decimals" maximim number of decimals

• "grouping" define if thousand symbol must be showed

Currency field

org.openswing.swing.client.CurrencyControl

This control extends NumericControl class, therefore it inherits all its properties, besides the followings:

- "currencySymbol" currency symbol

- "decimalSymbol" decimal symbol
- "groupingSymbol" thousand symbol

Currency, decimal and thousand symbols are always visible.

Date + calendar input field

org.openswing.swing.client.DateControl

Date+calendar input field has several additional properties:

- "dateType" define the content of graphics control: date (Consts.TYPE_DATE), hour (Consts.TYPE_TIME) or date+hour (Consts.TYPE_DATE_TIME)
- "dateFormat" define the date format; supported formats are: Resources.YMD, Resources.DMY, Resources.MDY or Resources.YDM
- "lowerLimit" e "upperLimit" define minimum and maximum allowed date respectively
- "separator"- define separator symbol between day, month and year
- "timeFormat" define time format used to show an hour; supported formats are: Resources.HH_MM or Resources.H_MM_AAA

To preset the date control content to the current date value, it can be used the shortcut key F1 (when the cursor is inside the date control).

Combo-box

org.openswing.swing.client.ComboBoxControl

The content of a combo-box control is defined starting from a domain (se domains paragraph). This input field has several additional properties:

- "domain" define the domain related to this control (i.e. the list of combo items)
- "domainId" define the domain identifier, by which the combo-box automatically retrieves the domain from ClientSettings class
- "nullAsDefaultValue" define if combo-box must be initialized with a null value (i.e. no item is selected at the beginning)
- "translateItemDescriptions" - define if items description must be translated

Check-box

org.openswing.swing.client.CheckBoxControl

Check-box control has the additional property "text" indicating the (optional) text that must be showed on the right of the check-box.

"allowNullValue" property allows to add to check-box a third optional state: null, i.e a check box can be selected, deselected and set to null.

Radio-button | org.openswing.swing.client.RadioButtonControl Radio button control has the additional property "text" indicating the (optional) text that must be showed on the right of the radio button.

Image control

org.openswing.swing.client.ImageControl

This control is a panel composed of (i) an image panel (classe org.openswing.swing.client.ImageControl . ImagePanel ), i.e. a scrollpane that shows an image and (ii) a button (optional) used to select an image from the local file system and show it in the image panel.

This input field has several additional properties:

- "autoResize" force the image panel dimension, so that it will have a width and height defined though "imageHeight" and "imageWidth" properties
- "imageWidth" set image width; this property is ignored if "autoResize" property is set to "true"
- "imageHeight" set image height; this property is ignored if "autoResize" property is set to "true"
- "fileFilter" allows to define the list of image formats supported in the window used to select an image from file system; the default setting is to allow the selection of images having file extension "gif" or "jpg"
- "showButton" define if the button for image selection is (in)visible; default value: "true"

ImageControl provides a utility method that can be used to listen ActionEvents fired by the selection button:

public void addActionListener(ActionListener listener)

by means of this method it is possible to capture the event of image selection: the property ActionCommand of ActionEvent argument contains the selected image path.

ImageControl is based on ImagePanel component. This component can be directly used instead of ImageControl if there is no need to link the image to a Form object.

ImagePanel provides some utility methods:

- public void setImage(byte[] image) set an image into the ImagePanel starting from a byte[]
- public void setImageAsStream(InputStream in) throws IOException set an image into the ImagePanel starting from an InputStream
- public byte[] getImage() give back the image currently showed in the image panel, as a byte[]
- public void setImageName(String imageName ) set an image into the ImagePanel starting from an image file name; the image file must reside in "images" subfolder.

FormattedTextControl | org.openswing.swing.client.FormattedTextControl A wrapper of javax.swing.JFormattedTextField. See Swing Javadoc about JFormattedTextField for more information.

ListControl

org.openswing.swing.client.ListControl

This component is a wrapper of a JList component and provides the same utility methods of JList.

A mandatory property of ListControl is the domain identifier, used to show as list items the domain's descriptions; when an item is selected the related domain code is returned.

The value of the attribute can be of any type (e.g. a Java data type, such as String, BigDecimal, etc) or could be a java.util.List that contains any data type, according to the list selection mode: ListSelectionModel.SINGLE_SELECTION_INTERVAL or another, respectively.

CheckBoxListControl

org.openswing.swing.client.CheckBoxListControl

This component is a wrapper of a JList component and provides the same utility methods of JList. Moreover, for each item is showed a check-box too, in order to select multiple items by selecting check-boxes.

A mandatory property of CheckBoxListControl is the domain identifier, used to show as list items the domain's descriptions; when an item is selected the related domain code is returned.

The value of the attribute can be of any type (e.g. a Java data type, such as String, BigDecimal, etc) or could be a java.util.List that contains any data type, according to the list selection mode: ListSelectionModel.SINGLE_SELECTION_INTERVAL or another, respectively.

Password input field

org.openswing.swing.client.PasswordControl

Password input field has several additional properties:

- "maxCharacters" maximum number of characters allowed
- "trimText" define if text must be trimmed, i.e. if spaces characters at the left and on the right of text must be removed
- "upperCase" define if text is always expressed in uppercase
- "rpadding" define if must be applied right padding on the text (additional spaces added on the right of the text until the text length is exactly uquals to "maxCharacters"); this property is useful when the graphics control is linked to a database field of type CHAR.

Progress bar control

org.openswing.swing.client.ProgressBarControl

This field is a read only control that shows a progress bar; it provides several additional properties:

- "minValue" minimum value allowed in the progress bar; default value = 0
- "maxValue" maximum value allowed in the progress bar; default value = 100
- "color" - i.e. the current used color
- "showAllBands" - flag used to determine how to color the progress bar: <code>true</code> to paint the bar with many colors, each band with its color, <code>false</code> to paint the bar with ony one color: the color related to the last matched band

The latter method is used when a programmer has defined some colored bands in the progress bar, through the method:

public final boolean addColoredBand(double minValue, double maxValue, Color color)

This method adds an interval [minValue,maxValue] and a color to use to paint that interval.

Combo-box multi column

org.openswing.swing.client.ComboBoxVOControl

The content of a combo-box control is defined starting from a list of value objects, retrieved through a ItemsDataLocator. More than one v.o. attributes can be mapped as combo item and these attributes can also be mapped to the container v.o. (i.e. the v.o. of the grid or of the Form). This input field has several additional properties:

- "nullAsDefaultValue" define if combo-box must be initialized with a null value (i.e. no item is selected at the beginning)
- "allColumnPreferredWidth" - the width of each column showed in the combo item
- "allColumnVisible" - define if all attributes defined in the combo v.o. will be visible in the combo item

This input field provides some mandatory methods that a programmer must invoke:

- "addCombo2ParentLink" - as for a lookup (see lookup section), define which combo attributes must be linked to container's v.o. attributes
- "setComboValueObjectClassName" - define the v.o. type associated to each combo item
- "setComboDataLocator"- define an ItemsDataLocator class that will be automatically invoked by the combo box to fetch items (i.e. the list of value objects)

Moreover, the input field allows to specify which combo's v.o. attributes to use to compose an item, through the following methods:

- "setPreferredWidthColumn" - the column width, for a specified attribute
- "setVisibleColumn"- define if the specified attribute must be mapped in the combo item.

List multi column

org.openswing.swing.client.ListVOControl

The content of a list control is defined starting from a list of value objects, retrieved through a ItemsDataLocator. More than one v.o. attributes can be mapped as item and these attributes can also be mapped to the container v.o. (i.e. the v.o. of the grid or of the Form). This input field has several additional properties:

- "nullAsDefaultValue" define if list must be initialized with a null value (i.e. no item is selected at the beginning)
- "allColumnPreferredWidth" - the width of each column showed in the item
- "allColumnVisible" - define if all attributes defined in the list v.o. will be visible in the item

This input field provides some mandatory methods that a programmer must invoke:

- "addList2ParentLink" - as for a lookup (see lookup section), define which list attributes must be linked to container's v.o. attributes
- "setListValueObjectClassName" - define the v.o. type associated to each item
- "setListDataLocator"- define an ItemsDataLocator class that will be automatically invoked by the list to fetch items (i.e. the list of value objects)

Moreover, the input field allows to specify which list's v.o. attributes to use to compose an item, through the following methods:

- "setPreferredWidthColumn" - the column width, for a specified attribute
- "setVisibleColumn"- define if the specified attribute must be mapped in the item.

The value of the attribute can be of any type (e.g. a Java data type, such as String, BigDecimal, etc) or could be a java.util.List that contains any data type, according to the list selection mode: ListSelectionModel.SINGLE_SELECTION_INTERVAL or another, respectively.

Link button

org.openswing.swing.client.LinkButton

A link, whose text can be translated according to internationalization settings. It is possible to define text color when mouse is over the link and it is possible to add an ActionListener to listen mouse clicks on the link. It provides some optional properties:

- "uri" - if filled, it contains an URI that will be automatically showed within the browser when user clicks on this link
- "labelAttributeName"- if filled, it allows to bind LinkButton to Form panel, in order to automatically set the link label starting from this attribute value
- "tooltipAttributeName" - if filled, it allows to bind LinkButton to Form panel, in order to automatically show a tooltip text for this link ; tooltipo text is setted starting from this attribute value
- "uriAttributeName"- if filled, it allows to bind LinkButton to Form panel, in order to automatically set the link URI to show when clicking on this link; URI is setted starting from this attribute value.

ClientSettings.DISABLED_INPUT_CONTROLS_ FOCUSABLE global property can be used to (do not) allow focus settings onto disabled input controls: when set to "true" all input controls (both enabled and disabled) are focusable, so also the content of a disabled control can be selected and copied; when set to "false" (default value) focus is not appliable to disable input controls, so focus will be moved only among editable components: disabled components are skipped when using TAB key to move focus.

## 5.3 Graphics controls container (Form)

The class org.openswing.swing.form.client.Form extends javax.swing.JPanel class, therefore it can be used as graphics controls container. This class analyzes all components inside it (including those nested within folder, splitpanes or jscrollpane added to the Form) and registers all recognized graphics controls.

Example:

###

# 5.3.1 Supported operation modes of Form

All graphics controls recognized and registered inside the Form are liable to the same operations, applied at every operation mode change.

The Form has 3 possible operation modes: insertion, editing, read only, that are identified by the following constants: Consts.INSERT, Consts.EDIT e Consts.READONLY. To switch from a mode to another, is available the method Form.setMode() . To retrieve the current operation mode of the Form is available the method Form.getMode() .

When the Form is switched to INSERT mode, all graphics controls will be cleaned out and the ones that has "enabledOnInsert" property set to "true" are enabled too. When the Form is switched to EDIT mode, all graphics controls having "enabledOnEdit" property set to "true" are enabled. When the Form is switched to READONLY mode, all graphics controls are disabled.

Graphics controls registration is automatically performed when the Form become visible. To postpone the controls recognition/registration activity or to re-execute it, two Form methods are available :

- public final void bind(InputControl comp) throws Exception used to register a single graphics control, that could be outside the Form panel, too.
- public final void unbind(InputControl comp) throws Exception used to unregister a single graphics control, that could be external to Form panel.

# 5.3.2 Buttons connected to Form

OpenSwing provides some buttons having a definite meaning (see Buttons paragraph); these buttons can be linked to the Form, through the following Form methods:

- public final void setInsertButton(InsertButton insertButton) by means of this method the insert button can be linked to the form; in this way, when the insert button is pressed, the Form switches to insert mode, all controls will be cleaned out and those controls that are declared as enabled on insert will be enabled.
- public final void setCopyButton(CopyButton copyButton) by means of this method the copy button can be linked to the form; in this way, when the copy button is pressed, the Form switches to insert mode, all controls will be cleaned out, except those declared as "duplicable" (which maintain the current value on them) and those controls that are declared as enabled on insert will be enabled.
- public final void setEditButton(EditButton editButton) - by means of this method the edit button can be linked to the form; in this way, when the edit button is pressed, the Form switches to edit mode and those controls that are declared as enabled on edit will be enabled..
- public final void setReloadButton(ReloadButton reloadButton) by means of this method the reload button can be linked to the form; in this way, when the reload button is pressed, the Form switches to read only mode, all controls will be disabled and data model linked to the Form will be reloaded and data just loaded will be set onto the graphics controls.
- public final void setSaveButton(SaveButton saveButton) - by means of this method the save button can be linked to the form; in this way, when the save button is pressed, the Form will attempt to store data and, if saving operation will be correctly performed, the Form switches to read only mode and all controls will be disabled.
- public final void setDeleteButton(DeleteButton deleteButton) by means of this method the delete button can be linked to the form; in this way, when the delete button is pressed, the Form will attempt to delete data and, if deleting operation will be correctly performed, the Form switches to read only mode and all controls will be disabled and cleaned out.
- public final void addGenericButton(GenericButton b) by means of this method a generic button can be linked to the form; in this way, the generic button will receive the same effects of the others buttons when operation mode is changed, that is, all generic buttons will be disabled on insert and edit modes and will be enabled in read only mode.
- public final void addLinkButton(LinkButton b) by means of this method a LinkButton can be linked to the form; in this way, LinkButton will receive the same effects of the others link/button when operation mode is changed, that is, all links will be disabled on insert and edit modes and will be enabled in read only mode.

A required property that must be set in the Form object is " functionId "; this property defines an identifier associated to the Form that the Form exploits to decide if insert/edit/delete buttons must be enabled or not when the operation mode is changed: the setEnable method of these buttons always checks if the buttons must be enabled, by verifing authorizations defined in ClientSettings for the specified functionId. In OpenSwing buttons authorizations are defined as a collection of <functionId, related buttons authorizations> and are stored inside ClientSettings object (see buttons authorization section).

# 5.3.3 Form data model

A Form object represent a collector of graphics controls; all these controls share the same model: the data model linked to the Form; this data model is based on org.openswing.swing.form.model.client. VOModel class and requires a value object declaration, through the method:

public final void setVOClassName(String voClassName)

Graphics controls added to a Form object are connected to attributes of the value object by means of graphics control "attributeName" property. Note that the "attributeName" property is not mandatory: a graphics control could not have setted that property if the control is not added to a Form, but rather to a simple JPanel (or another Container object). However, if graphics control has been added to a Form, then "attributeName" property must be set: by means of this property the Form (i) can correctly fill the graphics control when data model is loaded and (ii) can retrieve from graphics control the current value on it and update the corresponding attribute of the value object.

Form object provides some methods to synchronize data model and graphics controls:

- public final boolean push() update value object stored in the Form data model starting from values currently showed in graphics controls; push method executes the updating operation only if all graphics controls are in a valid state (i.e. all mandatory controls are filled and all controls have a value set on them)
- public final boolean pull(String attributeName) fill the graphics control identified by the specified attribute, as from the attribute value stored in the data model's value object.
- public final boolean pull() fill all graphics controls binded to the Form, as from the context of the data model's value object
- public final void reload() disable all graphics controls, set the Form to read only mode, reload the data model and fill all graphics controls according to the value object loaded.

# 5.3.4 Form Controller

A Form object requires a controller object linked to it; the controller class must be defined by the programmer and must extends org.openswing.swing.form.client.FormController class.

Data model, Form and Controller are the tern of M-V-C pattern (Model-View-Controller), on which the controller component acts as manager of events generated by the other two components (expecially for events fired by the Form).

To connect Form and Controller the programmer must invoke the method:

public final void setFormController(FormController formController)

This class provides a few methods that can be overriden by the programmer:

- public Response insertRecord(ValueObject newPersistentObject) throws Exception method automatically invoked by the Form on saving data (saving button has been pressed) when the Form is in insert mode: the value object passed as argument to the method is the value object stored in the Form data model and filled with all graphics controls values.

  By overriding this method, the programmer can exploit the value object passed as argument to carry on the saving operation.

  The method requires as return value a Response object (see response messages paragraph): the programmer must return one of the following objects: ErrorResponse in case of error or VOResponse in case of saving operation correctly completed; VOResponse object must contain the value object passed in the saving request, enhanced with possibile futher data, calculated during saving operation (such as a progressive determined by accessing the database).

  The Form object exploits the returned value object to re-set the data model and update graphics controls values.

  Note that before calling this method, the Form has already checked all controls to verify their validity state (by invoking Form.push method): this insure that the saving operation can be executed starting from a state where all mandatory graphics controls are correctly filled. If validity check has no success, then insertRecord method is not called.

- public Response updateRecord(ValueObject oldPersistentObject, ValueObject persistentObject) throws Exception method automatically invoked by the Form on saving data (saving button has been pressed) when the Form is in edit mode; two value objects are passed as arguments to the method: (i) the value object initially stored in the Form, before editing data in the form and (ii) the value object currently stored in the data model, that is filled with all graphics controls values.

  By overriding this method, the programmer could carry on the saving operation by exploiting the value object passed as argument and the initial value object, which is constructed from the record read from database before editing; the initial value object can be useful for example with web applications that are concurrently accessed: before updating the record in the database, values from the initial value object will be used to check if the record has been already changed from another client; only if the record is not yet changed, the updating operation is performed.

  The method requires as return value a Response object (see response messages paragraph): the programmer must return one of the following objects: ErrorResponse in case of error or VOResponse in case of saving operation correctly completed; VOResponse object must contain the value object passed in the saving request, enhanced with possibile futher data, calculated during saving operation (such as updating data, updating user, etc.).

  The Form object exploits the returned value object to re-set the data model and update graphics controls values.

  Note that before calling this method, the Form has already checked all controls to verify their validity state (by invoking Form.push method): this insure that the saving operation can be executed starting from a state where all mandatory graphics controls are correctly filled. If validity check has no success, then updateRecord method is not called.

- public Response deleteRecord(ValueObject persistentObject) throws Exception method automatically invoked by the Form on deleting data (delete button has been pressed) when the Form is in read only mode; the value object stored in the Form data model is passed as argument. By overriding this method, the programmer could carry on the deleting operation by exploiting the value object passed as argument.

  The method requires as return value a Response object (see response messages paragraph): the programmer must return one of the following objects: ErrorResponse in case of error or VOResponse in case of deleting operation correctly completed; VOResponse object must contain Boolean object, indicating the deleting result.

- public void createPersistentObject(ValueObject PersistentObject) throws Exception callback method automatically invoked by the Form when it is switched to insert mode data; the void value object just created and stored in the Form data model is passed as argument. By overriding this method, the programmer could fill some attribute values of the void value object to the purpose of pre-define some graphics controls.
- public void loadDataCompleted(boolean error) callback method automatically invoked by the Form when data model loading has been completed; data loading can be invoked by means of the reloadData method of the Form object. The reloadData method executes the loading in a separated thread, to the purpose of not blocking the application. By overriding this method, the programmer can intercept the data loading completed event.

  A programmer can override this method to insert instructions that start data loading operations for other components, such as grids or other panels not directly linked to the Form.

- public void afterReloadData() callback method automatically invoked by the Form when data model has been reloaded because the reload button has been pressed..
- public void afterEditData() - callback method automatically invoked by the Form when data updating operation has been correctly completed.
- public void afterInsertData() - callback method automatically invoked by the Form when data inserting operation has been correctly completed.
- public void afterDeleteData() - callback method automatically invoked by the Form when data deleting operation has been correctly completed.
- public Response loadData(Class valueObjectClass) a programmer must override this method to define retrieval logic that has to be used to fetch the value object to store in the Form data model. When the Form data model requires the value object (e.g. when Form.reloadData method is invoked or when user has pressed on reload button) it calls loadData method of the controller class. The method requires as return value a Response object (see response messages paragraph): the programmer must return one of the following objects: ErrorResponse in case of error or VOResponse in case of loading operation correctly completed; VOResponse object must contain the value object declared in the Form.

  The Form object exploits the returned value object to re-set the data model and update graphics controls values.

- public void modeChanged(int currentMode) callback method automatically invoked by the Form on changing the Form operation mode. A programmer can override this method to insert instructions about graphics controls (dis)abilitation, controls filling or forwarding the change mode event to other components (such as grids or other forms).
- public boolean beforeEditData(Form form) - callback method automatically invoked by the Form when the user has clicked on edit button. A programmer can override this method to stop operation mode switching according to custom policies, such as user authorization settings or other checks.
- public boolean beforeInsertData(Form form) - callback method automatically invoked by the Form when the user has clicked on insert button. A programmer can override this method to stop operation mode switching according to custom policies, such as user authorization settings or other checks.
- public boolean beforeDeleteData(Form form) - callback method automatically invoked by the Form when the user has clicked on delete button. A programmer can override this method to stop operation mode switching according to custom policies, such as user authorization settings or other checks.
- public void afterEditData(Form form) - callback method automatically invoked by the Form when the user has clicked on edit button. A programmer can override this method to intercept the operation mode switching; when this method is invoked, beforeEditData() method has been already invoked and the form mode has been already switched.
- public void afterInsertData(Form form) - callback method automatically invoked by the Form when the user has clicked on insert button. A programmer can override this method to intercept the operation mode switching; when this method is invoked, beforeInsertData() method has been already invoked and the form mode has been already switched.
- public boolean validateControl(String attributeName,Object oldValue,Object newValue) - callback method automatically invoked by the Form each time an input control is edited: this method define if the new just edited value is valid. Default behaviour: input control value is valid. A programmer can override this method to define if the current edited value is valid: by returning "false", the last valid value is resetted within the input control.

# 5.3.5 How to link parent grid control to the Form

The Form object provides two methods that allow to link the Form to the parent grid: in this way the binding created between grid and its detail Form allows to automatically reload data in the Form while selecting row in grid through the navigator bar. Other features are provided through these two methods:

- public final void linkGrid(GridControl grid, HashSet pkAttributes, boolean reloadModelWhen SelectingOnGrid) this method invoke the second method, by passing null as "navBar" argument (i.e. no navigator bar is linked to the Form)
- public final void linkGrid(GridControl grid, HashSet pkAttributes, boolean reloadModelWhen SelectingOnGrid,NavigatorBar navBar) "grid" argument allows to link parent grid and Form; the effect is that when a user clicks on a button of the grid's navigator bar, the Form is reloaded too, according to the selected row in grid. This is accomplished by means of the method loadData of the FormController: this method will be automatically invoked by the grid each time a row is selected on grid by means of the navigator bar. A programmer must insert into loadData method a logic to re-calculate primary key of the Form each time the method is invoked; the primary key can be retrieved by accessing the v.o. of the grid related to the current selected row (row in grid is always selected before calling loadData method).

"navBar" argument is related to the navigator bar to directly link to the Form (that must be different from the optional mavigator bar binded to the grid). This second navigator bar will fire events to the grid and, as consequence, the grid will invoke loadData method of the FormController.

"reloadModelWhenSelectingOnGrid" boolean argument allows to establish if Form loading is possible when using grid's navigator bar or only when using Form's navigator bar.

"pkAttributes" argument has another use: it forces the refresh of grid content after inserting/edit/deleting data in the Form. This HashSet must contain attribute names of the v.o. of the grid and of the Form: they are used to identify the unique row in grid having that values, i.e. to identify the row in grid related to the Form content. These feature is used for the three operations available in Form: (i) after inserting new data in the Form and saving them, a grid loading is performed to fetch only one row, the row related the the new Form data just saved. The primary key values identified by "pkAttributes" are used to fetch data for the grid by applying a filter based on that pk. The row just fetched is then appended to the grid content. (ii) after updating Form content and saving these changes, a grid loading is performed to fetch only one row, the row related the Form data just updated. The primary key values identified by "pkAttributes" are used to fetch data for the grid by applying a filter based on that pk. The row just fetched is then used to replace the old row in the grid whose content has been changed by the updating operation on the Form. (iii) ) after deleting Form content, the row related the Form data just deleted is identified and removed from the grid.

Thanks to this mechanism, it is no more needed to reload the entire content of the grid each time the Form is used to insert/update data (grid reloading was not a good solution because sorting and/or filtering conditions applied to grid could hide the new/updated rows being processed through the Form).

Demo4 sample shows how to link grid control to the Form.

## 5.4 Buttons

OpenSwing provides some buttons that assume a predefined meaning, having a standard behaviour if they are connected to grid or Form; these buttons are located in the package org.openswing.swing.client

Button | Description
Insert button | org.openswing.swing.client.InsertButton it should be connected to a grid or Form; when pressed, it disables itself and the edit, delete and copy buttons; it also enables save and reload buttons. A shortcut is associated to the button: CTRL+I. See ClientSettings.INSERT_BUTTON_KEY attribute for more info.

Copy button

org.openswing.swing.client.CopyButton - it should be connected to a grid or Form; when pressed, it disables itself and the edit, delete and insert buttons; it also enables save and reload buttons.

A shortcut is associated to the button: CTRL+C.
See ClientSettings.COPY_BUTTON_KEY attribute for more info.

Edit button

org.openswing.swing.client.EditButton - it should be connected to a grid or Form; when pressed, it disables itself and the insert, delete and copy buttons; it also enables save and reload buttons.

A shortcut is associated to the button: CTRL+E.
See ClientSettings.EDIT_BUTTON_KEY attribute for more info.

Reload button

org.openswing.swing.client.ReloadButton - it should be connected to a grid or Form; when pressed, it disables the save button and enables the edit, delete, insert and copy buttons if they was initially enabled.

A shortcut is associated to the button: CTRL+Z.
See ClientSettings.RELOAD_BUTTON_KEY attribute for more info.

Save button

org.openswing.swing.client.SaveButton - it should be connected to a grid or Form; when pressed, it disables itself (only if saving operation was correcly completed) and enables the edit, delete, insert and copy buttons if they was initially enabled.

A shortcut is associated to the button: CTRL+S.
See ClientSettings.SAVE_BUTTON_KEY attribute for more info.

Delete button | org.openswing.swing.client.DeleteButton - it should be connected to a grid or Form; when pressed, it perform the deleting operation. A shortcut is associated to the button: CTRL+D. See ClientSettings.DELETE_BUTTON_KEY attribute for more info.
Date export button | org.openswing.swing.client.ExportButton it should be connected to a grid to export in Excel/csv/XML/HTML/PDF/RTF format the whole resultset associated to the grid. A shortcut is associated to the button: CTRL+X. See ClientSettings.EXPORT_BUTTON_KEY attribute for more info.
Date import button | org.openswing.swing.client.ImportButton it should be connected to a grid to import record to grid from a document having Excel/csv format. A shortcut is associated to the button: CTRL+M. See ClientSettings.IMPORT_BUTTON_KEY attribute for more info.

Filtering/Sorting button

org.openswing.swing.client.FilterButton it should be connected to a grid; when pressed, it shows a dialog window that allows to define filtering and sorting conditions that must be apply to grid.

A shortcut is associated to the button: CTRL+F.
See ClientSettings.FILTER_BUTTON_KEY attribute for more info.

Navigation bar

org.openswing.swing.client.NavigatorBar it should be connected to a grid to move the selected row in grid: at the beginning of the resultset, one page backward, one row before, one row after, one page forwards and at the end of the resultset, respectively.

If it is connected to a Form panel, then it fires events to the grid and, as consequence of the grid to Form binding, also the Form content will be reloaded according to the new selected row in grid.

It is possible to hide page buttons by setting the property ClientSettings.SHOW_PAGINATION_BUTTONS_ON_NAVBAR to false.

Generic button

org.openswing.swing.client.GenericButton a programmer can create any number of generic buttons having a specified image and link them to a grid or to a Form object. In this case the abilitation state of the generic buttons will be defined by the operation mode of the grid/Form. When the grid/Form switches to read only mode then the connected generic buttons will be enabled; if the grid/Form switches to insert/edit modes then the connected generic buttons will be disabled, to the purpose of avoiding to open child windows or to execute custom logics activated through the buttons when the grid/Form is currently being modified.
GenericButton class provides "attributeName" optional property, in order to set button's text according to attribute value of Form value object.

All buttons described above can show an image, an image and a text or only a text. This behavior can be defined through ClientSettings.BUTTON_BEHAVIOR global property.

OpenSwing provides org.openswing.swing. mdi.client.DefaultToolBar class that is a special panel that includes all buttons described above: it is possible to initialize ClientSettings.MDI_TOOLBAR global property in order to add a unique toolbar at the top of the MDI environment and manage this toolbar by all internal frame components. A programmer can bind a GridControl or a Form panel to that toolbar, by using instructions such as:

grid.setInsertButton(ClientSettings.MDI_TOOLBAR.getInsertButton());

for each toolbar button to bind to the specific grid.

See "demo48" to see in detail how to use unique toolbar.

## 5.5 Lookup

A lookup is a component that consists of an input field (named code field) used to validate codes and a button (named lookup button) used to select a code from a set of available codes.

When the user digits a code in the code field, this code will be rewritten in uppercase and validated when focus is lost from the code field. Validation operation will be demanded to a dedicated class, named lookup controller (described below).

A code could be selected also by clicking on the lookup button (or by pressing F1 key) that will open:

• a modal dialog window that contains a lookup grid reporting a list of codes, or alternatively

• a modal dialog window that contains a tree, where its nodes represent codes to select, or alternatively

• a modal dialog window that contains a tree and a grid, where the selection of a tree node will reload the grid content, i.e. the list of codes (filtered by the selected tree node).

The selected code will automatically reported in the code field.

OpenSwing provides a lookup graphics control, that can be added to a Form object (or used outside a Form, too) and also a lookup column, that can be used in a grid.

# 5.5.1 Lookup graphics control

The lookup graphics control is based on the class org.openswing.swing . client.CodLookupControl , that implements InputControl interface, so that it provides all base properties of any other base graphics control. In addition, lookup graphics control also provides some other properties:

- "controllerClassName" an (optional) class name that represents a graphical functionality dedicated to the definition of codes selected in the lookup (i.e. for listing, inserting, editing, deleting of codes); this graphical functionality will be invoked by the lookup when the user clicks on "+" button (or by pressing F2 key); this button will be visible only if this property is setted.
- "maxCharacters" maximum number of characters alloed in the code field
- "allowOnlyNumbers" define if a code is a numeric code (i.e. only digits are allowed) or an alphanumeric code; this property is useful when the code is related to a database field of numeric type.
- "codBoxVisible" define if the code field is visible; the code field may be omitted when there is not any code to validate, such as when the code is an internal progressive that must not be showed.
- "lookupButtonVisible" define if the lookup button is visible; the button may be omitted when you want to force the code validation, without selecting it from a list of codes.
- "enableCodBox" define if the code field is enabled; code field could be disabled when the field is used to show a description that must not be validated but only selected by means of lookup button.
- "autoCompletitionWaitTime" - wait time (expressed in ms) before showing code auto completition feature for lookup controls; default value: ClientSettings.LOOKUP_AUTO_COMPLETITION_WAIT_TIME ( = -1, i.e. do not enable auto completition)

# 5.5.2 Lookup column

It offers the same features described for lookup graphics control; this type of column will be further described in "Grid columns" paragraph.

# 5.5.3 Lookup Controller

When defining a lookup (both a graphics control and lookup column), you have to connect the lokoup to a lookup controller, through the method:

public final void setLookupController(LookupController controller)

A programmer must create an instance of org.openswing.swing.lookup.client. LookupController class. The tasks of this controller are to validate the code when the code field loses the focus and to retrieve a list of codes when the user clicks on the lookup button.

On validating a code or by selecting a code from the list of codes, the result is the same: a value object (named lookup value object) is stored inside the lookup controller; in the first case the value object is retrieved by the controller as result of code validation; in the second case the value object is retrieved from the list of codes, i.e. the grid containing the list of codes has a grid model composed of a list of lookup value objects.

When creating the lookup controller, a programmer must define the type of value object that the controller has to support, through the method:

public final void setLookupValueObjectClassName(String lookupValueObjectClassName)

When clicking on lookup button, the grid columns construction is automatically performed by the lookup controller, starting from the collection of attributes defined in the lookup value object: for each attribute in the lookup v.o., the controller will create a grid column having a column type compatible to the attribute type. A programmer can define further column properties through setter methods available in the controller and described below.

A controller allows to (optionally) define a mapping between lookup value object's attributes and attributes of the value object stored in the lookup container, i.e. the container on which the lookup is added.

In with way events like code validation or code selection from a list of codes can trigger attributes updating in a grid or in a Form object where the lookup is inserted. For example a programmer may insert a lookup graphics control in a Form and take advantage of the lookup events to fill (or to clean out) other graphics controls in the same Form.

To define a mapping between lookup v.o. attributes and container v.o. attributes, a programmer can invoke many times (one for each attribute to map) the controller method:

public final void addLookup2ParentLink(String lookupAttributeName,String parentAttributeName)

Sometimes it is useful to force code validation without to pass through losting focus on code field; to force a code validation a programmer can invoke the controller method:

public final void forceValidate()

The lookup controller allows to listen every event fired by the lookup, by adding the following lookup listener:

public final void addLookupListener(LookupListener listener)

This method requires to define an implementation for the interface LookupListener, having the following methods:

• public void codeValidated(boolean validated) this callback is called by the lookup when a code has been already validated and returns as argument the validation result

• public void codeChanged(ValueObject parentVO,Collection parentChangedAttributes) this callback is called by the lookup when the code has been changed; the code can change because the user has manually changed it from the code field or because the user has select another code starting from the lookup button

• public void beforeLookupAction(ValueObject parentVO) this callback is called by the lookup before starting validation code operation or before opening the window tha contains the list of codes (i.e. on pressing lookup button); this method is useful to pass any parameter to the business logic binded to the lookup that this logic requires to perform the code validation or to perform the retrieving of the list of codes

• public void forceValidate() this callback is called by the lookup when the validation code operation has been forced.

When defining a lookup, there is another method that a programmer must define:

public final void setLookupDataLocator(LookupDataLocator lookupDataLocator)

through this method a programmer can define the class dedicated to lookup data retrieving, i.e. this class has the task of forwarding a validation code operation and forwarding the retrieval of a list of codes (see "Data retrieval from a lookup" paragraph).

What to do when validating an incorrect code digited in the code field? there are three alternative actions that a lookup can perform:

- clear code field and, as consequence: clear lookup value object, update parent value object according to attributes mapping, generate lookup events
- restore the last valid code digited into the field and, as consequence, valid it again so that: the lookup value object will be filled according to that last code, update parent value object according to attributes mapping and generate lookup events. If there is not any last valid code, then an empty code will be setted, as for the first alternative
- mantain the invalid code within the code field and force focus in the code field so that the user can change the code starting from the value currently setted on it. Lookup is also marked as invalid, so saving operation is not allowed.

It is possible to define which action to perform through the "onInvalidCode" property in LookupController class; therefore it is possible to customize the lookup behaviour per single lookup. This property can assume three alternative values:

- LookupController.ON_INVALID_CODE_CLEAR_CODE
- LookupController.ON_INVALID_CODE_RESTORE_LAST_VALID_CODE
- LookupController.ON_INVALID_CODE_RESTORE_FOCUS

The default value for "onInvalidCode" property is defined through ClientSettings.ON_INVALID_CODE, so that it is possible to define the default behaviour for all lookups.

# 5.5.4 Data retrieval for a lookup

A lookup needs to define a class for data retrieval, used to validate code and to retrieve a list of value objects to populate the lookup grid. This class must extends the abstract class org.openswing.swing.lookup.client. LookupDataLocator .

OpenSwing provides a default implementation of this abstract class: org.openswing.swing.lookup.client. LookupServerDataLocator . This implementation forwards data retrieval to server-side classes, remotelly invokoed through ClientUtils.getData method, i.e. an HTTP request is send to a java servlet that will dispatch the request to a specific class dedicated to validation code operation or to retrieve a list of lookup value object to feed the lookup grid. This implementation has been created to work together with the server-side servlet org.openswing.swing.server.Controller (see "Server-side classes" paragraph).

A programmer can define his own implementation of LookupDataLocator interface, to the purpose of contacting server-side logic according to his needs, e.g. via RMI or using SOAP protocol.

<< Previous Chapter | Next Chapter >>

Documentation Download Spring integration Samples Tutorial Installation info Mailing lists Public forums Project Page

### Related Links

HSSF Log4J JCalendar Java DB Conn Pool

Licence | Contacts | ©2007 Mauro Carniel