001: /*******************************************************************************
002: * Copyright (c) 2003, 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.contexts;
011:
012: import java.util.Collection;
013:
014: import org.eclipse.swt.widgets.Shell;
015:
016: /**
017: * <p>
018: * An instance of this interface provides support for managing contexts at the
019: * <code>IWorkbench</code> level. This provides the functionality necessary to
020: * enabled contexts, disable or enabled the key binding service, as well as
021: * register shells as particular types of windows.
022: * <p>
023: * This interface is not intended to be extended or implemented by clients.
024: * </p>
025: *
026: * @since 3.0
027: * @deprecated Please use <code>IBindingService</code> and
028: * <code>IContextService</code> instead.
029: * @see org.eclipse.ui.contexts.IContextService
030: * @see org.eclipse.ui.keys.IBindingService
031: */
032: public interface IWorkbenchContextSupport {
033:
034: /**
035: * The identifier for the context that is active when a shell registered as
036: * a dialog.
037: */
038: public static final String CONTEXT_ID_DIALOG = IContextService.CONTEXT_ID_DIALOG;
039:
040: /**
041: * The identifier for the context that is active when a shell is registered
042: * as either a window or a dialog.
043: */
044: public static final String CONTEXT_ID_DIALOG_AND_WINDOW = IContextService.CONTEXT_ID_DIALOG_AND_WINDOW;
045:
046: /**
047: * The identifier for the context that is active when a shell is registered
048: * as a window.
049: */
050: public static final String CONTEXT_ID_WINDOW = IContextService.CONTEXT_ID_WINDOW;
051:
052: /**
053: * The type used for registration indicating that the shell should be
054: * treated as a dialog. When the given shell is active, the "In Dialogs"
055: * context should also be active.
056: */
057: public static final int TYPE_DIALOG = IContextService.TYPE_DIALOG;
058:
059: /**
060: * The type used for registration indicating that the shell should not
061: * receive any key bindings be default. When the given shell is active, we
062: * should not provide any <code>EnabledSubmission</code> instances for the
063: * "In Dialogs" or "In Windows" contexts.
064: *
065: */
066: public static final int TYPE_NONE = IContextService.TYPE_NONE;
067:
068: /**
069: * The type used for registration indicating that the shell should be
070: * treated as a window. When the given shell is active, the "In Windows"
071: * context should also be active.
072: */
073: public static final int TYPE_WINDOW = IContextService.TYPE_WINDOW;
074:
075: /**
076: * <p>
077: * Add a single enabled submission for consideration. An enabled submission
078: * is a description of certain criteria under which a particular context
079: * should become active. All added submissions will be check when the
080: * conditions in the workbench change, and zero or more contexts will be
081: * selected as active.
082: * </p>
083: * <p>
084: * Just because an enabled submission is added, it does not mean that the
085: * corresponding context will become active. The workbench will consider the
086: * request, but other factors (such as conflicts) may prevent the context
087: * from becoming active.
088: * </p>
089: *
090: * @param enabledSubmission
091: * The enabled submission to be considered; must not be
092: * <code>null</code>.
093: */
094: void addEnabledSubmission(EnabledSubmission enabledSubmission);
095:
096: /**
097: * <p>
098: * Adds zero or more enabled submissions for consideration. An enabled
099: * submission is a description of certain criteria under which a particular
100: * context should become active. All added submissions will be check when
101: * the conditions in the workbench change, and zero or more contexts will be
102: * selected as active.
103: * </p>
104: * <p>
105: * Just because an enabled submission is added, it does not mean that the
106: * corresponding context will become active. The workbench will consider the
107: * request, but other factors (such as conflicts) may prevent the context
108: * from becoming active.
109: * </p>
110: *
111: * @param enabledSubmissions
112: * The enabled submissions to be considered; must not be
113: * <code>null</code>, but may be empty. Every element in the
114: * collection must be an instance of
115: * <code>EnabledSubmission</code>.
116: */
117: void addEnabledSubmissions(Collection enabledSubmissions);
118:
119: /**
120: * Returns the context manager for the workbench.
121: *
122: * @return the context manager for the workbench. Guaranteed not to be
123: * <code>null</code>.
124: */
125: IContextManager getContextManager();
126:
127: /**
128: * Returns the shell type for the given shell.
129: *
130: * @param shell
131: * The shell for which the type should be determined. If this
132: * value is <code>null</code>, then
133: * <code>IWorkbenchContextSupport.TYPE_NONE</code> is returned.
134: * @return <code>IWorkbenchContextSupport.TYPE_WINDOW</code>,
135: * <code>IWorkbenchContextSupport.TYPE_DIALOG</code>, or
136: * <code>IWorkbenchContextSupport.TYPE_NONE</code>.
137: * @since 3.1
138: */
139: public int getShellType(final Shell shell);
140:
141: /**
142: * Tests whether the global key binding architecture is currently active.
143: *
144: * @return <code>true</code> if the key bindings are active;
145: * <code>false</code> otherwise.
146: */
147: public boolean isKeyFilterEnabled();
148:
149: /**
150: * Opens the key assistant dialog positioned near the key binding entry in
151: * the status bar.
152: *
153: * @since 3.1
154: */
155: public void openKeyAssistDialog();
156:
157: /**
158: * <p>
159: * Registers a shell to automatically promote or demote some basic types of
160: * contexts. The "In Dialogs" and "In Windows" contexts are provided by the
161: * system. This a convenience method to ensure that these contexts are
162: * promoted when the given is shell is active.
163: * </p>
164: * <p>
165: * If a shell is registered as a window, then the "In Windows" context is
166: * enabled when that shell is active. If a shell is registered as a dialog --
167: * or is not registered, but has a parent shell -- then the "In Dialogs"
168: * context is enabled when that shell is active. If the shell is registered
169: * as none -- or is not registered, but has no parent shell -- then the
170: * neither of the contexts will be enabled (by us -- someone else can always
171: * enabled them).
172: * </p>
173: * <p>
174: * If the provided shell has already been registered, then this method will
175: * change the registration.
176: * </p>
177: *
178: * @param shell
179: * The shell to register for key bindings; must not be
180: * <code>null</code>.
181: * @param type
182: * The type of shell being registered. This value must be one of
183: * the constants given in this interface.
184: *
185: * @return <code>true</code> if the shell had already been registered
186: * (i.e., the registration has changed); <code>false</code>
187: * otherwise.
188: */
189: public boolean registerShell(final Shell shell, final int type);
190:
191: /**
192: * <p>
193: * Removes a single enabled submission from consideration. Only the same
194: * enabled submission will be removed; equivalent submissions will not be
195: * removed. Removing an enabled submission does not necessarily mean that
196: * the corresponding context will become inactive. It is possible that other
197: * parts of the application have requested that the context be enabled.
198: * </p>
199: * <p>
200: * There is no way to disable a context. It is only possible to not enable
201: * it.
202: * </p>
203: *
204: * @param enabledSubmission
205: * The enabled submission to be removed; must not be
206: * <code>null</code>.
207: */
208: void removeEnabledSubmission(EnabledSubmission enabledSubmission);
209:
210: /**
211: * <p>
212: * Removes a collection of enabled submissions from consideration. Only the
213: * same enabled submissions will be removed; equivalent submissions will not
214: * be removed. Removing an enabled submission does not necessarily mean that
215: * the corresponding context will become inactive. It is possible that other
216: * parts of the application have requested that the context be enabled.
217: * </p>
218: * <p>
219: * There is no way to disable a context. It is only possible to not enable
220: * it.
221: * </p>
222: *
223: * @param enabledSubmissions
224: * The enabled submissions to be removed; must not be
225: * <code>null</code>, but may be empty. The collection must
226: * only contain instances of <code>EnabledSubmission</code>.
227: */
228: void removeEnabledSubmissions(Collection enabledSubmissions);
229:
230: /**
231: * Enables or disables the global key binding architecture. The architecture
232: * should be enabled by default.
233: *
234: * When enabled, keyboard shortcuts are active, and that key events can
235: * trigger commands. This also means that widgets may not see all key events
236: * (as they might be trapped as a keyboard shortcut).
237: *
238: * When disabled, no key events will trapped as keyboard shortcuts, and that
239: * no commands can be triggered by keyboard events. (Exception: it is
240: * possible that someone listening for key events on a widget could trigger
241: * a command.)
242: *
243: * @param enabled
244: * Whether the key filter should be enabled.
245: */
246: public void setKeyFilterEnabled(final boolean enabled);
247:
248: /**
249: * <p>
250: * Unregisters a shell that was previously registered. After this method
251: * completes, the shell will be treated as if it had never been registered
252: * at all. If you have registered a shell, you should ensure that this
253: * method is called when the shell is disposed. Otherwise, a potential
254: * memory leak will exist.
255: * </p>
256: * <p>
257: * If the shell was never registered, or if the shell is <code>null</code>,
258: * then this method returns <code>false</code> and does nothing.
259: *
260: * @param shell
261: * The shell to be unregistered; does nothing if this value is
262: * <code>null</code>.
263: *
264: * @return <code>true</code> if the shell had been registered;
265: * <code>false</code> otherwise.
266: */
267: public boolean unregisterShell(final Shell shell);
268: }
|