IContributionItem


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 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  
12  package org.eclipse.jface.action;
13  
14  import org.eclipse.swt.widgets.Composite;
15  import org.eclipse.swt.widgets.CoolBar;
16  import org.eclipse.swt.widgets.Menu;
17  import org.eclipse.swt.widgets.ToolBar;
18  
19  /**
20   * A contribution item represents a contribution to a shared UI resource such as a
21   * menu or tool bar. More generally, contribution items are managed by a contribution
22   * manager.
23   * For instance, in a tool bar a contribution item is a tool bar button or a separator.
24   * In a menu bar a contribution item is a menu, and in a menu a contribution item 
25   * is a menu item or separator.
26   * <p>
27   * A contribution item can realize itself in different SWT widgets, using the different 
28   * <code>fill</code> methods.  The same type of contribution item can be used with a 
29   * <code>MenuBarManager</code>, <code>ToolBarManager</code>, <code>CoolBarManager</code>, 
30   * </code>or a <code>StatusLineManager</code>.
31   * </p>
32   * <p>
33   * This interface is internal to the framework; it should not be implemented outside
34   * the framework.
35   * </p>
36   *
37   * @see IContributionManager
38   */
39  public interface IContributionItem {
40  
41      /**
42       * Disposes of this contribution item. Called by the parent
43       * contribution manager when the manager is being disposed.
44       * Clients should not call this method directly, unless they
45       * have removed this contribution item from the containing
46       * IContributionManager before the contribution lifecycle
47       * has ended.
48       * 
49       * @since 2.1
50       */
51      public void dispose();
52  
53      /**
54       * Fills the given composite control with controls representing this 
55       * contribution item.  Used by <code>StatusLineManager</code>.
56       *
57       * @param parent the parent control
58       */
59      public void fill(Composite parent);
60  
61      /**
62       * Fills the given menu with controls representing this contribution item.
63       * Used by <code>MenuManager</code>.
64       *
65       * @param parent the parent menu
66       * @param index the index where the controls are inserted,
67       *   or <code>-1</code> to insert at the end
68       */
69      public void fill(Menu parent, int index);
70  
71      /**
72       * Fills the given tool bar with controls representing this contribution item.
73       * Used by <code>ToolBarManager</code>.
74       *
75       * @param parent the parent tool bar
76       * @param index the index where the controls are inserted,
77       *   or <code>-1</code> to insert at the end
78       */
79      public void fill(ToolBar parent, int index);
80  
81      /**
82       * Fills the given cool bar with controls representing this contribution item.
83       * Used by <code>CoolBarManager</code>.
84       *
85       * @param parent the parent cool bar
86       * @param index the index where the controls are inserted,
87       *   or <code>-1</code> to insert at the end
88       * @since 3.0
89       */
90      public void fill(CoolBar parent, int index);
91  
92      /**
93       * Returns the identifier of this contribution item.
94       * The id is used for retrieving an item from its manager.
95       *
96       * @return the contribution item identifier, or <code>null</code>
97       *   if none
98       */
99      public String   getId();
100 
101     /**
102      * Returns whether this contribution item is enabled.
103      * 
104      * @return <code>true</code> if this item is enabled
105      */
106     public boolean isEnabled();
107 
108     /**
109      * Returns whether this contribution item is dirty. A dirty item will be
110      * recreated when the action bar is updated.
111      * 
112      * @return <code>true</code> if this item is dirty
113      */
114     public boolean isDirty();
115 
116     /**
117      * Returns whether this contribution item is dynamic. A dynamic contribution
118      * item contributes items conditionally, dependent on some internal state.
119      *
120      * @return <code>true</code> if this item is dynamic, and
121      *  <code>false</code> for normal items
122      */
123     public boolean isDynamic();
124 
125     /**
126      * Returns whether this contribution item is a group marker.
127      * This information is used when adding items to a group.
128      *
129      * @return <code>true</code> if this item is a group marker, and
130      *  <code>false</code> for normal items
131      *
132      * @see GroupMarker
133      * @see IContributionManager#appendToGroup(String, IContributionItem)
134      * @see IContributionManager#prependToGroup(String, IContributionItem)
135      */
136     public boolean isGroupMarker();
137 
138     /**
139      * Returns whether this contribution item is a separator.
140      * This information is used to enable hiding of unnecessary separators.
141      *
142      * @return <code>true</code> if this item is a separator, and
143      *  <code>false</code> for normal items
144      * @see Separator
145      */
146     public boolean isSeparator();
147 
148     /**
149      * Returns whether this contribution item is visibile within its manager.
150      *
151      * @return <code>true</code> if this item is visible, and
152      *  <code>false</code> otherwise
153      */
154     public boolean isVisible();
155 
156     /**
157      * Saves any state information of the control(s) owned by this contribution item.
158      * The contribution manager calls this method before disposing of the controls.
159      * 
160      * @since 3.0
161      */
162     public void saveWidgetState();
163 
164     /**
165      * Sets the parent manager of this item
166      * 
167      * @param parent the parent contribution manager
168      * @since 2.0
169      */
170     public void setParent(IContributionManager parent);
171 
172     /**
173      * Sets whether this contribution item is visibile within its manager.
174      *
175      * @param visible <code>true</code> if this item should be visible, and
176      *  <code>false</code> otherwise
177      */
178     public void setVisible(boolean visible);
179 
180     /**
181      * Updates any SWT controls cached by this contribution item with any
182      * changes which have been made to this contribution item since the last update.
183      * Called by contribution manager update methods.
184      */
185     public void update();
186 
187     /**
188      * Updates any SWT controls cached by this contribution item with changes
189      * for the the given property. 
190      * 
191      * @param id the id of the changed property
192      * @since 2.0
193      */
194     public void update(String   id);
195 }
196
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags