001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 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.commands;
011:
012: /**
013: * <p>
014: * An instance of <code>IKeyConfiguration</code> is a handle representing a
015: * key configuration as defined by the extension point
016: * <code>org.eclipse.ui.commands</code>. The identifier of the handle is
017: * identifier of the key configuration being represented.
018: * </p>
019: * <p>
020: * An instance of <code>IKeyConfiguration</code> can be obtained from an
021: * instance of <code>ICommandManager</code> for any identifier, whether or not
022: * a key configuration with that identifier defined in the plugin registry.
023: * </p>
024: * <p>
025: * The handle-based nature of this API allows it to work well with runtime
026: * plugin activation and deactivation. If a key configuration is defined, that
027: * means that its corresponding plug-in is active. If the plug-in is then
028: * deactivated, the configuration will still exist but it will be undefined.
029: * An attempt to use an undefined key configuration will result in a
030: * <code>NotDefinedException</code> being thrown.
031: * </p>
032: * <p>
033: * This interface is not intended to be extended or implemented by clients.
034: * </p>
035: *
036: * @since 3.0
037: * @see IKeyConfigurationListener
038: * @see ICommandManager
039: * @see org.eclipse.jface.bindings.Scheme
040: * @deprecated Please use the bindings support in the "org.eclipse.jface"
041: * plug-in instead.
042: */
043: public interface IKeyConfiguration extends Comparable {
044:
045: /**
046: * Registers an instance of <code>IKeyConfigurationListener</code> to
047: * listen for changes to attributes of this instance.
048: *
049: * @param keyConfigurationListener
050: * the instance of <code>IKeyConfigurationListener</code> to
051: * register. Must not be <code>null</code>. If an attempt is
052: * made to register an instance of <code>IKeyConfigurationListener</code>
053: * which is already registered with this instance, no operation
054: * is performed.
055: */
056: void addKeyConfigurationListener(
057: IKeyConfigurationListener keyConfigurationListener);
058:
059: /**
060: * <p>
061: * Returns the description of the key configuration represented by this
062: * handle, suitable for display to the user.
063: * </p>
064: * <p>
065: * Notification is sent to all registered listeners if this attribute
066: * changes.
067: * </p>
068: *
069: * @return the description of the key configuration represented by this
070: * handle. Guaranteed not to be <code>null</code>.
071: * @throws NotDefinedException
072: * if the key configuration represented by this handle is not
073: * defined.
074: */
075: String getDescription() throws NotDefinedException;
076:
077: /**
078: * Returns the identifier of this handle.
079: *
080: * @return the identifier of this handle. Guaranteed not to be
081: * <code>null</code>.
082: */
083: String getId();
084:
085: /**
086: * <p>
087: * Returns the name of the key configuration represented by this handle,
088: * suitable for display to the user.
089: * </p>
090: * <p>
091: * Notification is sent to all registered listeners if this attribute
092: * changes.
093: * </p>
094: *
095: * @return the name of the key configuration represented by this handle.
096: * Guaranteed not to be <code>null</code>.
097: * @throws NotDefinedException
098: * if the key configuration represented by this handle is not
099: * defined.
100: */
101: String getName() throws NotDefinedException;
102:
103: /**
104: * <p>
105: * Returns the identifier of the parent of the key configuration
106: * represented by this handle.
107: * </p>
108: * <p>
109: * Notification is sent to all registered listeners if this attribute
110: * changes.
111: * </p>
112: *
113: * @return the identifier of the parent of the key configuration
114: * represented by this handle. May be <code>null</code>.
115: * @throws NotDefinedException
116: * if the key configuration represented by this handle is not
117: * defined.
118: */
119: String getParentId() throws NotDefinedException;
120:
121: /**
122: * <p>
123: * Returns whether or not this command is active. Instances of
124: * <code>ICommand</code> are activated and deactivated by the instance of
125: * <code>ICommandManager</code> from whence they were brokered.
126: * </p>
127: * <p>
128: * Notification is sent to all registered listeners if this attribute
129: * changes.
130: * </p>
131: *
132: * @return <code>true</code>, iff this command is active.
133: */
134: boolean isActive();
135:
136: /**
137: * <p>
138: * Returns whether or not the key configuration represented by this handle
139: * is defined.
140: * </p>
141: * <p>
142: * Notification is sent to all registered listeners if this attribute
143: * changes.
144: * </p>
145: *
146: * @return <code>true</code>, iff the key configuration represented by
147: * this handle is defined.
148: */
149: boolean isDefined();
150:
151: /**
152: * Unregisters an instance of <code>IKeyConfigurationListener</code>
153: * listening for changes to attributes of this instance.
154: *
155: * @param keyConfigurationListener
156: * the instance of <code>IKeyConfigurationListener</code> to
157: * unregister. Must not be <code>null</code>. If an attempt is
158: * made to unregister an instance of
159: * <code>IKeyConfigurationListener</code> which is not already
160: * registered with this instance, no operation is performed.
161: */
162: void removeKeyConfigurationListener(
163: IKeyConfigurationListener keyConfigurationListener);
164: }
|