The UI half objects of an extension to the base ULC widgets can be placed in one or more separate packages. It is important to follow the rules described below (i.e. provide a typeString method that returns the fully qualified class name). Do not modify the existing ULC Java packages! In this example the package is called com.ibm.ulc.examples.pieExtension. For more information on using Java, see the javadoc .
Note: | The extensions must be placed in the classpath of the UI Engine. The easiest way of doing this is to export the extension to the UIEngine/lib directory. |
To instantiate an object, the UI Engine uses the following name-qualification rules:
Each UI half object must initialize its state from the faceless half. In addition, PieChart offers the following API:
UIPieChart descends from com.ibm.ulc.UIComponent. UIPieChart adapts PieChart so that it can be used by the UI Engine. As part of doing so, it keeps a reference to the PieChart widget. Here is an excerpt from the class definition of UIPieChart:
public class UIPieChart extends UIComponent implements ActionListener { private PieChart fPieChart= null; }
To restore its state from the faceless half object, UIPieChart overrides restoreState():
public void restoreState(ORBConnection conn, Anything args) { super.restoreState(conn, args); fPieChart= new PieChart(args.get("w", 200), args.get("h", 150)); fPieChart.setData(args.get("data")); fPieChart.addActionListener(this); }
A call to the inherited restoreState() method restores the inherited state. The PieChart widget is created and initialized with the restored state. The ORBConnection argument is not used in this example and is just passed on to the base class.
Communication between the UI Engine and faceless half objects is based on data objects called Anythings. An Anything is a dynamic data structure that can be transferred between processes. The restoreState() method receives an Anything as its argument and uses Anything accessor methods to retrieve the individual arguments. Anythings can contain either a simple data type or arrays and dictionaries of Anythings. Proper retrieval of the arguments requires that both faceless and UI half objects handle Anythings in a analogous way. In this case, the Anything is a dictionary, and restoreState() retrieves the arguments by name. For example, args.get("w") retrieves the width argument of the pie chart. In the same way, the setData() method restores the pie chart's data from the Anything and passes it on to the PieChart widget.
So that UIPieChart can notify the faceless half when a pie segment is clicked, UIPieChart implements the ActionListener interface. UIPieChart also registers itself as an action listener of PieChart.
Requests sent from the faceless half are dispatched to handleRequest(). This method receives the name of the request with its arguments packaged as an Anything. UIPieChart implements only a single request (named setData()) to set the pie chart's data:
public void handleRequest(ORBConnection conn, String request, Anything args){ if (request.equals("setData")) { setData(args); return; } super.handleRequest(conn, request, args); }
The handleRequest() method uses setData() to extract the data from the Anything and install it in PieChart. Calling the inherited handleRequest() method enables the base classes to handle its request.
As part of implementing the ActionListener interface, UIPieChart implements the actionPerformed() method, which calls sendEventULC() to send the event:
public void actionPerformed(ActionEvent e) { sendEventULC("action", "cmd", new Anything(e.getActionCommand())); }sendEventULC() takes the name of the event, its type name, and an argument. The event's argument is wrapped into an Anything. In this case, it is a simple string that corresponds to the label of the clicked pie segment.