IHandlerService


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  
12  package org.eclipse.ui.handlers;
13  
14  import java.util.Collection  ;
15  
16  import org.eclipse.core.commands.Command;
17  import org.eclipse.core.commands.ExecutionEvent;
18  import org.eclipse.core.commands.ExecutionException;
19  import org.eclipse.core.commands.IHandler;
20  import org.eclipse.core.commands.NotEnabledException;
21  import org.eclipse.core.commands.NotHandledException;
22  import org.eclipse.core.commands.ParameterizedCommand;
23  import org.eclipse.core.commands.common.NotDefinedException;
24  import org.eclipse.core.expressions.Expression;
25  import org.eclipse.core.expressions.IEvaluationContext;
26  import org.eclipse.swt.widgets.Event;
27  import org.eclipse.ui.services.IServiceWithSources;
28  
29  /**
30   * <p>
31   * Provides services related to activating and deactivating handlers within the
32   * workbench.
33   * </p>
34   * <p>
35   * This interface is not intended to be implemented or extended by clients.
36   * </p>
37   * 
38   * @since 3.1
39   */
40  public interface IHandlerService extends IServiceWithSources {
41  
42      /**
43       * <p>
44       * Activates the given handler from a child service. This is used by slave
45       * and nested services to promote handler activations up to the root. By
46       * using this method, it is possible for handlers coming from a more nested
47       * component to override the nested component.
48       * </p>
49       * 
50       * @param activation
51       *            The activation that is local to the child service; must not be
52       *            <code>null</code>.
53       * @return A token which can be used to later cancel the activation. Only
54       *         someone with access to this token can cancel the activation. The
55       *         activation will automatically be cancelled if the context from
56       *         which this service was retrieved is destroyed. This activation is
57       *         local to this service (i.e., it is not the activation that is
58       *         passed as a parameter).
59       * @since 3.2
60       */
61      public IHandlerActivation activateHandler(IHandlerActivation activation);
62  
63      /**
64       * <p>
65       * Activates the given handler within the context of this service. If this
66       * service was retrieved from the workbench, then this handler will be
67       * active globally. If the service was retrieved from a nested component,
68       * then the handler will only be active within that component.
69       * </p>
70       * <p>
71       * Also, it is guaranteed that the handlers submitted through a particular
72       * service will be cleaned up when that services is destroyed. So, for
73       * example, a service retrieved from a <code>IWorkbenchPartSite</code>
74       * would deactivate all of its handlers when the site is destroyed.
75       * </p>
76       * 
77       * @param commandId
78       *            The identifier for the command which this handler handles;
79       *            must not be <code>null</code>.
80       * @param handler
81       *            The handler to activate; must not be <code>null</code>.
82       * @return A token which can be used to later cancel the activation. Only
83       *         someone with access to this token can cancel the activation. The
84       *         activation will automatically be cancelled if the context from
85       *         which this service was retrieved is destroyed.
86       */
87      public IHandlerActivation activateHandler(String   commandId, IHandler handler);
88  
89      /**
90       * <p>
91       * Activates the given handler within the context of this service. The
92       * handler becomes active when <code>expression</code> evaluates to
93       * <code>true</code>. This is the same as calling
94       * {@link #activateHandler(String, IHandler, Expression, boolean)} with
95       * global==false.
96       * </p>
97       * <p>
98       * Also, it is guaranteed that the handlers submitted through a particular
99       * 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, int sourcePriorities);
200 
201     /**
202      * Creates an execution event based on an SWT event. This execution event
203      * can then be passed to a command for execution.
204      * 
205      * @param command
206      *            The command for which an execution event should be created;
207      *            must not be <code>null</code>.
208      * @param event
209      *            The SWT event triggering the command execution; may be
210      *            <code>null</code>.
211      * @return An execution event suitable for calling
212      *         {@link Command#executeWithChecks(ExecutionEvent)}.
213      * @since 3.2
214      * @see Command#executeWithChecks(ExecutionEvent)
215      */
216     public ExecutionEvent createExecutionEvent(Command command, Event event);
217 
218     /**
219      * Creates a parameterized execution event based on an SWT event and a
220      * parameterized command. This execution event can then be passed to a
221      * command for execution.
222      * 
223      * @param command
224      *            The parameterized command for which an execution event should
225      *            be created; must not be <code>null</code>.
226      * @param event
227      *            The SWT event triggering the command execution; may be
228      *            <code>null</code>.
229      * @return An execution event suitable for calling
230      *         {@link Command#executeWithChecks(ExecutionEvent)}.
231      * @since 3.2
232      * @see ParameterizedCommand#getCommand()
233      * @see Command#executeWithChecks(ExecutionEvent)
234      */
235     public ExecutionEvent createExecutionEvent(ParameterizedCommand command,
236             Event event);
237 
238     /**
239      * Deactivates the given handler within the context of this service. If the
240      * handler was activated with a different service, then it must be
241      * deactivated from that service instead. It is only possible to retract a
242      * handler activation with this method. That is, you must have the same
243      * <code>IHandlerActivation</code> used to activate the handler.
244      * 
245      * @param activation
246      *            The token that was returned from a call to
247      *            <code>activateHandler</code>; must not be <code>null</code>.
248      */
249     public void deactivateHandler(IHandlerActivation activation);
250 
251     /**
252      * Deactivates the given handlers within the context of this service. If the
253      * handler was activated with a different service, then it must be
254      * deactivated from that service instead. It is only possible to retract a
255      * handler activation with this method. That is, you must have the same
256      * <code>IHandlerActivation</code> used to activate the handler.
257      * 
258      * @param activations
259      *            The tokens that were returned from a call to
260      *            <code>activateHandler</code>. This collection must only
261      *            contain instances of <code>IHandlerActivation</code>. The
262      *            collection must not be <code>null</code>.
263      */
264     public void deactivateHandlers(Collection   activations);
265 
266     /**
267      * Executes the command with the given identifier and no parameters.
268      * 
269      * @param commandId
270      *            The identifier of the command to execute; must not be
271      *            <code>null</code>.
272      * @param event
273      *            The SWT event triggering the command execution; may be
274      *            <code>null</code>.
275      * @return The return value from the execution; may be <code>null</code>.
276      * @throws ExecutionException
277      *             If the handler has problems executing this command.
278      * @throws NotDefinedException
279      *             If the command you are trying to execute is not defined.
280      * @throws NotEnabledException
281      *             If the command you are trying to execute is not enabled.
282      * @throws NotHandledException
283      *             If there is no handler.
284      * @since 3.2
285      * @see Command#executeWithChecks(ExecutionEvent)
286      */
287     public Object   executeCommand(String   commandId, Event event)
288             throws ExecutionException, NotDefinedException,
289             NotEnabledException, NotHandledException;
290 
291     /**
292      * Executes the given parameterized command.
293      * 
294      * @param command
295      *            The parameterized command to be executed; must not be
296      *            <code>null</code>.
297      * @param event
298      *            The SWT event triggering the command execution; may be
299      *            <code>null</code>.
300      * @return The return value from the execution; may be <code>null</code>.
301      * @throws ExecutionException
302      *             If the handler has problems executing this command.
303      * @throws NotDefinedException
304      *             If the command you are trying to execute is not defined.
305      * @throws NotEnabledException
306      *             If the command you are trying to execute is not enabled.
307      * @throws NotHandledException
308      *             If there is no handler.
309      * @since 3.2
310      * @see Command#executeWithChecks(ExecutionEvent)
311      */
312     public Object   executeCommand(ParameterizedCommand command, Event event)
313             throws ExecutionException, NotDefinedException,
314             NotEnabledException, NotHandledException;
315 
316     /**
317      * Returns an evaluation context representing the current state of the
318      * world. This is equivalent to the application context required by
319      * {@link ExecutionEvent}.
320      * 
321      * @return the current state of the application; never <code>null</code>.
322      * @see ParameterizedCommand#executeWithChecks(Object, Object)
323      * @see ExecutionEvent#ExecutionEvent(Command, java.util.Map, Object,
324      *      Object)
325      */
326     public IEvaluationContext getCurrentState();
327 
328     /**
329      * <p>
330      * Reads the handler information from the registry. This will overwrite any
331      * of the existing information in the handler service. This method is
332      * intended to be called during start-up. When this method completes, this
333      * handler service will reflect the current state of the registry.
334      * </p>
335      */
336     public void readRegistry();
337 
338     /**
339      * Sets the help context identifier to associate with a particular handler.
340      * 
341      * @param handler
342      *            The handler with which to register a help context identifier;
343      *            must not be <code>null</code>.
344      * @param helpContextId
345      *            The help context identifier to register; may be
346      *            <code>null</code> if the help context identifier should be
347      *            removed.
348      * @since 3.2
349      */
350     public void setHelpContextId(IHandler handler, String   helpContextId);
351 }
352
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags