blob: 1124fa743eacaa92d3cf469859b61aced7805f76 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<!-- -*- xhtml -*- -->
<title>Paint Application Tutorial for NetBeans Platform 7.3</title>
<link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css"/>
<meta name="AUDIENCE" content="NBUSER"/>
<meta name="TYPE" content="ARTICLE"/>
<meta name="EXPIRES" content="N"/>
<meta name="developer" content="gwielenga@netbeans.org"/>
<meta name="indexed" content="y"/>
<meta name="description"
content="A guide to creating a Paint application."/>
<!-- Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. -->
<!-- Use is subject to license terms.-->
</head>
<body>
<h1>NetBeans Platform Paint Application Tutorial</h1>
<p>This tutorial takes you through the basics of using NetBeans IDE to develop rich-client applications
on top of the NetBeans Platform. When you develop applications on top of the NetBeans Platform, you are
developing on top of the NetBeans IDE's core. All the modules belonging to the IDE that are not relevant to
your application are excluded, but those that are useful are kept. By reusing features readily available in IDE's core,
you save yourself a lot of time and energy. </p>
<p><strong class="notes">Note: </strong>This document uses the NetBeans IDE 7.3 Release
or above. If you
are using an earlier version, see <a href="72/nbm-paintapp.html">the previous version
of this document</a>.</p>
<p><b>Contents</b></p>
<p><img src="../images/articles/73/netbeans-stamp.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 7.3" title="Content on this page applies to NetBeans IDE 7.3"/></p>
<ul class="toc">
<li><a href="#intro">Introduction to the Paint Application</a></li>
<li><a href="#setup">Setting Up the Paint Application</a>
<ul>
<li><a href="#creatingModuleSuite">Creating the Application Skeleton</a></li>
<li><a href="#creatingModProj">Creating the Module</a></li>
</ul>
</li>
<li><a href="#impMod">Creating and Embedding the Paint Canvas</a>
<ul>
<li><a href="#creatingCanv">Creating the Canvas</a></li>
<li><a href="#prepTopComp">Embedding the Canvas in a Window</a></li>
</ul>
</li>
<li><a href="#runPack">Running, Branding, and Packaging the Application</a>
<ul>
<li><a href="#run">Running the Application</a></li>
<li><a href="#brand">Branding the Application</a></li>
<li><a href="#package">Packaging the Application</a></li>
</ul>
</li>
</ul>
<p><b>To follow this tutorial, you need the software and resources listed in the following
table.</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="https://netbeans.org/downloads/index.html">NetBeans IDE</a></td>
<td class="tbltd1">version 7.3 or above</td>
</tr>
<tr>
<td class="tbltd1"><a href="http://java.sun.com/javase/downloads/index.jsp">Java Developer Kit (JDK)</a></td>
<td class="tbltd1">Version 6 or above</td>
</tr>
</tbody>
</table>
<p class="tips">For troubleshooting purposes, you are welcome to download the <a href="http://java.net/projects/nb-api-samples/sources/api-samples/show/versions/7.3/tutorials/PaintApp">completed tutorial source code</a>.</p>
<p><a name="intro"></a></p><h2>Introduction to the Paint Application</h2>
<p>This tutorial is designed to get you going as quickly as possible.
You will create a simple application on the NetBeans Platform. The
application allows the user to
paint on the screen:</p>
<p><img src="../images/tutorials/paintapp/73/result-2.png" alt="image of completed application"/></p>
<p>This initial version is far from a full fledged
paint application, but it demonstrates a very simple case of creating an application on top of the NetBeans Platform.</p>
<p><b class="notes">Note:</b> The
<a href="nbm-google.html">NetBeans Plugin Quick Start</a> is a better tutorial for you if, instead of
rich-client applications, you want to
learn about NetBeans modules. </p>
<p><a name="setup"></a></p><h2>Setting Up the Paint Application</h2>
<p>In this section, you create the structure of your application. You first need to create an application skeleton, which you
can do via a wizard. Then you will create the module that will contain your code.</p>
<div class="indent">
<h3 class="tutorial"><a name="creatingModuleSuite"></a>Creating the Application Skeleton</h3>
<p>The "NetBeans Platform Application" template will create your application's skeleton.
The skeleton will consist of a set of modules that
work together to form the basis of your application. You will use the Project Properties dialog to assign your application's splashscreen,
application name, and the type and number of NetBeans modules that you want to use. You can also take advantage
of such actions as creating a ZIP distribution and building a Java WebStart (JNLP) application, which are
important tools in making your application available to other users.</p>
<div class="indent">
<ol>
<li><p>Choose File &gt; New Project. Under Categories, select NetBeans Modules. Under projects,
select NetBeans Platform Application:</p>
<p><img src="../images/tutorials/paintapp/73/new-app-1.png" alt="project template"/></p>
<p>Click Next.</p></li>
<li><p>In the Name and Location panel, type <tt>PaintApp</tt> in Project Name.
Change the
Project Location to any directory on your computer:</p>
<p><img src="../images/tutorials/paintapp/73/new-app-2.png" alt="project template"/></p>
<p>Click Finish.</p></li>
<li><p>The new application skeleton opens in the IDE. Look at the new
project structure:</p>
<p><img src="../images/tutorials/paintapp/73/new-app-3.png" alt="project template"/></p>
<p class="tips">You see two subnodes in the Projects window. The first subnode, the "Modules" node,
shows you the custom modules that are part of the application. Right now, as you can
see, there are none. You can right-click on this subnode and then invoke wizards
for creating new modules or for wrapping external JARs into the application.
The "Important Files" node shows the build scripts and
other supporting files used by the application.</p></li>
<li><p>Right-click the application and choose Run. The default splash screen is shown
and then you see the starting point of your new application:</p>
<p><img src="../images/tutorials/paintapp/73/new-app-4.png" alt="project template"/></p>
<p>Look through the menu
bar and the toolbar to see the features that your application already has, such
as an Exit menu item, a Properties window, and an Output window.</p></li>
</ol>
</div>
<h3 class="tutorial"><a name="creatingModProj"></a>Creating the Functionality Module</h3>
<p>Now you need a module to contain the actual code you're going to write.</p>
<div class="indent">
<ol>
<li><p>Right-click the "Modules" node in the Paint Application. Select Add New:</p>
<p><img src="../images/tutorials/paintapp/73/new-mod-1.png" alt="name and location panel"/></p>
</li>
<li><p>In the Name and Location panel, type <tt>Paint</tt> in Project Name.</p>
<p><img src="../images/tutorials/paintapp/73/new-mod-2.png" alt="name and location panel"/></p>
<p>Notice that the module sources will be stored within a folder in
the application's directory on disk. Click Next.</p></li>
<li><p>In the Basic Module Configuration panel, type <tt>org.netbeans.paint</tt> as the
"Code Name Base". The code name base is a unique string identifying the module
to other modules in the application.
Leave everything unchanged.</p>
<p><img src="../images/tutorials/paintapp/73/new-mod-3.png" alt="name and location panel"/></p>
<p>Click Finish. The IDE creates the <tt>Paint</tt>
project.</p></li>
<li><p>Take a look at the structure of your application.
The project contains all of your sources and
project metadata, such as the project's Ant build script. The project
opens in the IDE. You can view its logical structure in the Projects window (Ctrl-1) and its
file structure in the Files window (Ctrl-2). For example, the Projects
window should look as follows:</p>
<p><br/><img src="../images/tutorials/paintapp/73/new-mod-4.png" alt="name and location panel"/></p>
</li>
<li><p>You will need to subclass several classes that belong to the <a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans APIs</a>.
All NetBeans APIs are implemented by modules,
so this task really just means
adding some modules to the list of modules that our module needs in order to run.
In the Projects window, right-click the <tt>Paint</tt> project node and choose Properties.
The Project Properties dialog box opens. Under Categories, click Libraries.
For each of the API's listed in the table below, click "Add Dependency..." and then, in the Filter text box, start typing the name of the
class that you want to subclass.</p>
<p></p>
<table width="76%" border="1">
<tbody>
<tr>
<td>
<div><b>Class</b></div>
</td>
<td>
<div><b>API</b></div>
</td>
<td>
<div><b>Purpose</b></div>
</td>
</tr>
<tr>
<td><tt>Lookup</tt></td>
<td><tt>Lookup API</tt></td>
<td>Enables loosely coupled communication between modules.</td>
</tr>
<tr>
<td><tt>ActionID</tt></td>
<td><tt>UI Utilities API</tt></td>
<td>Provides annotations for registering Actions
in the NetBeans Platform virtual filesystem, as
well as the <tt>ColorComboBox</tt> class.</td>
</tr>
<tr>
<td><tt>Messages</tt></td>
<td><tt>Utilities API</tt></td>
<td>Provides a variety of general utility classes,
including support for internationalization
via the Bundle class and <tt>@Messages</tt> annotation.</td>
</tr>
<tr>
<td><tt>TopComponent</tt></td>
<td><tt>Window System API</tt></td>
<td>Gives you access to the NetBeans window system.</td>
</tr>
</tbody>
</table>
<br/>
<p>The first column in the table above lists all the classes that you will subclass in this tutorial.
In each case, start typing the class name in the Filter and watch the Module list narrow. Use the table's second column to pick the appropriate API (or, in the case of <tt>ColorChooser</tt>, the library) from the narrowed Module list and then click OK to confirm the choice.
Click OK to exit the Project Properties dialog box.</p>
<p>In the Projects window, expand the Paint module's project node and
then expand the Libraries node. Notice that all the libraries you have
selected are displayed:</p>
<p><img src="../images/tutorials/paintapp/73/new-dep-1.png" alt="initial-proj-window"/></p>
<p>Expand the Paint module's Important Files node and double-click
the Project Metadata node. Notice that the API's you
selected have been declared as module dependencies
in the file. When the module is compiled, the declared dependencies
are added to the module's manifest file.</p></li>
</ol>
</div>
</div>
<h2><a name="impMod"></a>Creating and Embedding the Paint Canvas</h2>
<div class="indent">
<h3 class="tutorial"><a name="creatingCanv"></a>Creating the Canvas</h3>
<p>The next step is to create the actual component on which the user can paint. Here, you use a pure Swing component&#8212;so, let's
skip the details of its implementation and just provide the final version. The color chooser bean, which you created the library
wrapper module for, is used in the source code for this panel&#8212;when you run the finished application, you will see it
in the toolbar of the panel for editing images.</p>
<div class="indent">
<ol>
<li>In the Projects window, expand the <tt>Paint</tt> node, then expand the Source Packages node, and then
right-click the <tt>org.netbeans.paint</tt> node. Choose New &gt; Java Class.</li>
<li>Enter <tt>PaintCanvas</tt> as the Class Name. Ensure that <tt>org.netbeans.paint</tt> is listed as the
Package. Click Finish. <tt>PaintCanvas.java</tt> opens in the Source editor.</li>
<li>Replace the default content of the file with the content found
<a href="../images/tutorials/paintapp/70/PaintCanvas.java">here</a>.
If you named your package something other than <tt>org.netbeans.paint</tt>, correct the package name in the
Source editor.</li>
</ol>
</div>
<h3 class="tutorial"><a name="prepTopComp"></a>Embedding the Canvas in a Window</h3>
<p>Now you'll write the only class in this application that needs to
touch the <a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans APIs</a>. It is a <tt><a href="http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.html">TopComponent</a></tt> class. A <tt>TopComponent</tt> class is
just a <tt>JPanel</tt> class which the NetBeans windowing system knows how to talk
to&#8212;so that it can be put inside a tabbed
container inside the main window.</p>
<div class="indent">
<ol>
<li>In the Projects window, expand the <tt>Paint</tt> node, then expand the Source Packages node, and then
right-click the <tt>org.netbeans.paint</tt> node. Choose New &gt; Java Class.
Enter <tt>PaintTopComponent</tt> as the Class Name. Ensure that <tt>org.netbeans.paint</tt> is listed as the
Package. Click Finish. <tt>PaintTopComponent.java</tt> opens in the Source editor.</li>
<li>Near the top of the file, change the class declaration to the following:
<pre class="examplecode">public class PaintTopComponent extends TopComponent implements ActionListener, ChangeListener {</pre></li>
<li>Press Ctrl-Shift-I to fix imports and click OK. The IDE makes the necessary import package
declarations at the top of the file:
<pre class="examplecode">import java.awt.event.ActionListener;
import javax.swing.event.ChangeListener;
import org.openide.windows.TopComponent;</pre>
<p>Notice the red line under the class declaration that you just entered. Position the cursor in the line and notice that a
light bulb appears in the left margin. Click the light bulb (or press Alt-Enter), as shown below:</p>
<p><img src="../images/tutorials/paintapp/73/new-dep-2.png" alt="initial-proj-window"/></p>
<p>Select Implement all
abstract methods. The IDE generates two method skeletons&#8212;<tt>actionPerformed()</tt> and <tt>stateChanged()</tt>. You will fill these
out later in this tutorial.</p></li>
<li>Register the <tt>PaintTopComponent</tt> in the window system by adding annotations
to the top of the class, as shown here, and then press Ctrl-Shift-I to let the IDE
generate the appropriate import statements:
<pre class="examplecode"><a href="http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.Description.html">@TopComponent.Description</a>(
preferredID = "PaintTopComponent",
iconBase = "/org/netbeans/paint/new_icon.png",
persistenceType = TopComponent.PERSISTENCE_ALWAYS)
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.Registration.html">@TopComponent.Registration</a>(
mode = "editor",
openAtStartup = true)
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionID.html">@ActionID</a>(
category = "Window",
id = "org.netbeans.paint.PaintTopComponent")
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionReferences.html">@ActionReferences</a>({
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionReference.html">@ActionReference</a>(
path = "Menu/Window",
position = 0),
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionReference.html">@ActionReference</a>(
path = "Toolbars/File",
position = 0)
})
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.OpenActionRegistration.html">@TopComponent.OpenActionRegistration</a>(
displayName = "#CTL_NewCanvasAction")
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/NbBundle.Messages.html">@Messages</a>({
"CTL_NewCanvasAction=New Canvas",
"LBL_Clear=Clear",
"LBL_Foreground=Foreground",
"LBL_BrushSize=Brush Size",
"# {0} - image",
"UnsavedImageNameFormat=Image {0}"})
public class PaintTopComponent extends TopComponent implements ActionListener, ChangeListener {</pre>
<p class="notes"><b>Note:</b> While the module is being compiled, the annotations
above will be processed. XML entries will be created in the module's <tt>generated-layer.xml</tt>
file, for each of the @TopComponent* and @Action* annotations. The <tt>generated-layer.xml</tt>
file will be contributed by the module to the System Filesystem of the application. Read
more <a href="http://wiki.netbeans.org/DevFaqSystemFilesystem">about the System Filesystem here</a>. For example, the <tt>PaintTopComponent</tt> will be displayed
in the main area of the application, defined by the "editor"
position, as specified by the <tt>@TopComponent.Registration</tt> annotation above. For each
item defined in the <tt>@Messages</tt> annotation, a new key/value string is generated into a <tt>Bundle.java</tt>
class.</p></li>
<li><p>Add these two icons to "org/netbeans/paint":</p>
<p><img src="../images/tutorials/paintapp/70/new_icon.png" alt="Lightbulb."/>
<img src="../images/tutorials/paintapp/70/new_icon24.png" alt="Lightbulb."/></p>
<p>The 16x16 pixel icon will be used for the Small Toolbar Icons display,
while the 24x24 pixel icon will be used for the Large Toolbar display, as
well as in the tab of the window, as defined by <tt>@TopComponent.Description</tt> above.</p>
</li>
<li>The <tt>TopComponent</tt> class is a wrapper for the <tt>Canvas</tt> you created earlier. All
the new import statements and code below is normal Java Swing code. Copy it below and paste it into your <tt>PaintTopComponent</tt> source file:
<pre class="examplecode">package org.netbeans.paint;
import java.awt.BorderLayout;
import java.awt.Dimension;
import java.awt.FlowLayout;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import javax.swing.JButton;
import javax.swing.JComponent;
import javax.swing.JLabel;
import javax.swing.JScrollPane;
import javax.swing.JSlider;
import javax.swing.JToolBar;
import javax.swing.event.ChangeEvent;
import javax.swing.event.ChangeListener;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
import org.openide.awt.ActionReferences;
import org.openide.awt.ColorComboBox;
import org.openide.util.NbBundle.Messages;
import org.openide.windows.TopComponent;
@TopComponent.Description(
preferredID = "PaintTopComponent",
iconBase = "/org/netbeans/paint/new_icon.png",
persistenceType = TopComponent.PERSISTENCE_ALWAYS)
@TopComponent.Registration(
mode = "editor",
openAtStartup = true)
@ActionID(
category = "Window",
id = "org.netbeans.paint.PaintTopComponent")
@ActionReferences({
@ActionReference(
path = "Menu/Window",
position = 0),
@ActionReference(
path = "Toolbars/File",
position = 0)
})
@TopComponent.OpenActionRegistration(
displayName = "#CTL_NewCanvasAction")
@Messages({
"CTL_NewCanvasAction=New Canvas",
"LBL_Clear=Clear",
"LBL_Foreground=Foreground",
"LBL_BrushSize=Brush Size",
"# {0} - image",
"UnsavedImageNameFormat=Image {0}"})
public class PaintTopComponent extends TopComponent implements ActionListener, ChangeListener {
private PaintCanvas canvas = new PaintCanvas(); //The component the user draws on
private final JComponent preview = canvas.getBrushSizeView(); //A component in the toolbar that shows the paintbrush size
private final JSlider brushSizeSlider = new JSlider(1, 24); //A slider to set the brush size
private final JToolBar toolbar = new JToolBar(); //The toolbar
private final ColorComboBox color = new ColorComboBox(); //Our color chooser component from the ColorChooser library
private final JButton clear = new JButton(Bundle.LBL_Clear()); //A button to clear the canvas
private final JLabel label = new JLabel(Bundle.LBL_Foreground()); //A label for the color chooser
private final JLabel brushSizeLabel = new JLabel(Bundle.LBL_BrushSize()); //A label for the brush size slider
private static int ct = 0; //A counter you use to provide names for new images
public PaintTopComponent() {
initComponents();
setDisplayName(Bundle.UnsavedImageNameFormat(ct++));
}
private void initComponents() {
setLayout(new BorderLayout());
//Configure our components, attach listeners:
color.addActionListener(this);
clear.addActionListener(this);
brushSizeSlider.setValue(canvas.getBrushDiameter());
brushSizeSlider.addChangeListener(this);
color.setSelectedColor(canvas.getColor());
color.setMaximumSize(new Dimension(16, 16));
//Install the toolbar and the painting component:
add(toolbar, BorderLayout.NORTH);
add(new JScrollPane(canvas), BorderLayout.CENTER);
//Configure the toolbar:
toolbar.setLayout(new FlowLayout(FlowLayout.LEFT, 7, 7));
toolbar.setFloatable(false);
//Now populate our toolbar:
toolbar.add(label);
toolbar.add(color);
toolbar.add(brushSizeLabel);
toolbar.add(brushSizeSlider);
toolbar.add(preview);
toolbar.add(clear);
}
@Override
public void actionPerformed(ActionEvent e) {
if (e.getSource() instanceof JButton) {
canvas.clear();
} else if (e.getSource() instanceof ColorComboBox) {
ColorComboBox cc = (ColorComboBox) e.getSource();
canvas.setColor(cc.getSelectedColor());
}
}
@Override
public void stateChanged(ChangeEvent e) {
canvas.setBrushDiameter(brushSizeSlider.getValue());
}
}</pre>
</li>
</ol>
</div>
</div>
<h2><a name="runPack"></a>Running, Branding, and Packaging the Application</h2>
<p>In this section, you try out the application and then package it for distribution to your users.</p>
<div class="indent">
<h3 class="tutorial"><a name="run"></a>Running the Application</h3>
<div class="indent">
<ol>
<li><p>Right-click the application and choose Run:</p>
<p><img src="../images/tutorials/paintapp/73/run-1.png" alt="image of completed application"/></p>
</li>
<li><p>The application starts up, a splash screen is displayed, and then your application is shown.
Paint something, as shown below:</p>
<p><img src="../images/tutorials/paintapp/73/result-2.png" alt="image of completed application"/></p>
</li>
<li><p>Use the application and try to identify areas where you'd like to provide
more functionality.</p>
</li>
</ol>
</div>
</div>
<div class="indent">
<h3 class="tutorial"><a name="brand"></a>Branding the Application</h3>
<div class="indent">
<ol>
<li><p>Right-click the application and choose Branding.</p></li>
<li><p>The Branding Window is shown, use it to change icons, the splash screen, the window features,
and the strings displayed in the application:</p>
<p><img src="../images/tutorials/paintapp/73/brand-1.png" alt="image of completed application"/></p>
</li>
</ol>
</div>
</div>
<div class="indent">
<h3 class="tutorial"><a name="package"></a>Packaging the Application</h3>
<div class="indent">
<ol>
<li><p>Right-click the application and choose Package as:</p>
<p><img src="../images/tutorials/paintapp/73/dist-1.png" alt="image of completed application"/></p>
</li>
<li><p>Choose the distribution mechanism relevant to your business needs and
your user requirements.</p>
</li>
<li><p>Switch to the Files window (Ctrl-2) to see the result.</p>
</li>
</ol>
</div>
</div>
<p>That's it! You have completed the Paint Application. You have learned how to set up a NetBeans
Platform application and how to create a new
window that displays something to the user.</p>
<p>Next, you are recommended to work through the <a href="https://platform.netbeans.org/tutorials/nbm-crud.html">NetBeans Platform CRUD Application Tutorial</a>, which
will teach you how to create a business-oriented NetBeans Platform application that interacts with a database.</p>
<div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&amp;subject=Feedback: NetBeans Platform Paint Application Tutorial 7.3">Send Us Your Feedback</a></div>
</body>
</html>