001: /*******************************************************************************
002: * Copyright (c) 2005, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.commands;
011:
012: import java.util.Collection;
013: import java.util.Map;
014:
015: import org.eclipse.core.commands.Category;
016: import org.eclipse.core.commands.Command;
017: import org.eclipse.core.commands.CommandManager;
018: import org.eclipse.core.commands.IExecutionListener;
019: import org.eclipse.core.commands.IHandler;
020: import org.eclipse.core.commands.ParameterType;
021: import org.eclipse.core.commands.ParameterizedCommand;
022: import org.eclipse.core.commands.SerializationException;
023: import org.eclipse.core.commands.common.NotDefinedException;
024: import org.eclipse.ui.menus.UIElement;
025: import org.eclipse.ui.services.IDisposable;
026:
027: /**
028: * <p>
029: * Provides services related to the command architecture within the workbench.
030: * This service can be used to access the set of commands and command
031: * categories.
032: * </p>
033: * <p>
034: * This interface should not be implemented or extended by clients.
035: * </p>
036: *
037: * @since 3.1
038: */
039: public interface ICommandService extends IDisposable {
040:
041: /**
042: * The identifier of the category in which all auto-generated commands will
043: * appear. This value must never be <code>null</code>.
044: *
045: * @since 3.2
046: */
047: public static final String AUTOGENERATED_CATEGORY_ID = CommandManager.AUTOGENERATED_CATEGORY_ID;
048:
049: /**
050: * Adds an execution listener to the command service. This listener will be
051: * notified as commands are executed.
052: *
053: * @param listener
054: * The listener to add; must not be <code>null</code>.
055: */
056: public void addExecutionListener(IExecutionListener listener);
057:
058: /**
059: * Sets the name and description of the category for uncategorized commands.
060: * This is the category that will be returned if
061: * {@link #getCategory(String)} is called with <code>null</code>.
062: *
063: * @param name
064: * The name of the category for uncategorized commands; must not
065: * be <code>null</code>.
066: * @param description
067: * The description of the category for uncategorized commands;
068: * may be <code>null</code>.
069: * @since 3.2
070: */
071: public void defineUncategorizedCategory(String name,
072: String description);
073:
074: /**
075: * <p>
076: * Returns a {@link ParameterizedCommand} with a command and
077: * parameterizations as specified in the provided
078: * <code>serializedParameterizedCommand</code> string. The
079: * <code>serializedParameterizedCommand</code> must use the format
080: * returned by {@link ParameterizedCommand#serialize()} and described in the
081: * Javadoc for that method.
082: * </p>
083: * <p>
084: * If a parameter id encoded in the
085: * <code>serializedParameterizedCommand</code> does not exist in the
086: * encoded command, that parameter id and value are ignored. A given
087: * parameter id should not be used more than once in
088: * <code>serializedParameterizedCommand</code>. This will not result in
089: * an exception, but the value of the parameter when the command is executed
090: * cannot be specified here.
091: * </p>
092: * <p>
093: * This method will never return <code>null</code>, however it may throw
094: * an exception if there is a problem processing the serialization string or
095: * the encoded command is undefined.
096: * </p>
097: *
098: * @param serializedParameterizedCommand
099: * a <code>String</code> representing a command id and
100: * parameter ids and values
101: * @return a <code>ParameterizedCommand</code> with the command and
102: * parameterizations encoded in the
103: * <code>serializedParameterizedCommand</code>
104: * @throws NotDefinedException
105: * if the command indicated in
106: * <code>serializedParameterizedCommand</code> is not defined
107: * @throws SerializationException
108: * if there is an error deserializing
109: * <code>serializedParameterizedCommand</code>
110: * @see ParameterizedCommand#serialize()
111: * @see CommandManager#deserialize(String)
112: * @since 3.2
113: */
114: public ParameterizedCommand deserialize(
115: String serializedParameterizedCommand)
116: throws NotDefinedException, SerializationException;
117:
118: /**
119: * Retrieves the category with the given identifier. If no such category
120: * exists, then an undefined category with the given id is created.
121: *
122: * @param categoryId
123: * The identifier to find. If the category is <code>null</code>,
124: * then a category suitable for uncategorized items is defined
125: * and returned.
126: * @return A category with the given identifier, either defined or
127: * undefined.
128: */
129: public Category getCategory(String categoryId);
130:
131: /**
132: * Retrieves the command with the given identifier. If no such command
133: * exists, then an undefined command with the given id is created.
134: *
135: * @param commandId
136: * The identifier to find; must not be <code>null</code>.
137: * @return A command with the given identifier, either defined or undefined.
138: */
139: public Command getCommand(String commandId);
140:
141: /**
142: * Returns the collection of all of the defined categories in the workbench.
143: *
144: * @return The collection of categories (<code>Category</code>) that are
145: * defined; never <code>null</code>, but may be empty.
146: * @since 3.2
147: */
148: public Category[] getDefinedCategories();
149:
150: /**
151: * Returns the collection of the identifiers for all of the defined
152: * categories in the workbench.
153: *
154: * @return The collection of category identifiers (<code>String</code>)
155: * that are defined; never <code>null</code>, but may be empty.
156: */
157: public Collection getDefinedCategoryIds();
158:
159: /**
160: * Returns the collection of the identifiers for all of the defined commands
161: * in the workbench.
162: *
163: * @return The collection of command identifiers (<code>String</code>)
164: * that are defined; never <code>null</code>, but may be empty.
165: */
166: public Collection getDefinedCommandIds();
167:
168: /**
169: * Returns the collection of all of the defined commands in the workbench.
170: *
171: * @return The collection of commands (<code>Command</code>) that are
172: * defined; never <code>null</code>, but may be empty.
173: * @since 3.2
174: */
175: public Command[] getDefinedCommands();
176:
177: /**
178: * Returns the collection of the identifiers for all of the defined command
179: * parameter types in the workbench.
180: *
181: * @return The collection of command parameter type identifiers (<code>String</code>)
182: * that are defined; never <code>null</code>, but may be empty.
183: * @since 3.2
184: */
185: public Collection getDefinedParameterTypeIds();
186:
187: /**
188: * Returns the collection of all of the defined command parameter types in
189: * the workbench.
190: *
191: * @return The collection of command parameter types (<code>ParameterType</code>)
192: * that are defined; never <code>null</code>, but may be empty.
193: * @since 3.2
194: */
195: public ParameterType[] getDefinedParameterTypes();
196:
197: /**
198: * Gets the help context identifier for a particular command. The command's
199: * handler is first checked for a help context identifier. If the handler
200: * does not have a help context identifier, then the help context identifier
201: * for the command is returned. If neither has a help context identifier,
202: * then <code>null</code> is returned.
203: *
204: * @param command
205: * The command for which the help context should be retrieved;
206: * must not be <code>null</code>.
207: * @return The help context identifier to use for the given command; may be
208: * <code>null</code>.
209: * @throws NotDefinedException
210: * If the given command is not defined.
211: * @since 3.2
212: */
213: public String getHelpContextId(Command command)
214: throws NotDefinedException;
215:
216: /**
217: * Gets the help context identifier for a particular command. The command's
218: * handler is first checked for a help context identifier. If the handler
219: * does not have a help context identifier, then the help context identifier
220: * for the command is returned. If neither has a help context identifier,
221: * then <code>null</code> is returned.
222: *
223: * @param commandId
224: * The identifier of the command for which the help context
225: * should be retrieved; must not be <code>null</code>.
226: * @return The help context identifier to use for the given command; may be
227: * <code>null</code>.
228: * @throws NotDefinedException
229: * If the command with the given identifier is not defined.
230: * @since 3.2
231: */
232: public String getHelpContextId(String commandId)
233: throws NotDefinedException;
234:
235: /**
236: * Retrieves the command parameter type with the given identifier. If no
237: * such parameter type exists, then an undefined parameter type with the
238: * given id is created.
239: *
240: * @param parameterTypeId
241: * The identifier to find; must not be <code>null</code>.
242: * @return A command parameter type with the given identifier, either
243: * defined or undefined.
244: * @since 3.2
245: */
246: public ParameterType getParameterType(String parameterTypeId);
247:
248: /**
249: * <p>
250: * Reads the command information from the registry and the preferences. This
251: * will overwrite any of the existing information in the command service.
252: * This method is intended to be called during start-up. When this method
253: * completes, this command service will reflect the current state of the
254: * registry and preference store.
255: * </p>
256: */
257: public void readRegistry();
258:
259: /**
260: * Removes an execution listener from the command service.
261: *
262: * @param listener
263: * The listener to remove; must not be <code>null</code>.
264: */
265: public void removeExecutionListener(IExecutionListener listener);
266:
267: /**
268: * Sets the help context identifier to associate with a particular handler.
269: *
270: * @param handler
271: * The handler with which to register a help context identifier;
272: * must not be <code>null</code>.
273: * @param helpContextId
274: * The help context identifier to register; may be
275: * <code>null</code> if the help context identifier should be
276: * removed.
277: * @since 3.2
278: */
279: public void setHelpContextId(IHandler handler, String helpContextId);
280:
281: /**
282: * Register that this element accepts callbacks for this parameterized
283: * command.
284: *
285: * @param command
286: * The parameterized command that is already specialized. Must
287: * not be <code>null</code>.
288: * @param element
289: * The callback to register for this specialized command
290: * instance. Must not be <code>null</code>.
291: * @return A reference for the registered element that can be used to
292: * unregister it.
293: * @throws NotDefinedException
294: * If the command included in the ParameterizedCommand is not
295: * defined, or the element is <code>null</code>.
296: * @since 3.3
297: */
298: public IElementReference registerElementForCommand(
299: ParameterizedCommand command, UIElement element)
300: throws NotDefinedException;
301:
302: /**
303: * Re-register a callback element provided by the ICommandService. This
304: * element reference must not currently be held by the ICommandService. i.e.
305: * it must have been removed using
306: * {@link #unregisterElement(IElementReference)}.
307: *
308: * @param elementReference
309: * The reference to re-register. Must not be <code>null</code>.
310: * @since 3.3
311: */
312: public void registerElement(IElementReference elementReference);
313:
314: /**
315: * Unregister an element callback. It will be removed from the
316: * ICommandService. The same service that is used to register an element for
317: * a command <b>must</b> be used to unregister the element.
318: *
319: * @param elementReference
320: * The callback reference that was provided by the command
321: * service on registration. Must not be <code>null</code>.
322: * @since 3.3
323: */
324: public void unregisterElement(IElementReference elementReference);
325:
326: /**
327: * Refresh any elements registered against the command with the given id.
328: * It allows the active handler the opportunity to provide user feedback. If
329: * the command is parameterized, some of the parameters can be specified to
330: * help narrow down which elements to refresh.
331: * <p>
332: * The service locator used in registering the element can also be used to
333: * scope the search. For example: if you wanted all elements for your
334: * command but only within the part's workbench window, you could use:
335: *
336: * <pre>
337: * Map filter = new HashMap();
338: * filter.put(IServiceScopes.WINDOW_SCOPE, getSite().getPage()
339: * .getWorkbenchWindow());
340: * commandService.refreshElements(commandId, filter);
341: * </pre>
342: *
343: * </p>
344: *
345: * @param commandId
346: * The command id to refresh if it has registered eleemnts.
347: * @param filter
348: * key-value pairs that can narrow down the callbacks to return.
349: * The parameters are <b>AND</b>ed together. This may be
350: * <code>null</code>.
351: * @since 3.3
352: */
353: public void refreshElements(String commandId, Map filter);
354: }
|