IWorkbenchContextSupport


1   /*******************************************************************************
2    * Copyright (c) 2003, 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  package org.eclipse.ui.contexts;
12  
13  import java.util.Collection  ;
14  
15  import org.eclipse.swt.widgets.Shell;
16  
17  /**
18   * <p>
19   * An instance of this interface provides support for managing contexts at the
20   * <code>IWorkbench</code> level. This provides the functionality necessary to
21   * enabled contexts, disable or enabled the key binding service, as well as
22   * register shells as particular types of windows.
23   * <p>
24   * This interface is not intended to be extended or implemented by clients.
25   * </p>
26   * 
27   * @since 3.0
28   * @deprecated Please use <code>IBindingService</code> and
29   *             <code>IContextService</code> instead.
30   * @see org.eclipse.ui.contexts.IContextService
31   * @see org.eclipse.ui.keys.IBindingService
32   */
33  public interface IWorkbenchContextSupport {
34  
35      /**
36       * The identifier for the context that is active when a shell registered as
37       * a dialog.
38       */
39      public static final String   CONTEXT_ID_DIALOG = IContextService.CONTEXT_ID_DIALOG;
40  
41      /**
42       * The identifier for the context that is active when a shell is registered
43       * as either a window or a dialog.
44       */
45      public static final String   CONTEXT_ID_DIALOG_AND_WINDOW = IContextService.CONTEXT_ID_DIALOG_AND_WINDOW;
46  
47      /**
48       * The identifier for the context that is active when a shell is registered
49       * as a window.
50       */
51      public static final String   CONTEXT_ID_WINDOW = IContextService.CONTEXT_ID_WINDOW;
52  
53      /**
54       * The type used for registration indicating that the shell should be
55       * treated as a dialog. When the given shell is active, the "In Dialogs"
56       * context should also be active.
57       */
58      public static final int TYPE_DIALOG = IContextService.TYPE_DIALOG;
59  
60      /**
61       * The type used for registration indicating that the shell should not
62       * receive any key bindings be default. When the given shell is active, we
63       * should not provide any <code>EnabledSubmission</code> instances for the
64       * "In Dialogs" or "In Windows" contexts.
65       * 
66       */
67      public static final int TYPE_NONE = IContextService.TYPE_NONE;
68  
69      /**
70       * The type used for registration indicating that the shell should be
71       * treated as a window. When the given shell is active, the "In Windows"
72       * context should also be active.
73       */
74      public static final int TYPE_WINDOW = IContextService.TYPE_WINDOW;
75  
76      /**
77       * <p>
78       * Add a single enabled submission for consideration. An enabled submission
79       * is a description of certain criteria under which a particular context
80       * should become active. All added submissions will be check when the
81       * conditions in the workbench change, and zero or more contexts will be
82       * selected as active.
83       * </p>
84       * <p>
85       * Just because an enabled submission is added, it does not mean that the
86       * corresponding context will become active. The workbench will consider the
87       * request, but other factors (such as conflicts) may prevent the context
88       * from becoming active.
89       * </p>
90       * 
91       * @param enabledSubmission
92       *            The enabled submission to be considered; must not be
93       *            <code>null</code>.
94       */
95      void addEnabledSubmission(EnabledSubmission enabledSubmission);
96  
97      /**
98       * <p>
99       * Adds zero or more enabled submissions for consideration. An enabled
100      * submission is a description of certain criteria under which a particular
101      * context should become active. All added submissions will be check when
102      * the conditions in the workbench change, and zero or more contexts will be
103      * selected as active.
104      * </p>
105      * <p>
106      * Just because an enabled submission is added, it does not mean that the
107      * corresponding context will become active. The workbench will consider the
108      * request, but other factors (such as conflicts) may prevent the context
109      * from becoming active.
110      * </p>
111      * 
112      * @param enabledSubmissions
113      *            The enabled submissions to be considered; must not be
114      *            <code>null</code>, but may be empty. Every element in the
115      *            collection must be an instance of
116      *            <code>EnabledSubmission</code>.
117      */
118     void addEnabledSubmissions(Collection   enabledSubmissions);
119 
120     /**
121      * Returns the context manager for the workbench.
122      * 
123      * @return the context manager for the workbench. Guaranteed not to be
124      *         <code>null</code>.
125      */
126     IContextManager getContextManager();
127 
128     /**
129      * Returns the shell type for the given shell.
130      * 
131      * @param shell
132      *            The shell for which the type should be determined. If this
133      *            value is <code>null</code>, then
134      *            <code>IWorkbenchContextSupport.TYPE_NONE</code> is returned.
135      * @return <code>IWorkbenchContextSupport.TYPE_WINDOW</code>,
136      *         <code>IWorkbenchContextSupport.TYPE_DIALOG</code>, or
137      *         <code>IWorkbenchContextSupport.TYPE_NONE</code>.
138      * @since 3.1
139      */
140     public int getShellType(final Shell shell);
141 
142     /**
143      * Tests whether the global key binding architecture is currently active.
144      * 
145      * @return <code>true</code> if the key bindings are active;
146      *         <code>false</code> otherwise.
147      */
148     public boolean isKeyFilterEnabled();
149 
150     /**
151      * Opens the key assistant dialog positioned near the key binding entry in
152      * the status bar.
153      * 
154      * @since 3.1
155      */
156     public void openKeyAssistDialog();
157 
158     /**
159      * <p>
160      * Registers a shell to automatically promote or demote some basic types of
161      * contexts. The "In Dialogs" and "In Windows" contexts are provided by the
162      * system. This a convenience method to ensure that these contexts are
163      * promoted when the given is shell is active.
164      * </p>
165      * <p>
166      * If a shell is registered as a window, then the "In Windows" context is
167      * enabled when that shell is active. If a shell is registered as a dialog --
168      * or is not registered, but has a parent shell -- then the "In Dialogs"
169      * context is enabled when that shell is active. If the shell is registered
170      * as none -- or is not registered, but has no parent shell -- then the
171      * neither of the contexts will be enabled (by us -- someone else can always
172      * enabled them).
173      * </p>
174      * <p>
175      * If the provided shell has already been registered, then this method will
176      * change the registration.
177      * </p>
178      * 
179      * @param shell
180      *            The shell to register for key bindings; must not be
181      *            <code>null</code>.
182      * @param type
183      *            The type of shell being registered. This value must be one of
184      *            the constants given in this interface.
185      * 
186      * @return <code>true</code> if the shell had already been registered
187      *         (i.e., the registration has changed); <code>false</code>
188      *         otherwise.
189      */
190     public boolean registerShell(final Shell shell, final int type);
191 
192     /**
193      * <p>
194      * Removes a single enabled submission from consideration. Only the same
195      * enabled submission will be removed; equivalent submissions will not be
196      * removed. Removing an enabled submission does not necessarily mean that
197      * the corresponding context will become inactive. It is possible that other
198      * parts of the application have requested that the context be enabled.
199      * </p>
200      * <p>
201      * There is no way to disable a context. It is only possible to not enable
202      * it.
203      * </p>
204      * 
205      * @param enabledSubmission
206      *            The enabled submission to be removed; must not be
207      *            <code>null</code>.
208      */
209     void removeEnabledSubmission(EnabledSubmission enabledSubmission);
210 
211     /**
212      * <p>
213      * Removes a collection of enabled submissions from consideration. Only the
214      * same enabled submissions will be removed; equivalent submissions will not
215      * be removed. Removing an enabled submission does not necessarily mean that
216      * the corresponding context will become inactive. It is possible that other
217      * parts of the application have requested that the context be enabled.
218      * </p>
219      * <p>
220      * There is no way to disable a context. It is only possible to not enable
221      * it.
222      * </p>
223      * 
224      * @param enabledSubmissions
225      *            The enabled submissions to be removed; must not be
226      *            <code>null</code>, but may be empty. The collection must
227      *            only contain instances of <code>EnabledSubmission</code>.
228      */
229     void removeEnabledSubmissions(Collection   enabledSubmissions);
230 
231     /**
232      * Enables or disables the global key binding architecture. The architecture
233      * should be enabled by default.
234      * 
235      * When enabled, keyboard shortcuts are active, and that key events can
236      * trigger commands. This also means that widgets may not see all key events
237      * (as they might be trapped as a keyboard shortcut).
238      * 
239      * When disabled, no key events will trapped as keyboard shortcuts, and that
240      * no commands can be triggered by keyboard events. (Exception: it is
241      * possible that someone listening for key events on a widget could trigger
242      * a command.)
243      * 
244      * @param enabled
245      *            Whether the key filter should be enabled.
246      */
247     public void setKeyFilterEnabled(final boolean enabled);
248 
249     /**
250      * <p>
251      * Unregisters a shell that was previously registered. After this method
252      * completes, the shell will be treated as if it had never been registered
253      * at all. If you have registered a shell, you should ensure that this
254      * method is called when the shell is disposed. Otherwise, a potential
255      * memory leak will exist.
256      * </p>
257      * <p>
258      * If the shell was never registered, or if the shell is <code>null</code>,
259      * then this method returns <code>false</code> and does nothing.
260      * 
261      * @param shell
262      *            The shell to be unregistered; does nothing if this value is
263      *            <code>null</code>.
264      * 
265      * @return <code>true</code> if the shell had been registered;
266      *         <code>false</code> otherwise.
267      */
268     public boolean unregisterShell(final Shell shell);
269 }
270
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags