See: Description
| Package | Description |
|---|---|
| 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
PaletteItemRegistration and PaletteItemRegistrations
Introduced a new annotation for registering palette items.
Deprecating
PaletteModule - it should not
be part of the API to begin with. Now it is registered with
OnShowing
annotation and thus implements 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".
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.
The Common Palette content is a two-level hierarchy. The top-most level are Categories, the Category children are Items. It's possible to select (highlight) items in the palette panel using a mouse or keyboard and then inserted/dropped into an editor that supports the palette.
The palette content can come from two different sources:
The following steps must be taken if a module wants to define its own palette content as a hierarchy of folders and files in its XML layer:
<filesystem>
<folder name="MyModulePalette">
<folder name="Category1">
<file name="PaletteItem_1.myitem" url="palette/PaletteItem_1.xml" />
<file name="PaletteItem_2.myitem" url="palette/PaletteItem_2.xml" />
<file name="PaletteItem_3.myitem" url="palette/PaletteItem_3.xml" />
</folder>
<folder name="Category2">
<file name="PaletteItem_4.myitem" url="palette/PaletteItem_4.xml" />
<file name="PaletteItem_5.myitem" url="palette/PaletteItem_5.xml" />
<file name="PaletteItem_6.myitem" url="palette/PaletteItem_6.xml" />
</folder>
</folder>
</filesystem>
class MyPaletteActions extends PaletteActions {
public Action getPreferredAction(Lookup lookup) {
Node itemNode = (Node)lookup.lookup( Node.class );
if( null != itemNode ) {
return new InsertItemAtDefaultLocationAction( itemNode );
}
return null;
}
public Action[] getCustomItemActions(Lookup lookup) {
Node itemNode = (Node)lookup.lookup( Node.class );
if( null != itemNode ) {
return new Action[] { new CustomizeItemAction( itemNode ) };
}
return null;
}
public Action[] getCustomCategoryActions(Lookup lookup) {
Node categoryNode = (Node)lookup.lookup( Node.class );
if( null != categoryNode ) {
return new Action[] { new CustomizeCategoryAction( categoryNode ) };
}
return null;
}
public Action[] getImportActions() {
return new Action[] { new ImportItemsFromWebAction() };
}
public Action[] getCustomPaletteActions() {
return null; //no custom actions for palette's root
}
}
class MyClass {
PaletteController controller;
PaletteController initializePalette() {
try {
controller = PaletteFactory.createPalette( "MyPalette", new MyPaletteActions() );
} catch (IOException ex) {
ex.printStackTrace();
return;
}
controller.addPropertyChangeListener( new PropertyChangeListener() {
public void propertyChange(PropertyChangeEvent evt) {
if( PaletteController.PROP_SELECTED_ITEM.equals( evt.getPropertyName() ) ) {
Lookup selItem = controller.getSelectedItem();
if( null == selItem ) {
//nothing is selected in palette
} else {
Node selNode = (Node)selItem.lookup( Node.class );
if( null != selNode ) {
//change mouse cursor for editor window to indicate
//the type of palette item that can be dropped
changeCursorInEditorWindow( selNode );
}
}
}
}
});
return controller;
}
}
class MyEditorTopComponent extends TopComponent {
private MyEditorTopComponent() {
this( new InstanceContent() );
}
private MyEditorTopComponent( InstanceContent content ) {
super( new AbstractLookup( content ) );
content.add( initializePalette() );
initEditorComponents();
}
PaletteController controller;
private PaletteController initializePalette() {
if( null == controller ) {
controller = PaletteFactory.createPalette( "MyPalette", new MyPaletteActions() );
}
return controller;
}
}
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 (PaletteController.clearSelection()) or leave the item selected to implement 'multi drop' insertion scenario.
It is possible to filter palette content and hide some categories and/or items from the user by extending PaletteFilter class.
class MyPaletteFilter extends PaletteFilter {
public boolean isValidItem(Lookup lookup) {
Node itemNode = (Node)lookup.lookup( Node.class );
return isItemVisibleInCurrentEditorContext( itemNode );
}
public boolean isValidCategory(Lookup lookup) {
Node categoryNode = (Node)lookup.lookup( Node.class );
return isCategoryVisibleInCurrentEditorContext( categoryNode );
}
private boolean isItemVisibleInCurrentEditorContext( Node item ) {
boolean res = true;
//check current cursor positions and/or item type and decide whether
//the item is valid, i.e. can be selected and dropped into editor
return res;
}
private boolean isCategoryVisibleInCurrentEditorContext( Node item ) {
boolean res = true;
//check current cursor positions and/or category type and decide whether
//the category is valid, i.e. its items can be selected and dropped into editor
return res;
}
Then initialize the palette using the following method:
MyPaletteFilter filter = new MyPaletteFilter();
PaletteController controller = PaletteFactory.createPalette( "MyPalette", new MyPaletteActions(), filter, null );
It is necessary to call PaletteController.refresh() to refresh and repaint the palette window whenever the filtering condition has changed:
myPaletteFilter.setShowSomeSpecialCategories( false );
paletteController.refresh();
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().
In the example below the palette will not show item names initially
(only icons are visible), the user can change this in palette's context menu.
Category1 is read-only therefore the user cannot remove it.
Category2 is not initially visible, the user can change this in
palette's customizer.
<filesystem>
<folder name="MyModulePalette">
<attr name="showItemNames" stringvalue="false"/>
<folder name="Category1">
<attr name="isReadonly" stringvalue="true"/>
<file name="PaletteItem_1.myitem" url="palette/PaletteItem_1.myitem" />
<file name="PaletteItem_2.myitem" url="palette/PaletteItem_2.myitem" />
<file name="PaletteItem_3.myitem" url="palette/PaletteItem_3.myitem" />
</folder>
<folder name="Category2">
<attr name="isVisible" stringvalue="false"/>
<file name="PaletteItem_4.myitem" url="palette/PaletteItem_4.myitem" />
<file name="PaletteItem_5.myitem" url="palette/PaletteItem_5.myitem" />
<file name="PaletteItem_6.myitem" url="palette/PaletteItem_6.myitem" />
</folder>
</folder>
</filesystem>
It is possible to add new palette categories and/or palette item at runtime when the palette window is already visible.
Adding a new category is very straight-forward, it basically means creating a new folder under palette's root folder in XML layer:
FileObject paletteRoot = FileUtil.getConfigFile( "MyModulePalette" );
paletteRoot.createFolder( "NewCategory" );
Adding a new item is a similar task:
FileObject paletteRoot = FileUtil.getConfigFile( "MyPalette" );
FileObject targetCategoryFO = paletteRoot.getFileObject( "CategoryName" );
DataFolder targetCategoryDF = DataFolder.findFolder( targetCategoryFO );
DataObject dobj = (DataObject)itemNode.getLookup().lookup( DataObject.class );
dobj.copy( targetCategoryFolder );
Please refer to Nodes API in case the palette content is defined as a hierarchy of arbitrary Nodes.
The following steps must be taken when writing the item using the support provided by this module:
|
|
|
|
The sources for the module are in the NetBeans Mercurial repositories.
Nothing.
Read more about the implementation in the answers to architecture questions.
Built on March 10 2014. | Portions Copyright 1997-2014 Oracle. All rights reserved.