Configuring the tree component

TGO > Programmers documentation > Graphic components > Tree component > Configuring the tree component

Identifies the rendering information necessary to customize a tree view.

Introduction

Introduces the different ways to configure tree component display.

Configuring the tree component through a CSS file

Describes display customization using CSS.

Configuring the tree component through the API

Describes how to configure the tree view, tree view interactor, and tree adapter of a tree component with the API.

Loading a project file

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

Customizing the rendering of tree nodes

Provides a link to further information on rendering tree nodes.

Introduction

The tree 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 tree data.

You can customize the tree view with properties such as background, cell renderer and selection look and feel. You can also customize the tree adapter and the way the business objects are represented.

Configuring the tree component through a CSS file

You can customize the following features in a CSS file:

Tree view

Selection look and feel

Background

Tree cell renderer

Row height

Scrolling on expand

Tree adapter

Filter

Comparator

Origins

Accepted classes

Excluded classes

Expansion strategy factory

Tree node factory

Tree nodes

Properties listed under Customizing tree nodes in the Styling documentation.

Tree controller

View interactor

Object interactor

You can customize the following features in a CSS file:

How to load a CSS file in a tree component

The tree 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="tree.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 IlpTree.setStyleSheets as follows:

treeComponent = new IlpTree();

try {

treeComponent.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 tree component in a CSS file

The following code represents an example of configuring a tree using CSS. It is based on the CSS file located in <installdir> /samples/tree/styling/srchtml/tree.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.

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

// Tree Component configuration

// Type: Tree

// The following list shows all possible properties for

// the tree component.

// - view : enables the tree view configuration

// - interactor: enables the interactor configuration

// - adapter: enables the adapter configuration

// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Tree {

view: true;

adapter: true;

}

View {

background: #FFFFDF;

selectionLookAndFeel: Highlight;

}

The Tree rule

This rule specifies the elements of the tree 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 Tree 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 tree component:

CSS properties of the tree component
CSS Property	Type of Value	Default	Usage
view	boolean	false	Enables the customization of the tree view.
interactor	boolean	false	Enables the customization of the tree interactors.
adapter	boolean	false	Enables the customization of the tree adapter.

The View rule

This rule specifies the properties that are applied to the tree view.

The following CSS properties affect the appearance of the tree view:

CSS properties of the tree view
CSS Property	Type of Value	Default	Usage
background	Color	null	Color to be used in the background of the tree view. If the value is null, the color of the active look-and-feel is used.
cellRenderer	TreeCellRenderer	IlpTreeCellRenderer	Renders the tree nodes.
scrollsOnExpand	boolean	true	When a node is expanded, this property determines whether or not the node scrolls up, so that the maximum number of descendants are visible. The default is true.
selectionLookAndFeel	int	HIGHLIGHT	Sets the way the selection is rendered to/manipulated by the end-user. Two possible values: HIGHLIGHT or CHECKBOX
toggleClickCount	int	2	Number of mouse clicks before a node expands or collapses. The default is 2.
rootVisible	boolean	false	Defines whether the root nodes in the tree are visible or not.
showsRootHandles	boolean	true	Defines whether the handles that enable nodes to be expanded by the user are visible or not.
rowHeight	int	-1	Defines the row height. If the value is -1, the row height depends on the tree node rendering. If the value is greater than 0, the tree node height corresponds to the value defined by the user.
expandsSelectedPaths	boolean	true	Defines whether the parent path of the selected node is expanded or not. If true, all the parents of the selected node are expanded, although they may not all be visible in the JTree. If false, the parent nodes are not expanded and thus not made visible in the JTree.

Refer to the class IlpViewRenderer in the Rogue Wave® JViews TGOJava API Reference Documentationfor more information on configuring the view in a tree component.

The Interactor rule

This rule controls the configuration of the tree view interactor. The tree view interactor is responsible for handling events that occur in the tree view. You can define an interactor for the tree view or specific interactors for the tree nodes.

CSS Properties of the Tree View Interactor
Property Name	Property Type
viewInteractor	ilog.cpl.interactor.IlpViewInteractor

How to configure a tree view interactor in a CSS file

Prior to configuring the view interactor, you need to configure the tree component so that the interactor configuration is enabled:

Tree {

interactor: true;

}

After that, you can customize the view interactor 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;

}

Subobject#viewInt {

popupMenuFactory: @+viewPopupMenuFactory;

action[0]: @+viewAction0;

}

Subobject#viewPopupMenuFactory {

}

Subobject#viewAction0 {

gesture: BUTTON2_CLICKED;

action: @=showDetailsAction;

}

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 tree view. Please refer to Interacting with the tree view and Interacting with the tree nodes for more information about interactor customization.

When the interactor renderer is enabled, you can also customize interactors for specific tree nodes using CSS selectors to set the value of property interactor. For more information, refer to IlpInteractorRenderer.

The Adapter rule

This rule controls the configuration of the tree adapter. The tree adapter is responsible for converting the business objects in the data source to representation objects (tree nodes) in the tree 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 tree component.

Comparator: specifies that the position of the objects in the tree will follow a comparison rule. In this way, it is possible, for example, to display tree nodes in alphabetical order.

Expansion strategy: defines how the objects will be loaded in the tree component, that is, either at initialization time or on demand, as the user interacts with the tree nodes.

Origins: defines which objects become root nodes in the tree.

Accepted classes: defines the list of business classes that are accepted by the tree adapter. Only the business objects that match one of these business classes will be mapped to representation objects by the tree adapter.

Excluded classes: defines the list of business classes that are excluded by the tree adapter. The business objects of these business classes will not be mapped to representation objects by the tree adapter.

Object Attribute Changed Events Filtering: applies a filter so that attribute value changes occuring in the business objects currently in the data source are not notified to the tree component. This allows you to fine tune the notifications that are sent to the tree regarding attribute value changes in the business objects present in the data source. If an attribute value change event is not important to your application needs or to the tree cell rendering, it can be discarded, improving the performance of your tree component.

These tree adapter features can be customized through CSS using the following properties:

CSS properties of the tree adapter
Property Name	Property Type
filter	ilog.cpl.util.IlpFilter
origins	list of object identifiers
comparator	java.util.Comparator
nodeFactory	ilog.cpl.tree.IlpTreeNodeFactory
expansionStrategyFactory	ilog.cpl.util.IlpExpansionStrategy Factory
acceptedClasses	list of IlpClass
excludedClasses	list of IlpClass
objectAttributeChangedFilter	ilog.cpl.util.IlpFilter

How to configure a tree adapter in a CSS file

Prior to configuring the adapter, you need to configure the tree component so that the adapter configuration is enabled:

Tree {

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: @+treeFilter;

comparator: @+treeComparator;

expansionStrategyFactory: @+treeExpStrategyFactory;

nodeFactory: @+treeNodeFactory;

objectAttributeChangedfilter: @+eventFilter;

origins[0]: ROOT1;

origins[1]: ROOT2;

}

Subobject#treeFilter {

}

Subobject#treeComparator {

}

Subobject#treeExpStrategyFactory {

}

Subobject#treeNodeFactory {

adapter: @adapter;

}

Subobject#eventFilter {

}

How to programmatically configure a tree adapter using CSS

You can programmatically modify the CSS configuration of the default tree adapter ( IlpContainmentTreeAdapter) 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 tree adapter API:

IlpMutableStyleSheet mutable = adapter.getMutableStyleSheet();

This method automatically registers the mutable style sheet into 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 to the adapter as a regular style sheet 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 tree component through the API

For details of the classes involved in the architecture of the tree component, see Architecture of the tree component.

For details about programming the individual services of a tree component, see Tree component services.

How to configure the tree view with the API

The following code sample shows how to configure the tree view ( IlpTreeView) through the API.

IlpTreeView view = tree.getView();

// Setting the selection mode

view.setSelectionLookAndFeel(IlpTreeView.HIGHLIGHT_SELECTION_LOOK_AND_FEEL);

// Setting the tree cell renderer

view.setCellRenderer(new MyTreeCellRenderer());

// Setting the background color

view.setBackground(Color.white);

How to configure the tree view interactor with the API

The following code sample shows how to configure the tree view interactor through the API. For details of this interactor, see Interacting with the tree view.

IlpTree tree = // ...

// Retrieve the view interactor

IlpViewInteractor viewInteractor = tree.getViewInteractor();

// Create an action

Action myAction = new MyAction();

// Clicking the 3rd mouse button will trigger myAction

viewInteractor.setGestureAction(IlpGesture.BUTTON3_CLICKED,myAction);

How to configure the tree adapter with the API

The following code sample shows how to configure the tree adapter ( IlpAbstractTreeAdapter) through the API.

IlpAbstractTreeAdapter adapter = tree.getAdapter();

// Setting the filter

IlpFilter myFilter = new MyFilter();

// (it is the same as tree.setFilter(myFilter)

adapter.setFilter(myFilter);

// Origin

List myOrigins = new ArrayList();

myOrigins.add(objectID_1);

myOrigins.add(objectID_2);

myOrigins.add(objectID_n);

// in this case we want to display the

// origins

boolean showOrigin = true;

adapter.setOrigins(myOrigins, showOrigin);

// Expansion Strategy Factory

// Usually the expansion strategy factory relies

// on the adapter to access the data source and to

// load/release objects

IlpExpansionStrategyFactory myExpFactory = new

MyExpansionStrategyFactory(adapter);

adapter.setExpansionStrategyFactory(myExpFactory);

// Tree Node Factory

IlpTreeNodeFactory myNodeFactory = new MyTreeNodeFactory();

adapter.setNodeFactory(myNodeFactory);

// Setting the object attribute value changed event filter IlpFilter

myEventFilter = new MyEventFilter();

adapter.setObjectAttributeChangedFilter(myEventFilter);

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 tree 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 tree component

The following code sample shows how to load a project file into a tree component, using the method setProject.

IlpTree tree = new IlpTree();

tree.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 tree 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 the rendering of tree nodes

The JViews TGO tree component renders instances of both user-defined and predefined business classes using a default tree cell renderer ( IlpTreeCellRenderer) that you can customize through style sheets. The default tree cell renderer uses CSS properties to define how each tree node will be represented.

For details on how to customize the rendering of tree nodes, see Customizing tree nodes.