// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= Handling Images in a Java GUI Application
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:syntax: true
:icons: font
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Handling Images in a Java GUI Application - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Handling Images in a Java GUI Application

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 `link:http://download.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String)[+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.

[.feature]
--
image::images/newproj-small.png[role="left", link="images/newproj.png"]
--


[start=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:

[.feature]
--
image::images/form-small.png[role="left", link="images/form.png"]
--


== 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.

[.feature]
--
image::images/package-small.png[role="left", link="images/package.png"]
--


[start=2]
. Click Finish.

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

image::images/project-with-imagepack.png[]


== 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.

[.feature]
--
image::images/importimage-small.png[role="left", link="images/importimage.png"]
--


[start=4]
. In the icon property dialog box, click Import to Project.

[start=5]
. In the file chooser navigate to any image that is on your system that you want to use. Then click Next.

[start=6]
. In the Select target folder page of the wizard, select the `newpackage` folder and click Finish.

[.feature]
--
image::images/targetfolder-small.png[role="left", link="images/targetfolder.png"]
--


[start=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.

[.feature]
--
image::images/label-added-small.png[role="left", link="images/label-added.png"]
--

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 `jLabel1` to the center of the form.

[.feature]
--
image::images/centered-small.png[role="left", link="images/centered.png"]
--

*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:


[source,java]
----

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 `link:http://download.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String)[+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 link:http://docs.oracle.com/javase/1.4.2/docs/api/java/awt/event/MouseEvent.html[+Class MouseEvent+] for details.


== Building and Running the Application

Now that you have generated the code for accessing and displaying the image, you can build and run the application to ensure that the image is accessed.

First you need to set the project's main class. When you set the main class, the IDE knows which class to run when you run the project. In addition, this ensures that the `Main-Class` element in the application's JAR file is generated when you build the application.

*To set the project's main class:*

1. Right-click the ImageDisplayApp project's node and choose Properties.
2. In the Project Properties dialog box, select the Run category.
3. Click the Browse button that is next to the Main Class field. Then select the `org.me.myimageapp.ImageDisplay` class.

[.feature]
--
image::images/mainclass-small.png[role="left", link="images/mainclass.png"]
--


[start=4]
. Click the Select Main Class button.

[start=5]
. Click OK to close the Project Properties dialog box.

*To build the project:*

* Choose Run > Clean &amp; Build Project (_project_name_) from the main toolbar.

You can view the build products of the application in the Files window. The `build` folder contains the compiled class. The `dist` folder contains a runnable JAR file that contains the compiled class and the image.

image::images/files.png[]

*To run the project:*

* Choose Run > Run Project (_project_name_) from the main toolbar.


== Creating Custom Code

In many applications, the image that is displayed is not determined statically like it is in this example. For example, the image to display might be determined by something that the user clicks.

If you need to be able to choose the image to display programmatically, you can write your own custom code to access and display resources. The IDE prevents you from writing code directly in the Source view's "guarded blocks" that contain code generated by the GUI Builder. However, you can insert code in the guarded blocks through property editors that you can access through the Properties window. Using the property editors in this manner ensures that your custom code is not lost when you make design changes in the GUI Builder.

*For example, to write custom code for a JLabel's `icon` property:*

1. Select the JLabel in the Design View or in the Navigator window.
2. In the Properties window, click the ellipsis (...) button that is next to the `icon` property.
3. From the dropdown list at the top of the dialog box, select the Custom Code option.

[.feature]
--
image:images/custom-code-small.png[role="left", link="images/custom-code.png"]
--

The Custom Code option in this property editor lets you fill in the parameter of the `setIcon` method yourself. You can fill in this parameter with the necessary logic or with a call to a separate method that you have hand-coded elsewhere in the class.

[.feature]
--
image::images/custom-view-small.png[role="left", link="images/custom-view.png"]
--


== Summary

This tutorial has shown you how to access images from an application that you create in the NetBeans IDE. Image handling is further discussed in the Java Tutorial.

*Note: *The example given in this tutorial is very similar to the first example in the link:http://java.sun.com/docs/books/tutorial/uiswing/components/icon.html[+How to Use Icons section+] of the Java Tutorial. One difference is that the code that is generated when you follow this tutorial uses `link:http://download.oracle.com/javase/6/docs/api/javax/swing/JLabel.html[+JLabel+]`'s `link:http://download.oracle.com/javase/6/docs/api/javax/swing/JLabel.html#setIcon(javax.swing.Icon)[+setIcon+]` method to apply the icon to the label. In the Java Tutorial example, the icon is applied to the label by being passed through its constructor.