| /******************************************************************************* |
| * Copyright (c) 2003, 2005 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.ui.contexts; |
| |
| import java.util.Collection; |
| |
| import org.eclipse.swt.widgets.Shell; |
| |
| /** |
| * <p> |
| * An instance of this interface provides support for managing contexts at the |
| * <code>IWorkbench</code> level. This provides the functionality necessary to |
| * enabled contexts, disable or enabled the key binding service, as well as |
| * register shells as particular types of windows. |
| * <p> |
| * This interface is not intended to be extended or implemented by clients. |
| * </p> |
| * |
| * @since 3.0 |
| * @deprecated Please use <code>IBindingService</code> and |
| * <code>IContextService</code> instead. |
| * @see org.eclipse.ui.contexts.IContextService |
| * @see org.eclipse.ui.keys.IBindingService |
| */ |
| public interface IWorkbenchContextSupport { |
| |
| /** |
| * The identifier for the context that is active when a shell registered as |
| * a dialog. |
| */ |
| public static final String CONTEXT_ID_DIALOG = IContextService.CONTEXT_ID_DIALOG; |
| |
| /** |
| * The identifier for the context that is active when a shell is registered |
| * as either a window or a dialog. |
| */ |
| public static final String CONTEXT_ID_DIALOG_AND_WINDOW = IContextService.CONTEXT_ID_DIALOG_AND_WINDOW; |
| |
| /** |
| * The identifier for the context that is active when a shell is registered |
| * as a window. |
| */ |
| public static final String CONTEXT_ID_WINDOW = IContextService.CONTEXT_ID_WINDOW; |
| |
| /** |
| * The type used for registration indicating that the shell should be |
| * treated as a dialog. When the given shell is active, the "In Dialogs" |
| * context should also be active. |
| */ |
| public static final int TYPE_DIALOG = IContextService.TYPE_DIALOG; |
| |
| /** |
| * The type used for registration indicating that the shell should not |
| * receive any key bindings be default. When the given shell is active, we |
| * should not provide any <code>EnabledSubmission</code> instances for the |
| * "In Dialogs" or "In Windows" contexts. |
| * |
| */ |
| public static final int TYPE_NONE = IContextService.TYPE_NONE; |
| |
| /** |
| * The type used for registration indicating that the shell should be |
| * treated as a window. When the given shell is active, the "In Windows" |
| * context should also be active. |
| */ |
| public static final int TYPE_WINDOW = IContextService.TYPE_WINDOW; |
| |
| /** |
| * <p> |
| * Add a single enabled submission for consideration. An enabled submission |
| * is a description of certain criteria under which a particular context |
| * should become active. All added submissions will be check when the |
| * conditions in the workbench change, and zero or more contexts will be |
| * selected as active. |
| * </p> |
| * <p> |
| * Just because an enabled submission is added, it does not mean that the |
| * corresponding context will become active. The workbench will consider the |
| * request, but other factors (such as conflicts) may prevent the context |
| * from becoming active. |
| * </p> |
| * |
| * @param enabledSubmission |
| * The enabled submission to be considered; must not be |
| * <code>null</code>. |
| */ |
| void addEnabledSubmission(EnabledSubmission enabledSubmission); |
| |
| /** |
| * <p> |
| * Adds zero or more enabled submissions for consideration. An enabled |
| * submission is a description of certain criteria under which a particular |
| * context should become active. All added submissions will be check when |
| * the conditions in the workbench change, and zero or more contexts will be |
| * selected as active. |
| * </p> |
| * <p> |
| * Just because an enabled submission is added, it does not mean that the |
| * corresponding context will become active. The workbench will consider the |
| * request, but other factors (such as conflicts) may prevent the context |
| * from becoming active. |
| * </p> |
| * |
| * @param enabledSubmissions |
| * The enabled submissions to be considered; must not be |
| * <code>null</code>, but may be empty. Every element in the |
| * collection must be an instance of |
| * <code>EnabledSubmission</code>. |
| */ |
| void addEnabledSubmissions(Collection enabledSubmissions); |
| |
| /** |
| * Returns the context manager for the workbench. |
| * |
| * @return the context manager for the workbench. Guaranteed not to be |
| * <code>null</code>. |
| */ |
| IContextManager getContextManager(); |
| |
| /** |
| * Returns the shell type for the given shell. |
| * |
| * @param shell |
| * The shell for which the type should be determined. If this |
| * value is <code>null</code>, then |
| * <code>IWorkbenchContextSupport.TYPE_NONE</code> is returned. |
| * @return <code>IWorkbenchContextSupport.TYPE_WINDOW</code>, |
| * <code>IWorkbenchContextSupport.TYPE_DIALOG</code>, or |
| * <code>IWorkbenchContextSupport.TYPE_NONE</code>. |
| * @since 3.1 |
| */ |
| public int getShellType(final Shell shell); |
| |
| /** |
| * Tests whether the global key binding architecture is currently active. |
| * |
| * @return <code>true</code> if the key bindings are active; |
| * <code>false</code> otherwise. |
| */ |
| public boolean isKeyFilterEnabled(); |
| |
| /** |
| * Opens the key assistant dialog positioned near the key binding entry in |
| * the status bar. |
| * |
| * @since 3.1 |
| */ |
| public void openKeyAssistDialog(); |
| |
| /** |
| * <p> |
| * Registers a shell to automatically promote or demote some basic types of |
| * contexts. The "In Dialogs" and "In Windows" contexts are provided by the |
| * system. This a convenience method to ensure that these contexts are |
| * promoted when the given is shell is active. |
| * </p> |
| * <p> |
| * If a shell is registered as a window, then the "In Windows" context is |
| * enabled when that shell is active. If a shell is registered as a dialog -- |
| * or is not registered, but has a parent shell -- then the "In Dialogs" |
| * context is enabled when that shell is active. If the shell is registered |
| * as none -- or is not registered, but has no parent shell -- then the |
| * neither of the contexts will be enabled (by us -- someone else can always |
| * enabled them). |
| * </p> |
| * <p> |
| * If the provided shell has already been registered, then this method will |
| * change the registration. |
| * </p> |
| * |
| * @param shell |
| * The shell to register for key bindings; must not be |
| * <code>null</code>. |
| * @param type |
| * The type of shell being registered. This value must be one of |
| * the constants given in this interface. |
| * |
| * @return <code>true</code> if the shell had already been registered |
| * (i.e., the registration has changed); <code>false</code> |
| * otherwise. |
| */ |
| public boolean registerShell(final Shell shell, final int type); |
| |
| /** |
| * <p> |
| * Removes a single enabled submission from consideration. Only the same |
| * enabled submission will be removed; equivalent submissions will not be |
| * removed. Removing an enabled submission does not necessarily mean that |
| * the corresponding context will become inactive. It is possible that other |
| * parts of the application have requested that the context be enabled. |
| * </p> |
| * <p> |
| * There is no way to disable a context. It is only possible to not enable |
| * it. |
| * </p> |
| * |
| * @param enabledSubmission |
| * The enabled submission to be removed; must not be |
| * <code>null</code>. |
| */ |
| void removeEnabledSubmission(EnabledSubmission enabledSubmission); |
| |
| /** |
| * <p> |
| * Removes a collection of enabled submissions from consideration. Only the |
| * same enabled submissions will be removed; equivalent submissions will not |
| * be removed. Removing an enabled submission does not necessarily mean that |
| * the corresponding context will become inactive. It is possible that other |
| * parts of the application have requested that the context be enabled. |
| * </p> |
| * <p> |
| * There is no way to disable a context. It is only possible to not enable |
| * it. |
| * </p> |
| * |
| * @param enabledSubmissions |
| * The enabled submissions to be removed; must not be |
| * <code>null</code>, but may be empty. The collection must |
| * only contain instances of <code>EnabledSubmission</code>. |
| */ |
| void removeEnabledSubmissions(Collection enabledSubmissions); |
| |
| /** |
| * Enables or disables the global key binding architecture. The architecture |
| * should be enabled by default. |
| * |
| * When enabled, keyboard shortcuts are active, and that key events can |
| * trigger commands. This also means that widgets may not see all key events |
| * (as they might be trapped as a keyboard shortcut). |
| * |
| * When disabled, no key events will trapped as keyboard shortcuts, and that |
| * no commands can be triggered by keyboard events. (Exception: it is |
| * possible that someone listening for key events on a widget could trigger |
| * a command.) |
| * |
| * @param enabled |
| * Whether the key filter should be enabled. |
| */ |
| public void setKeyFilterEnabled(final boolean enabled); |
| |
| /** |
| * <p> |
| * Unregisters a shell that was previously registered. After this method |
| * completes, the shell will be treated as if it had never been registered |
| * at all. If you have registered a shell, you should ensure that this |
| * method is called when the shell is disposed. Otherwise, a potential |
| * memory leak will exist. |
| * </p> |
| * <p> |
| * If the shell was never registered, or if the shell is <code>null</code>, |
| * then this method returns <code>false</code> and does nothing. |
| * |
| * @param shell |
| * The shell to be unregistered; does nothing if this value is |
| * <code>null</code>. |
| * |
| * @return <code>true</code> if the shell had been registered; |
| * <code>false</code> otherwise. |
| */ |
| public boolean unregisterShell(final Shell shell); |
| } |