Working with the ImageRegionSelector Bean

Introduction

The ImageRegionSelector bean displays an image and allows a user to select one of several predefined regions. When a region is selected, other interested components are notified through the use of standard Java events.

A major goal of the ImageRegionSelector is concerned with the definition of the regions. The implementation of the ImageRegionSelector both simplifies the process of region definition and supports discontiguous and complex regions. This is achieved through a technique known as region painting, where it is not necessary to define regions by specifying a set of polygons.

Due to the accuracy of region definition, the ImageRegionSelector provides effective and visually attractive feedback to users through tooltips and a range of rollover and selection emphasis options.

An example of the use of ImageRegionSelectors is shown below, where two components are used in a house buying application. It allows the user to specify in which area they would like to live within the East Anglian region of England and the type of housing they would like. Once these are specified the applet displays the details of suitable houses

ImageRegionSelector Example

Applications

You can use an ImageRegionSelector to provide the equivalent of an HTML image map within Java applications. However, unlike image maps, the ImageRegionSelector provides good feedback to users and simplifies the definition of complex and discontiguous regions.

Applications include:

User Feedback

The ImageRegionSelector bean supports three optional types of user feedback which can all be set through the bean's properties:
  1. A tooltip can be defined for each region. For example, in the house buying applet shown above, when the mouse hovers over the area of Bedfordshire, a tooltip appears stating "Click here for the County of Bedfordshire".
  2. When you move the mouse into a region, a rollover emphasis can be applied to highlight the region. The emphasis styles available are described below.
  3. When you select a region, a selection emphasis can be applied to highlight the selected region.
You can use any of the following emphasis styles to show rollover or selection: An example of each emphasis style is shown below:

Emphasis styles

Using Region Painting for Region Definition

The ImageRegionSelector uses a second image, called the Color Map Image, to define the selectable regions of the display image. This color map image is never shown to the user as it is solely used to define regions within the corresponding display image. To define a set of regions in an image, follow the steps below:
  1. Copy the display image to a new image file, known as the color map image
  2. Load the color map image into an image editing program
  3. For each region:
    1. Choose an index number to be returned when this region is selected
    2. Select the associated color from the predefined set of colors described in section Color Map Image Colors
    3. Fill the region with the selected color

The predefined set of mapping colors corresponds to the standard set of 216 web-safe colors - without the color magenta. This color is reserved as a background color, and therefore should be used in the non-selectable areas of the color map image. This means that the ImageRegionSelector can represent up to 215 selectable regions.

The ImageRegionSelector ignores any area of the display image for which the corresponding area of the color map image is not painted with one of the predefined set of colors.

Please note that you should provide the color map image in a .gif or other suitable format that maintains the RGB value of each pixel. The region definition can be distorted if other formats, such as .jpeg, are used which may alter the RGB values of the pixels. Both .jpg and .gif are suitable formats for the display and cutaway images.

Shown below are the three images which are used to produce the ImageRegionSelector component which selects the house type required in the above example. The selector uses three images since "cutaway" emphasis is specified for region selection. This makes it possible to give selected regions the desired red tinge as there is no separate emphasis style which does this.

Display image and corresponding color map and cutaway images

Building Applications with ImageRegionSelectors

To build an ImageRegionSelector application, create an applet or application that instantiates an ImageRegionSelector Bean. You can either write Java code or use a visual builder tool that supports Swing, such as VisualAge for Java, Inprise JBuilder, or Symantec Visual Cafe.

The ImageRegionSelector bean is a visual component that displays an image to the user and waits for one of a set of predefined regions to be selected. Therefore at the very least the ImageRegionSelector requires two of its properties to be set. A Display Image needs to be specified so that it can be displayed to the user and a Color Map Image is specified to define the selectable regions.

In order for the ImageRegionSelector to communicate selections with other components, such components need to register themselves as listeners of Item events. See the following sections on how to achieve this both in a visual builder and writing source code.

Creating an ImageRegionSelector Application Using a Visual Builder

This section describes some common scenarios for building applets by using a visual tool such as Visual Age for Java.

You will need to adapt the scenarios to the specific terminology and connection techniques of the tool you use.

Most tools require you to import the s_imageregionselector jar before you can use the beans. The tool may also allow you to add the ImageRegionSelector bean to a palette.

  1. Start the visual builder.
  2. Import s_imageregionselector.jar into the builder. This jar includes all the classes required to create an ImageRegionSelector component.
  3. Create and customize an ImageRegionSelector:
    1. Create an instance of the ImageRegionSelector Bean.
    2. Position the ImageRegionSelector. The bean defaults to a standard size which is changed according to the size of the Display Image when one is specified.
    3. Use the property editors to specify:
      • The display image
      • The color map image
  4. Optionally use the property editors to specify:
    • The rollover emphasis style
    • The selection emphasis style
    • The cutaway image - only necessary if cutaway emphasis has been specified
    • The selected region
    • Tooltip values
    • Region names
  5. Link ImageRegionSelector's itemStateChanged event to interact with other components in the applet (see below)
Connecting the Beans in VisualAge for Java

The following information explains how the ImageRegionSelector beans events are linked to other beans within VisualAge for Java. These wiring instructions will differ between other visual building applications.

The diagram below shows an ImageRegionSelector bean and 2 swing JLabel beans within a JApplet. The JLabels are used to display, upon selection, the name of the region selected and the index of that region. All the relevant property values have been set for the ImageRegionSelector - including the "region names" property which supplies the name of the selected region.

Wiring events in VisualAge for Java

To display the selected index in JLabel1:

To display the name of the selected region in JLabel2:

Creating an ImageRegionSelector Application by Programming in Java

If you are creating an applet you must subclass the JFC JApplet class, if you are writing an application you must use one of the JFC top level window classes, such as JWindow, JFrame, or JDialog.

To a programmer the ImageRegionSelector acts in a very similar way to a JComboBox component in that it is added to a container and interested components register themselves as listeners for Item events. As with a JComboBox, the ImageRegionSelector implements the ItemSelectable interface which means any components that wish to receive notification of region selection and deselection must implement the ItemListener interface, using the itemStateChanged method to receive the event

Since the ImageRegionSelector component extends JComponent is simply added to its parent container with a suitable location for it to be displayed. It is fully customized using API calls to set its properties.

For more information about the ImageRegionSelector classes, see the API documentation.

Example Code

The following samples help you understand how to create your own ImageRegionSelector applications by programming in Java:

Frequently Asked Questions

Which version of VisualAge for Java should I use ?

You should use VisualAge for Java Version 2.0 (with the Rollup 2 fix applied) or higher.

Why don't I see the display image when I run an Applet in Netscape ?

This occurs if you have the extracted the images files from the s_imageregionselector.jar and maintained their directory structure, and have added that directory structure to your CLASSPATH.

Why don't I see the display image when I run an Applet in IE4 ?

This occurs with the version of the JVM that shipped with IE 4.01. Later releases fix the problem. A workaround is to extract the GIF files from s_imageregionselector.jar and to place them under your CODEBASE directory, taking care to maintain the correct directory structure.

Why does the property editor window sometimes paint incorrectly in Symantec Visual Cafe 2.5 ?

Symantec have noted the issue. If you force the property editor window to refresh, for example by covering then uncovering it, it paints correctly.

Why does the ImageRegionSelector Bean sometimes appear twice when I add s_imageregionselector.jar to a new page in the palette in InPrise JBuilder 2 ?

We don't know, but the duplicate entries function correctly. However, when you restart JBuilder they no longer appear.