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.keys;
011:
012: import java.io.IOException;
013: import java.util.Map;
014:
015: import org.eclipse.core.commands.ParameterizedCommand;
016: import org.eclipse.jface.bindings.Binding;
017: import org.eclipse.jface.bindings.Scheme;
018: import org.eclipse.jface.bindings.TriggerSequence;
019: import org.eclipse.ui.commands.ICommandService;
020: import org.eclipse.ui.services.IDisposable;
021:
022: /**
023: * <p>
024: * Provides services related to the binding architecture (e.g., keyboard
025: * shortcuts) within the workbench. This service can be used to access the
026: * currently active bindings, as well as the current state of the binding
027: * architecture.
028: * </p>
029: * <p>
030: * This interface should not be implemented or extended by clients.
031: * </p>
032: *
033: * @since 3.1
034: */
035: public interface IBindingService extends IDisposable {
036:
037: /**
038: * The default default value for the active scheme id. This value can be
039: * overridden using the "plugin_customization.ini" file. The
040: * <code>BindingPersistence</code> code needs to know this value so it can
041: * try to decide if someone overrode the default.
042: */
043: public static final String DEFAULT_DEFAULT_ACTIVE_SCHEME_ID = "org.eclipse.ui.defaultAcceleratorConfiguration"; //$NON-NLS-1$
044:
045: /**
046: * Gets the active bindings for a given parameterized command.
047: *
048: * @param parameterizedCommand
049: * The fully-parameterized command for which the active bindings
050: * should be found; must not be <code>null</code>.
051: * @return The array of all active bindings for the given command. This
052: * collection may be empty, but it is never <code>null</code>.
053: */
054: public TriggerSequence[] getActiveBindingsFor(
055: ParameterizedCommand parameterizedCommand);
056:
057: /**
058: * Gets the active bindings for a given command identifier. It is assumed
059: * that the command has no parameters.
060: *
061: * @param commandId
062: * The id of the command for which the active bindings should be
063: * found; must not be <code>null</code>.
064: * @return The array of all active bindings for the given command. This
065: * collection may be empty, but it is never <code>null</code>.
066: */
067: public TriggerSequence[] getActiveBindingsFor(String commandId);
068:
069: /**
070: * Returns the currently active scheme.
071: *
072: * @return The currently active scheme. This value may (in certain rare
073: * circumstances) be <code>null</code>.
074: */
075: public Scheme getActiveScheme();
076:
077: /**
078: * Gets the best active binding for a command. The best binding is the one
079: * that would be most appropriate to show in a menu. Bindings which belong
080: * to a child scheme are given preference over those in a parent scheme.
081: * Bindings which belong to a particular locale or platform are given
082: * preference over those that do not. The rest of the calculaton is based
083: * most on various concepts of "length", as well as giving some modifier
084: * keys preference (e.g., <code>Alt</code> is less likely to appear than
085: * <code>Ctrl</code>).
086: *
087: * @param commandId
088: * The identifier of the command for which the best active
089: * binding should be retrieved; must not be <code>null</code>.
090: * @return The trigger sequence for the best binding; may be
091: * <code>null</code> if no bindings are active for the given
092: * command.
093: * @since 3.2
094: */
095: public TriggerSequence getBestActiveBindingFor(String commandId);
096:
097: /**
098: * Gets the formatted string representing the best active binding for a
099: * command. The best binding is the one that would be most appropriate to
100: * show in a menu. Bindings which belong to a child scheme are given
101: * preference over those in a parent scheme. The rest of the calculaton is
102: * based most on various concepts of "length", as well as giving some
103: * modifier keys preference (e.g., <code>Alt</code> is less likely to
104: * appear than <code>Ctrl</code>).
105: *
106: * @param commandId
107: * The identifier of the command for which the best active
108: * binding should be retrieved; must not be <code>null</code>.
109: * @return The formatted string for the best binding; may be
110: * <code>null</code> if no bindings are active for the given
111: * command.
112: * @since 3.2
113: */
114: public String getBestActiveBindingFormattedFor(String commandId);
115:
116: /**
117: * Returns the current set of bindings.
118: *
119: * @return The current array of bindings (<code>Binding</code>).
120: */
121: public Binding[] getBindings();
122:
123: /**
124: * Returns the current state of the key binding buffer. This will contain
125: * all of the keys currently awaiting processing. If the system is currently
126: * executing a command (as a result of a key press), then this will contain
127: * the trigger sequence used to execute the command. If the key binding
128: * architecture has seen part of multi-key binding, then this will contain
129: * the part that it has seen. Otherwise, this will return nothing.
130: *
131: * @return The trigger sequence indicating the current state of the key
132: * binding buffer; never <code>null</code>, but may be empty if
133: * there is nothing in the buffer.
134: * @since 3.2
135: */
136: public TriggerSequence getBuffer();
137:
138: /**
139: * Returns the default scheme identifier for the currently running
140: * application.
141: *
142: * @return The default scheme identifier (<code>String</code>); never
143: * <code>null</code>, but may be empty or point to an undefined
144: * scheme.
145: */
146: public String getDefaultSchemeId();
147:
148: /**
149: * Returns the array of defined schemes in the workbench.
150: *
151: * @return The array of schemes (<code>Scheme</code>) that are defined;
152: * it may be <code>null</code>, and it may be empty.
153: */
154: public Scheme[] getDefinedSchemes();
155:
156: /**
157: * Returns the currently active locale.
158: *
159: * @return The current locale.
160: */
161: public String getLocale();
162:
163: /**
164: * Returns all of the possible bindings that start with the given trigger
165: * (but are not equal to the given trigger).
166: *
167: * @param trigger
168: * The prefix to look for; must not be <code>null</code>.
169: * @return A map of triggers (<code>TriggerSequence</code>) to bindings (<code>Binding</code>).
170: * This map may be empty, but it is never <code>null</code>.
171: */
172: public Map getPartialMatches(TriggerSequence trigger);
173:
174: /**
175: * Returns the command identifier for the active binding matching this
176: * trigger, if any.
177: *
178: * @param trigger
179: * The trigger to match; may be <code>null</code>.
180: * @return The binding that matches, if any; <code>null</code> otherwise.
181: */
182: public Binding getPerfectMatch(TriggerSequence trigger);
183:
184: /**
185: * Returns the currently active platform.
186: *
187: * @return The current platform.
188: */
189: public String getPlatform();
190:
191: /**
192: * Retrieves the scheme with the given identifier. If no such scheme exists,
193: * then an undefined scheme with the given id is created.
194: *
195: * @param schemeId
196: * The identifier to find; must not be <code>null</code>.
197: * @return A scheme with the given identifier, either defined or undefined.
198: */
199: public Scheme getScheme(String schemeId);
200:
201: /**
202: * Tests whether the global key binding architecture is currently active.
203: *
204: * @return <code>true</code> if the key bindings are active;
205: * <code>false</code> otherwise.
206: */
207: public boolean isKeyFilterEnabled();
208:
209: /**
210: * Returns whether the given trigger sequence is a partial match for the
211: * given sequence.
212: *
213: * @param trigger
214: * The sequence which should be the prefix for some binding;
215: * should not be <code>null</code>.
216: * @return <code>true</code> if the trigger can be found in the active
217: * bindings; <code>false</code> otherwise.
218: */
219: public boolean isPartialMatch(TriggerSequence trigger);
220:
221: /**
222: * Returns whether the given trigger sequence is a perfect match for the
223: * given sequence.
224: *
225: * @param trigger
226: * The sequence which should match exactly; should not be
227: * <code>null</code>.
228: * @return <code>true</code> if the trigger can be found in the active
229: * bindings; <code>false</code> otherwise.
230: */
231: public boolean isPerfectMatch(TriggerSequence trigger);
232:
233: /**
234: * Opens the key assistant dialog positioned near the key binding entry in
235: * the status bar.
236: */
237: public void openKeyAssistDialog();
238:
239: /**
240: * <p>
241: * Reads the binding information from the registry and the preferences. This
242: * will overwrite any of the existing information in the binding service.
243: * This method is intended to be called during start-up. When this method
244: * completes, this binding service will reflect the current state of the
245: * registry and preference store.
246: * </p>
247: *
248: * @param commandService
249: * Ignored.
250: */
251: public void readRegistryAndPreferences(
252: ICommandService commandService);
253:
254: /**
255: * <p>
256: * Writes the given active scheme and bindings to the preference store. Only
257: * the bindings that are of the <code>Binding.USER</code> type will be
258: * written; the others will be ignored. This should only be used by
259: * applications trying to persist user preferences. If you are trying to
260: * change the active scheme as an RCP application, then you should be using
261: * the <code>plugin_customization.ini</code> file. If you are trying to
262: * switch between groups of bindings dynamically, you should be using
263: * contexts.
264: * </p>
265: * <p>
266: * This method also updates the active scheme and bindings in the system to
267: * match those written to the preference store.
268: * </p>
269: *
270: * @param activeScheme
271: * The scheme which should be persisted; may be <code>null</code>.
272: * @param bindings
273: * The bindings which should be persisted; may be
274: * <code>null</code>.
275: * @throws IOException
276: * If something goes wrong while writing to the preference
277: * store.
278: * @see org.eclipse.ui.IWorkbenchPreferenceConstants
279: * @see org.eclipse.ui.contexts.IContextService
280: */
281: public void savePreferences(Scheme activeScheme, Binding[] bindings)
282: throws IOException;
283:
284: /**
285: * <p>
286: * Enables or disables the global key binding architecture. The architecture
287: * should be enabled by default.
288: * </p>
289: * <p>
290: * When enabled, keyboard shortcuts are active, and that key events can
291: * trigger commands. This also means that widgets may not see all key events
292: * (as they might be trapped as a keyboard shortcut).
293: * </p>
294: * <p>
295: * When disabled, no key events will trapped as keyboard shortcuts, and that
296: * no commands can be triggered by keyboard events. (Exception: it is
297: * possible that someone listening for key events on a widget could trigger
298: * a command.)
299: * </p>
300: *
301: * @param enabled
302: * Whether the key filter should be enabled.
303: */
304: public void setKeyFilterEnabled(boolean enabled);
305: }
|