IMenuService


1   /*******************************************************************************
2    * Copyright (c) 2005, 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.internal.menus;
12  
13  import java.util.Collection  ;
14  
15  import org.eclipse.core.expressions.Expression;
16  import org.eclipse.ui.services.IServiceWithSources;
17  
18  /**
19   * <p>
20   * Provides services related to the menu architecture within the workbench. This
21   * service can be used to access the set of menu, tool bar and status line
22   * contributions. It can also be used to contribute additional items to the
23   * menu, tool bar and status line.
24   * </p>
25   * <p>
26   * This interface should not be implemented or extended by clients.
27   * </p>
28   * <p>
29   * <strong>PROVISIONAL</strong>. This class or interface has been added as part
30   * of a work in progress. There is a guarantee neither that this API will work
31   * nor that it will remain the same. Please do not use this API without
32   * consulting with the Platform/UI team.
33   * </p>
34   * <p>
35   * This class is meant to exist in the <code>org.eclipse.ui.menus</code>
36   * package.
37   * </p>
38   * 
39   * @since 3.2
40   */
41  public interface IMenuService extends IServiceWithSources {
42  
43      /**
44       * <p>
45       * Contributes the given menu element within the context of this service. If
46       * this service was retrieved from the workbench, then this contribution
47       * will be visible globally. If the service was retrieved from a nested
48       * component, then the contribution will only be visible within that
49       * component.
50       * </p>
51       * <p>
52       * Also, it is guaranteed that the contributions submitted through a
53       * particular service will be cleaned up when that service is destroyed. So,
54       * for example, a service retrieved from a <code>IWorkbenchPartSite</code>
55       * would remove all of its contributions when the site is destroyed.
56       * </p>
57       * 
58       * @param menuElement
59       *            The menu element to contribute; must not be <code>null</code>.
60       * @return A token which can be used to later cancel the contribution. Only
61       *         someone with access to this token can cancel the contribution.
62       *         The contribution will automatically be cancelled if the context
63       *         from which this service was retrieved is destroyed.
64       */
65      public IMenuContribution contributeMenu(MenuElement menuElement);
66  
67      /**
68       * <p>
69       * Contributes the given menu element within the context of this service.
70       * The menu element becomes visible when <code>expression</code> evaluates
71       * to <code>true</code>.
72       * </p>
73       * <p>
74       * Also, it is guaranteed that the contribution submitted through a
75       * particular service will be cleaned up when that services is destroyed.
76       * So, for example, a service retrieved from a
77       * <code>IWorkbenchPartSite</code> would remove all of its contributions
78       * when the site is destroyed.
79       * </p>
80       * 
81       * @param menuElement
82       *            The menu element to contribution; must not be
83       *            <code>null</code>.
84       * @param expression
85       *            This expression must evaluate to <code>true</code> before
86       *            this handler will really become visible. The expression may be
87       *            <code>null</code> if the menu element should always be
88       *            visible.
89       * @return A token which can be used to later cancel the contribution. Only
90       *         someone with access to this token can cancel the contribution.
91       *         The contribution will automatically be cancelled if the context
92       *         from which this service was retrieved is destroyed.
93       */
94      public IMenuContribution contributeMenu(MenuElement menuElement,
95              Expression expression);
96  
97      /**
98       * Retrieves the action set with the given identifier. If no such action set
99       * exists, then an undefined action set is created and returned. An action
100      * set is a logical grouping of menu elements, that can be made visible or
101      * hidden as a group.
102      * 
103      * @param actionSetId
104      *            The identifier to find; must not be <code>null</code>.
105      * @return An action set with the given identifier, either defined or
106      *         undefined.
107      */
108     public SActionSet getActionSet(String   actionSetId);
109 
110     /**
111      * Returns those action sets that are defined.
112      * 
113      * @return The defined action sets; this value may be empty, but it is never
114      *         <code>null</code>.
115      */
116     public SActionSet[] getDefinedActionSets();
117 
118     /**
119      * Returns those groups that are defined.
120      * 
121      * @return The defined groups; this value may be empty, but it is never
122      *         <code>null</code>.
123      */
124     public SGroup[] getDefinedGroups();
125 
126     /**
127      * Returns those items that are defined.
128      * 
129      * @return The defined items; this value may be empty, but it is never
130      *         <code>null</code>.
131      */
132     public SItem[] getDefinedItems();
133 
134     /**
135      * Returns those menus that are defined.
136      * 
137      * @return The defined menus; this value may be empty, but it is never
138      *         <code>null</code>.
139      */
140     public SMenu[] getDefinedMenus();
141 
142     /**
143      * Returns those widgets that are defined.
144      * 
145      * @return The defined widgets; this value may be empty, but it is never
146      *         <code>null</code>.
147      */
148     public SWidget[] getDefinedWidgets();
149 
150     /**
151      * Retrieves the group with the given identifier. If no such group exists,
152      * then an undefined group is created and returned. A group is a logical
153      * grouping of items and widgets within a menu.
154      * 
155      * @param groupId
156      *            The identifier to find; must not be <code>null</code>.
157      * @return A group with the given identifier, either defined or undefined.
158      */
159     public SGroup getGroup(String   groupId);
160 
161     /**
162      * Retrieves the item with the given identifier. If no such item exists,
163      * then an undefined item is created and returned. An item is a single entry
164      * in a menu, tool bar or status line.
165      * 
166      * @param itemId
167      *            The identifier to find; must not be <code>null</code>.
168      * @return An item with the given identifier, either defined or undefined.
169      */
170     public SItem getItem(String   itemId);
171 
172     /**
173      * <p>
174      * Retrieves the layout for the menu elements held by this menu manager.
175      * This layout does not consider visibility or whether the elements are
176      * currently shown. It is simply the layout if everything was visible and
177      * showing. It also does not consider dynamic menu elements, which will be
178      * asked to make changes to the layout before the menu element is shown.
179      * </p>
180      * <p>
181      * The result of this computation is cached between subsequent calls. So, if
182      * no changes are made to the menu elements, the layout can be retrieved in
183      * constant time. Otherwise, it will take <code>O(n)</code> time to
184      * compute, where <code>n</code> is the number of menu elements held by
185      * this manager.
186      * </p>
187      * 
188      * @return The menu layout; never <code>null</code>.
189      */
190     public SMenuLayout getLayout();
191 
192     /**
193      * Retrieves the menu with the given identifier. If no such menu exists,
194      * then an undefined group is created and returned. A menu is either a
195      * top-level menu, a context menu, a cool bar or a tool bar.
196      * 
197      * @param menuId
198      *            The identifier to find; must not be <code>null</code>.
199      * @return A menu with the given identifier, either defined or undefined.
200      */
201     public SMenu getMenu(String   menuId);
202 
203     /**
204      * Retrieves the widget with the given identifier. If no such widget exists,
205      * then an undefined widget is created and returned. A widget is a custom
206      * contribution into a menu. This allows the plug-in to draw the widgets as
207      * desired.
208      * 
209      * @param widgetId
210      *            The identifier to find; must not be <code>null</code>.
211      * @return A widget with the given identifier, either defined or undefined.
212      */
213     public SWidget getWidget(String   widgetId);
214 
215     /**
216      * <p>
217      * Reads the menu information from the registry and the preferences. This
218      * will overwrite any of the existing information in the menu service. This
219      * method is intended to be called during start-up. When this method
220      * completes, this menu service will reflect the current state of the
221      * registry and preference store.
222      * </p>
223      * <p>
224      * This will also attach listeners that will monitor changes to the registry
225      * and preference store and update appropriately.
226      * </p>
227      */
228     public void readRegistry();
229 
230     /**
231      * Removes the given contribution within the context of this service. If the
232      * contribution was contributed with a different service, then it must be
233      * removed from that service instead. It is only possible to retract a
234      * contribution with this method. That is, you must have the same
235      * <code>IMenuContribution</code> used to contribute.
236      * 
237      * @param contribution
238      *            The token that was returned from a call to
239      *            <code>contributeMenu</code>; must not be <code>null</code>.
240      */
241     public void removeContribution(IMenuContribution contribution);
242 
243     /**
244      * Removes the given contribution within the context of this service. If the
245      * contribution was contributed with a different service, then it must be
246      * removed from that service instead. It is only possible to retract a
247      * contribution with this method. That is, you must have the same
248      * <code>IMenuContribution</code> used to contribute.
249      * 
250      * @param contributions
251      *            The tokens that were returned from a call to
252      *            <code>contributeMenu</code>. This collection must only
253      *            contain instances of <code>IMenuContribution</code>. The
254      *            collection must not be <code>null</code>.
255      */
256     public void removeContributions(Collection   contributions);
257 }
258
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags