/*******************************************************************************
* 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
* @noimplement This interface is not intended to be implemented by clients.
*/
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);
}