This document lists changes made to the Palette API/SPI.
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.
PaletteItemRegistration and PaletteItemRegistrations
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
PaletteItemRegistration and PaletteItemRegistrations
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
PaletteItemRegistration and PaletteItemRegistrations
PaletteItemRegistration PaletteItemRegistrations; made by: skygo; issues:
#227345
Introduced a new annotation for registering palette items.
PaletteModule; made by: jtulach; issues:
#200636
Runnable.
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.
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".
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.
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.
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.
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.
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.
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.
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.
To indicate that this is now considered a stable API, the major release version was incremented to 1 from 0.
void customize( ExTransferable t, Lookup item ) to provide
custom data flavors for items dragged from the palette to editor.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.