KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > cheatsheets > AbstractItemExtensionElement


1 /*******************************************************************************
2  * Copyright (c) 2004, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.ui.cheatsheets;
12
13 import org.eclipse.swt.widgets.Composite;
14
15 /**
16  * Base class for adding controls to cheat sheet items.
17  * <p>
18  * Subclasses are used in conjunction with the
19  * <code>org.eclipse.ui.cheatsheets.cheatSheetItemExtension</code> extension
20  * point. Subclasses must be public and have a public 1-arg constructor
21  * that takes the name of the attribute type <code>String</code>. The
22  * extension point specifies the name of the subclass and the name of the XML
23  * attribute that it can handle. When the cheat sheet framework encounters an
24  * item (or subitem) element in the cheat sheet content file with an attribute
25  * with a matching name, an instance of the corresponding item extension subclass
26  * is created. It is up to this instance to remember the attribute value if
27  * required. Later, when creating the visual controls for the item
28  * are being created, the instance is given the opportunity to add extra controls.
29  * </p>
30  *
31  * @since 3.0
32  */
33 public abstract class AbstractItemExtensionElement {
34     
35     /**
36      * Name of the XML attribute that this item extension handles.
37      */
38     private String JavaDoc attributeName;
39     
40     /**
41      * Creates a new item element extension for handling the
42      * XML attributes of the given name.
43      *
44      * @param attributeName the name of the attribute that this item extension handles
45      * @exception IllegalArgumentException if <code>attributeName</code>
46      * is <code>null</code>
47      */
48     public AbstractItemExtensionElement(String JavaDoc attributeName) {
49         if (attributeName == null) {
50             throw new IllegalArgumentException JavaDoc();
51         }
52         this.attributeName = attributeName;
53     }
54
55     /**
56      * Returns the name of the XML attribute that this item extension handles.
57      *
58      * @return the name of the attribute that this item extension handles
59      */
60     public final String JavaDoc getAttributeName() {
61         return this.attributeName;
62     }
63     
64     /**
65      * Called by the cheat sheet framework to parse and extract information
66      * from the string value of the XML attribute.
67      *
68      * @param attributeValue the attribute value specified in the cheat sheet
69      * content file
70      */
71     public abstract void handleAttribute(String JavaDoc attributeValue);
72
73     /**
74      * Called by the cheat sheet framework when creating the visual
75      * representation of a step. This method should add a small button
76      * (suggested size 16x16 pixels) to the given composite to decorate the step.
77      * <p>
78      * Important note: In some presentations of the cheatsheet, the color of the
79      * background is varied to emphasize the current step. Because of this, it is
80      * important to always use the background color of the composite
81      * (<code>composite.getBackground()</code>) as the background color for any
82      * additional controls; otherwise the new controls will not match their
83      * surrounding.
84      * </p>
85      *
86      * @param composite the composite to add extra controls to
87      */
88     public abstract void createControl(Composite composite);
89
90     /**
91      * Called by the cheat sheet framework to dispose of this item element extension.
92      * <p>
93      * This is the last method called on the <code>AbstractItemExtensionElement</code>.
94      * At this point the controls (if they were ever created) have been disposed as part
95      * of an SWT composite. There is no guarantee that createControl() has been called,
96      * so the controls may never have been created.
97      * </p>
98      * <p>
99      * Within this method an item element extension may release any resources, fonts,
100      * images, etc.&nbsp; held by this part. It is also very important to deregister
101      * all listeners.
102      * </p>
103      * <p>
104      * Clients should not call this method (the cheat sheet framework calls this method
105      * at appropriate times).
106      * </p>
107      */
108     public abstract void dispose();
109 }
110
Popular Tags