Perforce JViews TGO Sample: Tree Component - Basic

Description

This sample shows how to use the basic features of the Perforce JViews TGO tree component.

How to Use the Sample

The sample shows a basic tree, with a few nodes representing network elements and the shelves, cards, ports, and LEDs they contain. The sample illustrates the representation of predefined JTGO business objects in the tree component, as well as the basic features provided by the tree.

The tree supports standard interaction for expanding and collapsing nodes, as well as multiple selection. Click a node to select it. Use the Shift key to select several adjacent nodes or Ctrl to select individual nodes. You will see the names of the selected nodes appear in the 'Current selection' area at the bottom of the screen. The JTGO tree component has two representations for selection: Highlight and Checkbox. To switch between the two modes use the 'Selection mode' list in the lower part of the sample window.

The sample also shows how to define custom behavior. Double-clicking any tree node shows a small dialog with some information about the associated business object. Right-clicking any node displays a contextual pop-up menu that allows you to set the selected nodes as roots of the tree. To reset the tree to its original state, right-click outside any node and select 'Reset root nodes' from the pop-up menu.

Using the 'Filter pattern' text field in the lower part of the window you can apply a simple filter to the tree. Type a text into the field, press Return, and only the nodes with names containing the given pattern are displayed. Note that a node will only be shown if its parent is also shown. Using '1' or '2' as the pattern gives the best results in this sample.

Finally, the sample shows how the look of the predefined business objects and the tree component can be customized by style sheets. You can select from a number of predefined style sheet files (each of which change a single aspect of the representation) using the 'Style sheet' list in the lower part of the screen.

How to Run the Sample as an Application

This sample can be run as an application. The installation directory contains an executable JAR file, tree-basic.jar, that allows you to execute the sample with a double click from a file browser. Note that if you are using Internet Explorer, you can open the installation directory and execute the JAR file from the browser. This technique may not work in other Web browsers.

Alternatively, you can run the sample application from the command line. First check that the Ant utility is properly configured. If not, see the instructions on how to configure Ant for Perforce JViews.

Then, go to the installation directory of the sample and type:

ant run

Topics Covered

• Initializing a JTGO application
• Creating a tree component
• Reading data from project XML file
• Sorting tree nodes
• Managing selection in a tree
• Showing a contextual pop-up menu
• Defining custom interactions
• Filtering tree nodes
• Changing the rendering of the tree and its nodes

Detailed Description

This sample shows how to create a JTGO tree component and use its basic features. The specific code of this sample is in the doSample method of basic.Main. It contains the following steps:

• Initialize JTGO.
  A JTGO application must be initialized using the static method ilog.cpl.IlpSystem.Init. This method must be called before any other JTGO code.
  You can pass the name of a deployment descriptor file to this method, but in this sample we do not need one, since there are no initial data files to load.
• Initialize the Swing aspect of the application.
  This is standard Swing code and is not explained here.
  
• Create a tree component.
  The tree component is of the class ilog.cpl.IlpTree, a JavaBean with a default constructor.
  
• Load a project configuration (project) from an XML file.
  The project configuration defines the component configuration files (CSS files) and the data source information.
  When the project file is set, the following steps are performed:
  • The configuration files are applied to the component.
  • A data source is created according to the class specified in the project configuration. In this case, it creates a standard data source of class ilog.tgo.datasource.IltDefaultDataSource.
  • The data file network is read containing predefined JTGO classes (business objects).
  • And finally the data source is attached to the component.
  The component configuration can also be specified later through the method ilog.cpl.IlpTree.setStyleSheets, you pass the name of a configuration file (tree) which describes view and object configuration.
  The data source and its contents can also be specified in the component throught the method ilog.cpl.IlpTree.setDataSource and ilog.cpl.datasource.IlpDefaultDataSource.parse.
  
• Sort the tree nodes.
  To sort the nodes, create a comparator and set it to the component. The comparator will be called with pairs of business objects and is expected to return an ordering for each pair. In the sample, the predefined ilog.cpl.util.IlpAttributeComparator class is used, which compares two business objects based on the value of one or more attributes.
  The comparator is set to the tree component with a call to the ilog.cpl.IlpTree.setSortComparator method.
• Manage the selection.
  First, you set the selection mode to TreeSelectionModel.DISCONTIGUOUS_TREE_SELECTION. This mode allows you to select multiple nodes in different parts of the tree. It is the default; the code is included here for illustration only. There are various other choices for the selection mode. See ilog.cpl.tree.IlpTreeSelectionModel for details.
  Then, a selection listener is added to the tree component, so that you are notified of any changes in selection. The source of any tree selection event is the tree selection model of class ilog.cpl.tree.IlpTreeSelectionModel. The selection model allows you to access the selected business objects easily. In the sample, we take these objects and display their names in a list.
• Create a pop-up menu.
  You create a pop-up menu factory using the ilog.cpl.interactor.IlpAbstractPopupMenuFactory class. This factory will be asked to create a menu whenever the user right-clicks anywhere inside the tree component.
  One of its createPopupMenu methods takes an ilog.cpl.util.selection.IlpObjectSelectionModel parameter. This allows you to easily access the selection at the time the menu is invoked and to configure the pop-up menu accordingly.
  The pop-up menu factory is associated with the tree by setting it to the tree interactor, which is retrieved using ilog.cpl.IlpTree.getViewInteractor.
  In this sample, the pop-up contains an action to change the root nodes of the tree. The root nodes are changed using the ilog.cpl.datasource.IlpAbstractHierarchyAdapter.setOrigins method of the tree adapter. The adapter is accessed using the ilog.cpl.IlpTree.getAdapter method.
• React to double-clicking a tree node.
  When the user double-clicks a node, you want to display a dialog showing additional information about the business object. You do this by creating a Swing Action and attaching it to the ilog.cpl.interactor.IlpGesture.BUTTON1_DOUBLE_CLICKED gesture.
  Within the actionPerformed method, you extract the business object that was under the cursor (if any) and access its attributes to fill the dialog.
• Filter the tree nodes.
  To filter the nodes of the tree, create an instance of ilog.cpl.util.IlpFilter and associate it with the tree using the ilog.cpl.IlpTree.setFilter method. The filter will be called whenever the tree is asked to display a business object. The object will only be represented if the filter returns true.
  
• Change the rendering.
  The sample shows the effect of changing the style sheet for the IltObject class. Two sample style sheet files are included:
  
  • Large_font
    Uses a larger font for the labels.
    
  • Red_selection
    Shows the selection in red.
    
  Load a style sheet with the ilog.cpl.IlpTree.setStyleSheets method. Note that this changes the styles locally for the tree component only.
• Add the tree to your Swing application.
  IlpTree is a Swing JComponent, so it can be added to your application like any other Swing component.
  

Installation Directory

The Tree Component - Basic sample is installed here.

Classes Involved

• ilog.cpl.IlpSystem

  The class that initializes a JViews TGO application.

• ilog.tgo.datasource.IltDefaultDataSource

  The default datasource implementation.

• ilog.cpl.IlpTree

  The tree component.

• ilog.cpl.project.IlpTGOProject

  The project definition.

• ilog.cpl.util.IlpAttributeComparator

  The comparator used to sort nodes in the tree component.

• ilog.cpl.tree.IlpTreeSelectionModel

  The tree component selection model implementation.

• ilog.cpl.interactor.IlpAbstractPopupMenuFactory

  The pop-up menu factory helper implementation.

• ilog.cpl.util.selection.IlpObjectSelectionModel

  The selection model that handles business objects.

• ilog.cpl.util.IlpFilter

  The interface that defines object filters.

Source Files

• basic.Main

  The entry point of the sample.