How to use a Rhino IconRenderer

Table of Contents


Introduction

This document is a reference for SGI software engineers who will be using IconRenderers for Rhino applications. IconRenderer is a class that can generate an icon that represents a particular Item. Many of the Rhino infrastructure components use an IconRenderer to display the icon associated with an Item, including the ItemView, the ItemTable, the ResultView, and the TreeView. The IconRenderer gives the programmer the ability to define what icon an Item should use, and have that icon used everywhere that an Item's icon is displayed.

There is one IconRenderer for each Category. The IconRenderer is responsible for monitoring the Category and generating icons for any Items that listeners have expressed interest in.

For more information on IconRenderers in general, see the IconRenderer documentation API documentation.


Before you begin

Before you begin to create an IconRenderer for a particular Category, you need to understand the names and terms that the Rhino infrastructure uses in relation to Categories. See the The names of Categories on the client and on the server documentation for more information.

Specifying the IconRenderer to use for a Category

The HostContext keeps track of which IconRenderer to use for each Category. To specify a Category's IconRenderer, place the ICON_RENDERER resource in the Category's resource file. For example, to specify that the RhinoExampleCategory should use the "com.sgi.rhexamp.category.IconRenderer" class as its IconRenderer, the following entry would be made in /com/sgi/rhexamp/category/rhexampRhinoExampleCategoryP.properties:
com.sgi.rhexamp.category.rhexampRhinoExampleCategory.iconRenderer = com.sgi.rhexamp.category.IconRenderer
If this resource is not specified, then the HostContext creates a ResourceBasedIconRenderer object for the Category.

Using the ResourceBasedIconRenderer

The ResourceBasedIconRenderer is a subclass of IconRenderer that is used to display icons if there is no ICON_RENDERER resource specified (see Specifying the IconRenderer to use for a Category). To use the ResourceBasedIconRenderer, you must place specific resources in the Category's resource file.

Using the same icon for all the Items in a Category

If you want to use the same icon for all the Items in a Category, then only the "icon" resource is needed, defined as <name>.icon (see the DEFAULT_ICON documentation for more information). The icon described by the "icon" resource can be either classpath-relative pathnames to .gif or .jpg icons, or they can be package-qualified names of FtrIcon. For example, if all of the Items in the RhinoExample Category should show an icon of a rhino, then the following lines would be placed in the resource file:
A: RHINO_EXAMPLE_CATEGORY=com.sgi.rhexamp.category.rhexampRhinoExampleCategory
B: ${RHINO_EXAMPLE_CATEGORY}.icon = /com/sgi/sysadm/ui/images/sysadm.gif

Using different icons for each Item in a Category

To show a different icon for each Item in the Category, add the "iconBasedOn" resource, defined as <name>.iconBasedOn, where <name> is the package-qualified name of the Category (see the ICON_BASED_ON documentation for more information). This resource specifies which of the Item's Attributes the icon will be based on.

In conjunction with the "iconBasedOn" resource, there should be "icon" resources, defined as <name>.icon.<Attribute's value>, where <Attribute's value> is one of the values that the Attribute specified by "iconBasedOn" can have. (See the ICON documentation for more information). If no "icon" resource is found that matched the value of the Attribute specified by "iconBasedOn", then the default icon (as described above) will be used.

For example, in the RhinoExample category, the icon is based on the type, so the following entries are made in the resource file:

A: RHINO_EXAMPLE_CATEGORY=com.sgi.rhexamp.category.rhexampRhinoExampleCategory
B:
C: ${RHINO_EXAMPLE_CATEGORY}.iconBasedOn = type
D: ${RHINO_EXAMPLE_CATEGORY}.icon = com.sgi.rhexamp.ftr.Unknown
E: ${RHINO_EXAMPLE_CATEGORY}.icon.Clock = com.sgi.rhexamp.ftr.Clock
F: ${RHINO_EXAMPLE_CATEGORY}.icon.Printer = com.sgi.rhexamp.ftr.Printer
G: ${RHINO_EXAMPLE_CATEGORY}.icon.NetscapeExecutable = com.sgi.rhexamp.ftr.NetscapeExecutable
With the resource defined as shown, then the icon displayed will be based on the "type" Attribute of the Item. For example, if the "type" is "Clock", then the FtrIcon com.sgi.rhexamp.ftr.Clock will be used. If the "type" Attribute is not one of "Clock", "Printer" or "NetscapeExecutable", then the com.sgi.rhexamp.ftr.Unknown will be displayed.

Another way to show different icons for each Item in the Category is to use the "iconModifiers" resource, defined as <name>.iconModifiers (see the ICON_MODIFIERS documentation for more information). This resource defines an array of Attributes of the Item that will be passed to the set method of FtrIcon. The FtrIcon can then use the Attributes to choose how to display the icon. The Attributes defined by the "iconModifiers" resource will be passed to the FtrIcon that is created. The Attributes will be passed to the FtrIcon both in the case where a default icon is used and in the case where a specific icon is used. These Attributes will be ignored if the icon is not an FtrIcon.

For example, if the FtrIcons for the RhinoExampleCategory could draw themselves differently based on the "mode" Attribute of the Item, then add the following to the resource file:

A: ${RHINO_EXAMPLE_CATEGORY}.iconModifiers0 = mode
In this case, the Item's "mode" Attribute will be passed to whatever FtrIcon is used (which - as described above - depends on the "type" Attribute).

Using a subclass of IconRenderer

To provide complete control of the icon that is used for an Item, it is also possible to subclass the IconRenderer class and provide the necessary Java code for rendering icons. See the IconRenderer documentation for more information. It is also possible to subclass the ResourceBasedIconRenderer to add to the existing functionality of the ResourceBasedIconRenderer.