IKeyConfiguration


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 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  
12  package org.eclipse.ui.commands;
13  
14  /**
15   * <p>
16   * An instance of <code>IKeyConfiguration</code> is a handle representing a
17   * key configuration as defined by the extension point
18   * <code>org.eclipse.ui.commands</code>. The identifier of the handle is
19   * identifier of the key configuration being represented.
20   * </p>
21   * <p>
22   * An instance of <code>IKeyConfiguration</code> can be obtained from an
23   * instance of <code>ICommandManager</code> for any identifier, whether or not
24   * a key configuration with that identifier defined in the plugin registry.
25   * </p>
26   * <p>
27   * The handle-based nature of this API allows it to work well with runtime
28   * plugin activation and deactivation. If a key configuration is defined, that
29   * means that its corresponding plug-in is active. If the plug-in is then
30   * deactivated, the configuration will still exist but it will be undefined.
31   * An attempt to use an undefined key configuration will result in a
32   * <code>NotDefinedException</code> being thrown.
33   * </p>
34   * <p>
35   * This interface is not intended to be extended or implemented by clients.
36   * </p>
37   * 
38   * @since 3.0
39   * @see IKeyConfigurationListener
40   * @see ICommandManager
41   * @see org.eclipse.jface.bindings.Scheme
42   * @deprecated Please use the bindings support in the "org.eclipse.jface"
43   * plug-in instead.
44   */
45  public interface IKeyConfiguration extends Comparable   {
46  
47      /**
48       * Registers an instance of <code>IKeyConfigurationListener</code> to
49       * listen for changes to attributes of this instance.
50       * 
51       * @param keyConfigurationListener
52       *            the instance of <code>IKeyConfigurationListener</code> to
53       *            register. Must not be <code>null</code>. If an attempt is
54       *            made to register an instance of <code>IKeyConfigurationListener</code>
55       *            which is already registered with this instance, no operation
56       *            is performed.
57       */
58      void addKeyConfigurationListener(
59              IKeyConfigurationListener keyConfigurationListener);
60  
61      /**
62       * <p>
63       * Returns the description of the key configuration represented by this
64       * handle, suitable for display to the user.
65       * </p>
66       * <p>
67       * Notification is sent to all registered listeners if this attribute
68       * changes.
69       * </p>
70       * 
71       * @return the description of the key configuration represented by this
72       *         handle. Guaranteed not to be <code>null</code>.
73       * @throws NotDefinedException
74       *             if the key configuration represented by this handle is not
75       *             defined.
76       */
77      String   getDescription() throws NotDefinedException;
78  
79      /**
80       * Returns the identifier of this handle.
81       * 
82       * @return the identifier of this handle. Guaranteed not to be
83       *         <code>null</code>.
84       */
85      String   getId();
86  
87      /**
88       * <p>
89       * Returns the name of the key configuration represented by this handle,
90       * suitable for display to the user.
91       * </p>
92       * <p>
93       * Notification is sent to all registered listeners if this attribute
94       * changes.
95       * </p>
96       * 
97       * @return the name of the key configuration represented by this handle.
98       *         Guaranteed not to be <code>null</code>.
99       * @throws NotDefinedException
100      *             if the key configuration represented by this handle is not
101      *             defined.
102      */
103     String   getName() throws NotDefinedException;
104 
105     /**
106      * <p>
107      * Returns the identifier of the parent of the key configuration
108      * represented by this handle.
109      * </p>
110      * <p>
111      * Notification is sent to all registered listeners if this attribute
112      * changes.
113      * </p>
114      * 
115      * @return the identifier of the parent of the key configuration
116      *         represented by this handle. May be <code>null</code>.
117      * @throws NotDefinedException
118      *             if the key configuration represented by this handle is not
119      *             defined.
120      */
121     String   getParentId() throws NotDefinedException;
122 
123     /**
124      * <p>
125      * Returns whether or not this command is active. Instances of
126      * <code>ICommand</code> are activated and deactivated by the instance of
127      * <code>ICommandManager</code> from whence they were brokered.
128      * </p>
129      * <p>
130      * Notification is sent to all registered listeners if this attribute
131      * changes.
132      * </p>
133      * 
134      * @return <code>true</code>, iff this command is active.
135      */
136     boolean isActive();
137 
138     /**
139      * <p>
140      * Returns whether or not the key configuration represented by this handle
141      * is defined.
142      * </p>
143      * <p>
144      * Notification is sent to all registered listeners if this attribute
145      * changes.
146      * </p>
147      * 
148      * @return <code>true</code>, iff the key configuration represented by
149      *         this handle is defined.
150      */
151     boolean isDefined();
152 
153     /**
154      * Unregisters an instance of <code>IKeyConfigurationListener</code>
155      * listening for changes to attributes of this instance.
156      * 
157      * @param keyConfigurationListener
158      *            the instance of <code>IKeyConfigurationListener</code> to
159      *            unregister. Must not be <code>null</code>. If an attempt is
160      *            made to unregister an instance of
161      *            <code>IKeyConfigurationListener</code> which is not already
162      *            registered with this instance, no operation is performed.
163      */
164     void removeKeyConfigurationListener(
165             IKeyConfigurationListener keyConfigurationListener);
166 }
167
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags