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