Learn how to extend the AWT with your own image buttons

Subclass an AWT component so you can build an image button for toolbars, palettes, and other "icon-friendly" environments

You might take it for granted that every modern-day GUI toolkit has inherent support for icons and icon buttons, but don't be so quick to assume -- Java's Abstract Windowing Toolkit (AWT) doesn't live up to that expectation. Yes, the AWT does contain a Button class, but because Button is implemented through platform-dependent GUI components, you can't draw into a button and expect your image to display properly, if at all.

Before you start cursing the AWT (yet again), let me assure you that a solution exists. The most straightforward approach and the technique we'll be examining in this article involves subclasssing the AWT's Canvas class. Although the primary purpose of the Canvas class is drawing (perfect for our purposes), it doesn't provide the mouse handling or any of the typical button-press effects (let alone mouse-over effects) you would expect for a button. We'll address these limitations by working with several classes I've created to support fully flexible, active image buttons.

Getting started with the ImageButton class

Our first step toward creating image buttons is to implement a new class that works within the Java environment and also supports drawing. To make sure our new class (which we'll call

ImageButton.java

) works within the Java environment, we should subclass it from an existing AWT component. The AWT contains two candidates --

Canvas

and

Panel

-- that support drawing. Although we could use either class,

Panel

has additional capabilities that we don't need, so we'll go with

Canvas

. Here is the class declaration:

   
public class ImageButton extends Canvas {

Determining button states

Our image button needs to support a number of different states: UNARMED, OVER, ARMED, and DISABLED. Let's take a look at the characteristics of each state.

When the user is not interacting with the button in any way, the button is in its UNARMED state. To follow suit with many applications, such as Internet Explorer and the new Netscape Navigator 4.0 pre-release, we're going to implement an OVER state, which will highlight a button as the user moves the mouse over it. The ARMED state, which we'll represent by showing a depressed button, occurs when the user clicks and holds on a button. If the user releases the mouse while the button is in the ARMED state, the corresponding action will be performed; however, users can return to the UNARMED state by moving the mouse off of the button without releasing the mouse. The last state we'll be supporting is DISABLED, which is implemented through the ImageButton programming interface by calling the AWT disabled function. A disabled button should not respond to any user action. We'll be using a grayed-out effect to indicate a disabled button.

Our image button will support only one state at a time (a button can't very well be ARMED and UNARMED at the same time now, can it?). We'll represent the four states in a single int, with four constants, as shown here:

public static final int UNARMED = 0; public static final int ARMED = 1; public static final int OVER = 2; public static final int DISABLED = 3;

private int buttonState = UNARMED;

Defining borders

Most buttons have a visible border that may change depending upon the state. But unfortunately, the

Canvas

component is completely blank by default, and it doesn't provide any built-in support for drawing a border around the rectangular region it encompasses.

We will have to draw the borders ourselves, so our next step is to decide what type of borders we want and which states they will correspond with. By implementing the border features in a separate class (we'll call this class Border), we can use one or more instances of the class in our ImageButton and switch between them as the states change.

Currently, the most popular kind of border is the shaded 3D-style border. We can actually use this border style for two of our button states: To indicate a button is unarmed, we'll use this style with darker bottom and right edges and lighter top and left edges; to indicate a button is armed (depressed) we'll use this style with darker top and left edges and lighter bottom and right edges.

I have implemented a very configurable class (Border.java) that supports multiple border styles, including NONE, THREED_OUT, and THREED_IN, among others. Two of Border's methods -- getInsets() and paint() -- do the bulk of the work. The getInsets() method returns the number of pixels at the top, left, bottom, and right that are necessary to make space for the border. (Note that the border is not required to be symmetrical.) The getInsets() method is used both to determine the size of the image button and to calculate the appropriate location at which to draw the button's image. As shown in the following snippet, getInsets() takes into account the border thickness and variable margins at each edge:

   
public Insets getInsets() {
        int top = borderThickness + topMargin;
        int left = borderThickness + leftMargin;
        int bottom = borderThickness + bottomMargin;
        int right = borderThickness + rightMargin;
        return new Insets( top, left, bottom, right );
    }

The Border paint() method, which is similar to the AWT Component paint() method, takes a Graphics parameter as input and draws the border in its current configuration. Border does not maintain the x-y coordinates or size of the image button, so these are passed to paint(). Also, the border color, if not set explicitly, can be derived from the button's current background color, another parameter to paint(). (This approach is desirable for borders like the 3D borders that should be given brighter and darker colors relative to the current background color.) Here is the function declaration for paint():

    
public void paint( Graphics g, Color background, 
                       int x, int y, int width, int height );

Different styles for different states

Back in the ImageButton class, a button needs to maintain variables for, potentially, four different borders and four different images for each of the four button states. Since we already defined the states as integers 0 through 3, we can use these values as indexes into the following arrays:

   
private Image images[] = new Image[4];
    private Border borders[] = new Border[4];

For convenience, I subclassed Border to define the default button borders for the ARMED and UNARMED states. The constructor for DefaultImageButtonBorder takes a boolean (true if constructing the default armed border and false if unarmed). These borders can be reused by any or all instances of ImageButton and are, therefore, defined as static variables in ImageButton and assigned in the ImageButton constructor. Here are those declarations:

    
private static final Border defaultUnarmedBorder =
        new DefaultImageButtonBorder( false );
    private static final Border defaultArmedBorder =
        new DefaultImageButtonBorder( true );

Constructing the image button

We're done with all the background stuff, so now we can get to the heart of the matter -- creating the image button. As application programmers, we create an image button the same way we create a button component -- by calling

new ImageButton()

. The are two constructors involved -- one has no parameters, and the other takes an image to be used as the unarmed image. Here are those constructors:

public ImageButton() { tracker = new MediaTracker( this ); setUnarmedBorder( defaultUnarmedBorder ); setArmedBorder( defaultArmedBorder ); }

public ImageButton( Image image ) { this(); setUnarmedImage( image ); }

Setting the images and borders

To update the images array and load the images into a MediaTracker, which is used to start and manage the image loading in a background thread, we'll use a private method,

setImage()

, which is called by the

setUnarmedImage()

,

setArmedImage()

,

setOverImage()

, and

setDisabledImage()

functions.

setImage()

also requests a repaint if the image that was just set is the image for the current state. For example, if the current state is UNARMED and the image id passed to

setImage()

is UNARMED, the image button must be repainted, as shown here:

    
private synchronized void setImage( int id, Image image ) {
        if ( images[id] != image ) {
            images[id] = image;
            if ( image != null ) {
                tracker.addImage( image, id );
                tracker.checkID( id, true );
            }
            if ( buttonState == id ) {
                repaint();
            }
        }
    }

Simple image buttons (for example, those in Netscape Navigator 3.0) typically use the same image for the UNARMED, ARMED, and OVER states. To simplify the creation of a such a button, we can use setUnarmedImage() to set the images for the ARMED and OVER states, provided those images are null (their initial values), to the unarmed image. The DISABLED state, however, is a special case. If the disabled image is null, a "disabled-looking" image is generated from the unarmed image. Notice in Listing 1 that setUnarmedImage() optionally calls setDisabledImage() with the value null. If the image passed to setDisabledImage() is null, we can generate the disabled image automatically by blanking out every other pixel in the current unarmed image. This technique actually gives the resulting image a "grayed-out" effect. The image is generated using a FilteredImageSource, and my own RGBImageFilter DisableImageFilter, which we'll get into later on in the article.

public void setUnarmedImage( Image image ) { setImage( UNARMED, image ); if ( images[ARMED] == null ) { setArmedImage( image ); } if ( images[OVER] == null ) { setOverImage( image ); } if ( ( images[DISABLED] == null ) || generatedDisabled ) { setDisabledImage( null ); } }

public void setArmedImage( Image image ) { if ( image != null ) { setImage( ARMED, image ); } else { setImage( ARMED, images[UNARMED] ); } }

public void setOverImage( Image image ) { if ( image != null ) { setImage( OVER, image ); } else { setImage( OVER, images[UNARMED] ); } }

public void setDisabledImage( Image image ) { generatedDisabled = false; if ( ( image == null ) && ( images[UNARMED] != null ) ) { generatedDisabled = true; image = createImage( new FilteredImageSource(images[UNARMED].getSource(), new DisableImageFilter() ) ); } setImage( DISABLED, image ); }

Listing 1: The setXxxImage functions

Note: You'll see in the source that I've also provided public getXxxImage functions (for example, getUnarmedImage()) to get the current image for each of the states. Borders are set and retrieved through almost identical set and get functions, like setUnarmedBorder() and getDisabledBorder(). The only difference is that no special case for disabled borders exists.

Setting the button state

Now that we've seen how to set the images and borders for an image button, our next step is to see how to set the actual button states. Notice from the code snippet below that I use a public method (

getButtonState()

) to get the current button state, but a protected method (

setButtonState()

) to set the button state. I use this approach because button state changes are the result of certain external events, and as such, should be handled by the

ImageButton

class itself. By making

setButtonState()

protected instead of private, however, I purposefully leave a back door open for subclasses that might extend the functionality of

ImageButton

, which may result in setting the state in response to other types of events.

public int getButtonState() { return buttonState; }

protected void setButtonState( int buttonState ) { if ( buttonState != this.buttonState ) { this.buttonState = buttonState; repaint(); } }

The setButtonState() method checks to see if the new state is different then the old one. If so, it assigns the new value to the buttonState variable and calls the repaint() method, causing the image button to be repainted with a potentially different border and/or image.

Handling the DISABLED state

I decided to piggy-back on the existing AWT API for disabling and enabling components so that use of the ImageButton API is consistent with all other AWT components.

ImageButton

overrides the

disable()

and

enable()

functions from

Component

class in order to essentially trap these requests and set the button state appropriately. The original methods are then invoked on the superclass. Therefore, if

disable()

is called, we will not get any mouse events, and no state changes will occur until the button is enabled again. Here are the two functions:

public void disable() { setButtonState( DISABLED ); super.disable(); }

public void enable() { setButtonState( UNARMED ); super.enable(); }

Painting the ImageButton

1 2 Page 1
Page 1 of 2