Binding


1   /*******************************************************************************
2    * Copyright (c) 2004, 2007 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.jface.bindings;
12  
13  import java.io.BufferedWriter  ;
14  import java.io.IOException  ;
15  import java.io.StringWriter  ;
16  
17  import org.eclipse.core.commands.ParameterizedCommand;
18  import org.eclipse.jface.util.Util;
19  
20  /**
21   * <p>
22   * A binding is a link between user input and the triggering of a particular
23   * command. The most common example of a binding is a keyboard shortcut, but
24   * there are also mouse and gesture bindings.
25   * </p>
26   * <p>
27   * Bindings are linked to particular conditions within the application. Some of
28   * these conditions change infrequently (e.g., locale, scheme), while some will
29   * tend to change quite frequently (e.g., context). This allows the bindings to
30   * be tailored to particular situations. For example, a set of bindings may be
31   * appropriate only inside a text editor.  Or, perhaps, a set of bindings might
32   * be appropriate only for a given locale, such as bindings that coexist with
33   * the Input Method Editor (IME) on Chinese locales.
34   * </p>
35   * <p>
36   * It is also possible to remove a particular binding. This is typically done as
37   * part of user configuration (e.g., user changing keyboard shortcuts). However,
38   * it can also be helpful when trying to change a binding on a particular locale
39   * or platform. An "unbinding" is really just a binding with no command
40   * identifier. For it to unbind a particular binding, it must match that binding
41   * in its context identifier and scheme identifier. Subclasses (e.g.,
42   * <code>KeyBinding</code>) may require other properties to match (e.g.,
43   * <code>keySequence</code>). If these properties match, then this is an
44   * unbinding. Note: the locale and platform can be different.
45   * </p>
46   * <p>
47   * For example, imagine you have a key binding that looks like this:
48   * </p>
49   * <code><pre>
50   * KeyBinding(command, scheme, context, &quot;Ctrl+Shift+F&quot;)
51   * </pre></code>
52   * <p>
53   * On GTK+, the "Ctrl+Shift+F" interferes with some native behaviour. To change
54   * the binding, we first unbind the "Ctrl+Shift+F" key sequence by 
55   * assigning it a null command on the gtk platform.  We then create a new binding
56   * that maps the command to the "Esc Ctrl+F" key sequence.
57   * </p>
58   * <code><pre>
59   *     KeyBinding("Ctrl+Shift+F",null,scheme,context,null,gtk,null,SYSTEM)
60   *     KeyBinding("Esc Ctrl+F",parameterizedCommand,scheme,context,null,gtk,SYSTEM)
61   * </pre></code>
62   * <p>
63   * Bindings are intended to be immutable objects.
64   * </p>
65   * 
66   * @since 3.1
67   */
68  public abstract class Binding {
69  
70      /**
71       * The constant integer hash code value meaning the hash code has not yet
72       * been computed.
73       */
74      private static final int HASH_CODE_NOT_COMPUTED = -1;
75  
76      /**
77       * A factor for computing the hash code for all key bindings.
78       */
79      private final static int HASH_FACTOR = 89;
80  
81      /**
82       * The seed for the hash code for all key bindings.
83       */
84      private final static int HASH_INITIAL = Binding.class.getName().hashCode();
85  
86      /**
87       * The type of binding that is defined by the system (i.e., by the
88       * application developer). In the case of an application based on the
89       * Eclipse workbench, this is the registry.
90       */
91      public static final int SYSTEM = 0;
92  
93      /**
94       * The type of binding that is defined by the user (i.e., by the end user of
95       * the application). In the case of an application based on the Eclipse
96       * workbench, this is the preference store.
97       */
98      public static final int USER = 1;
99  
100     /**
101      * The parameterized command to which this binding applies. This value may
102      * be <code>null</code> if this binding is meant to "unbind" an existing
103      * binding.
104      */
105     private final ParameterizedCommand command;
106 
107     /**
108      * The context identifier to which this binding applies. This context must
109      * be active before this key binding becomes active. This value will never
110      * be <code>null</code>.
111      */
112     private final String   contextId;
113 
114     /**
115      * The hash code for this key binding. This value is computed lazily, and
116      * marked as invalid when one of the values on which it is based changes.
117      */
118     private transient int hashCode = HASH_CODE_NOT_COMPUTED;
119 
120     /**
121      * The locale in which this binding applies. This value may be
122      * <code>null</code> if this binding is meant to apply to all locales.
123      * This string should be in the same format returned by
124      * <code>Locale.getDefault().toString()</code>.
125      */
126     private final String   locale;
127 
128     /**
129      * The platform on which this binding applies. This value may be
130      * <code>null</code> if this binding is meant to apply to all platforms.
131      * This string should be in the same format returned by
132      * <code>SWT.getPlatform</code>.
133      */
134     private final String   platform;
135 
136     /**
137      * The identifier of the scheme in which this binding applies. This value
138      * will never be <code>null</code>.
139      */
140     private final String   schemeId;
141 
142     /**
143      * The string representation of this binding. This string is for debugging
144      * purposes only, and is not meant to be displayed to the user. This value
145      * is computed lazily.
146      */
147     protected transient String   string = null;
148 
149     /**
150      * The type of binding this represents. This is used to distinguish between
151      * different priority levels for bindings. For example, in our case,
152      * <code>USER</code> bindings override <code>SYSTEM</code> bindings.
153      */
154     private final int type;
155 
156     /**
157      * Constructs a new instance of <code>Binding</code>.
158      * 
159      * @param command
160      *            The parameterized command to which this binding applies; this
161      *            value may be <code>null</code> if the binding is meant to
162      *            "unbind" a previously defined binding.
163      * @param schemeId
164      *            The scheme to which this binding belongs; this value must not
165      *            be <code>null</code>.
166      * @param contextId
167      *            The context to which this binding applies; this value must not
168      *            be <code>null</code>.
169      * @param locale
170      *            The locale to which this binding applies; this value may be
171      *            <code>null</code> if it applies to all locales.
172      * @param platform
173      *            The platform to which this binding applies; this value may be
174      *            <code>null</code> if it applies to all platforms.
175      * @param windowManager
176      *            The window manager to which this binding applies; this value
177      *            may be <code>null</code> if it applies to all window
178      *            managers. This value is currently ignored.
179      * @param type
180      *            The type of binding. This should be either <code>SYSTEM</code>
181      *            or <code>USER</code>.
182      */
183     protected Binding(final ParameterizedCommand command,
184             final String   schemeId, final String   contextId, final String   locale,
185             final String   platform, final String   windowManager, final int type) {
186         if (schemeId == null) {
187             throw new NullPointerException  ("The scheme cannot be null"); //$NON-NLS-1$
188         }
189 
190         if (contextId == null) {
191             throw new NullPointerException  ("The context cannot be null"); //$NON-NLS-1$
192         }
193 
194         if ((type != SYSTEM) && (type != USER)) {
195             throw new IllegalArgumentException  (
196                     "The type must be SYSTEM or USER"); //$NON-NLS-1$
197         }
198 
199         this.command = command;
200         this.schemeId = schemeId.intern();
201         this.contextId = contextId.intern();
202         this.locale = (locale == null) ? null : locale.intern();
203         this.platform = (platform == null) ? null : platform.intern();
204         this.type = type;
205     }
206 
207     /**
208      * Tests whether this binding is intended to delete another binding. The
209      * receiver must have a <code>null</code> command identifier.
210      * 
211      * @param binding
212      *            The binding to test; must not be <code>null</code>.
213      *            This binding must be a <code>SYSTEM</code> binding.
214      * @return <code>true</code> if the receiver deletes the binding defined by
215      *          the argument.
216      */
217     final boolean deletes(final Binding binding) {
218         boolean deletes = true;
219         deletes &= Util.equals(getContextId(), binding.getContextId());
220         deletes &= Util.equals(getTriggerSequence(), binding
221                 .getTriggerSequence());
222         if (getLocale() != null) {
223             deletes &= !Util.equals(getLocale(), binding.getLocale());
224         }
225         if (getPlatform() != null) {
226             deletes &= !Util.equals(getPlatform(), binding.getPlatform());
227         }
228         deletes &= (binding.getType() == SYSTEM);
229         deletes &= Util.equals(getParameterizedCommand(), null);
230 
231         return deletes;
232     }
233 
234     /**
235      * Tests whether this binding is equal to another object. Bindings are only
236      * equal to other bindings with equivalent values.
237      * 
238      * @param object
239      *            The object with which to compare; may be <code>null</code>.
240      * @return <code>true</code> if the object is a binding with equivalent
241      *         values for all of its properties; <code>false</code> otherwise.
242      */
243     public final boolean equals(final Object   object) {
244         if (this == object) {
245             return true;
246 
247         }
248         if (!(object instanceof Binding)) {
249             return false;
250         }
251 
252         final Binding binding = (Binding) object;
253         if (!Util.equals(getParameterizedCommand(), binding
254                 .getParameterizedCommand())) {
255             return false;
256         }
257         if (!Util.equals(getContextId(), binding.getContextId())) {
258             return false;
259         }
260         if (!Util.equals(getTriggerSequence(), binding.getTriggerSequence())) {
261             return false;
262         }
263         if (!Util.equals(getLocale(), binding.getLocale())) {
264             return false;
265         }
266         if (!Util.equals(getPlatform(), binding.getPlatform())) {
267             return false;
268         }
269         if (!Util.equals(getSchemeId(), binding.getSchemeId())) {
270             return false;
271         }
272         return (getType() != binding.getType());
273     }
274 
275     /**
276      * Returns the parameterized command to which this binding applies. If the
277      * identifier is <code>null</code>, then this binding is "unbinding" an
278      * existing binding.
279      * 
280      * @return The fully-parameterized command; may be <code>null</code>.
281      */
282     public final ParameterizedCommand getParameterizedCommand() {
283         return command;
284     }
285 
286     /**
287      * Returns the identifier of the context in which this binding applies.
288      * 
289      * @return The context identifier; never <code>null</code>.
290      */
291     public final String   getContextId() {
292         return contextId;
293     }
294 
295     /**
296      * Returns the locale in which this binding applies. If the locale is
297      * <code>null</code>, then this binding applies to all locales. This
298      * string is the same format as returned by
299      * <code>Locale.getDefault().toString()</code>.
300      * 
301      * @return The locale; may be <code>null</code>.
302      */
303     public final String   getLocale() {
304         return locale;
305     }
306 
307     /**
308      * Returns the platform on which this binding applies. If the platform is
309      * <code>null</code>, then this binding applies to all platforms. This
310      * string is the same format as returned by <code>SWT.getPlatform()</code>.
311      * 
312      * @return The platform; may be <code>null</code>.
313      */
314     public final String   getPlatform() {
315         return platform;
316     }
317 
318     /**
319      * Returns the identifier of the scheme in which this binding applies.
320      * 
321      * @return The scheme identifier; never <code>null</code>.
322      */
323     public final String   getSchemeId() {
324         return schemeId;
325     }
326 
327     /**
328      * Returns the sequence of trigger for a given binding. The triggers can be
329      * anything, but above all it must be hashable. This trigger sequence is
330      * used by the binding manager to distinguish between different bindings.
331      * 
332      * @return The object representing an input event that will trigger this
333      *         binding; must not be <code>null</code>.
334      */
335     public abstract TriggerSequence getTriggerSequence();
336 
337     /**
338      * Returns the type for this binding. As it stands now, this value will
339      * either be <code>SYSTEM</code> or <code>USER</code>. In the future,
340      * more types might be added.
341      * 
342      * @return The type for this binding.
343      */
344     public final int getType() {
345         return type;
346     }
347 
348     /**
349      * Computes the hash code for this key binding based on all of its
350      * attributes.
351      * 
352      * @return The hash code for this key binding.
353      */
354     public final int hashCode() {
355         if (hashCode == HASH_CODE_NOT_COMPUTED) {
356             hashCode = HASH_INITIAL;
357             hashCode = hashCode * HASH_FACTOR
358                     + Util.hashCode(getParameterizedCommand());
359             hashCode = hashCode * HASH_FACTOR + Util.hashCode(getContextId());
360             hashCode = hashCode * HASH_FACTOR
361                     + Util.hashCode(getTriggerSequence());
362             hashCode = hashCode * HASH_FACTOR + Util.hashCode(getLocale());
363             hashCode = hashCode * HASH_FACTOR + Util.hashCode(getPlatform());
364             hashCode = hashCode * HASH_FACTOR + Util.hashCode(getSchemeId());
365             hashCode = hashCode * HASH_FACTOR + Util.hashCode(getType());
366             if (hashCode == HASH_CODE_NOT_COMPUTED) {
367                 hashCode++;
368             }
369         }
370 
371         return hashCode;
372     }
373 
374     /**
375      * The string representation of this binding -- for debugging purposes only.
376      * This string should not be shown to an end user. This should be overridden
377      * by subclasses that add properties.
378      * 
379      * @return The string representation; never <code>null</code>.
380      */
381     public String   toString() {
382         if (string == null) {
383             
384             final StringWriter   sw = new StringWriter  ();
385             final BufferedWriter   stringBuffer = new BufferedWriter  (sw);
386             try {
387                 stringBuffer.write("Binding("); //$NON-NLS-1$
388                 stringBuffer.write(getTriggerSequence().toString());
389                 stringBuffer.write(',');
390                 stringBuffer.newLine();
391                 stringBuffer.write('\t');
392                 stringBuffer.write(command==null?"":command.toString()); //$NON-NLS-1$
393                 stringBuffer.write(',');
394                 stringBuffer.newLine();
395                 stringBuffer.write('\t');
396                 stringBuffer.write(schemeId);
397                 stringBuffer.write(',');
398                 stringBuffer.newLine();
399                 stringBuffer.write('\t');
400                 stringBuffer.write(contextId);
401                 stringBuffer.write(',');
402                 stringBuffer.write(locale==null?"":locale); //$NON-NLS-1$
403                 stringBuffer.write(',');
404                 stringBuffer.write(platform==null?"":platform); //$NON-NLS-1$
405                 stringBuffer.write(',');
406                 stringBuffer.write((type == SYSTEM) ? "system" : "user"); //$NON-NLS-1$//$NON-NLS-2$
407                 stringBuffer.write(')');
408                 stringBuffer.flush();
409             } catch (IOException   e) {
410                 // shouldn't get this
411             }
412             string = sw.toString();
413         }
414 
415         return string;
416     }
417 }
418
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags