<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | |
<!--Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. | |
--> | |
<html> | |
<head> | |
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> | |
<meta name="description" content="Tutorial that shows how to handle images and | |
other resources when creating Swing applications in NetBeans IDE"> | |
<meta name="keywords" content="NetBeans, IDE, integrated development environment tutorial, guide, user, documentation, open source"> | |
<link rel="stylesheet" type="text/css" href="../../../netbeans.css"> | |
<title>Handling Images in a Java GUI Application - NetBeans IDE tutorial</title> | |
</head> | |
<body> | |
<h1>Handling Images in a Java GUI Application</h1> | |
<p><b>Contents</b></p> | |
<img src="../../../images_www/articles/71/netbeans-stamp-71-72-73.png" class="stamp" alt="Content on this page applies to NetBeans IDE 7.0, 7.1, 7.2, and 73" title="Content on this page applies to the NetBeans IDE 7.0, 7.1, 7.2, and 73"> | |
<ul class="toc"> | |
<li><a href="#intro">Introduction</a></li> | |
<li><a href="#form">Creating the Application Form</a></li> | |
<li><a href="#package">Adding a Package for the Image</a></li> | |
<li><a href="#displaying">Displaying the Image on the Label</a></li> | |
<li><a href="#building">Building and Running the Application</a></li> | |
<li><a href="#background">Displaying the Image as the Background on the Frame</a></li> | |
<li><a href="#custom">Creating Custom Code</a></li> | |
<li><a href="#summary">Summary</a></li> | |
<li><a href="#seealso">See Also</a></li> | |
</ul> | |
<p> | |
<b>To complete this tutorial, you need the following software and resources.</b> | |
</p> | |
<table> | |
<tbody> | |
<tr> | |
<th class="tblheader" scope="col">Software or Resource</th> | |
<th class="tblheader" scope="col">Version Required</th> | |
</tr> | |
<tr> | |
<td class="tbltd1"><a href="http://www.netbeans.org/downloads/index.html">NetBeans IDE</a></td> | |
<td class="tbltd1">Version 7.0, 7.1, 7.2, or 7.3</td> | |
</tr> | |
<tr> | |
<td class="tbltd1"><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development Kit (JDK)</a></td> | |
<td class="tbltd1">Version 6 or 7</td> | |
</tr> | |
</tbody> | |
</table> | |
<a name="intro"></a><h2>Introduction</h2> | |
<p>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 <code><a href="http://download.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String)" target="_blank">getResource()</a></code> 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.</p> | |
<p>The application that results from this tutorial will be a simple JFrame that | |
contains one JLabel that displays a single image.</p> | |
<h2>Creating the Application</h2> | |
<ol> | |
<li>Choose File > New Project.</li> | |
<li>In the New Project wizard, select Java > Java Application and click Next.</li> | |
<li>For Project Name, type <code>ImageDisplayApp</code>.</li> | |
<li>Clear the Create Main Class checkbox. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/newproj.png" rel="lytebox" title="New Project wizard - Click to Enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/newproj-small.png" alt="New Project wizard" border=1></a></p></li> | |
<li>Click Finish.</li> | |
</ol> | |
<a name="form"></a><h2>Creating the Application Form</h2> | |
<p>In this section, you create the JFrame form and add a JLabel to the form.</p> | |
<p><b>To create the JFrame form:</b></p> | |
<ol> | |
<li>In the Projects window, expand the <tt>ImageDisplayApp</tt> node.</li> | |
<li>Right-click the Source Packages node and choose New > JFrame Form.</li> | |
<li>For Class Name, type <code>ImageDisplay</code>.</li> | |
<li>For Package Name, type <code>org.me.myimageapp</code>.</li> | |
<li>Click Finish.</li> | |
</ol> | |
<p><b>To add the JLabel:</b></p> | |
<ul> | |
<li>In the Palette, select the Label component and drag it to the JFrame.</li> | |
</ul> | |
<p>For now, the form should look something like the following image:</p> | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/form.png" rel="lytebox" title="Generated form with the label added - Click to Enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/form-small.png" alt="Generated form with the label added" border=1></a></p> | |
<a name="package"></a><h2>Adding a Package for the Image</h2> | |
<p>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.</p> | |
<p><b>To create a package for the image:</b></p> | |
<ol> | |
<li>In the Projects window, right-click the <code>org.me.myimageapp</code> | |
node and choose New > Java Package.<br> | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/package.png" rel="lytebox" title="Adding a new Java package - Click to Enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/package-small.png" alt="Adding a new Java package" border=1></a></p></li> | |
<li>In the Package Name text field of the New Java Package wizard, replace <code>newpackage</code> with <code>resources</code> so that the new package is called <code>org.me.myimageapp.resources</code>.</li> | |
<li>Click Finish.</li> | |
</ol> | |
<p>In the Projects window, you should see a new package appear within the <code>Source Packages</code> folder.</p> | |
<p class="align-center"><img src="../../../images_www/articles/72/java/gui-image-display/project-with-imagepack.png" | |
alt="Projects window" border=1></p> | |
<a name="displaying"></a><h2>Displaying the Image on the Label</h2> | |
<p>In this application, the image will be embedded within a JLabel component.</p> | |
<p><b>To add the image to the label:</b></p> | |
<ol> | |
<li>In the GUI Designer, select the label that you have added to your form.</li> | |
<li>In the Properties window, click the Properties category and | |
scroll to the Icon property.</li> | |
<li>Click the ellipsis (...) button.<br> | |
The icon property editor is displayed. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/importimage.png" rel="lytebox" title="Icon Property Editor - Click to Enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/importimage-small.png" alt="Icon Property Editor" border=1></a></p></li> | |
<li>In the icon property dialog box, click Import to Project.</li> | |
<li>In the file chooser navigate to any image that is on your system that you want to use. | |
Then click Next.</li> | |
<li>In the Select target folder page of the wizard, select the <code>newpackage</code> folder and click Finish. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/targetfolder.png" rel="lytebox" title="Select Target Folder page of the Import Images to Project wizard"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/targetfolder-small.png" alt="Select Target Folder page of the Import Images to Project wizard" border=1></a></p> | |
</li> | |
<li>Click OK to close the icon property dialog box.</li> | |
</ol> | |
<p>After you click OK, the IDE does the following things:</p> | |
<ul> | |
<li>Copies the image to your project. Therefore, when you build and distribute the application, | |
the image is included in the distributable JAR file.</li> | |
<li>Generates code in the ImageDisplay class to access the image.</li> | |
<li>Displays your image on the label in the Design view of your form. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/label-added.png" rel="lytebox" title="Image added to the label"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/label-added-small.png" alt="Image added to the label" border=1></a></p></li> | |
</ul> | |
<p>At this point, you can do some simple things to improve the appearance of the | |
form, such as:</p> | |
<ul> | |
<li>In the Properties window, select the <code>text</code> property and delete | |
<code>jLabel1</code>. 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.</li> | |
<li>Drag the button to the center of the form. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/centered.png" rel="lytebox" title="The Design view of the ImageDisplay class with the image centered"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/centered-small.png" alt="The Design view of the ImageDisplay class with the image centered" border=1></a></p></li> | |
</ul> | |
<p><b>To view the generated code:</b></p> | |
<ol> | |
<li>In the GUI Designer, click the Source button. (Choose View > Source Editor Toolbar from the main menu if the Source button is hidden.)</li> | |
<li>Scroll down to the line that says Generated Code.</li> | |
<li>Click the plus sign (+) to the left of the Generated Code line to display | |
the code that the GUI Designer has generated.</li> | |
</ol> | |
<p>The key line is the following:</p> | |
<pre class="examplecode">jLabel1.setIcon(new javax.swing.ImageIcon(getClass().getResource("/org/me/myimageapp/newpackage/image.png"))); // NOI18N</pre> | |
<p>Since you have used the property editor for <code>jLabel1</code>'s <code>Icon</code> property, | |
the IDE has generated the <code>setIcon</code> method. The parameter of that method | |
contains a call to the <code><a href="http://download.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String)" target="_blank">getResource()</a></code> | |
method on an anonymous inner class of <code>ImageIcon</code>. | |
Notice that the generated path for the image corresponds with its location in | |
the application's package structure.</p> | |
<p class="notes"><b>Notes:</b></p> | |
<ul> | |
<li>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.</li> | |
<li>The <code>getResource</code> method is also useful | |
for accessing other types of resources, such as text files that | |
contain data that your application might need to use.</li> | |
</ul> | |
<p><b>To register event handlers for mouse events on the Jlabel:</b></p> | |
<p> | |
In the Design View, right-click the JLabel and choose Events > Mouse > mouseClicked/mousePressed/mouseReleased from the popup menu.<br> | |
An event handler is generated for the corresponding event.</p> | |
<p class="notes"><b>Note:</b> You can get the mouse coordinates (for example, the location of a mouse | |
click) in the event handler using the <code>event.getPoint()</code>, <code>event.getX()</code>, or <code>event.getY()</code> methods. See <a href="http://docs.oracle.com/javase/1.4.2/docs/api/java/awt/event/MouseEvent.html">Class MouseEvent</a> for details.</p> | |
<a name="background"></a> | |
<h2>Displaying the Image as the Background on the Frame</h2> | |
<p> 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.<br> 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.</p> | |
<p><b>To add a transparent JPanel to the JFrame with the image:</b></p> | |
<ol> | |
<li>Choose File > New Project.</li> | |
<li>In the New Project wizard, select Java > Java Application and click Next.</li> | |
<li>For Project Name, type <code>BackgroundImageApp</code>.</li> | |
<li>Clear the Create Main Class checkbox. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/prj.png" rel="lytebox" title="Creating a new project - Click to enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/prj-small.png" alt="Creating a new project" border=1></a></p></li> | |
<li>Click Finish.</li> | |
<li>In the Projects window, expand the <code>BackgroundImageApp</code> node.</li> | |
<li>Right-click the Source Packages node and choose New > JFrame Form.</li> | |
<li>For Class Name, type <code>ImageDisplay</code>.</li> | |
<li>For Package Name, type <code>org.me.mybackgroundapp</code>. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/newjframe.png" rel="lytebox" title="Adding a new form - Click to enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/newjframe-small.png" alt="Adding a new form" border=1></a></p></li> | |
<li>Click Finish.</li> | |
<li>In the Design view, right-click the JFrame and choose Set Layout > Grid Bag Layout from the popup menu. </li> | |
<li>Right-click the JFrame and choose Add From Pallette > Swing Containers > Panel from the popup menu. </li> | |
<li>In the Properties window, deselect the jPanel's <code>opaque</code> property.</li> | |
<li>Right-click the JFrame and choose Add From Pallette > Swing Controls > Label from the popup menu.</li> | |
<li>In the Projects window, right-click the <code>org.me.mybackgroundapp</code> | |
node and choose New > Java Package.</li> | |
<li>Click Finish. A new package is added. | |
<p class="align-center"><img src="../../../images_www/articles/72/java/gui-image-display/targetfolder-small.png" alt="Select Target Folder page of the Import Images to Project wizard" border=1></p></li> | |
<li>In the GUI Designer, select the label that you have added to your form.</li> | |
<li>In the Properties window, click the Properties category and scroll to the Icon property.</li> | |
<li>Click the ellipsis (...) button. </li> | |
<li>In the icon property dialog box, click Import to Project.</li> | |
<li>In the file chooser navigate to any image that is on your system that you want to use. Then click Next.</li> | |
<li>In the Select Target Folder page of the wizard, select the <code>newpackage</code> resources folder and click Finish.</li> | |
<li>Click OK to close the icon property dialog box.</li> | |
<li>In the Navigator, right-click the jPanel and choose Properties from the popup menu. </li> | |
<li>In the Properties dialog box set the <code>Grid X</code>, <code>Grid Y</code>, <code>Weight X</code>, and <code>Weight Y</code> properties to <code>1</code> and the <code>Fill</code> property to <code>Both</code>. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/panelprops.png" rel="lytebox" title="Panel properties - Click to enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/panelprops-small.png" alt="Panel properties" border=1></a></p></li> | |
<li>Click Close. </li> | |
<li>Repeat steps 24 and 25 for the jLabel.</li> | |
<li>In the Properties dialog box select the <code>text</code> property and delete <code>jLabel1</code>. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/labelprops.png" rel="lytebox" title="Label properties - Click to enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/labelprops-small.png" alt="Label properties" border=1></a></p> | |
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. | |
<p class="align-center"><img src="../../../images_www/articles/72/java/gui-image-display/background.png" | |
alt="Screenshot showing the Design view of the Background class." class="margin-around"></p></li> | |
</ol> | |
<p class="notes"><b>Note:</b> The advantage of the described solution is that the background image is shown at both design-time and runtime.</p> | |
<a name="building"></a><h2>Building and Running the Application</h2> | |
<p>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.</p> | |
<p>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 <code>Main-Class</code> element in the application's | |
JAR file is generated when you build the application.</p> | |
<p><b>To set the project's main class:</b></p> | |
<ol> | |
<li>Right-click the ImageDisplayApp project's node and | |
choose Properties.</li> | |
<li>In the Project Properties dialog box, select the Run | |
category.</li> | |
<li>Click the Browse button that is next to the Main Class | |
field. Then select the <code>org.me.myimageapp.ImageDisplay</code> | |
class. | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/labelprops.png" rel="lytebox" title="Label properties - Click to enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/labelprops-small.png" alt="Label properties" border=1></a></p></li> | |
<li>Click the Select Main Class button.</li> | |
<li>Click OK to close the Project Properties dialog box. </li> | |
</ol> | |
<p><b>To build the project:</b></p> | |
<ul> | |
<li>Choose Run > Clean & Build Project (<i>project_name</i>) from the main toolbar.</li> | |
</ul> | |
<p>You can view the build products of the application in the Files | |
window. The <code>build</code> folder contains the compiled class. | |
The <code>dist</code> folder contains a | |
runnable JAR file that contains the compiled class and the image.</p> | |
<p class="align-center"><img src="../../../images_www/articles/72/java/gui-image-display/files.png" | |
alt="The Files window with the build and dist folders expanded" border=1></p> | |
<p><b>To run the project:</b></p> | |
<ul> | |
<li>Choose Run > Run Project (<i>project_name</i>) from the main toolbar.</li> | |
</ul> | |
<a name="custom"></a><h2>Creating Custom Code</h2> | |
<p>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. </p> | |
<p>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.</p> | |
<p><b>For example, to write custom code for a JLabel's <code>icon</code> property:</b></p> | |
<ol> | |
<li>Select the JLabel in the Design View or in the Navigator window.</li> | |
<li>In the Properties window, click the ellipsis (...) button that is | |
next to the <code>icon</code> property.</li> | |
<li>From the dropdown list at the top of the dialog box, select | |
the Custom Code option.</li> | |
</ol> | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/custom-code.png" rel="lytebox" title="The Icon property editor with the Custom Code option selected - Click to enlarge"><img src="../../../images_www/articles/72/java/gui-image-display/custom-code-small.png" alt="The Icon property editor with the Custom Code option selected" border=1></a></p> | |
<p>The Custom Code option in this property editor lets you fill in the | |
parameter of the <code>setIcon</code> | |
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.</p> | |
<p class="align-center"><a href="../../../images_www/articles/72/java/gui-image-display/custom-view.png" rel="lytebox" title="Text area where you can enter the setIcon paramater - Click to enlarge"> | |
<img src="../../../images_www/articles/72/java/gui-image-display/custom-view-small.png" alt="Text area where you can enter the setIcon paramater" border=1></a></p> | |
<a name="summary"></a><h2>Summary</h2> | |
<p>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. </p> | |
<p class="notes"><b>Note: </b>The example given in this tutorial is very similar to the first | |
example in the | |
<a href="http://java.sun.com/docs/books/tutorial/uiswing/components/icon.html" target="_blank">How to Use Icons section</a> | |
of the Java Tutorial. One difference is that the code that is generated when you follow | |
this tutorial uses | |
<code><a href="http://download.oracle.com/javase/6/docs/api/javax/swing/JLabel.html" target="_blank">JLabel</a></code>'s | |
<code><a href="http://download.oracle.com/javase/6/docs/api/javax/swing/JLabel.html#setIcon(javax.swing.Icon)" target="_blank">setIcon</a></code> | |
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.</p> | |
<div class="feedback-box"> | |
<a href="/about/contact_form.html?to=3&subject=Feedback:%20Handling%20Images%20in%20a%20GUI%20Application">Send Feedback on This Tutorial</a> | |
</div> | |
<br style="clear:both;" > | |
<a name="seealso"></a><h2>See Also</h2> | |
<ul> | |
<li><a href="gui-functionality.html">Introduction to GUI Building</a></li> | |
<li><a href="quickstart-gui.html">Designing a Swing GUI in NetBeans IDE</a></li> | |
<li><a href="../../trails/matisse.html">Java GUI Applications Learning Trail</a></li> | |
<li><a href="../../trails/java-se.html">General Java Development Learning Trail</a></li> | |
<li><a href="http://wiki.netbeans.org/NetBeansUserFAQ#GUI_Editor_.28Matisse.29" target="_blank">GUI Builder - Frequently Asked Questions</a></li> | |
</ul> | |
</body> | |
</html> |