modules/ROOT/pages/tutorials/nbm-palette-api2.adoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= NetBeans Editor Component Palette Module Tutorial
:page-layout: platform_tutorial
:jbake-tags: tutorials 
:jbake-status: published
:page-syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:icons: font
:experimental:
:description: NetBeans Editor Component Palette Module Tutorial - Apache NetBeans
:keywords: Apache NetBeans Platform, Platform Tutorials, NetBeans Editor Component Palette Module Tutorial

ifdef::env-github[]
:imagesdir: ../../images
endif::[]

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.

// NOTE: If you are using an earlier version of Apache NetBeans, see link:74/nbm-palette-api2.html[the previous version of this document].

For troubleshooting purposes, you are welcome to download the link:http://web.archive.org/web/20170409072842/http://java.net/projects/nb-api-samples/show/versions/8.0/tutorials/palette[completed tutorial source code].

== Introduction to Component Palettes

In this tutorial, you implement several classes provided by the link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html[NetBeans Palette API]. Then you register the new component palette in the  ``layer.xml``  file, for the  ``text/x-java``  MIME type. The palette that you create in this way will only be visible if a Java source file is open.

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 xref:./nbm-palette-api1.adoc[NetBeans Code Snippet Module Tutorial].


== Setting up the Module Project

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.


[start=1]
1. Choose File > New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules. Under Projects, select Module. Click Next.

[start=2]
1. In the Name and Location panel, type  ``JavaSourceFilePalette``  in the Project Name field. Change the Project Location to any directory on your computer. Click Next.

[start=3]
1. In the Basic Module Configuration panel, type  ``org.netbeans.modules.javasourcefilepalette``  in Code Name Base. Click Finish.

The IDE creates the  ``JavaSourceFilePalette``  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).


== Creating the Component Palette and Code Snippets


=== Specifying the Module's Dependencies

You will need to subclass several classes that belong to link:https://bits.netbeans.org/dev/javadoc/index.html[NetBeans APIs]. Each has to be declared as a module dependency. Use the Project Properties dialog box for this purpose, as described below.


[start=1]
1. In the Projects window, right-click the  ``JavaSourceFilePalette``  project node and choose Properties. In the Project Properties dialog box, click Libraries.

[start=2]
1. 
For each of the following APIs, click "Add...", select the name from the Module list, and then click OK to confirm it:

* Common Palette
* Dialogs API
* Lookup API
* MIME Lookup API
* Nodes API
* Text API
* UI Utilities API
* Utilities API

[start=3]
1. Click OK to exit the Project Properties dialog box.

[start=4]
1. 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.


=== Integrating with the Component Palette

Component Palettes are defined by the link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/overview-summary.html[NetBeans Component Palette API]. The NetBeans Component Palette API consists of the following APIs:

|===
|*File* |*Description* 

| `` link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFactory.html[PaletteFactory]``  |Creates a new instance of the Component Palette. To do so, it invokes the  ``createPalette``  method which creates a new palette from a node or layer folder. 

| `` link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteController.html[PaletteController]``  |Provides access to data in the Component Palette. 

| `` link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteActions.html[PaletteActions]``  |Provides the actions on the palette, categories, and items in the palette. 

| `` link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFilter.html[PaletteFilter]``  |Controls whether a category or item is displayed in the palette. 
|===


To use the Palette API to create the palette in this tutorial, take the following steps:


[start=1]
1. Right-click the  ``JavaSourceFilePalette``  project node and choose New > Java Class. Create a Java file called  ``JavaSourceFileLayerPaletteFactory`` .

[start=2]
1. Replace the default content of the  ``JavaSourceFileLayerPaletteFactory.java``  file with the following:

[source,java,subs="macros,quotes"]
----

package org.netbeans.modules.javasourcefilepalette;

import java.io.IOException;
import javax.swing.Action;
import link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-editor-mimelookup/org/netbeans/api/editor/mimelookup/MimeRegistration.html[org.netbeans.api.editor.mimelookup.MimeRegistration];
import link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/DragAndDropHandler.html[org.netbeans.spi.palette.DragAndDropHandler];
import link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteActions.html[org.netbeans.spi.palette.PaletteActions];
import link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteController.html[org.netbeans.spi.palette.PaletteController];
import link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFactory.html[org.netbeans.spi.palette.PaletteFactory];
import org.openide.util.Exceptions;
import org.openide.util.Lookup;
import org.openide.util.datatransfer.ExTransferable;

public class JavaSourceFileLayerPaletteFactory {

    private static PaletteController palette = null;

    link:https://bits.netbeans.org/dev/javadoc/org-netbeans-modules-editor-mimelookup/org/netbeans/api/editor/mimelookup/MimeRegistration.html[@MimeRegistration](mimeType = "text/x-java", service = PaletteController.class)
    public static link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteController.html[PaletteController] createPalette() {
        try {
            if (null == palette) {
                return link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteFactory.html[PaletteFactory].createPalette(
                *//Folder:*
                "JavaPalette", 
                *//Palette Actions:*
                new link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteActions.html[PaletteActions]() {
                    @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;}
                }, 
                *//Palette Filter:*
                null, 
                *//Drag and Drop Handler:*
                new link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/DragAndDropHandler.html[DragAndDropHandler](true) {
                    @Override public void customize(ExTransferable et, Lookup lkp) {}
                });
            }
        } catch (IOException ex) {
            Exceptions.printStackTrace(ex);
        }
        return null;
    }

}
----


=== Creating the Code Snippets

Each code snippet requires the following files:

* A Java class that defines the piece of code to be dragged into the Source Editor.
* Optionally, a customizer where the user can specify something that will be added to the snippet, such as comments.
* A properties file that defines the labels and tooltips.
* A 16x16 pixel image for the 'Small Icon' display.
* A 32x32 pixel image for the 'Big Icon' display.

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  ``layer.xml``  file, as follows:


[source,xml]
----

<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>
----

The above can be generated automatically for you if you use the link:https://bits.netbeans.org/dev/javadoc/org-netbeans-spi-palette/org/netbeans/spi/palette/PaletteItemRegistration.html[@PaletteItemRegistration] annotation, as shown below, in a  ``package-info.java``  class:


[source,java,subs="macros"]
----

@PaletteItemRegistration(
         paletteid = "JavaPalette", 
         category = "Items", 
         itemid = "Comment", 
         icon32 = "org/netbeans/modules/javasourcefilepalette/BR32.png", 
         icon16 = "org/netbeans/modules/javasourcefilepalette/BR16.png", 
         body = "// new comment", 
         name = "New Comment", 
         tooltip = "// new comment")
package org.netbeans.modules.javasourcefilepalette;

import org.netbeans.spi.palette.PaletteItemRegistration;
----

For all the details on the information referred to in this subsection, work through the xref:./nbm-palette-api1.adoc[NetBeans Code Snippet Module Tutorial].


== Building and Installing the Module

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.


[start=1]
1. In the Projects window, right-click the  ``JavaSourceFilePalette``  project and choose Run.


[start=2]
1. 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:


image::tutorials/palette_api_java-snippets-javafx.png[]

xref:front::community/mailing-lists.adoc[Send Us Your Feedback]


== Next Steps

For more information about creating and developing NetBeans modules, see the following resources:

* xref:../kb/docs/platform.adoc[Other Related Tutorials]
* link:https://bits.netbeans.org/dev/javadoc/index.html[NetBeans API Javadoc]