001: /*******************************************************************************
002: * Copyright (c) 2005, 2006 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.handlers;
011:
012: import java.util.Collection;
013:
014: import org.eclipse.core.commands.Command;
015: import org.eclipse.core.commands.ExecutionEvent;
016: import org.eclipse.core.commands.ExecutionException;
017: import org.eclipse.core.commands.IHandler;
018: import org.eclipse.core.commands.NotEnabledException;
019: import org.eclipse.core.commands.NotHandledException;
020: import org.eclipse.core.commands.ParameterizedCommand;
021: import org.eclipse.core.commands.common.NotDefinedException;
022: import org.eclipse.core.expressions.Expression;
023: import org.eclipse.core.expressions.IEvaluationContext;
024: import org.eclipse.swt.widgets.Event;
025: import org.eclipse.ui.services.IServiceWithSources;
026:
027: /**
028: * <p>
029: * Provides services related to activating and deactivating handlers within the
030: * workbench.
031: * </p>
032: * <p>
033: * This interface is not intended to be implemented or extended by clients.
034: * </p>
035: *
036: * @since 3.1
037: */
038: public interface IHandlerService extends IServiceWithSources {
039:
040: /**
041: * <p>
042: * Activates the given handler from a child service. This is used by slave
043: * and nested services to promote handler activations up to the root. By
044: * using this method, it is possible for handlers coming from a more nested
045: * component to override the nested component.
046: * </p>
047: *
048: * @param activation
049: * The activation that is local to the child service; must not be
050: * <code>null</code>.
051: * @return A token which can be used to later cancel the activation. Only
052: * someone with access to this token can cancel the activation. The
053: * activation will automatically be cancelled if the context from
054: * which this service was retrieved is destroyed. This activation is
055: * local to this service (i.e., it is not the activation that is
056: * passed as a parameter).
057: * @since 3.2
058: */
059: public IHandlerActivation activateHandler(
060: IHandlerActivation activation);
061:
062: /**
063: * <p>
064: * Activates the given handler within the context of this service. If this
065: * service was retrieved from the workbench, then this handler will be
066: * active globally. If the service was retrieved from a nested component,
067: * then the handler will only be active within that component.
068: * </p>
069: * <p>
070: * Also, it is guaranteed that the handlers submitted through a particular
071: * service will be cleaned up when that services is destroyed. So, for
072: * example, a service retrieved from a <code>IWorkbenchPartSite</code>
073: * would deactivate all of its handlers when the site is destroyed.
074: * </p>
075: *
076: * @param commandId
077: * The identifier for the command which this handler handles;
078: * must not be <code>null</code>.
079: * @param handler
080: * The handler to activate; must not be <code>null</code>.
081: * @return A token which can be used to later cancel the activation. Only
082: * someone with access to this token can cancel the activation. The
083: * activation will automatically be cancelled if the context from
084: * which this service was retrieved is destroyed.
085: */
086: public IHandlerActivation activateHandler(String commandId,
087: IHandler handler);
088:
089: /**
090: * <p>
091: * Activates the given handler within the context of this service. The
092: * handler becomes active when <code>expression</code> evaluates to
093: * <code>true</code>. This is the same as calling
094: * {@link #activateHandler(String, IHandler, Expression, boolean)} with
095: * global==false.
096: * </p>
097: * <p>
098: * Also, it is guaranteed that the handlers submitted through a particular
099: * service will be cleaned up when that services is destroyed. So, for
100: * example, a service retrieved from a <code>IWorkbenchPartSite</code>
101: * would deactivate all of its handlers when the site is destroyed.
102: * </p>
103: *
104: * @param commandId
105: * The identifier for the command which this handler handles;
106: * must not be <code>null</code>.
107: * @param handler
108: * The handler to activate; must not be <code>null</code>.
109: * @param expression
110: * This expression must evaluate to <code>true</code> before
111: * this handler will really become active. The expression may be
112: * <code>null</code> if the handler should always be active.
113: * @return A token which can be used to later cancel the activation. Only
114: * someone with access to this token can cancel the activation. The
115: * activation will automatically be cancelled if the context from
116: * which this service was retrieved is destroyed.
117: *
118: * @see org.eclipse.ui.ISources
119: * @since 3.2
120: */
121: public IHandlerActivation activateHandler(String commandId,
122: IHandler handler, Expression expression);
123:
124: /**
125: * <p>
126: * Activates the given handler within the context of this service. The
127: * handler becomes active when <code>expression</code> evaluates to
128: * <code>true</code>. if global==<code>false</code>, then this
129: * handler service must also be the active service to active the handler.
130: * For example, the handler service on a part is active when that part is
131: * active.
132: * </p>
133: * <p>
134: * Also, it is guaranteed that the handlers submitted through a particular
135: * service will be cleaned up when that services is destroyed. So, for
136: * example, a service retrieved from a <code>IWorkbenchPartSite</code>
137: * would deactivate all of its handlers when the site is destroyed.
138: * </p>
139: *
140: * @param commandId
141: * The identifier for the command which this handler handles;
142: * must not be <code>null</code>.
143: * @param handler
144: * The handler to activate; must not be <code>null</code>.
145: * @param expression
146: * This expression must evaluate to <code>true</code> before
147: * this handler will really become active. The expression may be
148: * <code>null</code> if the handler should always be active.
149: * @param global
150: * Indicates that the handler should be activated irrespectively
151: * of whether the corresponding workbench component (e.g.,
152: * window, part, etc.) is active.
153: * @return A token which can be used to later cancel the activation. Only
154: * someone with access to this token can cancel the activation. The
155: * activation will automatically be cancelled if the context from
156: * which this service was retrieved is destroyed.
157: *
158: * @see org.eclipse.ui.ISources
159: * @since 3.2
160: */
161: public IHandlerActivation activateHandler(String commandId,
162: IHandler handler, Expression expression, boolean global);
163:
164: /**
165: * <p>
166: * Activates the given handler within the context of this service. The
167: * handler becomes active when <code>expression</code> evaluates to
168: * <code>true</code>.
169: * </p>
170: * <p>
171: * Also, it is guaranteed that the handlers submitted through a particular
172: * service will be cleaned up when that services is destroyed. So, for
173: * example, a service retrieved from a <code>IWorkbenchPartSite</code>
174: * would deactivate all of its handlers when the site is destroyed.
175: * </p>
176: *
177: * @param commandId
178: * The identifier for the command which this handler handles;
179: * must not be <code>null</code>.
180: * @param handler
181: * The handler to activate; must not be <code>null</code>.
182: * @param expression
183: * This expression must evaluate to <code>true</code> before
184: * this handler will really become active. The expression may be
185: * <code>null</code> if the handler should always be active.
186: * @param sourcePriorities
187: * The source priorities for the expression.
188: * @return A token which can be used to later cancel the activation. Only
189: * someone with access to this token can cancel the activation. The
190: * activation will automatically be cancelled if the context from
191: * which this service was retrieved is destroyed.
192: *
193: * @see org.eclipse.ui.ISources
194: * @deprecated Use
195: * {@link IHandlerService#activateHandler(String, IHandler, Expression)}
196: * instead.
197: */
198: public IHandlerActivation activateHandler(String commandId,
199: IHandler handler, Expression expression,
200: int sourcePriorities);
201:
202: /**
203: * Creates an execution event based on an SWT event. This execution event
204: * can then be passed to a command for execution.
205: *
206: * @param command
207: * The command for which an execution event should be created;
208: * must not be <code>null</code>.
209: * @param event
210: * The SWT event triggering the command execution; may be
211: * <code>null</code>.
212: * @return An execution event suitable for calling
213: * {@link Command#executeWithChecks(ExecutionEvent)}.
214: * @since 3.2
215: * @see Command#executeWithChecks(ExecutionEvent)
216: */
217: public ExecutionEvent createExecutionEvent(Command command,
218: Event event);
219:
220: /**
221: * Creates a parameterized execution event based on an SWT event and a
222: * parameterized command. This execution event can then be passed to a
223: * command for execution.
224: *
225: * @param command
226: * The parameterized command for which an execution event should
227: * be created; must not be <code>null</code>.
228: * @param event
229: * The SWT event triggering the command execution; may be
230: * <code>null</code>.
231: * @return An execution event suitable for calling
232: * {@link Command#executeWithChecks(ExecutionEvent)}.
233: * @since 3.2
234: * @see ParameterizedCommand#getCommand()
235: * @see Command#executeWithChecks(ExecutionEvent)
236: */
237: public ExecutionEvent createExecutionEvent(
238: ParameterizedCommand command, Event event);
239:
240: /**
241: * Deactivates the given handler within the context of this service. If the
242: * handler was activated with a different service, then it must be
243: * deactivated from that service instead. It is only possible to retract a
244: * handler activation with this method. That is, you must have the same
245: * <code>IHandlerActivation</code> used to activate the handler.
246: *
247: * @param activation
248: * The token that was returned from a call to
249: * <code>activateHandler</code>; must not be <code>null</code>.
250: */
251: public void deactivateHandler(IHandlerActivation activation);
252:
253: /**
254: * Deactivates the given handlers within the context of this service. If the
255: * handler was activated with a different service, then it must be
256: * deactivated from that service instead. It is only possible to retract a
257: * handler activation with this method. That is, you must have the same
258: * <code>IHandlerActivation</code> used to activate the handler.
259: *
260: * @param activations
261: * The tokens that were returned from a call to
262: * <code>activateHandler</code>. This collection must only
263: * contain instances of <code>IHandlerActivation</code>. The
264: * collection must not be <code>null</code>.
265: */
266: public void deactivateHandlers(Collection activations);
267:
268: /**
269: * Executes the command with the given identifier and no parameters.
270: *
271: * @param commandId
272: * The identifier of the command to execute; must not be
273: * <code>null</code>.
274: * @param event
275: * The SWT event triggering the command execution; may be
276: * <code>null</code>.
277: * @return The return value from the execution; may be <code>null</code>.
278: * @throws ExecutionException
279: * If the handler has problems executing this command.
280: * @throws NotDefinedException
281: * If the command you are trying to execute is not defined.
282: * @throws NotEnabledException
283: * If the command you are trying to execute is not enabled.
284: * @throws NotHandledException
285: * If there is no handler.
286: * @since 3.2
287: * @see Command#executeWithChecks(ExecutionEvent)
288: */
289: public Object executeCommand(String commandId, Event event)
290: throws ExecutionException, NotDefinedException,
291: NotEnabledException, NotHandledException;
292:
293: /**
294: * Executes the given parameterized command.
295: *
296: * @param command
297: * The parameterized command to be executed; must not be
298: * <code>null</code>.
299: * @param event
300: * The SWT event triggering the command execution; may be
301: * <code>null</code>.
302: * @return The return value from the execution; may be <code>null</code>.
303: * @throws ExecutionException
304: * If the handler has problems executing this command.
305: * @throws NotDefinedException
306: * If the command you are trying to execute is not defined.
307: * @throws NotEnabledException
308: * If the command you are trying to execute is not enabled.
309: * @throws NotHandledException
310: * If there is no handler.
311: * @since 3.2
312: * @see Command#executeWithChecks(ExecutionEvent)
313: */
314: public Object executeCommand(ParameterizedCommand command,
315: Event event) throws ExecutionException,
316: NotDefinedException, NotEnabledException,
317: NotHandledException;
318:
319: /**
320: * Returns an evaluation context representing the current state of the
321: * world. This is equivalent to the application context required by
322: * {@link ExecutionEvent}.
323: *
324: * @return the current state of the application; never <code>null</code>.
325: * @see ParameterizedCommand#executeWithChecks(Object, Object)
326: * @see ExecutionEvent#ExecutionEvent(Command, java.util.Map, Object,
327: * Object)
328: */
329: public IEvaluationContext getCurrentState();
330:
331: /**
332: * <p>
333: * Reads the handler information from the registry. This will overwrite any
334: * of the existing information in the handler service. This method is
335: * intended to be called during start-up. When this method completes, this
336: * handler service will reflect the current state of the registry.
337: * </p>
338: */
339: public void readRegistry();
340:
341: /**
342: * Sets the help context identifier to associate with a particular handler.
343: *
344: * @param handler
345: * The handler with which to register a help context identifier;
346: * must not be <code>null</code>.
347: * @param helpContextId
348: * The help context identifier to register; may be
349: * <code>null</code> if the help context identifier should be
350: * removed.
351: * @since 3.2
352: */
353: public void setHelpContextId(IHandler handler, String helpContextId);
354: }
|