org.openswing.swing.table.client
Class GridController

java.lang.Object
  extended byorg.openswing.swing.table.client.GridController
Direct Known Subclasses:
CustomGridControlController, LookupGridController

public class GridController
extends java.lang.Object

Title: OpenSwing Framework

Description: Grid Controller.

Copyright: Copyright (C) 2006 Mauro Carniel

This file is part of OpenSwing Framework. This library is free software; you can redistribute it and/or modify it under the terms of the (LGPL) Lesser General Public License as published by the Free Software Foundation; GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999 This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. The author may be contacted at: maurocarniel@tin.it


Constructor Summary
GridController()
           
 
Method Summary
 void afterDeleteGrid()
          Callback method invoked after deleting data when the grid was in READONLY mode (on pressing delete button).
 void afterEditGrid(GridControl grid)
          Callback method invoked after saving data when the grid was in EDIT mode (on pressing save button).
 void afterInsertGrid(GridControl grid)
          Callback method invoked after saving data when the grid was in INSERT mode (on pressing save button).
 void afterReloadGrid()
          Callback method invoked after data reloading (on pressing reload/cancel button).
 boolean beforeCopyGrid(GridControl grid)
          Callback method invoked on pressing COPY button.
 boolean beforeDeleteGrid(GridControl grid)
          Callback method invoked before deleting data when the grid was in READONLY mode (on pressing delete button).
 boolean beforeEditGrid(GridControl grid)
          Callback method invoked on pressing EDIT button.
 java.lang.Object beforeFilterGrid(java.lang.String attributeName, java.lang.Object value)
          Callback method invoked by grid when applying a quick filter condition or a filter condition from filter panel: before executing search it is possible to change filtering value passed as argument, by returning another value.
 boolean beforeInsertGrid(GridControl grid)
          Callback method invoked on pressing INSERT button.
 java.lang.Object beforeRetrieveAdditionalRows(java.lang.String attributeName, java.lang.String textToSearch)
          Callback method invoked by grid when attempting to search for the specified text in additional rows not yet loaded in grid: this method can be used to convert the text to search in the correct format, before grid executes the search and load additional data.
 void createValueObject(ValueObject valueObject)
          Callback method invoked when the user has clicked on the insert button
 Response deleteRecords(java.util.ArrayList persistentObjects)
          Method invoked when the user has clicked on delete button and the grid is in READONLY mode.
 void doubleClick(int rowNumber, ValueObject persistentObject)
          Callback method invoked when the user has double clicked on the selected row of the grid.
 void dragDropEnd()
          This message goes to DragSourceListener, informing it that the dragging has ended.
 boolean dragEnabled()
          Method called on beginning a drag event.
 void dragEnter()
          This message goes to DragSourceListener, informing it that the dragging has entered the DropSite.
 void dragExit()
          This message goes to DragSourceListener, informing it that the dragging has exited the DropSite.
 void dragOver()
          This message goes to DragSourceListener, informing it that the dragging is currently ocurring over the DropSite.
 void dropActionChanged()
          This method is invoked when the user changes the dropAction.
 boolean dropEnabled(java.lang.String gridId)
          Method called on firing a drop event onto the grid.
 void dropEnter()
          This method is invoked when you are dragging over the DropSite.
 void dropExit()
          This method is invoked when you are exit the DropSite without dropping.
 void dropOver(int row)
          This method is invoked when a drag operation is going on.
 void enterButton(int rowNumber, ValueObject persistentObject)
          Callback method invoked when the user has pressed ENTER button on the selected row of the grid.
 void exportGrid(ExportOptions exportOptions)
          Callback method invoked by grid when exporting data from grid.
 java.awt.Color getBackgroundColor(int row, java.lang.String attributeName, java.lang.Object value)
          Method used to define the background color for each cell of the grid.
 java.lang.String getCellTooltip(int row, java.lang.String attributeName)
           
 java.awt.Color getDeltaColor()
           
 int getDeltaRow()
           
 java.awt.Dimension getExportDialogSize(java.awt.Dimension dialogSize)
          Callback method invoked by grid before showing exporting dialog; this method can be overrided to redefine dialog size
 java.lang.String[] getExportingFormats()
          Callback method invoked by grid before showing exporting dialog; this method can be overrided to redefine document formats allowed for the grid
 java.awt.Font getFont(int row, java.lang.String attributeName, java.lang.Object value, java.awt.Font defaultFont)
          Method used to define the font to use for each cell of the grid.
 java.awt.Color getForegroundColor(int row, java.lang.String attributeName, java.lang.Object value)
          Method used to define the foreground color for each cell of the grid.
 java.lang.String getHeaderTooltip(java.lang.String attributeName)
           
 java.lang.Object getInitialQuickFilterValue(java.lang.String attributeName, java.lang.Object initialValue)
          Callback method invoked by grid before showing quick filter panel.
 Response insertRecords(int[] rowNumbers, java.util.ArrayList newValueObjects)
          Method invoked when the user has clicked on save button and the grid is in INSERT mode.
 boolean isCellEditable(GridControl grid, int row, java.lang.String attributeName)
           
 void loadDataCompleted(boolean error)
          Callback method invoked when the data loading is completed.
 void modeChanged(int currentMode)
          Callback method invoked each time the grid mode is changed.
 void rowChanged(int rowNumber)
          Callback method invoked when the user has selected another row.
 void selectedCell(int rowNumber, int columnIndex, java.lang.String attributedName, ValueObject persistentObject)
          Callback method invoked when a grid cell is selected.
 void setDeltaColor(java.awt.Color deltaColor)
          Set the background cell color used when deltaRow>0.
 void setDeltaRow(int deltaRow)
          Consente di definire la proprieta' che consente di definire un delta di righe colorate; valore di default: 0 (nessun delta).
 Response updateRecords(int[] rowNumbers, java.util.ArrayList oldPersistentObjects, java.util.ArrayList persistentObjects)
          Method invoked when the user has clicked on save button and the grid is in EDIT mode.
 boolean validateCell(int rowNumber, java.lang.String attributeName, java.lang.Object oldValue, java.lang.Object newValue)
          Callback method invoked each time a cell is edited: this method define if the new value is valid.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GridController

public GridController()
Method Detail

enterButton

public void enterButton(int rowNumber,
                        ValueObject persistentObject)
Callback method invoked when the user has pressed ENTER button on the selected row of the grid. Default behaviour: it calls doubleClick method.

Parameters:
rowNumber - selected row index
persistentObject - v.o. related to the selected row

doubleClick

public void doubleClick(int rowNumber,
                        ValueObject persistentObject)
Callback method invoked when the user has double clicked on the selected row of the grid.

Parameters:
rowNumber - selected row index
persistentObject - v.o. related to the selected row

selectedCell

public void selectedCell(int rowNumber,
                         int columnIndex,
                         java.lang.String attributedName,
                         ValueObject persistentObject)
Callback method invoked when a grid cell is selected.

Parameters:
rowNumber - selected row index
columnIndex - column index related to the column currently selected
attributedName - attribute name related to the column currently selected
persistentObject - v.o. related to the selected row

getBackgroundColor

public java.awt.Color getBackgroundColor(int row,
                                         java.lang.String attributeName,
                                         java.lang.Object value)
Method used to define the background color for each cell of the grid.

Parameters:
attributeName - attribute name related to the column currently selected
value - object contained in the selected cell
Returns:
background color of the selected cell

getForegroundColor

public java.awt.Color getForegroundColor(int row,
                                         java.lang.String attributeName,
                                         java.lang.Object value)
Method used to define the foreground color for each cell of the grid.

Parameters:
attributeName - attribute name related to the column currently selected
value - object contained in the selected cell
Returns:
foreground color of the selected cell

validateCell

public boolean validateCell(int rowNumber,
                            java.lang.String attributeName,
                            java.lang.Object oldValue,
                            java.lang.Object newValue)
Callback method invoked each time a cell is edited: this method define if the new value is valid. This method is invoked ONLY if: - the edited value is not equals to the old value OR it has exmplicitely called setCellAt or setValueAt - the cell is editable Default behaviour: cell value is valid.

Parameters:
rowNumber - selected row index
attributeName - attribute name related to the column currently selected
oldValue - old cell value (before cell editing)
newValue - new cell value (just edited)
Returns:
true if cell value is valid, false otherwise

getDeltaRow

public int getDeltaRow()
Returns:

setDeltaRow

public void setDeltaRow(int deltaRow)
Consente di definire la proprieta' che consente di definire un delta di righe colorate; valore di default: 0 (nessun delta).

Parameters:
deltaRow - proprieta' che consente di definire un delta di righe colorate

getDeltaColor

public java.awt.Color getDeltaColor()
Returns:
background cell color used when deltaRow>0

setDeltaColor

public void setDeltaColor(java.awt.Color deltaColor)
Set the background cell color used when deltaRow>0.

Parameters:
deltaColor - background cell color

insertRecords

public Response insertRecords(int[] rowNumbers,
                              java.util.ArrayList newValueObjects)
                       throws java.lang.Exception
Method invoked when the user has clicked on save button and the grid is in INSERT mode.

Parameters:
rowNumbers - row indexes related to the new rows to save
newValueObjects - list of new value objects to save
Returns:
an ErrorResponse value object in case of errors, VOListResponse if the operation is successfully completed
Throws:
java.lang.Exception

updateRecords

public Response updateRecords(int[] rowNumbers,
                              java.util.ArrayList oldPersistentObjects,
                              java.util.ArrayList persistentObjects)
                       throws java.lang.Exception
Method invoked when the user has clicked on save button and the grid is in EDIT mode.

Parameters:
rowNumbers - row indexes related to the changed/new rows
oldPersistentObjects - old value objects, previous the changes; it can contains null objects, in case of new inserted rows
persistentObjects - value objects related to the changed/new rows
Returns:
an ErrorResponse value object in case of errors, VOListResponse if the operation is successfully completed
Throws:
java.lang.Exception

deleteRecords

public Response deleteRecords(java.util.ArrayList persistentObjects)
                       throws java.lang.Exception
Method invoked when the user has clicked on delete button and the grid is in READONLY mode.

Parameters:
persistentObjects - value objects to delete (related to the currently selected rows)
Returns:
an ErrorResponse value object in case of errors, VOResponse if the operation is successfully completed
Throws:
java.lang.Exception

createValueObject

public void createValueObject(ValueObject valueObject)
                       throws java.lang.Exception
Callback method invoked when the user has clicked on the insert button

Parameters:
valueObject - empty value object just created: the user can manage it to fill some attribute values
Throws:
java.lang.Exception

loadDataCompleted

public void loadDataCompleted(boolean error)
Callback method invoked when the data loading is completed.

Parameters:
error - true if data loading has terminated with errors, false otherwise

rowChanged

public void rowChanged(int rowNumber)
Callback method invoked when the user has selected another row.

Parameters:
rowNumber - selected row index

afterReloadGrid

public void afterReloadGrid()
Callback method invoked after data reloading (on pressing reload/cancel button). The method is called ONLY if the operation is successfully completed.


beforeCopyGrid

public boolean beforeCopyGrid(GridControl grid)
Callback method invoked on pressing COPY button.

Returns:
true allows to go to INSERT mode (by copying data), false the mode change is interrupted

beforeEditGrid

public boolean beforeEditGrid(GridControl grid)
Callback method invoked on pressing EDIT button.

Returns:
true allows to go to EDIT mode, false the mode change is interrupted

beforeInsertGrid

public boolean beforeInsertGrid(GridControl grid)
Callback method invoked on pressing INSERT button.

Returns:
true allows to go to INSERT mode, false the mode change is interrupted

beforeDeleteGrid

public boolean beforeDeleteGrid(GridControl grid)
Callback method invoked before deleting data when the grid was in READONLY mode (on pressing delete button).

Returns:
true allows the deleting to continue, false the deleting is interrupted

afterEditGrid

public void afterEditGrid(GridControl grid)
Callback method invoked after saving data when the grid was in EDIT mode (on pressing save button). The method is called ONLY if the operation is successfully completed.


afterInsertGrid

public void afterInsertGrid(GridControl grid)
Callback method invoked after saving data when the grid was in INSERT mode (on pressing save button). The method is called ONLY if the operation is successfully completed.


afterDeleteGrid

public void afterDeleteGrid()
Callback method invoked after deleting data when the grid was in READONLY mode (on pressing delete button). The method is called ONLY if the operation is successfully completed.


modeChanged

public void modeChanged(int currentMode)
Callback method invoked each time the grid mode is changed.

Parameters:
currentMode - current grid mode

isCellEditable

public boolean isCellEditable(GridControl grid,
                              int row,
                              java.lang.String attributeName)
Parameters:
grid - grid
row - selected row index
attributeName - attribute name that identifies the selected grid column
Returns:
true if the selected cell is editable, false otherwise

getFont

public java.awt.Font getFont(int row,
                             java.lang.String attributeName,
                             java.lang.Object value,
                             java.awt.Font defaultFont)
Method used to define the font to use for each cell of the grid.

Parameters:
attributeName - attribute name related to the column currently selected
value - object contained in the selected cell
defaultFont - default font currently in used with this column
Returns:
font to use for the current cell; null means default font usage; default value: null

getHeaderTooltip

public java.lang.String getHeaderTooltip(java.lang.String attributeName)
Parameters:
attributeName - attribute name that identify a grid column
Returns:
tooltip text to show in the column header; this text will be automatically translated according to internationalization settings

getCellTooltip

public java.lang.String getCellTooltip(int row,
                                       java.lang.String attributeName)
Parameters:
row - row index in the grid
attributeName - attribute name that identify a grid column
Returns:
tooltip text to show in the cell identified by the specified row and attribute name; this text will be automatically translated according to internationalization settings

getInitialQuickFilterValue

public java.lang.Object getInitialQuickFilterValue(java.lang.String attributeName,
                                                   java.lang.Object initialValue)
Callback method invoked by grid before showing quick filter panel. It allows to reset the initial filter value to show within the quick filter panel: it is possible to change filtering value passed as argument, by returning another value.

Parameters:
attributeName - attribute name that identify the column just filtered
initialValue - initial value to show within the quick filter panel
Returns:
new couple of values to show as initial values within the quick filter panel

beforeFilterGrid

public java.lang.Object beforeFilterGrid(java.lang.String attributeName,
                                         java.lang.Object value)
Callback method invoked by grid when applying a quick filter condition or a filter condition from filter panel: before executing search it is possible to change filtering value passed as argument, by returning another value.

Parameters:
attributeName - attribute name that identify the column just filtered
value - current filtering value
Returns:
new value to use as filter condition

getExportDialogSize

public java.awt.Dimension getExportDialogSize(java.awt.Dimension dialogSize)
Callback method invoked by grid before showing exporting dialog; this method can be overrided to redefine dialog size

Parameters:
dialogSize - default dimension of exporting dialog
Returns:
size to set for exporting dialog

getExportingFormats

public java.lang.String[] getExportingFormats()
Callback method invoked by grid before showing exporting dialog; this method can be overrided to redefine document formats allowed for the grid

Returns:
list of available formats; possible values: ExportOptions.XLS_FORMAT, ExportOptions.CSV_FORMAT1, ExportOptions.CSV_FORMAT2, ExportOptions.XML_FORMAT, ExportOptions.XML_FORMAT_FAT, ExportOptions.HTML_FORMAT, ExportOptions.PDF_FORMAT, ExportOptions.RTF_FORMAT; default value: ClientSettings.EXPORTING_FORMATS

exportGrid

public void exportGrid(ExportOptions exportOptions)
Callback method invoked by grid when exporting data from grid.

Parameters:
exportOptions - options used to export data; these options can be programmatically changed, in order to customize exporting result

beforeRetrieveAdditionalRows

public java.lang.Object beforeRetrieveAdditionalRows(java.lang.String attributeName,
                                                     java.lang.String textToSearch)
Callback method invoked by grid when attempting to search for the specified text in additional rows not yet loaded in grid: this method can be used to convert the text to search in the correct format, before grid executes the search and load additional data.

Parameters:
attributeName - attribute name that identify the column used in search
Returns:
new value to use as filter condition

dragEnabled

public boolean dragEnabled()
Method called on beginning a drag event.

Returns:
true, dragging can continue, false drag is not allowed; default value: true

dropEnabled

public boolean dropEnabled(java.lang.String gridId)
Method called on firing a drop event onto the grid.

Parameters:
gridId - identifier of the source grid (grid that generate a draf event)
Returns:
true, drop is allowed, false drop is not allowed; default value: true

dragEnter

public void dragEnter()
This message goes to DragSourceListener, informing it that the dragging has entered the DropSite.


dragExit

public void dragExit()
This message goes to DragSourceListener, informing it that the dragging has exited the DropSite.


dragOver

public void dragOver()
This message goes to DragSourceListener, informing it that the dragging is currently ocurring over the DropSite.


dropActionChanged

public void dropActionChanged()
This method is invoked when the user changes the dropAction.


dragDropEnd

public void dragDropEnd()
This message goes to DragSourceListener, informing it that the dragging has ended.


dropEnter

public void dropEnter()
This method is invoked when you are dragging over the DropSite.


dropExit

public void dropExit()
This method is invoked when you are exit the DropSite without dropping.


dropOver

public void dropOver(int row)
This method is invoked when a drag operation is going on.