Configuring the table component
Identifies the rendering information necessary to display a table.
Introduces the different ways to configure table display.
Describes display customization using CSS.
Describes how to use the API to configure the table view and table interactor of a table component.
Describes how to load a project file that combines rendering style sheets and a data source.
Describes how to modify the rendering of a table.
Introduction
The table component can be customized either through a CSS configuration file or through the API, the easiest and preferred way being the CSS configuration. You also have the possibility to load a project file which combines the CSS configuration and the table data.
You can customize the table view with properties such as background, grid color, cell and header renderer. You can also customize the table adapter and the way business objects are represented.
Configuring the table component through a CSS file
You can customize the following features in a CSS file:
Table view
Background color
Grid color
Show/hide grid
Show/hide horizontal lines
Show/hide vertical lines
Row margin
Column margin
Fixed column count
Auto resize mode
Selection mode
Reordering
Header renderer
Default renderer
Table adapter
Filter
Accepted class
Excluded classes
Table row factory
Table column
Header renderer
Cell renderer
Table row
Row height
Table cell
Table controller
View interactor
Header interactor
Cell interactor
Object interactor
How to load a CSS file in a table component
The table configuration can be split across several CSS files that you can load by:
Specifying a project file that lists the style sheets and the data file to be loaded in the component (see
Loading a project file). The project file will be as follows:
<?xml version="1.0"?>
<tgo xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation = "ilog/cpl/schema/project.xsd"
style="configurationFile1.css,configurationFile2.css">
<datasource javaClass="ilog.tgo.datasource.IltDefaultDataSource"
fileName="table.xml"/>
</tgo>
If the settings in two of the CSS files disagree, the effect depends on the order of the filenames in the list: the last file mentioned takes precedence over the first file.
Using the method
IlpTable.setStyleSheets as follows:
tableComponent = new IlpTable();
try {
tableComponent.setStyleSheets(new String[] {
myConfigurationFile1,myConfigurationFile2 });
} catch (Exception e) {
}
If the settings in the CSS files disagree, the effect depends on the order of the filenames in the list: the last file listed takes precedence over the first one.
How to configure a table component in a CSS file
The following example shows you how you can customize the table component itself. It is based on the CSS file located in
<installdir> /samples/table/styling/srchtml/table.css.htmlwhere <installdir> is the directory where you have installed JViews TGO.
The configuration in CSS is organized as a set of
rules that define properties.
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Table Component configuration
// Type: Table
//
// This is the main selector when customizing
// a table component. It identifies the
// sub-components that will be addressed in the
// CSS customization. In the Table Component, it
// is possible to customize the view, controller
// and adapter using CSS.
//
// List of available properties:
// - view: boolean
// - interactor: boolean
// - adapter: boolean
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Table {
view: true;
interactor: true;
}
The Table rule
This rule specifies the elements of the table component that will be customized. It contains Boolean flags that indicate whether some specific customizable properties are present. For example, the customization of the property adapter is not taken into account unless adapter: true is declared in the Table rule.
This feature provides powerful cascading possibilities. You can define adapter customizations in a default CSS file and turn them on or off in another CSS file.
The following CSS properties affect the table component:
CSS properties of the table component
CSS property | Type of value | Default | Usage |
view | boolean | false | Enables the customization of the table view. |
interactor | boolean | false | Enables the customization of the table interactors. |
adapter | boolean | false | Enables the customization of the table adapter. |
The View rule
This rule specifies the properties that are applied to the table view.
The following CSS properties affect the appearance of the table view:
CSS Properties of the table view
CSS property | Type of value | Default | Usage |
autoResizeMode | | AUTO_RESIZE_OFF | Resize mode of the table. Possible values are: AUTO_RESIZE_OFF AUTO_RESIZE_ALL_COLUMNS AUTO_RESIZE_LAST_COLUMN. |
background | Color | null | Color to be used in the background of the table view. By default, the color is gray. |
gridColor | Color | null | Color to be used for the table grid. |
showGrid | Boolean | true | Determines whether the grid is displayed or not. |
showHorizontalLines | Boolean | true | Determines whether the grid horizontal lines are displayed or not. |
showVerticalLines | Boolean | true | Determines whether the grid vertical lines are displayed or not. |
rowMargin | Integer | 1 | Height in pixels of the margin between each row. |
columnMargin | Integer | 1 | Width in pixels of the margin between each column. |
reorderingAllowed | Boolean | true | Determines whether the user is allowed to reorder the columns of the table. |
fixedColumnCount | Integer | 0 | Defines the number of fixed columns. |
headerRenderer | | | The renderer used to perform the graphic representation of the headers of the table columns. |
defaultRenderer | | | The renderer used to perform the graphic representation of the table cells. |
selectionMode | | MULTIPLE_OBJECTS_SELECTION | Selection mode of the table. Possible values are: EMPTY_SELECTION SINGLE_OBJECT_SELECTION MULTIPLE_OBJECTS_SELECTION SINGLE_ATTRIBUTE_SELECTION MULTIPLE_ATTRIBUTES_SELECTION SINGLE_CELL_SELECTION MULTIPLE_CELLS_SELECTION |
How to configure a table view in a CSS file
Prior to configuring the table view, you need to configure the table component so that the view configuration is enabled:
Table {
view: true;
}
Then, you can customize the view properties in the View rule as illustrated by the following code extract. Refer to
The CSS specification in the
Styling documentation for details about the CSS syntax.
View {
reorderingAllowed : true;
autoResizeMode : AUTO_RESIZE_OFF;
selectionMode : MULTIPLE_OBJECTS_SELECTION;
fixedColumnCount: 1;
}
Refer to
IlpViewRenderer for more information.
The Interactor rule
This rule specifies the properties that are applied to the table controller. The following CSS properties affect how the table component handles mouse and keyboard events:
CSS Properties of the table interactor
Property name | Type | Default value | Usage |
viewInteractor | | | Defines the interactor that handles events in the view. |
headerInteractor | | | Defines the interactor that handles events in the table header. |
How to configure a table interactor in a CSS file
Prior to configuring the table interactor, you need to configure the table component so that the interactor configuration is enabled:
Table {
interactor: true;
}
After that, you can customize the each interactor property in the Interactor rule as illustrated by the following code extract. Refer to
The CSS specification in the
Styling documentation for details about the CSS syntax.
Interactor {
viewInteractor: @+viewInt;
headerInteractor: @+headerInt;
}
Subobject#viewInt {
class: 'ilog.cpl.table.interactor.IlpDefaultTableViewInteractor';
}
Subobject#headerInt {
class: 'ilog.cpl.table.interactor.IlpDefaultTableHeaderInteractor';
}
The behavior of the view interactor is determined by the actions that are associated with user gestures and keystrokes. This behavior can also be customized through CSS. You can also configure a pop-up menu to be displayed in the table view or table header. For more information about interactor customization, refer to
Interacting with the table view and
Interacting with the table cells.
For more information, refer to
IlpInteractorRenderer.
The Adapter rule
This rule controls the configuration of the table adapter. The table adapter is responsible for converting the business objects in the data source to representation objects (table rows) in the table component. It provides the following features:
Filtering: applies a filter so that business objects currently in the data source are not mapped to representation objects in the table component.
Accepted class: defines a specific class of business objects to be displayed in the table.
Excluded classes: defines a list of business classes whose business objects will not be displayed in the table.
These table adapter features can be customized through CSS using the following properties:
CSS properties of the table adapter
Property name | Property type |
filter | ilog.cpl.util.IlpFilter |
acceptedClass | String |
excludedClasses | |
representationObjectFactory | ilog.cpl.table.IlpTableRowFactory |
How to configure a table adapter in a CSS file
Prior to configuring the adapter, you need to configure the table component so that the adapter configuration is enabled:
Table {
adapter: true;
}
After that, you can customize each adapter property in the Adapter rule as illustrated by the following code extract. Refer to
The CSS specification in the
Styling documentation for details about the CSS syntax.
Adapter {
filter: @+tableFilter;
acceptedClass: ’ilog.tgo.model.IltNetworkElement;
representationObjectFactory: @+repObjFactory;
}
Subobject#tableFilter {
class: MyTableFilter;
}
Subobject#repObjFactory {
class: MyRepresentationObjectFactory;
}
How to programmatically configure a table adapter using CSS
You can programmatically modify the CSS configuration of the default table adapter (
IlpTableListAdapter) by using mutable style sheets through the
IlpMutableStyleSheet API.
Important The mutable style sheet is set to the adapter as a regular style sheet and is cascaded in the order in which it has been declared.
To use mutable style sheets:
1. Get the mutable style sheet.
You access the mutable style sheet through the getMutableStyleSheet() method in the table adapter API:
IlpMutableStyleSheet mutable = adapter.getMutableStyleSheet();
This method automatically registers the mutable style sheet in the adapter. You can manually instantiate an object of the class
IlpMutableStyleSheet and register it yourself through the
setStyleSheet() API:
IlpMutableStyleSheet mutable = new IlpMutableStyleSheet(adapter);
try {
adapter.setStyleSheets(new String[] { mutable.toString() });
} catch (Exception x) {
x.printStackTrace();
}
2. Set the CSS declarations.
Once you have the mutable style sheet, you can set the declarations you want:
mutable.setDeclaration("#myObjectId", "expansion", "NO_EXPANSION");
This creates the following CSS declaration into the mutable style sheet:
#myObjectId {
expansion: NO_EXPANSION;
}
3. Register the mutable style sheet.
The mutable style sheet should be set as a regular style sheet for the adapter using the setStyleSheet() method:
try {
adapter.setStyleSheets(new String[] { mutable.toString() });
} catch (Exception x) {
x.printStackTrace();
}
4. Set and update the CSS declarations.
The mutable style sheet can be modified even after being registered to the adapter:
// Update the expansion type for 'myObjectId'
mutable.setDeclaration("#myObjectId", "expansion", "IN_PLACE");
// Add a new declaration
mutable.setDeclaration("#myOtherId", "expansion", "IN_PLACE");
NOTE Like any style sheet, the mutable style sheet is lost when the setStyleSheet() API is invoked and a new set of style sheets is applied to the adapter.
How to customize the mutable style sheet
Reapplying a CSS configuration may be a heavy task, as the adapter may be forced to review filters, origins, recreate representation objects, and so on. It is important to use the mutable style sheet with care and to customize it properly to reapply the CSS wisely. To do so, there are two methods available in the
IlpMutableStyleSheet API:
setUpdateMask() and
setAdjusting().
1. setUpdateMask()
This method controls what should be recustomized once a declaration of the mutable style sheet has been updated. The CSS configuration of the adapter is divided into two parts: adapter customization and representation object customization.
The adapter customization handles the origins, filters, and so on:
Adapter {
origins[0]: id0;
origins[1]: id1;
showOrigin: true;
filter: @+myFilter;
}
The representation object customization handles the expansion type of a representation object:
#myObjectId {
expansion: IN_PLACE;
}
The accepted values for setUpdateMask() are:
IlpStylable.UPDATE_COMPONENT_MASK : Only the adapter part is recustomized.
IlpStylable.UPDATE_OBJECTS_MASK : Only the representation object part is recustomized.
IlpStylable.UPDATE_ALL_MASK : Bot the adapter and representation object parts are recustomized.
IlpStylable.UPDATE_NONE_MASK : Nothing is recustomized.
For example, if you update the expansion type of a representation object through the mutable style sheet, it is recommended that you set the update mask to UPDATE_OBJECTS_MASK as there is no need to reapply the CSS configuration for the adapter part:
mutable.setUpdateMask(IlpStylable.UPDATE_OBJECTS_MASK);
mutable.setDeclaration("object", "expansion", "IN_PLACE");
2. setAdjusting()
This method is used when a series of declarations must be applied to the mutable style sheet. When the method is set to true, the mutable style sheet puts all the calls to setDeclaration() into a queue. When the method is set back to false, all the queued declarations are processed in a batch:
mutable.setAdjusting(true);
mutable.setDeclaration("#myObjectId", "expansion", "IN_PLACE");
mutable.setDeclaration("#myOtherId", "expansion", "IN_PLACE");
mutable.setAdjusting(false);
Configuring the table component through the API
For details of the classes involved in the architecture of the table component, see
Filtering rows.
The following example shows how to configure the table view (
IlpTableView) through the API. For details on programming the individual services, see
Table component services.
How to configure the table view with the API
IlpTableView view = table.getView();
// Setting the selection mode
view.setSelectionMode(ListSelectionModel.SINGLE_OBJECT_SELECTION);
// Setting the table cell renderer
view.setDefaultRenderer(new MyTableCellRenderer());
// Setting the grid color
view.setGridColor(Color.blue);
The following example shows how to configure the table interactor through the API. For details, see
Interacting with the table view.
How to configure the table interactor with the API
// Create the table, and retrieve the view interactor
IlpTable tableComponent = new IlpTable()
IlpViewInteractor viewInteractor = tableComponent.getViewInteractor();
// Create a Swing action
// We assume the MyAction class is defined elsewhere
Action myAction = new MyAction();
// Double-clicking the left mouse button will trigger myAction
viewInteractor.setGestureAction(IlpGesture.BUTTON1_DOUBLE_CLICKED,myAction);
The following example shows how to configure the table adapter through the API. See
Table component services for details on programming the individual services.
How to configure the table adapter with the API
IlpListAdapter adapter = table.getAdapter();
// Accepted class
// (it is the same as adapter.setAcceptedClass)
table.setAcceptedClass(IltNetworkElement.GetIlpClass());
// Setting the filter
IlpFilter myFilter = new MyFilter();
// (it is the same as adapter.setFilter(myFilter)
table.setFilter(myFilter);
// Table Row Factory
IlpTableRowFactory myRowFactory = new MyTableRowFactory();
adapter.setRepresentationObjectFactory(myRowFactory);
Loading a project file
A project is a combination of style sheets that supply rendering information and a data source that supplies the data to be represented in a table component. A project is saved as an XML file with extension .itpr.
Loading a project file is the recommended way to configure a graphic component in Java™ as it is the fastest.
How to load a project file into a table component
The following code sample shows how to load a project file into a table component, using the method setProject.
IlpTable table = new IlpTable();
table.setProject(new URL("file:project.itpr");
The project is represented by the
IlpTGOProject class, included in the package
ilog.cpl.project. When a new project is created, the style sheet and data source are both null.
How to create a new project for the table component
The following code sample shows how to create a new project file by setting the style sheets and data source, then saving the project.
IlpTGOProject project = new IlpTGOProject();
project.setStyleSheet(new URL("file:example.css");
IltDefaultDataSource dataSource = new IltDefaultDataSource();
dataSource.setFileName("data.xml");
project.setDataSource(dataSource);
project.write(new URL("file:example.itpr");
Customizing column headers and rows
The table component uses a default renderer to render the column header (an instance of
IlpTableHeaderRenderer).
This renderer is based on the CSS configuration, which means that it uses the properties defined in the cascading style sheets for the business objects, the attributes, and the table component itself.
How to modify the table column renderer
To modify the rendering of the table, you can do one of the following:
1. Replace the default renderer by another one using the method setHeaderRenderer.
NOTE The Swing mechanism that allows you to associate a specific renderer with instances of a specific class in the table model is disabled.
2. Modify the JViews TGO default properties.
How to modify the default properties of a table
To modify the JViews TGO default properties in a table, create a custom CSS file and load it in your table component using the method IlpTable.setStyleSheets.
IlpTable tableComponent = new IlpTable();
String[] css = new String[] { "table.css" };
try {
tableComponent.setStyleSheets(css);
} catch (Exception e) {
}
For a description of the properties that you can use in a CSS file to modify the rendering of the table header and of the table rows, refer to
Customizing table column headers and rows.
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.