Configuring the tree component through 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 TGO Java API Reference Documentation for 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 {
  class: 'ilog.cpl.interactor.IlpDefaultViewInteractor;'
  popupMenuFactory: @+viewPopupMenuFactory;
  action[0]: @+viewAction0;
}
Subobject#viewPopupMenuFactory {
  class: 'AlarmPopupMenuFactory';
}
Subobject#viewAction0 {
  class: 'ilog.cpl.interactor.IlpGestureAction';
  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 {
  class: MyTreeFilter;
}
Subobject#treeComparator {
  class: MyTreeComparator;
}
Subobject#treeExpStrategyFactory {
  class: MyTreeExpansionStrategyFactory;
}
Subobject#treeNodeFactory {
  class: MyTreeNodeFactory;
  adapter: @adapter;
}
Subobject#eventFilter {
  class: MyTreeEventFilter;
}

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:

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();
}
```
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;
}
```
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();
}
```
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().

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");
```
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);
```