| /******************************************************************************* |
| * Copyright (c) 2005, 2006 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.keys; |
| |
| import java.io.IOException; |
| import java.util.Map; |
| |
| import org.eclipse.core.commands.ParameterizedCommand; |
| import org.eclipse.jface.bindings.Binding; |
| import org.eclipse.jface.bindings.Scheme; |
| import org.eclipse.jface.bindings.TriggerSequence; |
| import org.eclipse.ui.commands.ICommandService; |
| import org.eclipse.ui.services.IDisposable; |
| |
| /** |
| * <p> |
| * Provides services related to the binding architecture (e.g., keyboard |
| * shortcuts) within the workbench. This service can be used to access the |
| * currently active bindings, as well as the current state of the binding |
| * architecture. |
| * </p> |
| * <p> |
| * This interface should not be implemented or extended by clients. |
| * </p> |
| * |
| * @since 3.1 |
| */ |
| public interface IBindingService extends IDisposable { |
| |
| /** |
| * The default default value for the active scheme id. This value can be |
| * overridden using the "plugin_customization.ini" file. The |
| * <code>BindingPersistence</code> code needs to know this value so it can |
| * try to decide if someone overrode the default. |
| */ |
| public static final String DEFAULT_DEFAULT_ACTIVE_SCHEME_ID = "org.eclipse.ui.defaultAcceleratorConfiguration"; //$NON-NLS-1$ |
| |
| /** |
| * Gets the active bindings for a given parameterized command. |
| * |
| * @param parameterizedCommand |
| * The fully-parameterized command for which the active bindings |
| * should be found; must not be <code>null</code>. |
| * @return The array of all active bindings for the given command. This |
| * collection may be empty, but it is never <code>null</code>. |
| */ |
| public TriggerSequence[] getActiveBindingsFor( |
| ParameterizedCommand parameterizedCommand); |
| |
| /** |
| * Gets the active bindings for a given command identifier. It is assumed |
| * that the command has no parameters. |
| * |
| * @param commandId |
| * The id of the command for which the active bindings should be |
| * found; must not be <code>null</code>. |
| * @return The array of all active bindings for the given command. This |
| * collection may be empty, but it is never <code>null</code>. |
| */ |
| public TriggerSequence[] getActiveBindingsFor(String commandId); |
| |
| /** |
| * Returns the currently active scheme. |
| * |
| * @return The currently active scheme. This value may (in certain rare |
| * circumstances) be <code>null</code>. |
| */ |
| public Scheme getActiveScheme(); |
| |
| /** |
| * Gets the best active binding for a command. The best binding is the one |
| * that would be most appropriate to show in a menu. Bindings which belong |
| * to a child scheme are given preference over those in a parent scheme. |
| * Bindings which belong to a particular locale or platform are given |
| * preference over those that do not. The rest of the calculaton is based |
| * most on various concepts of "length", as well as giving some modifier |
| * keys preference (e.g., <code>Alt</code> is less likely to appear than |
| * <code>Ctrl</code>). |
| * |
| * @param commandId |
| * The identifier of the command for which the best active |
| * binding should be retrieved; must not be <code>null</code>. |
| * @return The trigger sequence for the best binding; may be |
| * <code>null</code> if no bindings are active for the given |
| * command. |
| * @since 3.2 |
| */ |
| public TriggerSequence getBestActiveBindingFor(String commandId); |
| |
| /** |
| * Gets the formatted string representing the best active binding for a |
| * command. The best binding is the one that would be most appropriate to |
| * show in a menu. Bindings which belong to a child scheme are given |
| * preference over those in a parent scheme. The rest of the calculaton is |
| * based most on various concepts of "length", as well as giving some |
| * modifier keys preference (e.g., <code>Alt</code> is less likely to |
| * appear than <code>Ctrl</code>). |
| * |
| * @param commandId |
| * The identifier of the command for which the best active |
| * binding should be retrieved; must not be <code>null</code>. |
| * @return The formatted string for the best binding; may be |
| * <code>null</code> if no bindings are active for the given |
| * command. |
| * @since 3.2 |
| */ |
| public String getBestActiveBindingFormattedFor(String commandId); |
| |
| /** |
| * Returns the current set of bindings. |
| * |
| * @return The current array of bindings (<code>Binding</code>). |
| */ |
| public Binding[] getBindings(); |
| |
| /** |
| * Returns the current state of the key binding buffer. This will contain |
| * all of the keys currently awaiting processing. If the system is currently |
| * executing a command (as a result of a key press), then this will contain |
| * the trigger sequence used to execute the command. If the key binding |
| * architecture has seen part of multi-key binding, then this will contain |
| * the part that it has seen. Otherwise, this will return nothing. |
| * |
| * @return The trigger sequence indicating the current state of the key |
| * binding buffer; never <code>null</code>, but may be empty if |
| * there is nothing in the buffer. |
| * @since 3.2 |
| */ |
| public TriggerSequence getBuffer(); |
| |
| /** |
| * Returns the default scheme identifier for the currently running |
| * application. |
| * |
| * @return The default scheme identifier (<code>String</code>); never |
| * <code>null</code>, but may be empty or point to an undefined |
| * scheme. |
| */ |
| public String getDefaultSchemeId(); |
| |
| /** |
| * Returns the array of defined schemes in the workbench. |
| * |
| * @return The array of schemes (<code>Scheme</code>) that are defined; |
| * it may be <code>null</code>, and it may be empty. |
| */ |
| public Scheme[] getDefinedSchemes(); |
| |
| /** |
| * Returns the currently active locale. |
| * |
| * @return The current locale. |
| */ |
| public String getLocale(); |
| |
| /** |
| * Returns all of the possible bindings that start with the given trigger |
| * (but are not equal to the given trigger). |
| * |
| * @param trigger |
| * The prefix to look for; must not be <code>null</code>. |
| * @return A map of triggers (<code>TriggerSequence</code>) to bindings (<code>Binding</code>). |
| * This map may be empty, but it is never <code>null</code>. |
| */ |
| public Map getPartialMatches(TriggerSequence trigger); |
| |
| /** |
| * Returns the command identifier for the active binding matching this |
| * trigger, if any. |
| * |
| * @param trigger |
| * The trigger to match; may be <code>null</code>. |
| * @return The binding that matches, if any; <code>null</code> otherwise. |
| */ |
| public Binding getPerfectMatch(TriggerSequence trigger); |
| |
| /** |
| * Returns the currently active platform. |
| * |
| * @return The current platform. |
| */ |
| public String getPlatform(); |
| |
| /** |
| * Retrieves the scheme with the given identifier. If no such scheme exists, |
| * then an undefined scheme with the given id is created. |
| * |
| * @param schemeId |
| * The identifier to find; must not be <code>null</code>. |
| * @return A scheme with the given identifier, either defined or undefined. |
| */ |
| public Scheme getScheme(String schemeId); |
| |
| /** |
| * 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(); |
| |
| /** |
| * Returns whether the given trigger sequence is a partial match for the |
| * given sequence. |
| * |
| * @param trigger |
| * The sequence which should be the prefix for some binding; |
| * should not be <code>null</code>. |
| * @return <code>true</code> if the trigger can be found in the active |
| * bindings; <code>false</code> otherwise. |
| */ |
| public boolean isPartialMatch(TriggerSequence trigger); |
| |
| /** |
| * Returns whether the given trigger sequence is a perfect match for the |
| * given sequence. |
| * |
| * @param trigger |
| * The sequence which should match exactly; should not be |
| * <code>null</code>. |
| * @return <code>true</code> if the trigger can be found in the active |
| * bindings; <code>false</code> otherwise. |
| */ |
| public boolean isPerfectMatch(TriggerSequence trigger); |
| |
| /** |
| * Opens the key assistant dialog positioned near the key binding entry in |
| * the status bar. |
| */ |
| public void openKeyAssistDialog(); |
| |
| /** |
| * <p> |
| * Reads the binding information from the registry and the preferences. This |
| * will overwrite any of the existing information in the binding service. |
| * This method is intended to be called during start-up. When this method |
| * completes, this binding service will reflect the current state of the |
| * registry and preference store. |
| * </p> |
| * |
| * @param commandService |
| * Ignored. |
| */ |
| public void readRegistryAndPreferences(ICommandService commandService); |
| |
| /** |
| * <p> |
| * Writes the given active scheme and bindings to the preference store. Only |
| * the bindings that are of the <code>Binding.USER</code> type will be |
| * written; the others will be ignored. This should only be used by |
| * applications trying to persist user preferences. If you are trying to |
| * change the active scheme as an RCP application, then you should be using |
| * the <code>plugin_customization.ini</code> file. If you are trying to |
| * switch between groups of bindings dynamically, you should be using |
| * contexts. |
| * </p> |
| * <p> |
| * This method also updates the active scheme and bindings in the system to |
| * match those written to the preference store. |
| * </p> |
| * |
| * @param activeScheme |
| * The scheme which should be persisted; may be <code>null</code>. |
| * @param bindings |
| * The bindings which should be persisted; may be |
| * <code>null</code>. |
| * @throws IOException |
| * If something goes wrong while writing to the preference |
| * store. |
| * @see org.eclipse.ui.IWorkbenchPreferenceConstants |
| * @see org.eclipse.ui.contexts.IContextService |
| */ |
| public void savePreferences(Scheme activeScheme, Binding[] bindings) |
| throws IOException; |
| |
| /** |
| * <p> |
| * Enables or disables the global key binding architecture. The architecture |
| * should be enabled by default. |
| * </p> |
| * <p> |
| * 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). |
| * </p> |
| * <p> |
| * 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.) |
| * </p> |
| * |
| * @param enabled |
| * Whether the key filter should be enabled. |
| */ |
| public void setKeyFilterEnabled(boolean enabled); |
| } |