IBindingService


1   /*******************************************************************************
2    * Copyright (c) 2005, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.keys;
12  
13  import java.io.IOException  ;
14  import java.util.Map  ;
15  
16  import org.eclipse.core.commands.ParameterizedCommand;
17  import org.eclipse.jface.bindings.Binding;
18  import org.eclipse.jface.bindings.Scheme;
19  import org.eclipse.jface.bindings.TriggerSequence;
20  import org.eclipse.ui.commands.ICommandService;
21  import org.eclipse.ui.services.IDisposable;
22  
23  /**
24   * <p>
25   * Provides services related to the binding architecture (e.g., keyboard
26   * shortcuts) within the workbench. This service can be used to access the
27   * currently active bindings, as well as the current state of the binding
28   * architecture.
29   * </p>
30   * <p>
31   * This interface should not be implemented or extended by clients.
32   * </p>
33   * 
34   * @since 3.1
35   */
36  public interface IBindingService extends IDisposable {
37  
38      /**
39       * The default default value for the active scheme id. This value can be
40       * overridden using the "plugin_customization.ini" file. The
41       * <code>BindingPersistence</code> code needs to know this value so it can
42       * try to decide if someone overrode the default.
43       */
44      public static final String   DEFAULT_DEFAULT_ACTIVE_SCHEME_ID = "org.eclipse.ui.defaultAcceleratorConfiguration"; //$NON-NLS-1$
45  
46      /**
47       * Gets the active bindings for a given parameterized command.
48       * 
49       * @param parameterizedCommand
50       *            The fully-parameterized command for which the active bindings
51       *            should be found; must not be <code>null</code>.
52       * @return The array of all active bindings for the given command. This
53       *         collection may be empty, but it is never <code>null</code>.
54       */
55      public TriggerSequence[] getActiveBindingsFor(
56              ParameterizedCommand parameterizedCommand);
57  
58      /**
59       * Gets the active bindings for a given command identifier. It is assumed
60       * that the command has no parameters.
61       * 
62       * @param commandId
63       *            The id of the command for which the active bindings should be
64       *            found; must not be <code>null</code>.
65       * @return The array of all active bindings for the given command. This
66       *         collection may be empty, but it is never <code>null</code>.
67       */
68      public TriggerSequence[] getActiveBindingsFor(String   commandId);
69  
70      /**
71       * Returns the currently active scheme.
72       * 
73       * @return The currently active scheme. This value may (in certain rare
74       *         circumstances) be <code>null</code>.
75       */
76      public Scheme getActiveScheme();
77  
78      /**
79       * Gets the best active binding for a command. The best binding is the one
80       * that would be most appropriate to show in a menu. Bindings which belong
81       * to a child scheme are given preference over those in a parent scheme.
82       * Bindings which belong to a particular locale or platform are given
83       * preference over those that do not. The rest of the calculaton is based
84       * most on various concepts of "length", as well as giving some modifier
85       * keys preference (e.g., <code>Alt</code> is less likely to appear than
86       * <code>Ctrl</code>).
87       * 
88       * @param commandId
89       *            The identifier of the command for which the best active
90       *            binding should be retrieved; must not be <code>null</code>.
91       * @return The trigger sequence for the best binding; may be
92       *         <code>null</code> if no bindings are active for the given
93       *         command.
94       * @since 3.2
95       */
96      public TriggerSequence getBestActiveBindingFor(String   commandId);
97  
98      /**
99       * Gets the formatted string representing the best active binding for a
100      * command. The best binding is the one that would be most appropriate to
101      * show in a menu. Bindings which belong to a child scheme are given
102      * preference over those in a parent scheme. The rest of the calculaton is
103      * based most on various concepts of "length", as well as giving some
104      * modifier keys preference (e.g., <code>Alt</code> is less likely to
105      * appear than <code>Ctrl</code>).
106      * 
107      * @param commandId
108      *            The identifier of the command for which the best active
109      *            binding should be retrieved; must not be <code>null</code>.
110      * @return The formatted string for the best binding; may be
111      *         <code>null</code> if no bindings are active for the given
112      *         command.
113      * @since 3.2
114      */
115     public String   getBestActiveBindingFormattedFor(String   commandId);
116 
117     /**
118      * Returns the current set of bindings.
119      * 
120      * @return The current array of bindings (<code>Binding</code>).
121      */
122     public Binding[] getBindings();
123 
124     /**
125      * Returns the current state of the key binding buffer. This will contain
126      * all of the keys currently awaiting processing. If the system is currently
127      * executing a command (as a result of a key press), then this will contain
128      * the trigger sequence used to execute the command. If the key binding
129      * architecture has seen part of multi-key binding, then this will contain
130      * the part that it has seen. Otherwise, this will return nothing.
131      * 
132      * @return The trigger sequence indicating the current state of the key
133      *         binding buffer; never <code>null</code>, but may be empty if
134      *         there is nothing in the buffer.
135      * @since 3.2
136      */
137     public TriggerSequence getBuffer();
138 
139     /**
140      * Returns the default scheme identifier for the currently running
141      * application.
142      * 
143      * @return The default scheme identifier (<code>String</code>); never
144      *         <code>null</code>, but may be empty or point to an undefined
145      *         scheme.
146      */
147     public String   getDefaultSchemeId();
148 
149     /**
150      * Returns the array of defined schemes in the workbench.
151      * 
152      * @return The array of schemes (<code>Scheme</code>) that are defined;
153      *         it may be <code>null</code>, and it may be empty.
154      */
155     public Scheme[] getDefinedSchemes();
156 
157     /**
158      * Returns the currently active locale.
159      * 
160      * @return The current locale.
161      */
162     public String   getLocale();
163 
164     /**
165      * Returns all of the possible bindings that start with the given trigger
166      * (but are not equal to the given trigger).
167      * 
168      * @param trigger
169      *            The prefix to look for; must not be <code>null</code>.
170      * @return A map of triggers (<code>TriggerSequence</code>) to bindings (<code>Binding</code>).
171      *         This map may be empty, but it is never <code>null</code>.
172      */
173     public Map   getPartialMatches(TriggerSequence trigger);
174 
175     /**
176      * Returns the command identifier for the active binding matching this
177      * trigger, if any.
178      * 
179      * @param trigger
180      *            The trigger to match; may be <code>null</code>.
181      * @return The binding that matches, if any; <code>null</code> otherwise.
182      */
183     public Binding getPerfectMatch(TriggerSequence trigger);
184 
185     /**
186      * Returns the currently active platform.
187      * 
188      * @return The current platform.
189      */
190     public String   getPlatform();
191 
192     /**
193      * Retrieves the scheme with the given identifier. If no such scheme exists,
194      * then an undefined scheme with the given id is created.
195      * 
196      * @param schemeId
197      *            The identifier to find; must not be <code>null</code>.
198      * @return A scheme with the given identifier, either defined or undefined.
199      */
200     public Scheme getScheme(String   schemeId);
201 
202     /**
203      * Tests whether the global key binding architecture is currently active.
204      * 
205      * @return <code>true</code> if the key bindings are active;
206      *         <code>false</code> otherwise.
207      */
208     public boolean isKeyFilterEnabled();
209 
210     /**
211      * Returns whether the given trigger sequence is a partial match for the
212      * given sequence.
213      * 
214      * @param trigger
215      *            The sequence which should be the prefix for some binding;
216      *            should not be <code>null</code>.
217      * @return <code>true</code> if the trigger can be found in the active
218      *         bindings; <code>false</code> otherwise.
219      */
220     public boolean isPartialMatch(TriggerSequence trigger);
221 
222     /**
223      * Returns whether the given trigger sequence is a perfect match for the
224      * given sequence.
225      * 
226      * @param trigger
227      *            The sequence which should match exactly; should not be
228      *            <code>null</code>.
229      * @return <code>true</code> if the trigger can be found in the active
230      *         bindings; <code>false</code> otherwise.
231      */
232     public boolean isPerfectMatch(TriggerSequence trigger);
233 
234     /**
235      * Opens the key assistant dialog positioned near the key binding entry in
236      * the status bar.
237      */
238     public void openKeyAssistDialog();
239 
240     /**
241      * <p>
242      * Reads the binding information from the registry and the preferences. This
243      * will overwrite any of the existing information in the binding service.
244      * This method is intended to be called during start-up. When this method
245      * completes, this binding service will reflect the current state of the
246      * registry and preference store.
247      * </p>
248      * 
249      * @param commandService
250      *            Ignored.
251      */
252     public void readRegistryAndPreferences(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 }
306
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags