<!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>NetBeans Editor Component Palette Module Tutorial for NetBeans Platform 7.1</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 short guide to using the Palette API to create a new palette."/> | |
<!-- Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved. --> | |
<!-- Use is subject to license terms.--> | |
</head> | |
<body> | |
<h1>NetBeans Editor Component Palette Module Tutorial</h1> | |
<p>This tutorial demonstrates how to create a component palette that provides drag-and-drop code snippets | |
for a new file type. Code snippets serve to speed up coding. The IDE provides a component palette for JSP files, | |
HTML files, and Form files. In this tutorial, you learn how to create a component palette for Java source files.</p> | |
<p><strong class="notes">Note: </strong>This document uses NetBeans Platform 7.1 | |
and NetBeans IDE 7.1. If you | |
are using an earlier version, see <a href="../70/nbm-palette-api2.html">the previous version | |
of this document</a>.</p> | |
<p><b>Contents</b></p> | |
<p><img src="../../images/articles/71/netbeans-stamp.png" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 7.1" title="Content on this page applies to NetBeans IDE 7.1"/></p> | |
<ul class="toc"> | |
<li><a href="#intro">Introduction to Component Palettes</a></li> | |
<li><a href="#creatingthemoduleproject">Setting Up the Module Project</a></li> | |
<li><a href="#coding-module">Creating the Component Palette and Code Snippets</a> | |
<ul> | |
<li><a href="#deps">Specifying the Module's Dependencies</a></li> | |
<li><a href="#creating-palettes">Creating the Component Palette</a></li> | |
<li><a href="#adding-drag-handler">Adding a DragAndDropHandler</a></li> | |
<li><a href="#creating-snippets">Creating the Code Snippets</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.1</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 </td> | |
</tr> | |
</tbody> | |
</table> | |
<h2 class="tutorial"><a name="intro"></a>Introduction to Component Palettes</h2> | |
<p>In this tutorial, you implement several classes provided by the | |
<a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html">NetBeans Palette API</a>. | |
Then you register the new component palette in the <tt>layer.xml</tt> file, for the <tt>text/x-java</tt> | |
MIME type. The palette that you create in this way will only be visible if a Java source file | |
is open.</p> | |
<p class="tips">If you do not want to create a new component palette, but only want to add a code snippet to an existing component palette, | |
see the <a href="nbm-palette-api1.html">NetBeans Code Snippet Module Tutorial</a>.</p> | |
<!-- | |
<div class="indent"> | |
<h3 class="tutorial"><a name="installing-sample"></a>Getting to Know the Sample</h3> | |
<p>Take the following steps to install the sample:</p> | |
<ol><li><a href="http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=2761">Download the completed sample</a> | |
from the Plugin Portal and install it in the IDE.</li> | |
<li>In the New Project wizard, you will find the sample here: | |
<p><img src="../../images/tutorials/componentpalette/65-new-proj-dialog.png" alt="New Project dialog"/></p></li> | |
<li>Complete the wizard and your project source structure will be as follows: | |
<p><img src="../../images/tutorials/componentpalette/65-new-proj-wiz.png" alt="Projects window initially"/></p></li> | |
<li>Right-click the project node and choose Run. A new instance of the IDE opens and the module is installed.</li> | |
<li>Verify that the module is correctly installed by opening a Java source file. You | |
should now see your new Java source file palette, containing one item: | |
<p><img src="../../images/tutorials/componentpalette/65-open-java-file.png" alt="" alt="Open Java source file"/></p></li> | |
<li>Drag the item into the Java source file and, when you drop the item, you will see the related customizer: | |
<p><img src="../../images/tutorials/componentpalette/65-customizer-in-java-file.png" alt="Customizer"/></p></li> | |
<li>When you complete the customizer, you will have a new main method, together with the | |
comment you typed in the customizer: | |
<p><img src="../../images/tutorials/componentpalette/65-dropped-main-method.png" alt="" alt="Dropped main method"/></p></li> | |
</ol> | |
<p>Now that you know what the end result looks like, you will create the module from scratch and learn about each part | |
while creating it.</p> | |
</div> | |
--> | |
<!-- ===================================================================================== --> | |
<h2 class="tutorial"><a name="creatingthemoduleproject"></a>Setting up the Module Project</h2> | |
<p>Before you start writing the module, you have to make sure you | |
that your project is set up correctly. The IDE provides a wizard that sets up all the basic files | |
needed for a module.</p> | |
<ol> | |
<li>Choose File > New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules. | |
Under Projects, select Module. Click Next.</li> | |
<li>In the Name and Location panel, type <tt>JavaSourceFilePalette</tt> in the Project Name field. | |
Change the Project Location to any directory on your computer. Click Next.</li> | |
<li>In the Basic Module Configuration panel, type <tt>org.netbeans.modules.javasourcefilepalette</tt> | |
in Code Name Base. Click Finish.</li> | |
</ol> | |
<p> The IDE creates the <tt>JavaSourceFilePalette</tt> | |
project. 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).</p> | |
<!-- ===================================================================================== --> | |
<h2><a name="coding-module"></a>Creating the Component Palette and Code Snippets</h2> | |
<div class="indent"> | |
<h3 class="tutorial"><a name="deps"></a>Specifying the Module's Dependencies</h3> | |
<p>You will need to subclass several classes that belong to <a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans APIs</a>. | |
Each has to be declared as a module dependency. | |
Use the Project Properties dialog box for this | |
purpose, as described below.</p> | |
<ol> | |
<li>In the Projects window, right-click the <tt>JavaSourceFilePalette</tt> project node and choose Properties. | |
In the Project Properties dialog box, click Libraries.</li> | |
<li><p>For each of the following APIs, click "Add...", | |
select the name from the Module list, and then click OK to confirm it:</p> | |
<p></p> | |
<ul> | |
<li>Common Palette</li> | |
<li>Dialogs API</li> | |
<li>Lookup API</li> | |
<li>MIME Lookup API</li> | |
<li>Nodes API</li> | |
<li>Text API</li> | |
<li>UI Utilities API</li> | |
<li>Utilities API</li> | |
</ul> | |
</li> | |
<li>Click OK to exit the Project Properties dialog box.</li> | |
<li>In the Projects window, expand the Important Files node, double-click the Project Metadata node, and note the | |
long list of APIs that you selected have been | |
declared as module dependencies.</li> | |
</ol> | |
<h3 class="tutorial"><a name="creating-palettes"></a>Creating the Component Palette</h3> | |
<p>Component Palettes are defined | |
by the <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html">NetBeans Palette API</a>. | |
Implementing the NetBeans Palette API for this tutorial means implementing the following NetBeans Palette API classes:</p> | |
<table width="76%" border="1"> | |
<tbody><tr> | |
<td> | |
<b>File</b> | |
</td> | |
<td> | |
<b>Description</b> | |
</td> | |
</tr> | |
<tr> | |
<td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFactory.html">PaletteFactory</a></tt></td> | |
<td>Creates a new instance of the Component Palette. To do so, it invokes | |
the <tt>createPalette</tt> method which creates a new palette from a specified folder | |
registered in the <tt>layer.xml</tt>.</td> | |
</tr> | |
<tr> | |
<td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteController.html">PaletteController</a></tt></td> | |
<td>Provides access to data in the Component Palette.</td> | |
</tr> | |
<tr> | |
<td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteActions.html">PaletteActions</a></tt></td> | |
<td>Provides the actions on the palette, categories, and items in the palette. | |
</td> | |
</tr> | |
</tbody> | |
</table> | |
<p>To use the Palette API to create the palette in this tutorial, take the following steps:</p> | |
<ol> | |
<li>Right-click the <tt>JavaSourceFilePalette</tt> project node and | |
choose New > Java Class. Create a Java file called <tt>JavaSourceFileLayerPaletteFactory</tt>.</li> | |
<li>Replace the default content of the <tt>JavaSourceFileLayerPaletteFactory.java</tt> file with the following: | |
<pre class="examplecode">public class JavaSourceFileLayerPaletteFactory { | |
//Name of the folder in the layer.xml file | |
//that is the root of the palette: | |
public static final String JAVA_PALETTE_FOLDER = "JavaPalette"; | |
private static PaletteController palette = null; | |
//Register the palette for the text/x-java MIME type: | |
@MimeRegistration(mimeType = "text/x-java", service = PaletteController.class) | |
public static PaletteController createPalette() { | |
try { | |
if (null == palette) | |
palette = PaletteFactory.createPalette( | |
JAVA_PALETTE_FOLDER, | |
new MyActions()); | |
return palette; | |
} catch (IOException ex) { | |
Exceptions.printStackTrace(ex); | |
} | |
return null; | |
} | |
private static class MyActions extends PaletteActions { | |
//Add new buttons to the Palette Manager here: | |
@Override | |
public Action[] getImportActions() { | |
return null; | |
} | |
//Add new contextual menu items to the palette here: | |
@Override | |
public Action[] getCustomPaletteActions() { | |
return null; | |
} | |
//Add new contextual menu items for palette categories here: | |
@Override | |
public Action[] getCustomCategoryActions(Lookup arg0) { | |
return null; | |
} | |
//Add new contextual menu items for palette items here: | |
@Override | |
public Action[] getCustomItemActions(Lookup arg0) { | |
return null; | |
} | |
//Define the double-click action here: | |
@Override | |
public Action getPreferredAction(Lookup arg0) { | |
return null; | |
} | |
} | |
}</pre></li> | |
</ol> | |
<h3 class="tutorial"><a name="adding-drag-handler"></a>Adding a DragAndDropHandler</h3> | |
<p>In this section, we change the <tt>PaletteController</tt>, in the code above, and | |
add a <tt>DragAndDropHandler</tt>. In doing so, we will let the user drag code snippets FROM | |
the editor INTO the palette:</p> | |
<pre class="examplecode">@MimeRegistration(mimeType = "text/x-java", service = PaletteController.class) | |
public static PaletteController createPalette() { | |
try { | |
if (null == palette) { | |
<b>//Add null for the PaletteFilter, which we are not using here, | |
//and then instantiate your implementation of the DragAndDropHandler</b>: | |
palette = PaletteFactory.createPalette( | |
JAVA_PALETTE_FOLDER, | |
new MyActions(), | |
<b>null, | |
new MyDragAndDropHandler()</b>); | |
} | |
return palette; | |
} catch (IOException ex) { | |
Exceptions.printStackTrace(ex); | |
} | |
return null; | |
} | |
<b>//Definition of the DragAndDropHandler: | |
private static class MyDragAndDropHandler extends DragAndDropHandler { | |
MyDragAndDropHandler() { | |
super(true); | |
} | |
//Maybe you don't like the default 'add to palette' implementation, | |
//so you could create your own here: | |
@Override | |
public void customize(ExTransferable t, Lookup item) { | |
} | |
}</b></pre> | |
<p>The above default implementation is all you need. Now the user will be able to drag | |
from the editor into the palette.</p> | |
<h3 class="tutorial"><a name="creating-snippets"></a>Creating the Code Snippets</h3> | |
<p>Each code snippet requires the following files:</p> | |
<ul> | |
<li>A Java class that defines the piece of code to be dragged into the Source Editor. This Java class | |
must refer to <tt>JavaSourceFilePaletteUtilities.java</tt>, which defines how the piece of code should be | |
inserted. For example, indentation and formatting are defined here.</li> | |
<li>Optionally, a customizer where the user can type something that will be added to | |
the snippet, such as comments.</li> | |
<li>A properties file that defines the labels and tooltips.</li> | |
<li>A 16x16 pixel image for the 'Small Icon' display.</li> | |
<li>A 32x32 pixel image for the 'Big Icon' display.</li></ul> | |
<p>After you have created or added the above files to the NetBeans module, you declare them in a resource declaration XML file, | |
which you register in the NetBeans | |
System Filesystem by using the <tt>layer.xml</tt> | |
file, as follows:</p> | |
<pre class="examplecode"><folder name="JavaPalette"> | |
<folder name="Items"> | |
<attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.javasourcefilepalette.Bundle"/> | |
<file name="Item.xml" url="resources/Item.xml"> | |
<attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.javasourcefilepalette.Bundle"/> | |
</file> | |
</folder> | |
</folder></pre> | |
<p class="tips">For all the details on the items above, work through the | |
<a href="nbm-palette-api1.html">NetBeans Code Snippet Module Tutorial</a>.</p> | |
</div> | |
<!-- ======================================================================================= --> | |
<h2><a name="building"></a>Building and Installing the Module</h2> | |
<p>The IDE uses an Ant build script to build and install your module. The build script is created for you | |
when you create the module project.</p> | |
<ol> | |
<li><p>In the Projects window, right-click the <tt>JavaSourceFilePalette</tt> project and choose Run. | |
The module is built and installed in the target platform. The target platform opens so that you | |
can try out your new module. The default target platform is the | |
installation used by the current instance of the development IDE.</p></li> | |
<li>Verify that the module is correctly installed by using it.</li> | |
</ol> | |
<div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20Component%20Palette%20Module%207.1%20Tutorial">Send Us Your Feedback</a></div> | |
<!-- ======================================================================================== --> | |
<h2><a name="nextsteps"></a>Next Steps</h2> | |
<p>For more information about creating and developing NetBeans modules, see the following resources: </p> | |
<ul> | |
<li><a href="https://netbeans.org/kb/trails/platform.html">Other Related Tutorials</a></li> | |
<li><a href="http://bits.netbeans.org/dev/javadoc/index.html">NetBeans API Javadoc</a></li> | |
</ul> | |
<!-- ======================================================================================== | |
<h2><a name="version"></a>Versioning </h2> | |
<table width="76%" border="1"> | |
<tbody> | |
<tr> | |
<td> | |
<div align="left"><b>Version</b></div> | |
</td> | |
<td> | |
<div align="left"><b>Date</b></div> | |
</td> | |
<td> | |
<div align="left"><b>Changes</b></div> | |
</td> | |
<td> | |
<div align="left"><b>Open Issues</b></div> | |
</td> | |
</tr> | |
<tr> | |
<td> | |
1 | |
</td> | |
<td> | |
29 November 2005 | |
</td> | |
<td> | |
Initial version | |
</td> | |
<td> | |
<ul> | |
<li>Needs to be reviewed! Use at your own risk! | |
<li>Need to add explanation for adding own dialog box for predefining values. | |
<li>Explanatory text for the use of the NetBeans APIs to be added. | |
<li>Check for copy-paste errors. | |
<li>Need to add more Javadoc links, for NetBeans API classes in the code. | |
</ul> | |
</td> | |
</tr> | |
<tr> | |
<td> | |
2 | |
</td> | |
<td> | |
30 November 2005 | |
</td> | |
<td> | |
<li>Changed the ZIP file because of problems (see <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=69571">Issue 69571</a>). | |
<li>Removed hyphens and changed screenshots. | |
</td> | |
<td> | |
All other issues from above must still be done. | |
</td> | |
</tr> | |
<tr> | |
<td> | |
3 | |
</td> | |
<td> | |
8 December 2005 | |
</td> | |
<td> | |
<li>Fixed reopened issue <a href="https://netbeans.org/bugzilla/show_bug.cgi?id=69571">Issue 69571</a> | |
<td> | |
All other issues from above must still be done. | |
</td> | |
</tr> | |
<tr> | |
<td> | |
4 | |
</td> | |
<td> | |
22 August 2006 | |
</td> | |
<td> | |
<li>Minor tweaks. | |
<td> | |
All other issues from above must still be done. | |
<br>Discovered that the editor support file is missing in the tutorial, | |
but not in the module that you can download from the top of the file. | |
<br>Discovered that there are several gaps and tbds in this tutorial. | |
</td> | |
</tr> | |
<tr> | |
<td> | |
5 | |
</td> | |
<td> | |
30 May 2007 | |
</td> | |
<td> | |
Began updating this tutorial for 6.0. | |
</td> | |
<td> | |
... | |
</td> | |
</tr> | |
<tr> | |
<td> | |
6 | |
</td> | |
<td> | |
5 November 2008 | |
</td> | |
<td> | |
Began & completed updating this tutorial for 6.5. | |
<p>Main changes: | |
<ul> | |
<li>New sample download link to Plugin Portal. | |
<li>Rewritten code to use <tt>layer.xml</tt> registration. | |
<li>Instead of JBoss palette and snippets for JBoss XML file, | |
created a palette for Java source files, which is now | |
possible because editor and palette do not need to be | |
in the same module. Therefore sections like | |
'Recognizing the New File Type' are not necessary (except | |
if the palette is for a new file type, in which case | |
the File Type Module tutorial should first be used). | |
<li>Omitted the code for creating the palette item, because | |
it is already described in the Code Snippet Module Tutorial. | |
</ul> | |
</td> | |
<td> | |
3 August 2009 | |
</td> | |
<td> | |
Fixed broken element tags so that formatting is now correct. | |
</td> | |
<td> | |
19 November 2011 | |
</td> | |
<td> | |
Began updating for 7.1. | |
</td> | |
</tr> | |
</tbody> | |
</table>--> | |
</body> | |
</html> |