# Presentation Palette Providers

###### Identifier:

org.eclipse.gmf.runtime.diagram.ui.paletteProviders

###### Since:

[Enter the first release in which this extension point appears.]

###### Description:

[Enter description of this extension point.]

###### Configuration Markup:

<!ELEMENT extension (paletteProvider+)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED

>

- point - The identifier of the extension point, i.e. `org.eclipse.gmf.runtime.diagram.ui.paletteProviders`
- id - The identifier of the extension, e.g. paletteProvider.
- name - The name of the extension, e.g. %ext.paletteProvider.

<!ELEMENT paletteProvider (Priority , editor? , content? , contribution*)>

<!ATTLIST paletteProvider

class CDATA "org.eclipse.gmf.runtime.diagram.ui.providers.DefaultPaletteProvider"

>

The palette provider description tag. A provider's description outlines the targetting context (the editor and the editor's content) and zero or more palette contributions in that context.

- class - The fully qualified name of the palette provider class

<!ELEMENT Priority EMPTY>

<!ATTLIST Priority

name (Lowest|Low|Medium|High|Highest)

>

The description for the priority of the palette provider

- name - The priority of the provider. It can be one of the following values: <Lowest, Low, Medium, High, Highest>. Consideration of dependencies has to be done when choosing the priority. A provider that adds contributions to paths (menus | groups) contributed by other providers has to have a higher priority than them. Similarly, a provider that contributes palette entries that have been predefined by other providers has to have a higher priority than them.

<!ELEMENT editor EMPTY>

<!ATTLIST editor

id CDATA #IMPLIED

class CDATA #IMPLIED

>

A descriptor for the targetted editor. The editor is not required when predefining palette entries.

- id - The published id of the targetted editor. Although this field is optional, at least one of the two fields (id & class) has to be specified.
- class - The fully qualified name of a class/interface that is assignable from or adaptable to the target editor. The name could be followed (between paranthesis "()") by the id of a plugin whose classloader is able to load that class. The finaly syntax is: className<(plugin id)>? Although this field is optional, at least one of the two fields (id & class) has to be specified.

<!ELEMENT content (method* , staticMethod*)>

<!ATTLIST content

class CDATA #IMPLIED

>

A descriptor for the targetted editor's content.

- class - The fully qualified name of a class/interface that is assignable from or adaptable to the target editor's content object. The name could be followed (between paranthesis "()") by the id of a plugin whose classloader is able to load that class. The finaly syntax is: className<(plugin id)>?

<!ELEMENT contribution (entry* , predefinedEntry*)>

<!ATTLIST contribution

factoryClass CDATA #IMPLIED

>

A descriptor for a palette contribution.

- factoryClass - The fully qualified name of a class that represents the factory for the contributions. The class has to implemenent the interface : org.eclipse.gmf.runtime.gef.ui.internal.ui.palette.PaletteFactory

<!ELEMENT entry (expand?)>

<!ATTLIST entry

kind (drawer|separator|template|tool|stack)

id CDATA #REQUIRED

path CDATA #IMPLIED

label CDATA #IMPLIED

description CDATA #IMPLIED

small_icon CDATA #IMPLIED

large_icon CDATA #IMPLIED

permission (None|HideOnly|Limited|Full)

defineOnly (true | false)

>

A descriptor for a palette contribution entry that will be contributed to the palette.

- kind - The kind of the entry (drawer | stack | separator | tool | template)
- id - a user-defined id for the entry (unique within a provider)
- path - A fully qualified path of contribution. The format is: /<drawer id</separator id | entry id>> or /<group id</separator id | entry id>> All path ids should have been previously defined. Previous means either earlier in the XML file or another one with a lower priority (order). If a path ends with a separator id, the new entry is appended to the elements following the separator (just before the next separator or at the end of the container if it has no more separators below that one). If a path ends with a normal entry id, the new entry is inserted after that entry. A path is required unless this palette entry is being defined only so that it can be contributed by another palette provider.
- label - the palette entry label (not required for separators)
- description - The pallete entry description
- small_icon - The palette entry small icon file name and path. A value of "None" on a palette drawer entry indicates that the default icon should not show up on a palette drawer.
- large_icon - The palette entry large icon
- permission - The palette entry permission (None | HideOnly | limited | full). For description of the meaning of those, please refer to GEF's documentation.
- defineOnly - If true, this palette entry is only being defined, but will not be contributed. In this case, the path is ignored and not required. When defining a palette drawer or palette stack, this flag need only be set on the palette drawer or stack to indicate that all the entries on the drawer are being defined only. The palette entry can be contributed by another palette extension using a predefinedEntry.

<!ELEMENT expand (content?)>

<!ATTLIST expand

force (true | false) "false"

>

A descriptor for a condition to make palette drawers initially expanded.

- force -

<!ELEMENT method (value* , notValue*)>

<!ATTLIST method

name CDATA #REQUIRED

value CDATA #IMPLIED

notValue CDATA #IMPLIED

>

A method to call by reflection on the object. The method has a name and a value. The value could be described by its string representation (value & notValue), or as an object "value" or "notValue". The rules of evaluation are as follows: 1- The return value string has to be in the "value" string set. 2- The return value string has to be not in the "notValue" string set. 3- The return value object has to be in the "value" object set. 4- The return value object has to be not in the "notValue" object set.

- name - The name of the method followed by an optional paramter set between paranthesis "()". The parameter set can contain any number of string parameters (literals). other param types are not supported. The method name could contain nested calling separated by "." The general format for this method name is : <func(<param<,param>*>?).<<func(<param<,param>*>?)>*
- value - A comma-separated (",") list of string representations of the method return value. The string representation of the value is expected to be "one" of those in the list. The syntax to use is the following: <string><,<string>>* If (",") is expected to be in one of the strings, it has to be escaped by a forward slash ("\"). "null" is accepted as a string and it means (a null object).
- notValue - A comma-separated (",") list of string representations of the method return value that is not expected (the execulsion set). The string representation of the value is expected "not" to be "one" of those in the list. The syntax to use is the following: <string><,<string>>* If (",") is expected to be in one of the strings, it has to be escaped by a forward slash ("\"). "null" is accepted as a string and it means (a null object).

<!ELEMENT value (method*)>

<!ATTLIST value

class CDATA #IMPLIED

>

A descriptor of an object that represents a method's returned value. The descriptor can include an optional set of methods to call on the "value" object.

- class - The fully qualified name of a class/interface that is assignable from or adaptable to the "value" object. The name could be followed (between paranthesis "()") by the id of a plugin whose classloader is able to load that class. The finaly syntax is: className<(plugin id)>?

<!ELEMENT notValue (method*)>

<!ATTLIST notValue

class CDATA #IMPLIED

>

A descriptor of an object that represents a method's returned value that is not required. The descriptor can include an optional set of methods to call on the "notValue" object.

- class - The fully qualified name of a class/interface that is assignable from or adaptable to the "value" object. The name could be followed (between paranthesis "()") by the id of a plugin whose classloader is able to load that class. The finaly syntax is: className<(plugin id)>?

<!ELEMENT predefinedEntry (expand?)>

<!ATTLIST predefinedEntry

id CDATA #REQUIRED

path CDATA #IMPLIED

remove (true | false)

>

A descriptor for a palette contribution entry that has already been defined by another plug-in and will now be contributed.

- id - The ID given to the palette entry when it was defined. If the palette entry is in a palette container (i.e. drawer or stack) the id is considered the full path of this palette entry.
- path - A fully qualified path describing where this palette entry should appear on the palette. The format is: /<drawer id</separator id | entry id>> or /<group id</separator id | entry id>> All path ids should have been previously defined. Previous means either earlier in the XML file or another one with a lower priority (order). If a path ends with a separator id, the new entry is appended to the elements following the separator (just before the next separator or at the end of the container if it has no more separators below that one). If a path ends with a normal entry id, the new entry is inserted after that entry. The path is not required if this predefined entry is not being contributed. That is, a predefined entry can be used to expand an existing drawer, remove an existing entry from the palette.
- remove - If true, an existing entry will be removed.

<!ELEMENT staticMethod (value* , notValue*)>

<!ATTLIST staticMethod

name CDATA #REQUIRED

value CDATA #IMPLIED

notValue CDATA #IMPLIED

>

A static method to call by reflection on the class. The static method has a name and a value. The value could be described by its string representation (value & notValue), or as an object "value" or "notValue". The rules of evaluation are as follows: 1- The return value string has to be in the "value" string set. 2- The return value string has to be not in the "notValue" string set. 3- The return value object has to be in the "value" object set. 4- The return value object has to be not in the "notValue" object set.

- name - The name of the Static Method, the format should be PluginID\ClassName.method followed by an optional paramter set between paranthesis "()". The parameter set can contain any number of primitive parameters or %Context(pluginID/className) to use the context object as a parameter . other param types are not supported. The method name could contain nested calling separated by "." The general format for this method name is : <pluginID/ClassName.func(<param<,param>*>?).<<func(<param<,param>*>?)>*
- value - A comma-separated (",") list of string representations of the method return value. The string representation of the value is expected to be "one" of those in the list. The syntax to use is the following: <string><,<string>>* If (",") is expected to be in one of the strings, it has to be escaped by a forward slash ("\"). "null" is accepted as a string and it means (a null object).
- notValue - A comma-separated (",") list of string representations of the method return value that is not expected (the execulsion set). The string representation of the value is expected "not" to be "one" of those in the list. The syntax to use is the following: <string><,<string>>* If (",") is expected to be in one of the strings, it has to be escaped by a forward slash ("\"). "null" is accepted as a string and it means (a null object).

###### Examples:

[Enter extension point usage example here.]

###### Supplied Implementation:

[Enter information about supplied implementation of this extension point.]

Copyright (c) 2005 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html