Configuring the table component

TGO > Programmers documentation > Graphic components > Table component > Configuring the table component

Identifies the rendering information necessary to display a table.

Introduction

Introduces the different ways to configure table display.

Configuring the table component through a CSS file

Describes display customization using CSS.

Configuring the table component through the API

Describes how to use the API to configure the table view and table interactor of a table component.

Loading a project file

Describes how to load a project file that combines rendering style sheets and a data source.

Customizing column headers and rows

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.html

where <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	IlpTableResizeMode	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	IlpTableHeaderRenderer	IlpTableHeaderRenderer	The renderer used to perform the graphic representation of the headers of the table columns.
defaultRenderer	IlpTableCellRenderer	IlpTableCellRenderer	The renderer used to perform the graphic representation of the table cells.
selectionMode	IlpTableSelectionMode	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	IlpViewInteractor	IlpDefaultTableViewInteractor	Defines the interactor that handles events in the view.
headerInteractor	IlpDefaultTableHeaderInteractor	IlpDefaultTableHeaderInteractor	Defines the interactor that handles events in the table header.

NOTE Events are only handled by the header interactor if the current view interactor is an IlpDefaultViewInteractor.

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 {

}

Subobject#headerInt {

}

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	list of IlpClass
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 {

}

Subobject#repObjFactory {

}

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.