blob: b50cc178c044c7e9c9cf21bb9bd8ef7f91986b2a [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<!-- -*- xhtml -*- -->
<title>Platform Plugin Quick Start</title>
<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 http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="description"
content="A guide describing how to implement a
Google Toolbar Module in NetBeans IDE 7.3.">
<link rel="stylesheet" type="text/css" href="https://netbeans.org/netbeans.css">
</head>
<!-- Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. -->
<!-- Use is subject to license terms.-->
<body>
<h1><a name="top"></a>NetBeans Platform Plugin Quick Start</h1>
<p>Welcome to NetBeans plugin development!
<p>This tutorial provides a simple and quick introduction to
the NetBeans plugin development workflow by walking you through the creation
of a new toolbar for any NetBeans Platform application. Once you are done with this tutorial, you
will have a general understanding of how to create, build, and install
plugins for the NetBeans Platform.
<p class="tips">After you finish this tutorial, you can move on to the
<a href="https://netbeans.org/kb/trails/platform.html">NetBeans Platform learning trail</a>.
The learning trail provides comprehensive tutorials
that highlight a wide range of NetBeans APIs for a variety of application types.
If you do not need to do a "Hello World" tutorial, you can skip the instructions
that follow and jump straight to the learning trail.
<p><b class="notes">Note:</b> This document uses NetBeans IDE 7.3 and NetBeans Platform 7.3. If you
are using an earlier version, see <a href="72/nbm-google.html">the previous version
of this document</a>.</p>
<p><b>Contents</b></p>
<p><img src="../images/articles/74/netbeans_stamp_74_73.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="#creating-module-project">Setting Up the Module Project</a></li>
<li><a href="#coding-module">Coding the Module</a>
<ul>
<li><a href="#creating-action">Creating the Action</a></li>
<li><a href="#creating-panel">Creating the Toolbar</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 7 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/GoogleToolbar">completed tutorial source code</a>.</p>
<p>The toolbar you create in this tutorial will
look as follows:</p>
<img src="../images/tutorials/google/70/google-result.png" border="1"
alt="Google toolbar displaying sample search string">
<p><p>When the user presses Enter in the toolbar above, the IDE's default
browser opens and the text in the toolbar is sent to a Google search,
with the results available in the open browser.</p>
<p>To create this toolbar, you
will use the <a href="http://bits.netbeans.org/dev/javadoc/">NetBeans APIs</a> to enhance
the NetBeans Platform's feature set. Specifically, you will create and register an action invoked by
a button created by the NetBeans Platform in the toolbar. You will then create
a <tt>JPanel</tt> containing a <tt>JLabel</tt>
and <tt>JTextField</tt> as GUI components.
Finally, you will implement <a href="http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/actions/Presenter.Toolbar.html"><tt>Presenter.Toolbar</tt></a> to
return the <tt>JPanel</tt> so that it displays in the toolbar, instead of the button.
<p class="tips"> Do some background reading before diving into
this tutorial. In particular, read the <a href="http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html">Modules API Reference</a> document,
which explains what modules are and provides some
context for this tutorial. Also note that there is an extensive Reference Material section
on the <a href="https://netbeans.org/kb/trails/platform.html">NetBeans Platform Learning Trail</a>.</p>
<!-- ===================================================================================== -->
<br>
<h2 class="tutorial"><a name="creating-module-project"></a>Setting up the Module Project</h2>
<p>We begin by creating the source structure common to all NetBeans Platform modules. Read the <a href="http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html">Modules API Reference</a> for details.</p>
<div class="indent">
<ol>
<li>Choose File &gt; New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules.
Under Projects, select Module:
<br><br>
<img src="../images/tutorials/google/73/new-project-0.png" alt="Step 0 of New Project wizard">
<br><br>
<p>The difference between the 4 templates above is as follows:</p>
<br/>
<ul>
<li>
<b>NetBeans Platform Application.</b> A project that groups a set of
module projects and library wrapper module projects that have dependencies on
each other, and lets you deploy them together as a unit. Automatically included
are a subset of the modules that make up the NetBeans Platform.</li>
<li>
<b>Module Suite.</b> Same as above, except that the pre-included modules are
more than only those relating to the NetBeans Platform&#8212;in this case,
all the modules that make up NetBeans IDE are included as well.</li>
<li>
<b>Library Wrapper Module.</b> A project that puts a library JAR file on its classpath and exports some or all of the JAR file's packages from the module as public packages.</li>
<li>
<b>Module.</b> A project for implementing the functionality, business logic, and user interface of a module or application built on the NetBeans Platform.</li>
</ul>
Click Next.</li>
<li>In the Name and Location panel:<br><br>
<ul><li>In the Project Name field, type <tt>GoogleToolbar</tt>.</li>
<li>In the Project Location field, change the value to any directory on your computer where
the module will be stored.</li></ul>
<p>If you see the below, click Next.
<br><br>
<img src="../images/tutorials/google/73/new-project-1.png" alt="Step 1 of New Project wizard">
<br><br>
</li>
<li>In the Basic Module Configuration panel:<br><br>
<ul><li>Type <tt>org.myorg.googletoolbar</tt>
in "Code Name Base", which defines the unique string identifying the
module you are creating. The code name base is also used as the main
package of the module, i.e., your main package will be "org.myorg.googletoolbar".
<li>Do not select the "Generate OSGi Bundle" checkbox, since we
will be using the default NetBeans module system, rather than OSGi.</ul>
<br>
<img src="../images/tutorials/google/73/new-project-2.png" alt="Step 2 of New Project wizard">
<br><br>
If you see the above, click Finish.</li>
</ol>
</div>
<p>The IDE creates the <tt>GoogleToolbar</tt> project:
<br><br>
<img src="../images/tutorials/google/73/new-project-3.png" alt="Step 3 of New Project wizard">
</p>
<p>A "project" is
a NetBeans IDE compilation/deployment unit. It contains a Build Script, as shown above,
which on disk is named "build.xml"
file. This is an Ant script for compiling and running the project.
The project contains all of your sources. 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).</p>
<p>If you expand the Important Files node, you can open the Module Manifest, shown above, which has
this content:</p>
<pre class="examplecode">Manifest-Version: 1.0
OpenIDE-Module: org.myorg.googletoolbar
OpenIDE-Module-Localizing-Bundle: org/myorg/googletoolbar/Bundle.properties
OpenIDE-Module-Specification-Version: 1.0</pre>
<p>For details on these NetBeans-specific manifest keys, read the <a href="http://bits.netbeans.org/dev/javadoc/org-openide-modules/org/openide/modules/doc-files/api.html">NetBeans Modules API</a> Javadoc description.
</p>
<!-- ===================================================================================== -->
<br>
<h2><a name="coding-module"></a>Coding the Module</h2>
<p>In order to create a Google toolbar, you need to complete the following steps:</p>
<ul>
<li><a href="#creating-action">Create the Action</a></li>
<li><a href="#creating-panel">Create the Toolbar</a></li>
</ul>
<div class="indent">
<h3 class="tutorial"><a name="creating-action"></a>Creating the Action</h3>
<p>In this section, you use the New Action wizard in NetBeans IDE to create a new Action.
An Action is a piece of code invoked by the user to do something
in the application. An Action can be invoked from a menu item, toolbar button,
and keyboard shortcut in the application.</p>
<p class="notes"><b>Note:</b> As you will see,
the New Action wizard creates a Java class with annotations. At compile-time,
the annotations are converted into XML elements in a file contributed
to the virtual filesystem of the application, which is how an Action is
registered in the application. For many questions and answers
relating to the creation and registration of Actions in the NetBeans Platform, see <a href="http://wiki.netbeans.org/NetBeansDeveloperFAQ#Actions:_How_to_add_things_to_Files.2C_Folders.2C_Menus.2C_Toolbars_and_more">Actions: How to add things to Files, Folders, Menus, Toolbars and more</a>
in the <a href="http://wiki.netbeans.org/NetBeansDeveloperFAQ">NetBeans Platform Wiki</a>.
<div class="indent">
<ol>
<li>Right-click the GoogleToolbar project node and choose New &gt; Action. If Action is not displayed, access it by
choosing Other, then in the New File wizard under Categories, select Module Development
and then Action:
<br><br>
<img src="../images/tutorials/google/73/new-action-0.png" alt="Step 1 of New Action wizard">
<br><br>
Click Next.</li>
<li>In the Action Type panel:
<br><br>
<ul><li>Keep the default setting, which will let the Action be unconditionally enabled,
as shown below.</li></ul>
<br>
<img src="../images/tutorials/google/73/new-action-1.png" alt="Step 1 of New Action wizard">
<br><br>
Click Next.
<li>In the GUI Registration panel:
<br><br>
<ul>
<li>Select File from the Category drop-down list. The Category drop-down
list controls where an action is shown in the Keyboard Shortcuts editor in the IDE.</li>
<li>Deselect
Global Menu Item because we will not need a menu item.</li>
<li>Select Global Toolbar Button. In the Toolbar drop-down list, select File, then
in the Position drop-down list, select the toolbar button's position within the toolbar, such as
the one shown below.</li></ul>
<br>
<img src="../images/tutorials/google/73/new-action-2.png" alt="Step 1 of New Action wizard">
<br><br>
Click Next.
<li><p>In the Name, Icon, and Location panel:
<br><br>
<ul><li>In the Class Name field, type <tt>GoogleActionListener</tt></li>
<li>In the Display Name field, type <tt>Google</tt></li>
<li>In the Icon field, browse to an icon that has a dimension of 16x16 pixels.
<br><br>
<p class="tips">If needed, here are two icons you can use:</p>
<ul><li>16x16: <img src="../images/tutorials/google/70/google.png" alt="16x16"></li>
<li>24x24: <img src="../images/tutorials/google/70/google24.png" alt="24x24"></li></ul>
<p>However,
note that in the end, you will not use the icon at all once you have created the toolbar&#8212;instead, you will display
the JPanel that you create in the next
section. </p>
</li></ul>
<p>The Name, Icon, and Location panel of the New Action wizard should now look like this:</p>
<br>
<img src="../images/tutorials/google/73/new-action-3.png" alt="Step 1 of New Action wizard">
</li>
<li><p>
Click Finish. The module source structure is now as follows:
<br><br>
<img src="../images/tutorials/google/73/new-action-4.png" alt="Step 1 of New Action wizard">
<br><br>
<p><tt>GoogleActionListener.java</tt>, which you should see in the Projects window, has this content:
<pre class="examplecode">package org.myorg.googletoolbar;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
import org.openide.awt.ActionRegistration;
import org.openide.util.NbBundle.Messages;
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionID.html">@ActionID</a>(
category = "File",
id = "org.myorg.googletoolbar.GoogleActionListener")
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionRegistration.html">@ActionRegistration</a>(
iconBase = "org/myorg/googletoolbar/google.png",
displayName = "#CTL_GoogleActionListener")
<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-util/org/openide/util/NbBundle.Messages.html">@Messages</a>("CTL_GoogleActionListener=Google")
public final class GoogleActionListener implements ActionListener {
@Override
public void actionPerformed(ActionEvent e) {
// TODO implement action body
}
}</pre>
<p class="notes"><b>Note:</b> When you build the module, which is done automatically in the next step
when you run the module, the class annotations
that you see above will be converted to XML tags in a file
that will be contributed to the virtual filesystem of
the application. The XML file will be named "generated-layer.xml" and
will be found in the "build\classes\META-INF"
folder of your module, which you can see if the Files window (Ctrl-2)
is open in the IDE. This file is created at compile-time and contains
XML entries generated from the NetBeans annotations that you have defined in
your Java classes. Together with the "layer.xml" file that your module can
optionally provide, the "generated-layer.xml" file defines the contributions
that the module makes to the virtual filesystem. Read about the virtual filesystem <a href="http://wiki.netbeans.org/DevFaqSystemFilesystem">here</a>,
in the <a href="http://wiki.netbeans.org/NetBeansDeveloperFAQ">NetBeans
Platform Wiki</a>. Aside from the javadoc link above, also
see <a href="https://blogs.oracle.com/geertjan/entry/messages">this article</a> for more information on the @Messages annotation.</p>
</li>
<li>In the Projects window, right-click the <tt>GoogleToolbar</tt> project node and choose Run.
The module is built and installed in a new instance of the IDE (which is currently set to be the target
platform). By default, the default target platform is the version of the IDE you are currently working
in. The target platform opens so that you can try out the new module. You should
be able to see your button and click it:
<br><br>
<img src="../images/tutorials/google/73/result-1.png" border="1"
alt="Google toolbar displaying sample search string"></li>
</ol>
</div>
<p>In the next section, you change the <tt>JButton</tt> that has been created
for you in the toolbar by the NetBeans Platform with your own <tt>JComponent</tt>.</p>
<h3 class="tutorial"><a name="creating-panel"></a>Creating the Toolbar</h3>
<p>In this section, you create a <tt>JPanel</tt> that will replace
the <tt>JButton</tt> that the NetBeans Platform created for you
in the previous section.
<div class="indent">
<ol>
<li>Right-click the project node and choose New &gt; Other. Under Categories, select Swing GUI Forms.
Under File Types, select JPanel Form:
<br><br>
<p><img src="../images/tutorials/google/73/new-toolbar-0.png" alt="resized JPanel"/></p>
<br><p>Click Next.</p></li>
<li>In the Name and Location panel, type <tt>GooglePanel</tt> as the Class Name and select the package
from the drop-down list:
<br><br>
<p><img src="../images/tutorials/google/73/new-toolbar-1.png" alt="resized JPanel"/></p>
<br><p>Click Finish. <tt>GooglePanel.java</tt> is added to the package and is
opened in the Design view in the Source Editor.</p></li>
<li>Place the cursor at the bottom right-hand corner of the JPanel, then select the JPanel and drag the
cursor to resize it, so that its width and length resemble that of a toolbar, as shown below:
<br><br>
<img src="../images/tutorials/google/73/new-toolbar-2.png" border="1" alt="resized JPanel"></li>
<li>Drag a <tt>JTextField</tt> item and a <tt>JLabel</tt> item from the Palette (Ctrl+Shift+8) directly into the <tt>JPanel</tt>,
then resize the <tt>JPanel</tt> and the other two items so that they fit snugly together. Finally, press F2 on the
<tt>JLabel</tt> and change its text to <tt>Google:</tt>, then delete the default text in the <tt>JTextField</tt>. (If
you click F2 over the <tt>JLabel</tt> and the <tt>JTextField</tt>, their display text will become editable.)
Your <tt>JPanel</tt> should now resemble the image shown below:
<br><br>
<img src="../images/tutorials/google/73/new-toolbar-3.png" border="1"
alt="JTextField and JLabel included in JPanel"></li>
<li>Double-click on the JTextField (or right-click on it and choose Events &gt; Action &gt; actionPerformed). This generates a
<tt>jTextField1ActionPerformed()</tt>
method in the <tt>GooglePanel.java</tt> source code, which displays in the Source Editor.
Fill out the
<tt>jTextField1ActionPerformed</tt> method as follows (inserted text shown in <strong>bold</strong>):
<pre class="examplecode">private void jTextField1ActionPerformed(java.awt.event.ActionEvent evt) {
<b>
try {
String searchText = URLEncoder.encode(jTextField1.getText(), "UTF-8");
URLDisplayer.getDefault().showURL
(new URL(&quot;http://www.google.com/search?hl=en&amp;q=&quot;+searchText+&quot;&amp;btnG=Google+Search&quot;));
} catch (Exception eee){
return;//nothing much to do
}
</b>
}</pre>
<p>If you need to, right-click in the Source Editor and choose Format (Alt+Shift+F).</p></li>
<li>Right-click in the Source Editor and choose Fix Imports (Ctrl+Shift+I). The Fix All Imports dialog
displays, listing suggested paths for unrecognized classes:
<br><br>
<img src="../images/tutorials/google/73/new-toolbar-4.png"
alt="Fix All Imports dialog containing suggested paths for unrecognized classes">
<br><br>
Click OK. The IDE creates the following import statements at the top of the class:
<pre>import java.net.URL;
import java.net.URLEncoder;
import <a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/HtmlBrowser.URLDisplayer.html">org.openide.awt.HtmlBrowser.URLDisplayer</a>;</pre>
Also notice that all errors disappear from the Source Editor.</li>
<li><p>Because the <tt>JPanel</tt> you have created is the component that will be rendered in the toolbar,
you need
to implement <tt><a href="http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/actions/Presenter.Toolbar.html">Presenter.Toolbar</a></tt>
in the <tt>ActionListener</tt> you created earlier, in order to display the <tt>JPanel</tt>
in the toolbar. Change the signature of Open <tt>GoogleActionListener.java</tt>. so
that <tt><a href="http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/actions/Presenter.Toolbar.html">Presenter.Toolbar</a></tt> is implemented.
When using <tt>Presenter.Toolbar</tt>, you need to extend <tt>AbstractAction</tt>, instead of
implementing <tt>ActionListener</tt>. Also, you can
delete the "iconBase" attribute (as well as the icons from the source tree)
because you no longer need an icon in this scenario. </p>
<br><p>The result
of these changes is as follows:</p>
<pre class="examplecode">package org.myorg.googletoolbar;
import java.awt.Component;
import java.awt.event.ActionEvent;
import javax.swing.AbstractAction;
import org.openide.awt.ActionID;
import org.openide.awt.ActionReference;
import org.openide.awt.ActionRegistration;
import org.openide.util.actions.Presenter;
@ActionID(
category = "File",
id = "org.myorg.googletoolbar.GoogleActionListener")
@ActionRegistration(
<a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/ActionRegistration.html#lazy()">lazy = false</a>,
displayName = "NOT-USED")
@ActionReference(
path = "Toolbars/File",
position = 0)
public final class GoogleActionListener extends AbstractAction implements Presenter.Toolbar {
@Override
public Component getToolbarPresenter() {
return new GooglePanel();
}
@Override
public void actionPerformed(ActionEvent e) {
//delegated to toolbar
}
}</pre>
</li>
<li>Run the module again. This time, instead of a <tt>JButton</tt>, you
should see your <tt>JPanel</tt>. Type a search string in the text field:
<br><br>
<p><img src="../images/tutorials/google/73/result-2.png"
alt="Google toolbar displaying sample search string"></p>
<br>
<p>Press Enter. The IDE's default browser starts up, if you have set one
in the Options window. Above, the embedded browser is shown in action.
The Google URL and your search string are sent to the
browser and a search is performed. When the search results are returned, you can view them in the browser.</p></li>
</ol>
</div>
</div>
<p>In this section, you have created a <tt>JPanel</tt> that displays a <tt>JTextField</tt>
and a <tt>JLabel</tt>. You have presented it in the NetBeans toolbar, thanks to
the <tt>Presenter.Toolbar</tt> class. When the user presses Enter in
the <tt>JTextField</tt>, its content
is sent to a Google search. The HTML browser opens and you
see the result of the Google search. The <tt>ActionListener</tt> is used
to integrate the <tt>JPanel</tt> within the application's toolbar, as registered
via the annotations in the <tt>ActionListener</tt>.
<br>
<div class="feedback-box"><a name="feedback"></a>
<a href="https://netbeans.org/about/contact_form.html?to=3&amp;subject=Feedback:%20NetBeans%20Plugin%20Quick%20Start%207.3">
Send Us Your Feedback</a></div>
<br style="clear:both;" />
<!-- ======================================================================================== -->
<h2><a name="nextsteps"></a>See Also</h2>
<p>This concludes the NetBeans Plugin Quick Start. This document has described
how to create a plugin that adds a Google Search toolbar to the IDE.
For more information about creating and developing plugins, see the following resources:
<ul>
<li><a href="https://netbeans.org/kb/trails/platform.html">NetBeans Platform Learning Trail</a></li>
<li><a href="http://bits.netbeans.org/dev/javadoc/">NetBeans API Javadoc</a></li>
<li>NetBeans API classes used in this tutorial:
<ul>
<li><tt><a href="http://bits.netbeans.org/dev/javadoc/org-openide-awt/org/openide/awt/HtmlBrowser.URLDisplayer.html">HtmlBrowser.URLDisplayer</a></tt>
<li><tt><a href="http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/actions/Presenter.Toolbar.html">Presenter.Toolbar</a></tt>
</ul>
</li>
</ul>
<!-- ======================================================================================== -->
</body>
</html>