UI Service Documentation
Plugin component management
When we say “plugin component management” we mean that the UIService allows a bundle to add its own component somewhere in the UI, through which the user could access a functionality provided by this bundle. The component (e.g. button, menu item) is provided by the bundle itself. It is added to the UI (e.g. to a toolbar or a menu) and when clicked it performs the operations defined by the bundle.
What is a “plugin component”?
A “plugin component” is a user interface widget (e.g. button, menu item, etc.) that:
- is supported from the UI Service implementation. A given implementation could support SWT, while others may support AWT or Swing, etc.
- is added to one of the “plugable containers” defined in the UI Service implementation.
What is a “plugable container”?
A “plugable container” is a user interface container (e.g. menu, toolbar, etc.) that:
- is provided by UI Service implementation.
- accepts “plugin components”
- has a ContainerID associated with it that identifies it. The ContainerID is one of the CONTAINER_XXX constants defined in the UIService interface.
How to use the plugin components management system?
If you want to implement the UIService: 1.Associate a ContainerID to all your ‘plugable containers’. 2.Implement the isContainerSupported (ContainerID) method to check if the container with the given ContainerID is supported. 3.Implement the getSupportedContainers method to return a set of ContainerIDs corresponding to all your ‘plugable container’s. 4.It is up to you to check whether the added ‘plugin component’ is an object compatible with the currently used library. Before adding any “plugin component” you should check the supported containers of the current UIService implementation. You could do this by invoking the method: getSupportedContainers() or by checking for a given ContainerID with the isContainerSupported(ContainerID) method. If you want to be informed in any time when a plugable container is added or removed from the list of supported containers, you should use the ContainerListener.
To add a “plugin component” use the following methods:
- addComponent(ContainerID containerID, Object component) - Adds the given component to the container corresponding to the given containderID. The containerID is the identifier of the container, where you want to add your component. The component is the object you want to insert.
- addComponent(ContainerID containerID, String constraint, Object component) - Adds the given component to the container corresponding to the given containerID at the given by constraint exact place. The containderID and the component are the same arguments as described above. The constraint argument is a String representing the exact position of the component in the container. It is one of the UIService constraints: START, END, TOP, BOTTOM, LEFT or RIGHT.
NOTE The containerID should be one of the ids returned by getSupportedContainers, otherwise an IllegalArgumentException is thrown.
NOTE If the given “plugin component” library is not compatible with the container library a ClassCastException is thrown.
Example 1: Adds a JMenuItem to the File menu of the application.
JMenuItem myMenuItem = new JMenuItem("Open my bundle");
myMenuItem.addActionListener(MyActionListener);
...
//Obtain the UI Service
ServiceReference uiServiceRef =
context.getServiceReference(UIService.class.getName());
UIService uiService =
(UIService)context.getService(uiServiceRef);
//Check if the File menu is a supported container.
boolean isContainerSupported
= uiService.isContainerSupported(UIService.CONTAINER_FILE_MENU);
if(isContainerSupported) {
//Add your menu item to the File menu
uiService.addComponent(UIService.CONTAINER_FILE_MENU, myMenuItem);
}
Example 2: Obtains the list of all supported containers and adds your JMenuItem to all of them. Note that this could be dangerous when your component is a specific component that doesn’t fits well to the container. Imagine for example, adding a JMenuItem to a toolbar container.
...
//Obtain the UI Service
...
//Obtain the list of supported containers
Iterator i = uiService.getSupportedContainers();
while(i.hasNext()) {
ContainerID containerID = (ContainerID)i.next();
//Add your component to all supported containers
uiService.addComponent(containerID, myMenuItem);
}