Cheat Sheet Item Extension

Identifier:

org.eclipse.ui.cheatsheets.cheatSheetItemExtension

Since:

3.0

Description:

This extension point should be used when an extra button needs to be added to a step in the cheat sheet. You can put a new attribute into the "item" tag in the cheat sheet content file, and when that value is read by the cheat sheet framework, it will check to see if there is a class registered through this extension point that will handle this attribute. The attribute name found in the cheat sheet content file is matched against all of the values found in the "itemAttribute" attribute of all of the registered cheatsheetItemExtension point implementations. If there is a match, the class specified to handle this item attribute is loaded by the cheat sheet framework and is called to handle the attribute specified in the cheat sheet content file. After having parsed the value of the item attribute, the class remains available to the cheat sheets framework. When the item is rendered for the cheat sheets view, the class is once again called to handle the addition of components to a Composite. The items that are added to this composite are displayed in the cheat sheet step (currently, beside the help icon). It is displayed only for the step that is described by the "item" tag that the attribute appeared in the cheat sheet content file. The suggested use of this extension point is adding a small (16x16) button with a graphic that opens a dialog box when pressed.

Configuration Markup:

<!ELEMENT extension (itemExtension)*>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

point - a fully qualified identifier of the target extension point
id - an optional identifier of the extension instance
name - an optional name of the extension instance

<!ELEMENT itemExtension EMPTY>

<!ATTLIST itemExtension

itemAttribute CDATA #REQUIRED

class CDATA #REQUIRED>

Use this item extension to add elements to cheat sheet steps. You can use this extension point to add icons and buttons (currently, beside the help icon) for a step in the cheat sheet. You specify the name of an attribute that you will put into the cheat sheet item tag. You also specify a class that will handle the parsing of the attribute value from the cheat sheet content file when the cheat sheet is loaded. The attribute valuemust be a string. The specified class must subclass org.eclipse.ui.cheatsheets.AbstractItemExtensionElement. After the cheat sheet content file is parsed and loaded, the class specified in the extension point is called again through the interface to add graphics or buttons to the step in the cheat sheet (currently, next to the help button).

itemAttribute - This attribute value must be the string value of an attribute name that is put into an item tag in the cheat sheet content file. If this attribute string matches an attribute parsed from the item tag in the cheat sheet content file, the class specified will be loaded and will be called to parse the full value of the attribute using the w3 DOM specification. It will later be called to add controls to a Composite, and the added components (usually graphics or buttons) will appear in the step of the cheat sheet for the item specified (currently, beside the help icon for that step).
class - The fully qualified class name of the class that subclasses org.eclipse.ui.cheatsheets.AbstractItemExtensionElement to handle unknown attributes in the cheat sheet content file and extend the steps in the cheat sheet. The class must be public, and have a public 1-argument constructor that accepts the attribute name (a String).

Examples:

Here is an example implementation of this extension point:


<extension point="org.eclipse.ui.cheatsheets.cheatSheetItemExtension">
 <itemExtension
   itemAttribute="xyzButton"
   class="com.example.HandleParsingAndAddButton">
 </itemExtension>
</extension>

And here is the item attribute for that extension:


<item title="XYZ Title" xyzButton="/icon/button.gif"/>

Note that the value of the attribute in the item tag can be ANYTHING. It can be anything because the class that parses that attribute is the class HandleParsingAndAddButton, which in this example parses a string /icon/button.gif from the attribute. It later will use that info to load the gif and use it as the icon for a new button.

API Information:

See the Javadoc information for org.eclipse.ui.cheatsheets.AbstractItemExtensionElement for API details.

Supplied Implementation:

There is no supplied implementation at this time.

Copyright (c) 2004, 2006 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0