Using Several Images from a Single File on an Image Button

How to obtain individual button images from a larger (composite) image by specifying pixel coordinates.

About this technique	Details
Category	Java Client Techniques> Version 2 AWT-based controls
Description	You'll learn about: Specifying a portion of an image in the Property Inspector Dynamically changing image properties of an image button
	You can run this technique code from: Database: Examples3_Java Form: frmImages NOTE   First make sure that database is running on your localhost SilverStream Server
Related reading	See the chapter on the Form Designer in the Tools Guide

Uploading an image for each button in your application may cost you in computational speed. To avoid having to upload multiple images for the various buttons images, you can upload a composite image of all the buttons, then use each button's image properties to access the only relevant portion of the image. This cropping technique is useful if you want to minimize the number of individual image files you maintain for your application.

The example uses a single image file as the source for multiple button images. The single large image is actually a composite of several images. You can extract individual portions of the large image by specifying the pixel coordinates for the upper left corner and the width and height.

When you run the form and click on a button in the central frame, the pixel coordinates for the button are displayed in the text box. For example if you click on the up image for the ADD button, the following is displayed: "Coordinates of ImageButton: x=1, y=1, w = 63, h = 26."

Specifying a portion of an image in the Property Inspector   

The following describes how to specify cropping values for the composite image so that a button displays a portion of the composite image.

1. Ensure that buttons.jpg is in the Examples3_Java/Media/Images store.

2. In design mode select the blank (gray) button on the right side of the display and open the Property Inspector.

3. Open Images on the property sheet

4. Specify a file name and image coordinates for one of the Images fields. For example for the Up image, you might specify:

     buttons.JPG 1 30 63 26 
   

   This information specifies that:

   • buttons.JPG is the file name of the composite image

   • 1 30 specifies the pixel coordinates of the upper left corner of the portion you want to use of the composite image

   • 63 is the width of the cropped image in pixels

   • 26 is the height of the cropped image in pixels

Dynamically changing image properties of an image button   

The following code uses setUpImage() and setDownImage() to change the images assigned to an image button. The button has both Up and Down images. A second button lets the user switch between two pairs of images for the button. The images are in a single image file that is a composite of all the images.

This is a code fragment in the handle_listImages_valueChanged() method.

  //Get the image. 
  Image imgBig = getImage(agGeneral.getDatabaseURL() +  
           "/SilverStream/Objectstore/Images/buttons.JPG"); 
   
  //Get the section you're interested in. (UP Image) 
  cropped= new FilteredImageSource (imgBig.getSource(), 
     new CropImageFilter (xCoordinate, yCoordinate,  
     width, height)); 
   
  //Assign to the image variable. 
  little = createImage (cropped); 
   
  //Set the up image property of the image button. 
  //ibDynamic is an AgcButtonImage object 
  ibDynamic.setUpImage(little); 
         
  //Get the section you're interested in. (DOWN Image) 
  cropped = new FilteredImageSource (imgBig.getSource(), 
     new CropImageFilter (xCoordinate, 30, width, height)); 
   
  //Assign to the image variable. 
  little = createImage (cropped); 
   
  //Set the down image property of the image button. 
  ibDynamic.setDownImage(little); 

Notes about the code

• cropped holds the cropped image, which is created with FilteredImageSource.

• The FilteredImageSource takes the big image and a filter object (in this case a CropImageFilter object) to produce image data for a filtered version of the big image.
  • imgBig.getSource() returns the ImageProducer that created the large image.

  • The CropImageFilter class is used for cropping images. It identifies a rectangular region that can be applied to an image source. Its constructor takes the (x,y) location of the upper left corner of the new image, and its width and height.

• createImage(), a method of Component, creates a new image object from the filter specifications.

• setUpImage() sets the "up" button image (that is, the button in its unpressed state) to the extracted image.

• Reassign cropped, this time to a different region on the big image. Note that the y-coordinate is set to 30 to define this region. The x-coordinate, the width and height values of the new image are the same.

• setDownImage() sets the "down" button image (that is, the button in its pressed state) to the new extracted image.