# Tutorial: Configuring and Extending the Diagram Palette

Version: 0.1 | Date: September 13, 2005 |
Version: 0.2 | Date: March 27, 2006 | Added section Separating the Definition and Contribution of a Palette Entry and section Removing an Existing Palette Entry.

## Contents

- Overview
- References
- Introduction
- Adding a Palette Provider Extension
- Creating and Registering the Palette Provider and Factory Classes
- Creating a Palette Drawer
- Creating a Palette Stack
- Creating a Palette Tool
- Adding a Palette Tool/Stack to an Existing Drawer or Stack
- Separating the Definition and Contribution of a Palette Entry
- Removing an Existing Palette Entry
- Summary

## Overview

[back to top]

The palette is a UI control that displays a set of tools to be used in conjunction with the active diagram editor. The tools may be used for selection, object creation or any other action to be performed on the active diagram. This tutorial provides the reader with a guide for configuration of palette drawers, tools and stacks.

## References

[back to top]

This tutorial references the following extension point:
org.eclipse.gmf.runtime.diagram.ui.paletteProviders

More information about this extension points can be found in the palette provider's schema documentation.

## Introduction

[back to top]

In this tutorial, we will use the Logic Diagram Example to illustrate how to configure the palette diagram for a logic diagram. To gain familiarity with the Logic Diagram Example, refer to the Logic Example Guide.

## Adding a Palette Provider Extension

[back to top]

Add an extension to register the palette drawer, stack and tools. The governing extension point for palette contribution is: org.eclipse.gmf.runtime.diagram.ui.paletteProviders

Please refer to the org.eclipse.gmf.runtime.diagram.ui.paletteProviders extension point documentation for specific information on the tags and attributes to use. The full extension XML can be found in org.eclipse.gmf.examples.runtime.diagram.logic/plugin.xml.

<!-- Palette Provider --> <extension id="logicPaletteProvider" name="%ext.logicPaletteProvider" point="org.eclipse.gmf.runtime.diagram.ui.paletteProviders"> ... </extension>

The contribution given above will result in the following Logic Designer palette drawer, stack and tools:

## Creating and Registering the Palette Provider and Factory Classes

[back to top]

The palette provider class reads the XML palette contributions from the provider's extension point and contributes them to an editor's palette based on the contribution criteria.

The factory contribution is explained below along with an excerpt from LogicPaletteFactory.

<!-- Palette Provider --> <extension ... <paletteProvider class="org.eclipse.gmf.runtime.diagram.ui.providers.internal.DefaultPaletteProvider" > <Priority name="Low"> </Priority> <editor id="LogicEditor"> </editor> <contribution factoryClass="org.eclipse.gmf.examples.runtime.diagram.logic.internal.providers.LogicPaletteFactory"> ... </extension>

The contribution factoryClass defines the factory class used to map the tools to a tool type (e.g. CreationTool). You may want to define a new tool in order to add new functionality to your tool.

public class LogicPaletteFactory extends PaletteFactory.Adapter { /** list of supported tool types. */ private Map toolMap = new HashMap(); { toolMap.put( LogicConstants.TOOL_LED, new CreationTool(LogicSemanticType.LED) ); toolMap.put( LogicConstants.TOOL_CIRCUIT, new CreationTool(LogicSemanticType.CIRCUIT) ); toolMap.put( LogicConstants.TOOL_ORGATE, new CreationTool(LogicSemanticType.ORGATE) ); toolMap.put( LogicConstants.TOOL_ANDGATE, new CreationTool(LogicSemanticType.ANDGATE) ); toolMap.put( LogicConstants.TOOL_XORGATE, new CreationTool(LogicSemanticType.XORGATE) ); toolMap.put( LogicConstants.TOOL_FLOWCONTAINER, new CreationTool(LogicSemanticType.FLOWCONTAINER) ); } /** list of supported tool types. */ private Map connectionMap = new HashMap(); { connectionMap.put( LogicConstants.TOOL_CONNECTION, new ConnectionCreationTool(LogicSemanticType.WIRE) ); } /* * Create the tool according to type */ public Tool createTool(String toolId) { if (toolId.equals(LogicConstants.TOOL_CONNECTION)) { return (ConnectionCreationTool)connectionMap.get(toolId); } else { return (CreationTool)toolMap.get(toolId); } } }

## Creating a Palette Drawer

[back to top]

A palette drawer is used to group a set of associated tools. The drawer can be open and closed by the application user.

The palette drawer can be added and removed by adding and removing the entry tag with kind set to drawer. The schema documentation specifies the rules for attributes. These attributes include the label, description, path, icon and id. The stack and tools that will reside under the drawer will need to include the drawer id in their respective paths. Note that removing a drawer requires removal of its stacks and tools.

The order of the drawers, stacks and tools depend on the associated priority and position with respect to other entries in the same XML document.

<!-- Palette Provider --> <extension ... <entry label="%LogicDrawer.Label" kind="drawer" description="%LogicDrawer.Description" path="/" small_icon="icons/comp.gif" id="logicDrawer"> <expand> <content> <!-- expand by default for LogicEditors --> </content> </expand> </entry> ... </extension>

## Creating a Palette Stack

[back to top]

A palette stack is used to group a set of closely related tools (e.g. gate types on a logic diagram).

The palette drawer can be added and removed by adding and removing the entry tag with kind set to stack. The schema documentation specifies the rules for attributes. These attributes include the label, description, path, icon and id. The tools that will reside within the stack will need to include the stack id in their respective paths. Note that removing a stack requires removal of the stack's tools.
<!-- Palette Provider --> <extension ... <entry label="%GateStack.Label" kind="stack" description="%GateStack.Description" small_icon="icons/or24.gif" path="/logicDrawer/" id="noteStack"> </entry> ... </extension>

## Creating a Palette Tool

[back to top]

The palette tool can be added and removed by adding and removing the entry tag with kind set to tool. The schema documentation specifies the rules for attributes. These attributes include the label, description, path, icon and id.
<!-- Palette Provider --> <extension ... <entry label="%LogicFlowTool.Label" kind="tool" description="%LogicFlowTool.Description" large_icon="icons/logicflow24.gif" path="/logicDrawer/" small_icon="icons/logicflow16.gif" id="FlowContainer"> </entry> ... </extension>

## Adding a Palette Tool/Stack to an Existing Drawer or Stack

[back to top]

To add or remove an existing drawer or stack, the user must specify the path to the existing drawer or stack in the entry tag attributes. The palette service execution is based on a REVERSE strategy and therefore the new tool or stack must have a higher priority than that of the destination.

The following XML will contribute a new logic tool into the Logic Drawer set up in the logic example. The palette factory class will need to set up the tool internally as well. Note the priority is set to medium and that the contribution is made by adding this excerpt to org.eclipse.gmf.runtime.diagram.ui.geoshapes\plugin.xml file.

<!-- Palette Provider --> <extension id="logicPaletteProvider" name="%ext.logicPaletteProvider" point="org.eclipse.gmf.runtime.diagram.ui.paletteProviders"> <paletteProvider class="org.eclipse.gmf.runtime.diagram.ui.providers.internal.DefaultPaletteProvider"> <Priority name="Medium"> </Priority> <editor id="LogicEditor"> </editor> <contribution factoryClass="org.eclipse.gmf.runtime.diagram.ui.geoshapes.internal.providers.GeoshapePaletteFactory"> <entry label="%NewLogicTool.Label" kind="tool" description="%NewLogicTool.Description" large_icon="icons/newlogic24.gif" path="/logicDrawer/" small_icon="icons/newlogic16.gif" id="NewTool"> </entry> </contribution> </paletteProvider> </extension>

The drawer now appears:

The label needs to be set in the appropriate plugin.properties file. It has been left uninterpolated for emphasis.

## Separating the Definition and Contribution of a Palette Entry

[back to top]

A plug-in may wish to define palette entries without contributing them to an editor so that other clients may contribute these palette entries to their editor's palette as appropriate.
To define a palette entry only, simply set defineOnly to true in the palette entry's schema definition. The following XML will define the geoshapes drawer without contributing it to an editor.

<extension point="org.eclipse.gmf.runtime.diagram.ui.paletteProviders"> <paletteProvider class="org.eclipse.gmf.runtime.diagram.ui.providers.DefaultPaletteProvider"> <Priority name="Low"> </Priority> <contribution factoryClass="org.eclipse.gmf.runtime.diagram.ui.geoshapes.internal.providers.GeoshapePaletteFactory"> <entry defineOnly="true" description="%GeoshapeDrawer.Description" id="geoshapeDrawer" kind="drawer" label="%GeoshapeDrawer.Label"> </entry> <entry label="%OvalTool.Label" kind="tool" description="%OvalTool.Description" large_icon="icons/IconEllipse24.gif" path="geoshapeDrawer/" small_icon="icons/IconEllipse.gif" id="oval"> </entry> ... </contribution> </paletteProvider> </extension>
The following XML shows how to contribute the predefined geoshapes drawer to an editor.
<extension point="org.eclipse.gmf.runtime.diagram.ui.paletteProviders"> <paletteProvider class="org.eclipse.gmf.runtime.diagram.ui.providers.DefaultPaletteProvider"> <Priority name="Medium"> </Priority> <editor id="GeoshapeEditor"> </editor> <contribution> <predefinedEntry id="geoshapeDrawer" path="/"> </predefinedEntry> </contribution> </paletteProvider> </extension>
The palette service execution is based on a REVERSE strategy and therefore the contribution of the palette entry must have a higher priority than that of the definition.
Other palette entries, such as palette tools can also be predefined and contributed by separate extensions. To add a palette tool from an existing drawer to a new drawer, use a predefined entry similar to the following:
<predefinedEntry id="existingDrawer/aTool" path="/myDrawer"/>
Drawers that have already been contributed, can be expanded by default on an editor by another plugin.
The following XML shows how an existing drawer would be expanded.
<extension point="org.eclipse.gmf.runtime.diagram.ui.paletteProviders"> <paletteProvider class="org.eclipse.gmf.runtime.diagram.ui.providers.DefaultPaletteProvider"> <Priority name="High"> </Priority> <contribution> <predefinedEntry id="geoshapeDrawer"> <expand force="true"/> </predefinedEntry> </contribution> </paletteProvider> </extension>

## Removing an Existing Palette Entry

[back to top]

A plug-in may wish to remove a palette entry that another plugin has already contributed.
To remove a palette entry, simply set remove to true in the predefined palette entry's schema definition. The following XML shows how to remove a tool from the geoshapes drawer.

<extension point="org.eclipse.gmf.runtime.diagram.ui.paletteProviders"> <paletteProvider class="org.eclipse.gmf.runtime.diagram.ui.providers.DefaultPaletteProvider"> <Priority name="High"> </Priority> <contribution> <predefinedEntry id="geoshapeDrawer/oval" remove="true"/> </contribution> </paletteProvider> </extension>

## Summary

[back to top]

In this tutorial, we did the following:

- Added a Palette Provider Extension
- Created and Registed the Palette Provider and Factory Classes
- Created a Palette Drawer
- Created a Palette Stack
- Created a Palette Tool
- Added a Palette Tool to an Existing Drawer
- Separated the Definition and Contribution of a Palette Drawer
- Removed an Existing Palette Tool

Copyright (c) 2000,2005,2006 IBM Corporation and others. All Rights Reserved.