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: import java.util.Map;
013: import java.util.Set;
014:
015: import org.eclipse.ui.keys.KeySequence;
016:
017: /**
018: * <p>
019: * An instance of <code>ICommandManager</code> can be used to obtain instances
020: * of <code>ICommand</code>, as well as manage whether or not those instances
021: * are active or inactive, enabled or disabled.
022: * </p>
023: * <p>
024: * This interface is not intended to be extended or implemented by clients.
025: * </p>
026: *
027: * @since 3.0
028: * @see org.eclipse.ui.commands.ICommand
029: * @see org.eclipse.ui.commands.ICommandManagerListener
030: * @see org.eclipse.core.commands.CommandManager
031: * @deprecated Please use the "org.eclipse.core.commands" plug-in instead.
032: */
033: public interface ICommandManager {
034:
035: /**
036: * Registers an instance of <code>ICommandManagerListener</code> to listen
037: * for changes to attributes of this instance.
038: *
039: * @param commandManagerListener
040: * the instance of <code>ICommandManagerListener</code> to
041: * register. Must not be <code>null</code>. If an attempt is
042: * made to register an instance of
043: * <code>ICommandManagerListener</code> which is already
044: * registered with this instance, no operation is performed.
045: */
046: void addCommandManagerListener(
047: ICommandManagerListener commandManagerListener);
048:
049: /**
050: * Returns the set of identifiers to active contexts.
051: * <p>
052: * Notification is sent to all registered listeners if this property
053: * changes.
054: * </p>
055: *
056: * @return the set of identifiers to active contexts. This set may be
057: * empty, but is guaranteed not to be <code>null</code>. If this
058: * set is not empty, it is guaranteed to only contain instances of
059: * <code>String</code>.
060: */
061: Set getActiveContextIds();
062:
063: /**
064: * Returns the active key configuration.
065: * <p>
066: * Notification is sent to all registered listeners if this property
067: * changes.
068: * </p>
069: *
070: * @return the active key configuration identifier. This set may be empty,
071: * but it is guaranteed to not be <code>null</code>. If this set
072: * is not empty, it is guaranteed to only contains instances of
073: * <code>String</code>.
074: */
075: String getActiveKeyConfigurationId();
076:
077: /**
078: * Returns the active locale. While this property tends to be simply the
079: * result of {@link java.util.Locale#getDefault()}, it may also be changed
080: * at runtime by different implementations of command manager.
081: * <p>
082: * Notification is sent to all registered listeners if this property
083: * changes.
084: * </p>
085: *
086: * @return the active locale. May be <code>null</code>.
087: */
088: String getActiveLocale();
089:
090: /**
091: * Returns the active platform. While this property tends to be simply the
092: * result of {@link org.eclipse.swt.SWT#getPlatform()}, it may also be
093: * changed at runtime by different implementations of command manager.
094: * <p>
095: * Notification is sent to all registered listeners if this property
096: * changes.
097: * </p>
098: *
099: * @return the active platform. May be <code>null</code>.
100: */
101: String getActivePlatform();
102:
103: /**
104: * Returns a handle to a category given an identifier.
105: *
106: * @param categoryId
107: * an identifier. Must not be <code>null</code>
108: * @return a handle to a category.
109: */
110: ICategory getCategory(String categoryId);
111:
112: /**
113: * Returns a handle to a command given an identifier.
114: *
115: * @param commandId
116: * an identifier. Must not be <code>null</code>
117: * @return a handle to a command; never <code>null</code>.
118: */
119: ICommand getCommand(String commandId);
120:
121: /**
122: * <p>
123: * Returns the set of identifiers to defined categories.
124: * </p>
125: * <p>
126: * Notification is sent to all registered listeners if this attribute
127: * changes.
128: * </p>
129: *
130: * @return the set of identifiers to defined categories. This set may be
131: * empty, but is guaranteed not to be <code>null</code>. If this
132: * set is not empty, it is guaranteed to only contain instances of
133: * <code>String</code>.
134: */
135: Set getDefinedCategoryIds();
136:
137: /**
138: * <p>
139: * Returns the set of identifiers to defined commands.
140: * </p>
141: * <p>
142: * Notification is sent to all registered listeners if this attribute
143: * changes.
144: * </p>
145: *
146: * @return the set of identifiers to defined commands. This set may be
147: * empty, but is guaranteed not to be <code>null</code>. If this
148: * set is not empty, it is guaranteed to only contain instances of
149: * <code>String</code>.
150: */
151: Set getDefinedCommandIds();
152:
153: /**
154: * <p>
155: * Returns the set of identifiers to defined key configurations.
156: * </p>
157: * <p>
158: * Notification is sent to all registered listeners if this attribute
159: * changes.
160: * </p>
161: *
162: * @return the set of identifiers to defined key configurations. This set
163: * may be empty, but is guaranteed not to be <code>null</code>.
164: * If this set is not empty, it is guaranteed to only contain
165: * instances of <code>String</code>.
166: */
167: Set getDefinedKeyConfigurationIds();
168:
169: /**
170: * Returns a handle to a key configuration given an identifier.
171: *
172: * @param keyConfigurationId
173: * an identifier. Must not be <code>null</code>
174: * @return a handle to a key configuration.
175: */
176: IKeyConfiguration getKeyConfiguration(String keyConfigurationId);
177:
178: /**
179: * Finds all of the commands which have key bindings that start with the
180: * given key sequence.
181: *
182: * @param keySequence
183: * The prefix to look for; must not be <code>null</code>.
184: * @return A map of all of the matching key sequences (
185: * <code>KeySequence</code>) to command identifiers (
186: * <code>String</code>). This map may be empty, but it is never
187: * <code>null</code>.
188: */
189: Map getPartialMatches(KeySequence keySequence);
190:
191: /**
192: * Finds the command which has the given key sequence as one of its key
193: * bindings.
194: *
195: * @param keySequence
196: * The key binding to look for; must not be <code>null</code>.
197: * @return The command id for the matching command, if any;
198: * <code>null</code> if none.
199: */
200: String getPerfectMatch(KeySequence keySequence);
201:
202: /**
203: * Checks to see whether there are any commands which have key bindings that
204: * start with the given key sequence.
205: *
206: * @param keySequence
207: * The prefix to look for; must not be <code>null</code>.
208: * @return <code>true</code> if at least one command has a key binding
209: * that starts with <code>keySequence</code>;<code>false</code>
210: * otherwise.
211: */
212: boolean isPartialMatch(KeySequence keySequence);
213:
214: /**
215: * Checks to see if there is a command with the given key sequence as one of
216: * its key bindings.
217: *
218: * @param keySequence
219: * The key binding to look for; must not be <code>null</code>.
220: * @return <code>true</code> if a command has a matching key binding;
221: * <code>false</code> otherwise.
222: */
223: boolean isPerfectMatch(KeySequence keySequence);
224:
225: /**
226: * Unregisters an instance of <code>ICommandManagerListener</code>
227: * listening for changes to attributes of this instance.
228: *
229: * @param commandManagerListener
230: * the instance of <code>ICommandManagerListener</code> to
231: * unregister. Must not be <code>null</code>. If an attempt is
232: * made to unregister an instance of
233: * <code>ICommandManagerListener</code> which is not already
234: * registered with this instance, no operation is performed.
235: */
236: void removeCommandManagerListener(
237: ICommandManagerListener commandManagerListener);
238: }
|