Introduction

This document lists changes made to the Palette API/SPI.


Index of APIs

Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work. For a full deprecation list, please consult the Javadoc.

All changes by date

Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled 1.20, your manifest should contain in its main attributes the line:

OpenIDE-Module-Module-Dependencies: org.netbeans.spi.palette > 1.20

Changes by affected class

org.netbeans.spi.palette.DragAndDropHandler

org.netbeans.spi.palette.PaletteActions

org.netbeans.spi.palette.PaletteItemRegistration

org.netbeans.spi.palette.PaletteItemRegistrations

org.netbeans.spi.palette.PaletteModule


Details of all changes by API and date


Palette API

Introduced PaletteItemRegistration and PaletteItemRegistrations

Dec 10 '13; API spec. version: 1.40; affected top-level classes: PaletteItemRegistration PaletteItemRegistrations; made by: skygo; issues: #227345

Introduced a new annotation for registering palette items.

Deprecating ModuleInstall

Apr 1 '12; API spec. version: 1.31; affected top-level classes: PaletteModule; made by: jtulach; issues: #200636
Deprecating PaletteModule - it should not be part of the API to begin with. Now it is registered with OnShowing annotation and thus implements Runnable.

Allow to turn the auto-show of palette window on/off.

Nov 8 '11; API spec. version: 1.29; made by: saubrecht; issues: #204786

A new branding token Palette.Window.Enabled in org.netbeans.spi.palette package allows to turn the automatic display of palette window on/off. When the property value is false then the palette window will not show when an editor with palette content is activated. The user must open/close the palette window manually. The default value is true which means the palette window will auto-show/hide when active editor changes. Note: The palette window is part of commonpalette TopComponent group which the form designer opens when activated. So to turn the palette window off completely it is necessary to remove its reference from that group.

Make palette hidden by default for selected document types.

Oct 21 '09; API spec. version: 1.20; made by: saubrecht; issues: #170718

A new boolean attribute can be set on palette's root node or on palette's root folder in XML layer to hide the palette window by default when a document the palette is associated with is activated. User then must open the palette window manually for the first time. The attribute's name is "paletteDefaultVisible" and the default value is "true".

Allowing user dropping text into the palette to create new custom code clips.

May 5 '08; API spec. version: 1.14; affected top-level classes: DragAndDropHandler; made by: saubrecht; issues: #93002

If the Common Palette is associated with a text editor then it's desired to allow users dragging and dropping text into the palette to create new custom code clips that can be dropped into editor later on.

That can be achieved simply by subclassing the default DragAndDropHandler class which manages all DragAndDrop-related operations in the Common Palette and turning the text dnd support in superclasses's constructor on. The default implementation pops up a dialog window when some text is dropped into the palette where user enters code clip name and tooltip and optionally selects appropriate icons.

Palette visibility is defined per document-type.

Feb 22 '08; API spec. version: 1.13; made by: saubrecht; issues: #62964

Now it's possible to close the palette window while e.g. editing an HTML file and the palette will still show up when designing a form.

Palette providers may need to define their own action that resets the palette to its default state.

Jun 12 '07; API spec. version: 1.11; affected top-level classes: PaletteActions; made by: saubrecht; issues: #105561

Now it's possible to provide an action that will be invoked when user chose 'Reset' in palette's popup menu or in Palette Manager window.

Allow associating palette content with document mime type.

Feb 27 '07; API spec. version: 1.10; made by: saubrecht; issues: #90213

The previous version of palette API mandated that editor TopComponent had to insert a PaletteController instance into its Lookup if it wants to associate the palette with it. Now it is possible to associate the palette also with an existing editor without the need to change its implementation, e.g. to add code snippets palette to java source editor.

If the mime type of active editor window has an associated instance of PaletteController in the XML layer system then palette window opens and displays the specified palette contents. The PaletteController from TopComponent's Lookup takes precedens over the PaletteController found from mime type lookup in the XML layer (if any) for backwards compatibility.

The new API is fully backwards compatible and there are no implications for existing palette providers.

Allow display name and tooltip to be defined directly in item's XML

Jan 30 '07; API spec. version: 1.8; made by: saubrecht; issues: #90212

Now it's possible to specify item's display name and tooltip directly in item's XML definition (instead of providing bundle name and keys). It's needed for items created at runtime, for example code snippets highlighted in the editor and dropped to the palette.

Palette providers need to be notified when the palette content is being refreshed.

Jan 27 '07; API spec. version: 1.9; affected top-level classes: PaletteActions; made by: saubrecht; issues: #88400

Now it's possible to provide an action that will be invoked as part of palette's 'refresh' logic.

Added helpId attribute

Oct 16 '06; API spec. version: 1.7; made by: saubrecht; issues: #77387

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.

The Common Palette API has been stabilized.

Jun 6 '06; API spec. version: 1.6; made by: saubrecht; issues: #77387

To indicate that this is now considered a stable API, the major release version was incremented to 1 from 0.

Added support for default drag and drop operations

Sep 13 '05; API spec. version: 1.4; made by: saubrecht
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).

Palette client support released

Aug 10 '05; API spec. version: 1.3; made by: lkotouc
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.

Added a new optional attribute that can specify the width of items in the palette.

Aug 9 '05; API spec. version: 1.2; made by: saubrecht
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.

Removing unnecessary exceptions from PaletteFactory

Aug 8 '05; API spec. version: 1.1; made by: saubrecht
Removed IOException from the signature of methods in PaletteFactory that accept Node as an argument.

Initial version released

Jul 21 '05; API spec. version: 1.0; made by: saubrecht
The first initial release of the Palette API.

Built on July 23 2014.  |  Portions Copyright 1997-2014 Oracle. All rights reserved.