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.contexts;
011:
012: import java.util.Collection;
013:
014: import org.eclipse.core.commands.contexts.Context;
015: import org.eclipse.core.commands.contexts.IContextManagerListener;
016: import org.eclipse.core.expressions.Expression;
017: import org.eclipse.swt.widgets.Shell;
018: import org.eclipse.ui.services.IServiceWithSources;
019:
020: /**
021: * <p>
022: * Provides services related to contexts in the Eclipse workbench. This provides
023: * access to contexts.
024: * </p>
025: * <p>
026: * This interface should not be implemented or extended by clients.
027: * </p>
028: *
029: * @since 3.1
030: */
031: public interface IContextService extends IServiceWithSources {
032:
033: /**
034: * The identifier for the context that is active when a shell registered as
035: * a dialog.
036: */
037: public static final String CONTEXT_ID_DIALOG = "org.eclipse.ui.contexts.dialog"; //$NON-NLS-1$
038:
039: /**
040: * The identifier for the context that is active when a shell is registered
041: * as either a window or a dialog.
042: */
043: public static final String CONTEXT_ID_DIALOG_AND_WINDOW = "org.eclipse.ui.contexts.dialogAndWindow"; //$NON-NLS-1$
044:
045: /**
046: * The identifier for the context that is active when a shell is registered
047: * as a window.
048: */
049: public static final String CONTEXT_ID_WINDOW = "org.eclipse.ui.contexts.window"; //$NON-NLS-1$
050:
051: /**
052: * The type used for registration indicating that the shell should be
053: * treated as a dialog. When the given shell is active, the "In Dialogs"
054: * context should also be active.
055: */
056: public static final int TYPE_DIALOG = 0;
057:
058: /**
059: * The type used for registration indicating that the shell should not
060: * receive any key bindings be default. When the given shell is active, we
061: * should not provide any <code>EnabledSubmission</code> instances for the
062: * "In Dialogs" or "In Windows" contexts.
063: *
064: */
065: public static final int TYPE_NONE = 1;
066:
067: /**
068: * The type used for registration indicating that the shell should be
069: * treated as a window. When the given shell is active, the "In Windows"
070: * context should also be active.
071: */
072: public static final int TYPE_WINDOW = 2;
073:
074: /**
075: * <p>
076: * Activates the given context within the context of this service. If this
077: * service was retrieved from the workbench, then this context will be
078: * active globally. If the service was retrieved from a nested component,
079: * then the context will only be active within that component.
080: * </p>
081: * <p>
082: * Also, it is guaranteed that the contexts submitted through a particular
083: * service will be cleaned up when that services is destroyed. So, for
084: * example, a service retrieved from a <code>IWorkbenchPartSite</code>
085: * would deactivate all of its contexts when the site is destroyed.
086: * </p>
087: *
088: * @param contextId
089: * The identifier for the context which should be activated; must
090: * not be <code>null</code>.
091: * @return A token which can be used to later cancel the activation. Only
092: * someone with access to this token can cancel the activation. The
093: * activation will automatically be cancelled if the context from
094: * which this service was retrieved is destroyed.
095: */
096: public IContextActivation activateContext(String contextId);
097:
098: /**
099: * <p>
100: * Activates the given context within the context of this service. The
101: * context becomes active when <code>expression</code> evaluates to
102: * <code>true</code>. This is the same as calling
103: * {@link #activateContext(String, Expression, boolean)} with global==<code>false</code>.
104: * </p>
105: * <p>
106: * Also, it is guaranteed that the context submitted through a particular
107: * service will be cleaned up when that services is destroyed. So, for
108: * example, a service retrieved from a <code>IWorkbenchPartSite</code>
109: * would deactivate all of its handlers when the site is destroyed.
110: * </p>
111: *
112: * @param contextId
113: * The identifier for the context which should be activated; must
114: * not be <code>null</code>.
115: * @param expression
116: * This expression must evaluate to <code>true</code> before
117: * this context will really become active. The expression may be
118: * <code>null</code> if the context should always be active.
119: * @return A token which can be used to later cancel the activation. Only
120: * someone with access to this token can cancel the activation. The
121: * activation will automatically be cancelled if the context from
122: * which this service was retrieved is destroyed.
123: *
124: * @see org.eclipse.ui.ISources
125: * @since 3.2
126: */
127: public IContextActivation activateContext(String contextId,
128: Expression expression);
129:
130: /**
131: * <p>
132: * Activates the given context within the context of this service. The
133: * context becomes active when <code>expression</code> evaluates to
134: * <code>true</code>. If global==<code>false</code> then this service
135: * must also be the active service to activate the context.
136: * </p>
137: * <p>
138: * Also, it is guaranteed that the context submitted through a particular
139: * service will be cleaned up when that services is destroyed. So, for
140: * example, a service retrieved from a <code>IWorkbenchPartSite</code>
141: * would deactivate all of its handlers when the site is destroyed.
142: * </p>
143: *
144: * @param contextId
145: * The identifier for the context which should be activated; must
146: * not be <code>null</code>.
147: * @param expression
148: * This expression must evaluate to <code>true</code> before
149: * this context will really become active. The expression may be
150: * <code>null</code> if the context should always be active.
151: * @param global
152: * Indicates that the handler should be activated irrespectively
153: * of whether the corresponding workbench component (e.g.,
154: * window, part, etc.) is active.
155: * @return A token which can be used to later cancel the activation. Only
156: * someone with access to this token can cancel the activation. The
157: * activation will automatically be cancelled if the context from
158: * which this service was retrieved is destroyed.
159: *
160: * @see org.eclipse.ui.ISources
161: * @since 3.2
162: */
163: public IContextActivation activateContext(String contextId,
164: Expression expression, boolean global);
165:
166: /**
167: * <p>
168: * Activates the given context within the context of this service. The
169: * context becomes active when <code>expression</code> evaluates to
170: * <code>true</code>.
171: * </p>
172: * <p>
173: * Also, it is guaranteed that the context submitted through a particular
174: * service will be cleaned up when that services is destroyed. So, for
175: * example, a service retrieved from a <code>IWorkbenchPartSite</code>
176: * would deactivate all of its handlers when the site is destroyed.
177: * </p>
178: *
179: * @param contextId
180: * The identifier for the context which should be activated; must
181: * not be <code>null</code>.
182: * @param expression
183: * This expression must evaluate to <code>true</code> before
184: * this context will really become active. The expression may be
185: * <code>null</code> if the context 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 IContextService#activateContext(String, Expression)}
196: * instead.
197: */
198: public IContextActivation activateContext(String contextId,
199: Expression expression, int sourcePriorities);
200:
201: /**
202: * Adds a listener to this context service. The listener will be notified
203: * when the set of defined contexts changes. This can be used to track the
204: * global appearance and disappearance of contexts.
205: *
206: * @param listener
207: * The listener to attach; must not be <code>null</code>.
208: * @since 3.2
209: */
210: public void addContextManagerListener(
211: 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(
347: IContextManagerListener listener);
348:
349: /**
350: * <p>
351: * Unregisters a shell that was previously registered. After this method
352: * completes, the shell will be treated as if it had never been registered
353: * at all. If you have registered a shell, you should ensure that this
354: * method is called when the shell is disposed. Otherwise, a potential
355: * memory leak will exist.
356: * </p>
357: * <p>
358: * If the shell was never registered, or if the shell is <code>null</code>,
359: * then this method returns <code>false</code> and does nothing.
360: *
361: * @param shell
362: * The shell to be unregistered; does nothing if this value is
363: * <code>null</code>.
364: *
365: * @return <code>true</code> if the shell had been registered;
366: * <code>false</code> otherwise.
367: */
368: public boolean unregisterShell(Shell shell);
369: }
|