<!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.2</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.2 | |
and NetBeans IDE 7.2. If you | |
are using an earlier version, see <a href="71/nbm-palette-api2.html">the previous version | |
of this document</a>.</p> | |
<p><b>Contents</b></p> | |
<p><img src="../images/articles/72/netbeans-stamp.gif" class="stamp" width="114" height="114" alt="Content on this page applies to NetBeans IDE 7.2" title="Content on this page applies to NetBeans IDE 7.2"/></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">Integrating with the Component Palette</a></li> | |
<li><a href="#creating-snippets">Creating the Code Snippets</a></li> | |
</ul></li> | |
<li><a href="#building">Building and Installing the Module</a></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.2</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> | |
<div class="indent"> | |
<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> | |
</div> | |
<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> | |
<div class="indent"> | |
<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> | |
</div> | |
<h3 class="tutorial"><a name="creating-palettes"></a>Integrating with 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 Component Palette API</a>. | |
The NetBeans Component Palette API consists of the following APIs:</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 node or layer folder.</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> | |
<tr> | |
<td align="left" valign="top"><tt><a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFilter.html">PaletteFilter</a></tt></td> | |
<td>Controls whether a category or item is displayed in the palette. | |
</td> | |
</tr> | |
</tbody> | |
</table> | |
<br/><br/> | |
<p>To use the Palette API to create the palette in this tutorial, take the following steps:</p> | |
<div class="indent"> | |
<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">package org.netbeans.modules.javasourcefilepalette; | |
import java.io.IOException; | |
import javax.swing.Action; | |
import <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-editor-mimelookup/org/netbeans/api/editor/mimelookup/MimeRegistration.html">org.netbeans.api.editor.mimelookup.MimeRegistration</a>; | |
import <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/DragAndDropHandler.html">org.netbeans.spi.palette.DragAndDropHandler</a>; | |
import <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteActions.html">org.netbeans.spi.palette.PaletteActions</a>; | |
import <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteController.html">org.netbeans.spi.palette.PaletteController</a>; | |
import <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFactory.html">org.netbeans.spi.palette.PaletteFactory</a>; | |
import org.openide.util.Exceptions; | |
import org.openide.util.Lookup; | |
import org.openide.util.datatransfer.ExTransferable; | |
public class JavaSourceFileLayerPaletteFactory { | |
private static PaletteController palette = null; | |
<a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-editor-mimelookup/org/netbeans/api/editor/mimelookup/MimeRegistration.html">@MimeRegistration</a>(mimeType = "text/x-java", service = PaletteController.class) | |
public static <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteController.html">PaletteController</a> createPalette() { | |
try { | |
if (null == palette) { | |
return <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFactory.html">PaletteFactory</a>.createPalette( | |
<b>//Folder:</b> | |
"JavaPalette", | |
<b>//Palette Actions:</b> | |
new <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteActions.html">PaletteActions</a>() { | |
@Override public Action[] getImportActions() {return null;} | |
@Override public Action[] getCustomPaletteActions() {return null;} | |
@Override public Action[] getCustomCategoryActions(Lookup lkp) {return null;} | |
@Override public Action[] getCustomItemActions(Lookup lkp) {return null;} | |
@Override public Action getPreferredAction(Lookup lkp) {return null;} | |
}, | |
<b>//Palette Filter:</b> | |
null, | |
<b>//Drag and Drop Handler:</b> | |
new <a href="http://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/DragAndDropHandler.html">DragAndDropHandler</a>(true) { | |
@Override public void customize(ExTransferable et, Lookup lkp) {} | |
}); | |
} | |
} catch (IOException ex) { | |
Exceptions.printStackTrace(ex); | |
} | |
return null; | |
} | |
}</pre></li> | |
</ol> | |
</div> | |
<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.</li> | |
<li>Optionally, a customizer where the user can specify 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> | |
<div class="indent"> | |
<ol> | |
<li><p>In the Projects window, right-click the <tt>JavaSourceFilePalette</tt> project | |
and choose Run.</p></li> | |
<li>The IDE opens. Open a Java file. The palette opens at the same time. Drag | |
snippets into the palette, a dialog opens, set a display name and other info, | |
and you'll see your snippet in the palette:<br/><br/> | |
<p><img src="../images/tutorials/palette_api/java-snippets-javafx.png"/></p> | |
</li> | |
</ol> | |
</div> | |
<div class="feedback-box"><a href="https://netbeans.org/about/contact_form.html?to=3&subject=Feedback:%20Component%20Palette%20Module%207.2%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> | |
<td> | |
9 July 2012 | |
</td> | |
<td> | |
Began updating for 7.2. | |
</td> | |
</tr> | |
</tbody> | |
</table>--> | |
</body> | |
</html> |