Overview (NetBeans Palette API) - NetBeans API Javadoc 5.5.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.netbeans.spi.palette/1 1.6.1

PREV NEXT

FRAMES NO FRAMES

NetBeans Palette API

See:
Description

Palette API

org.netbeans.spi.palette

Palette API
org.netbeans.spi.palette

The API provides access to the Common Component Palette. The palette clients can use this API to define content to be displayed in the common palette TopComponent when their editors are active. The module will autoload. Palette

The API includes support for the clients writing palette content insertable into the text editor.
This support covers the DTD definition of the palette item definition file format and the content of the Lookup holding object(s) representing the selected item. editor-palette-item-1_0.dtd

What is New (see all changes)?

Sep 26 '06 Added helpId attribute

Now it's possible to add helpId attribute to palette's root, categories and items that will be used to create appropriate HelpCtx. The attribute can be specified in XML layer as a folder (palette's root and categories) or file attribute (palette items) or it can be provided directly by appropriate Nodes.

When F1 key is pressed in palette's window then first the selected item is asked for HelpCtx id. If no item is selected or it does not provide specific help id then selected category is checked for help id. If the category does not provide any help id either then palette's root is asked for help id. If the root does not define any then the default help id CommonPalette will be used.
Jun 7 '06 The Common Palette API has been stabilized.

To indicate that this is now considered a stable API, the major release version was incremented to 1 from 0.
Sep 13 '05 Added support for default drag and drop operations
The abstract class DragAndDropHandler now provides default implementation for all drag and drop operations. The only method that needs to be overridden is void customize( ExTransferable t, Lookup item ) to provide custom data flavors for items dragged from the palette to editor.
There are also new methods (and their default implementations) in this class that handle reordering of categories and reordering of items (i.e. drag and drop operations withing the palette window).
Aug 10 '05 Palette client support released
The first release of the Palette client support. It involves namely DTD describing item definition file format and some implementation addons regarding definition file parsing and custom implementation class loading. The palette item implementor can either directly provide the item body or her own item class implementing org.openide.text.ActiveEditorDrop interface. Lookup that holds object(s) representing the selected item then associates custom item class instance with the org.openide.text.ActiveEditorDrop.class key and the body with java.lang.String key.
Aug 9 '05 Added a new optional attribute that can specify the width of items in the palette.
There's a new attribute "itemWidth" that can be set for palette's root node (or for palette's root folder in the layer). This attribute defines the width in pixels for all items in the palette thus forcing the same number of columns for all categories. If the attribute is omitted or its value is "-1" then the item widths will be calculated dynamically. The attribute is read-only.

Use Cases

Basic usage

The following steps must be taken if an editor module wants to display a palette of items that can be dropped to editor window:

Define palette's root folder in editor's layer and also define subfolders for categories and file objects for palette items.
Another option is to create a hierarchy of Nodes (root - categories - items).
Extend PaletteActions class that provides custom Actions for palette's popup menus.
Use PaletteFactory to create an instance of PaletteController. The editor module keeps a reference to this object and registers a PropertyChangeListner to it to be notified of palette's selection changes.
Add the instance of PaletteController to the lookup of editor's TopComponent.

When an item is selected in the palette and user clicks into the editor window then the module can ask for selected item by calling PaletteController.getSelectedItem(). This method returns a Lookup that holds object(s) representing the selected item. After the item is inserted into the editor window the module may clear palette's selection (ProgressController.clearSelection()) or leave the item selected to implement 'multi drop' insertion scenario.

Filtering

It is possible to filter palette content and hide some categories and/or items from the user by implementing PaletteFilter interface. Calling PaletteController.setPaletteFilter() updates palette content and repaints the palette window.

Default Settings

The initial state of the palette can be overridden by setting appropriate attributes to palette model. The list of supported attributes is defined in PaletteController class. If the palette model is create from Nodes then the attributes are extracted by calling Node.getValue() method on the root Node and category and item nodes. If the palette model is defined as folders and files in the layer then the attributes are extracted by calling FileObject.getAttribute().

Writing Item

The following steps must be taken when writing the item using the support provided by this module:

Create XML file with item definition according to the editor-palette-item-1_0.dtd.
Register it in the editor's layer file (see Basic usage).
Provide custom item implementation of the ActiveEditorDrop interface if needed. I must be referenced from the definition file.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

Group of java interfaces

Interface Name	In/Out	Stability	Specified in What Document?
Palette	Exported	Stable	overview-summary.html

Group of dtd interfaces

Interface Name	In/Out	Stability	Specified in What Document?
editor-palette-item-1_0.dtd	Exported	Stable	.../dtds/editor-palette-item-1_0.dtd

Group of java.io.File interfaces

Interface Name	In/Out	Stability	Specified in What Document?
org-netbeans-modules-palette.jar	Exported	Stable

Group of layer interfaces

Interface Name	In/Out	Stability	Specified in What Document?
user_settings	Exported	Private	There's a private XML file for user settings for each palette model.

Group of lookup interfaces

Interface Name	In/Out	Stability	Specified in What Document?
activated_node	Exported	Stable	Palette listens to system activated node changes. The palette TopComponent opens when an editor TopComponent with a PaletteController instance in its Lookup is opened or activated. Palette window closes when the editor window is closed or deactivated and no other visible editor window supports the palette. The palette window always shows the content from the last active editor window regardless where the input focus is. The palette content is updated when user activates a different editor window that supports the palette.
node_represention	Exported	Stable	The palette item implementor can either directly provide the item body or her own item class implementing `org.openide.text.ActiveEditorDrop` interface. Lookup that holds object(s) representing the selected item then associates custom item class instance with the `org.openide.text.ActiveEditorDrop.class` key and the body with `java.lang.String` key. Editor side implementor can use the Lookup content whenever the Lookup is given, namely in the editor-provided implementations of the `PaletteActions`, `DragAndDropHandler` and `PropertyChangeListener` (registered on the `PaletteController`) interfaces.

Implementation Details

What do other modules need to do to declare a dependency on this one?

OpenIDE-Module-Module-Dependencies org.netbeans.spi.palette/0 > 1.0

Read more about the implementation in the answers to architecture questions.