IContextService


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  package org.eclipse.ui.contexts;
12  
13  import java.util.Collection  ;
14  
15  import org.eclipse.core.commands.contexts.Context;
16  import org.eclipse.core.commands.contexts.IContextManagerListener;
17  import org.eclipse.core.expressions.Expression;
18  import org.eclipse.swt.widgets.Shell;
19  import org.eclipse.ui.services.IServiceWithSources;
20  
21  /**
22   * <p>
23   * Provides services related to contexts in the Eclipse workbench. This provides
24   * access to contexts.
25   * </p>
26   * <p>
27   * This interface should not be implemented or extended by clients.
28   * </p>
29   * 
30   * @since 3.1
31   */
32  public interface IContextService extends IServiceWithSources {
33  
34      /**
35       * The identifier for the context that is active when a shell registered as
36       * a dialog.
37       */
38      public static final String   CONTEXT_ID_DIALOG = "org.eclipse.ui.contexts.dialog"; //$NON-NLS-1$
39  
40      /**
41       * The identifier for the context that is active when a shell is registered
42       * as either a window or a dialog.
43       */
44      public static final String   CONTEXT_ID_DIALOG_AND_WINDOW = "org.eclipse.ui.contexts.dialogAndWindow"; //$NON-NLS-1$
45  
46      /**
47       * The identifier for the context that is active when a shell is registered
48       * as a window.
49       */
50      public static final String   CONTEXT_ID_WINDOW = "org.eclipse.ui.contexts.window"; //$NON-NLS-1$
51  
52      /**
53       * The type used for registration indicating that the shell should be
54       * treated as a dialog. When the given shell is active, the "In Dialogs"
55       * context should also be active.
56       */
57      public static final int TYPE_DIALOG = 0;
58  
59      /**
60       * The type used for registration indicating that the shell should not
61       * receive any key bindings be default. When the given shell is active, we
62       * should not provide any <code>EnabledSubmission</code> instances for the
63       * "In Dialogs" or "In Windows" contexts.
64       * 
65       */
66      public static final int TYPE_NONE = 1;
67  
68      /**
69       * The type used for registration indicating that the shell should be
70       * treated as a window. When the given shell is active, the "In Windows"
71       * context should also be active.
72       */
73      public static final int TYPE_WINDOW = 2;
74  
75      /**
76       * <p>
77       * Activates the given context within the context of this service. If this
78       * service was retrieved from the workbench, then this context will be
79       * active globally. If the service was retrieved from a nested component,
80       * then the context will only be active within that component.
81       * </p>
82       * <p>
83       * Also, it is guaranteed that the contexts submitted through a particular
84       * service will be cleaned up when that services is destroyed. So, for
85       * example, a service retrieved from a <code>IWorkbenchPartSite</code>
86       * would deactivate all of its contexts when the site is destroyed.
87       * </p>
88       * 
89       * @param contextId
90       *            The identifier for the context which should be activated; must
91       *            not be <code>null</code>.
92       * @return A token which can be used to later cancel the activation. Only
93       *         someone with access to this token can cancel the activation. The
94       *         activation will automatically be cancelled if the context from
95       *         which this service was retrieved is destroyed.
96       */
97      public IContextActivation activateContext(String   contextId);
98  
99      /**
100      * <p>
101      * Activates the given context within the context of this service. The
102      * context becomes active when <code>expression</code> evaluates to
103      * <code>true</code>. This is the same as calling
104      * {@link #activateContext(String, Expression, boolean)} with global==<code>false</code>.
105      * </p>
106      * <p>
107      * Also, it is guaranteed that the context submitted through a particular
108      * service will be cleaned up when that services is destroyed. So, for
109      * example, a service retrieved from a <code>IWorkbenchPartSite</code>
110      * would deactivate all of its handlers when the site is destroyed.
111      * </p>
112      * 
113      * @param contextId
114      *            The identifier for the context which should be activated; must
115      *            not be <code>null</code>.
116      * @param expression
117      *            This expression must evaluate to <code>true</code> before
118      *            this context will really become active. The expression may be
119      *            <code>null</code> if the context should always be active.
120      * @return A token which can be used to later cancel the activation. Only
121      *         someone with access to this token can cancel the activation. The
122      *         activation will automatically be cancelled if the context from
123      *         which this service was retrieved is destroyed.
124      * 
125      * @see org.eclipse.ui.ISources
126      * @since 3.2
127      */
128     public IContextActivation activateContext(String   contextId,
129             Expression expression);
130 
131     /**
132      * <p>
133      * Activates the given context within the context of this service. The
134      * context becomes active when <code>expression</code> evaluates to
135      * <code>true</code>. If global==<code>false</code> then this service
136      * must also be the active service to activate the context.
137      * </p>
138      * <p>
139      * Also, it is guaranteed that the context submitted through a particular
140      * service will be cleaned up when that services is destroyed. So, for
141      * example, a service retrieved from a <code>IWorkbenchPartSite</code>
142      * would deactivate all of its handlers when the site is destroyed.
143      * </p>
144      * 
145      * @param contextId
146      *            The identifier for the context which should be activated; must
147      *            not be <code>null</code>.
148      * @param expression
149      *            This expression must evaluate to <code>true</code> before
150      *            this context will really become active. The expression may be
151      *            <code>null</code> if the context should always be active.
152      * @param global
153      *            Indicates that the handler should be activated irrespectively
154      *            of whether the corresponding workbench component (e.g.,
155      *            window, part, etc.) is active.
156      * @return A token which can be used to later cancel the activation. Only
157      *         someone with access to this token can cancel the activation. The
158      *         activation will automatically be cancelled if the context from
159      *         which this service was retrieved is destroyed.
160      * 
161      * @see org.eclipse.ui.ISources
162      * @since 3.2
163      */
164     public IContextActivation activateContext(String   contextId,
165             Expression expression, boolean global);
166 
167     /**
168      * <p>
169      * Activates the given context within the context of this service. The
170      * context becomes active when <code>expression</code> evaluates to
171      * <code>true</code>.
172      * </p>
173      * <p>
174      * Also, it is guaranteed that the context submitted through a particular
175      * service will be cleaned up when that services is destroyed. So, for
176      * example, a service retrieved from a <code>IWorkbenchPartSite</code>
177      * would deactivate all of its handlers when the site is destroyed.
178      * </p>
179      * 
180      * @param contextId
181      *            The identifier for the context which should be activated; must
182      *            not be <code>null</code>.
183      * @param expression
184      *            This expression must evaluate to <code>true</code> before
185      *            this context will really become active. The expression may be
186      *            <code>null</code> if the context should always be active.
187      * @param sourcePriorities
188      *            The source priorities for the expression.
189      * @return A token which can be used to later cancel the activation. Only
190      *         someone with access to this token can cancel the activation. The
191      *         activation will automatically be cancelled if the context from
192      *         which this service was retrieved is destroyed.
193      * 
194      * @see org.eclipse.ui.ISources
195      * @deprecated Use
196      *             {@link IContextService#activateContext(String, Expression)}
197      *             instead.
198      */
199     public IContextActivation activateContext(String   contextId,
200             Expression expression, int sourcePriorities);
201 
202     /**
203      * Adds a listener to this context service. The listener will be notified
204      * when the set of defined contexts changes. This can be used to track the
205      * global appearance and disappearance of contexts.
206      * 
207      * @param listener
208      *            The listener to attach; must not be <code>null</code>.
209      * @since 3.2
210      */
211     public void addContextManagerListener(IContextManagerListener listener);
212 
213     /**
214      * Deactivates the given context within the context of this service. If the
215      * handler was context with a different service, then it must be deactivated
216      * from that service instead. It is only possible to retract a context
217      * activation with this method. That is, you must have the same
218      * <code>IContextActivation</code> used to activate the context.
219      * 
220      * @param activation
221      *            The token that was returned from a call to
222      *            <code>activateContext</code>; must not be <code>null</code>.
223      */
224     public void deactivateContext(IContextActivation activation);
225 
226     /**
227      * Deactivates the given contexts within the context of this service. If the
228      * contexts were activated with a different service, then they must be
229      * deactivated from that service instead. It is only possible to retract
230      * context activations with this method. That is, you must have the same
231      * <code>IContextActivation</code> instances used to activate the
232      * contexts.
233      * 
234      * @param activations
235      *            The tokens that were returned from a call to
236      *            <code>activateContext</code>. This collection must only
237      *            contain instances of <code>IContextActivation</code>. The
238      *            collection must not be <code>null</code>.
239      */
240     public void deactivateContexts(Collection   activations);
241 
242     /**
243      * Returns the set of active context identifiers.
244      * 
245      * @return The set of active context identifiers; this value may be
246      *         <code>null</code> if no active contexts have been set yet. If
247      *         the set is not <code>null</code>, then it contains only
248      *         instances of <code>String</code>.
249      * @since 3.2
250      */
251     public Collection   getActiveContextIds();
252 
253     /**
254      * Retrieves the context with the given identifier. If no such context
255      * exists, then an undefined context with the given id is created.
256      * 
257      * @param contextId
258      *            The identifier to find; must not be <code>null</code>.
259      * @return A context with the given identifier, either defined or undefined.
260      */
261     public Context getContext(String   contextId);
262 
263     /**
264      * Returns the collection of all of the defined contexts in the workbench.
265      * 
266      * @return The collection of contexts (<code>Context</code>) that are
267      *         defined; never <code>null</code>, but may be empty.
268      * @since 3.2
269      */
270     public Context[] getDefinedContexts();
271 
272     /**
273      * Returns the collection of the identifiers for all of the defined contexts
274      * in the workbench.
275      * 
276      * @return The collection of context identifiers (<code>String</code>)
277      *         that are defined; never <code>null</code>, but may be empty.
278      */
279     public Collection   getDefinedContextIds();
280 
281     /**
282      * Returns the shell type for the given shell.
283      * 
284      * @param shell
285      *            The shell for which the type should be determined. If this
286      *            value is <code>null</code>, then
287      *            <code>IContextService.TYPE_NONE</code> is returned.
288      * @return <code>IContextService.TYPE_WINDOW</code>,
289      *         <code>IContextService.TYPE_DIALOG</code>, or
290      *         <code>IContextService.TYPE_NONE</code>.
291      */
292     public int getShellType(Shell shell);
293 
294     /**
295      * <p>
296      * Reads the context information from the registry and the preferences. This
297      * will overwrite any of the existing information in the context service.
298      * This method is intended to be called during start-up. When this method
299      * completes, this context service will reflect the current state of the
300      * registry and preference store.
301      * </p>
302      */
303     public void readRegistry();
304 
305     /**
306      * <p>
307      * Registers a shell to automatically promote or demote some basic types of
308      * contexts. The "In Dialogs" and "In Windows" contexts are provided by the
309      * system. This a convenience method to ensure that these contexts are
310      * promoted when the given is shell is active.
311      * </p>
312      * <p>
313      * If a shell is registered as a window, then the "In Windows" context is
314      * enabled when that shell is active. If a shell is registered as a dialog --
315      * or is not registered, but has a parent shell -- then the "In Dialogs"
316      * context is enabled when that shell is active. If the shell is registered
317      * as none -- or is not registered, but has no parent shell -- then the
318      * neither of the contexts will be enabled (by us -- someone else can always
319      * enabled them).
320      * </p>
321      * <p>
322      * If the provided shell has already been registered, then this method will
323      * change the registration.
324      * </p>
325      * 
326      * @param shell
327      *            The shell to register for key bindings; must not be
328      *            <code>null</code>.
329      * @param type
330      *            The type of shell being registered. This value must be one of
331      *            the constants given in this interface.
332      * 
333      * @return <code>true</code> if the shell had already been registered
334      *         (i.e., the registration has changed); <code>false</code>
335      *         otherwise.
336      */
337     public boolean registerShell(Shell shell, int type);
338 
339     /**
340      * Removes a listener from this context service.
341      * 
342      * @param listener
343      *            The listener to be removed; must not be <code>null</code>.
344      * @since 3.2
345      */
346     public void removeContextManagerListener(IContextManagerListener listener);
347 
348     /**
349      * <p>
350      * Unregisters a shell that was previously registered. After this method
351      * completes, the shell will be treated as if it had never been registered
352      * at all. If you have registered a shell, you should ensure that this
353      * method is called when the shell is disposed. Otherwise, a potential
354      * memory leak will exist.
355      * </p>
356      * <p>
357      * If the shell was never registered, or if the shell is <code>null</code>,
358      * then this method returns <code>false</code> and does nothing.
359      * 
360      * @param shell
361      *            The shell to be unregistered; does nothing if this value is
362      *            <code>null</code>.
363      * 
364      * @return <code>true</code> if the shell had been registered;
365      *         <code>false</code> otherwise.
366      */
367     public boolean unregisterShell(Shell shell);
368 }
369
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags