IContributionManager


1   /*******************************************************************************
2    * Copyright (c) 2000, 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.jface.action;
12  
13  /**
14   * A contribution manager organizes contributions to such UI components
15   * as menus, toolbars and status lines.
16   * <p>
17   * A contribution manager keeps track of a list of contribution
18   * items. Each contribution item may has an optional identifier, which can be used
19   * to retrieve items from a manager, and for positioning items relative to
20   * each other. The list of contribution items can be subdivided into named groups 
21   * using special contribution items that serve as group markers.
22   * </p>
23   * <p>
24   * The <code>IContributionManager</code> interface provides general
25   * protocol for adding, removing, and retrieving contribution items.
26   * It also provides convenience methods that make it convenient
27   * to contribute actions. This interface should be implemented
28   * by all objects that wish to manage contributions.
29   * </p>
30   * <p>
31   * There are several implementions of this interface in this package,
32   * including ones for menus ({@link MenuManager <code>MenuManager</code>}),
33   * tool bars ({@link ToolBarManager <code>ToolBarManager</code>}),
34   * and status lines ({@link StatusLineManager <code>StatusLineManager</code>}).
35   * </p>
36   */
37  public interface IContributionManager {
38      /**
39       * Adds an action as a contribution item to this manager.
40       * Equivalent to <code>add(new ActionContributionItem(action))</code>.
41       *
42       * @param action the action
43       */
44      public void add(IAction action);
45  
46      /**
47       * Adds a contribution item to this manager.
48       *
49       * @param item the contribution item
50       */
51      public void add(IContributionItem item);
52  
53      /**
54       * Adds a contribution item for the given action at the end of the group
55       * with the given name.
56       * Equivalent to
57       * <code>appendToGroup(groupName,new ActionContributionItem(action))</code>.
58       *
59       * @param groupName the name of the group
60       * @param action the action
61       * @exception IllegalArgumentException if there is no group with
62       *   the given name
63       */
64      public void appendToGroup(String   groupName, IAction action);
65  
66      /**
67       * Adds a contribution item to this manager at the end of the group
68       * with the given name.
69       *
70       * @param groupName the name of the group
71       * @param item the contribution item
72       * @exception IllegalArgumentException if there is no group with
73       *   the given name
74       */
75      public void appendToGroup(String   groupName, IContributionItem item);
76  
77      /**
78       * Finds the contribution item with the given id.
79       *
80       * @param id the contribution item id
81       * @return the contribution item, or <code>null</code> if
82       *   no item with the given id can be found
83       */
84      public IContributionItem find(String   id);
85  
86      /**
87       * Returns all contribution items known to this manager.
88       *
89       * @return a list of contribution items
90       */
91      public IContributionItem[] getItems();
92  
93      /**
94       * Returns the overrides for the items of this manager.
95       * 
96       * @return the overrides for the items of this manager
97       * @since 2.0 
98       */
99      public IContributionManagerOverrides getOverrides();
100 
101     /**
102      * Inserts a contribution item for the given action after the item 
103      * with the given id.
104      * Equivalent to
105      * <code>insertAfter(id,new ActionContributionItem(action))</code>.
106      *
107      * @param id the contribution item id
108      * @param action the action to insert
109      * @exception IllegalArgumentException if there is no item with
110      *   the given id
111      */
112     public void insertAfter(String   id, IAction action);
113 
114     /**
115      * Inserts a contribution item after the item with the given id.
116      *
117      * @param id the contribution item id
118      * @param item the contribution item to insert
119      * @exception IllegalArgumentException if there is no item with
120      *   the given id
121      */
122     public void insertAfter(String   id, IContributionItem item);
123 
124     /**
125      * Inserts a contribution item for the given action before the item 
126      * with the given id.
127      * Equivalent to
128      * <code>insertBefore(id,new ActionContributionItem(action))</code>.
129      *
130      * @param id the contribution item id
131      * @param action the action to insert
132      * @exception IllegalArgumentException if there is no item with
133      *   the given id
134      */
135     public void insertBefore(String   id, IAction action);
136 
137     /**
138      * Inserts a contribution item before the item with the given id.
139      *
140      * @param id the contribution item id
141      * @param item the contribution item to insert
142      * @exception IllegalArgumentException if there is no item with
143      *   the given id
144      */
145     public void insertBefore(String   id, IContributionItem item);
146 
147     /**
148      * Returns whether the list of contributions has recently changed and
149      * has yet to be reflected in the corresponding widgets.
150      *
151      * @return <code>true</code> if this manager is dirty, and <code>false</code>
152      *   if it is up-to-date
153      */
154     public boolean isDirty();
155 
156     /**
157      * Returns whether this manager has any contribution items.
158      *
159      * @return <code>true</code> if there are no items, and
160      *   <code>false</code> otherwise
161      */
162     public boolean isEmpty();
163 
164     /**
165      * Marks this contribution manager as dirty.
166      */
167     public void markDirty();
168 
169     /**
170      * Adds a contribution item for the given action at the beginning of the 
171      * group with the given name.
172      * Equivalent to
173      * <code>prependToGroup(groupName,new ActionContributionItem(action))</code>.
174      *
175      * @param groupName the name of the group
176      * @param action the action
177      * @exception IllegalArgumentException if there is no group with
178      *   the given name
179      */
180     public void prependToGroup(String   groupName, IAction action);
181 
182     /**
183      * Adds a contribution item to this manager at the beginning of the 
184      * group with the given name.
185      *
186      * @param groupName the name of the group
187      * @param item the contribution item
188      * @exception IllegalArgumentException if there is no group with
189      *   the given name
190      */
191     public void prependToGroup(String   groupName, IContributionItem item);
192 
193     /**
194      * Removes and returns the contribution item with the given id from this manager.  
195      * Returns <code>null</code> if this manager has no contribution items
196      * with the given id.
197      *
198      * @param id the contribution item id
199      * @return the item that was found and removed, or <code>null</code> if none
200      */
201     public IContributionItem remove(String   id);
202 
203     /**
204      * Removes the given contribution item from the contribution items
205      * known to this manager.
206      *
207      * @param item the contribution item
208      * @return the <code>item</code> parameter if the item was removed,
209      *   and <code>null</code> if it was not found
210      */
211     public IContributionItem remove(IContributionItem item);
212 
213     /**
214      * Removes all contribution items from this manager.
215      */
216     public void removeAll();
217 
218     /**
219      * Updates this manager's underlying widget(s) with any changes which
220      * have been made to it or its items.  Normally changes to a contribution
221      * manager merely mark it as dirty, without updating the underlying widgets.
222      * This brings the underlying widgets up to date with any changes.
223      *
224      * @param force <code>true</code> means update even if not dirty,
225      *   and <code>false</code> for normal incremental updating
226      */
227     public void update(boolean force);
228 }
229
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags