Handling Images in a Java GUI Application

Introduction

Handling images in an application is a common problem for many beginning Java programmers. The standard way to access images in a Java application is by using the getResource() method. This tutorial shows you how to use the IDE's GUI Builder to generate the code to include images (and other resources) in your application. In addition, you will learn how to customize the way the IDE generates image handling code.
The application that results from this tutorial will be a simple JFrame that contains one JLabel that displays a single image.

Creating the Application

1. Choose File > New Project.
2. In the New Project wizard, select Java > Java Application and click Next.
3. For Project Name, type ImageDisplayApp.
4. Clear the Create Main Class checkbox.
   
5. Click Finish.

Creating the Application Form

In this section, you create the JFrame form and add a JLabel to the form.
To create the JFrame form:

1. In the Projects window, expand the ImageDisplayApp node.
2. Right-click the Source Packages node and choose New > JFrame Form.
3. For Class Name, type ImageDisplay.
4. For Package Name, type org.me.myimageapp.
5. Click Finish.

To add the JLabel:

• In the Palette, select the Label component and drag it to the JFrame.

For now, the form should look something like the following image:

Adding a Package for the Image

When you use images or other resources in an application, typically you create a separate Java package for the resources. On your local filesystem, a package corresponds with a folder.
To create a package for the image:

1. In the Projects window, right-click the org.me.myimageapp node and choose New > Java Package.
   
   
2. In the Package Name text field of the New Java Package wizard, replace newpackage with resources so that the new package is called org.me.myimageapp.resources.
3. Click Finish.

In the Projects window, you should see a new package appear within the Source Packages folder.

Displaying the Image on the Label

In this application, the image will be embedded within a JLabel component.
To add the image to the label:

1. In the GUI Designer, select the label that you have added to your form.
2. In the Properties window, click the Properties category and scroll to the Icon property.
3. Click the ellipsis (...) button.
   The icon property editor is displayed.
   
4. In the icon property dialog box, click Import to Project.
5. In the file chooser navigate to any image that is on your system that you want to use. Then click Next.
6. In the Select target folder page of the wizard, select the newpackage folder and click Finish.
   
7. Click OK to close the icon property dialog box.

After you click OK, the IDE does the following things:

• Copies the image to your project. Therefore, when you build and distribute the application, the image is included in the distributable JAR file.
• Generates code in the ImageDisplay class to access the image.
• Displays your image on the label in the Design view of your form.
  

At this point, you can do some simple things to improve the appearance of the form, such as:

• In the Properties window, select the text property and delete jLabel1. That value was generated by the GUI Builder as display text for the label. However, you are using the label to display an image rather than text, so that text is not needed.
• Drag the button to the center of the form.
  

To view the generated code:

1. In the GUI Designer, click the Source button. (Choose View > Source Editor Toolbar from the main menu if the Source button is hidden.)
2. Scroll down to the line that says Generated Code.
3. Click the plus sign (+) to the left of the Generated Code line to display the code that the GUI Designer has generated.

The key line is the following:

jLabel1.setIcon(new javax.swing.ImageIcon(getClass().getResource("/org/me/myimageapp/newpackage/image.png"))); // NOI18N

Since you have used the property editor for jLabel1's Icon property, the IDE has generated the setIcon method. The parameter of that method contains a call to the getResource() method on an anonymous inner class of ImageIcon. Notice that the generated path for the image corresponds with its location in the application's package structure.

Notes:

• If you use the External Image option in the icon property editor, the IDE will generate an absolute path to the image instead of copying the image to your project. Therefore, the image would appear when you run the application on your system, but it would probably not appear when running the application on another system.
• The getResource method is also useful for accessing other types of resources, such as text files that contain data that your application might need to use.

To register event handlers for mouse events on the Jlabel:
In the Design View, right-click the JLabel and choose Events > Mouse > mouseClicked/mousePressed/mouseReleased from the popup menu.
An event handler is generated for the corresponding event.

Note: You can get the mouse coordinates (for example, the location of a mouse click) in the event handler using the event.getPoint(), event.getX(), or event.getY() methods. See Class MouseEvent for details.

Displaying the Image as the Background on the Frame

There is no direct support for a background image of JFrame in the GUI Builder, since there is no direct support for a background image of JFrame in Swing.
Anyway, there are various indirect ways to achieve such a goal. In this application, the JLabel with the image will be embedded within a JFrame component, while a transparent JPanel will be placed over the JLabel and used as the parent of all the components.
To add a transparent JPanel to the JFrame with the image:

1. Choose File > New Project.
2. In the New Project wizard, select Java > Java Application and click Next.
3. For Project Name, type BackgroundImageApp.
4. Clear the Create Main Class checkbox.
   
5. Click Finish.
6. In the Projects window, expand the BackgroundImageApp node.
7. Right-click the Source Packages node and choose New > JFrame Form.
8. For Class Name, type ImageDisplay.
9. For Package Name, type org.me.mybackgroundapp.
   
10. Click Finish.
11. In the Design view, right-click the JFrame and choose Set Layout > Grid Bag Layout from the popup menu.
12. Right-click the JFrame and choose Add From Pallette > Swing Containers > Panel from the popup menu.
13. In the Properties window, deselect the jPanel's opaque property.
14. Right-click the JFrame and choose Add From Pallette > Swing Controls > Label from the popup menu.
15. In the Projects window, right-click the org.me.mybackgroundapp node and choose New > Java Package.
16. Click Finish. A new package is added.
    
17. In the GUI Designer, select the label that you have added to your form.
18. In the Properties window, click the Properties category and scroll to the Icon property.
19. Click the ellipsis (...) button.
20. In the icon property dialog box, click Import to Project.
21. In the file chooser navigate to any image that is on your system that you want to use. Then click Next.
22. In the Select Target Folder page of the wizard, select the newpackage resources folder and click Finish.
23. Click OK to close the icon property dialog box.
24. In the Navigator, right-click the jPanel and choose Properties from the popup menu.
25. In the Properties dialog box set the Grid X, Grid Y, Weight X, and Weight Y properties to 1 and the Fill property to Both.
    
26. Click Close.
27. Repeat steps 24 and 25 for the jLabel.
28. In the Properties dialog box select the text property and delete jLabel1.
    
    The background is done. Now you can drag, a jLabel and a jTextField to the jPanel from the Palette, for example. Both of them will display over the background image.
    

Note: The advantage of the described solution is that the background image is shown at both design-time and runtime.