org.netbeans.spi.palette/1 1.6.10

NetBeans Palette API

See:
          Description

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

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:

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:

  1. Create XML file with item definition according to the editor-palette-item-1_0.dtd.
  2. Register it in the editor's layer file (see Basic usage).
  3. 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 NameIn/OutStabilitySpecified in What Document?
PaletteExportedStableoverview-summary.html

Group of dtd interfaces
Interface NameIn/OutStabilitySpecified in What Document?
editor-palette-item-1_0.dtdExportedStable .../dtds/editor-palette-item-1_0.dtd

Group of java.io.File interfaces
Interface NameIn/OutStabilitySpecified in What Document?
org-netbeans-modules-palette.jarExportedStable

Group of layer interfaces
Interface NameIn/OutStabilitySpecified in What Document?
user_settingsExportedPrivate

There's a private XML file for user settings for each palette model.

Group of lookup interfaces
Interface NameIn/OutStabilitySpecified in What Document?
activated_nodeExportedStable

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_representionExportedStable

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.


org.netbeans.spi.palette/1 1.6.10

Built on July 11 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.