WorkbenchHelp


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  package org.eclipse.ui.help;
12  
13  import org.eclipse.help.IContext;
14  import org.eclipse.help.IHelp;
15  import org.eclipse.jface.action.IAction;
16  import org.eclipse.swt.events.HelpListener;
17  import org.eclipse.swt.widgets.Control;
18  import org.eclipse.swt.widgets.Menu;
19  import org.eclipse.swt.widgets.MenuItem;
20  import org.eclipse.ui.PlatformUI;
21  import org.eclipse.ui.commands.ICommand;
22  import org.eclipse.ui.internal.help.WorkbenchHelpSystem;
23  
24  /**
25   * Provides methods for accessing the help UI.
26   * <p>
27   * The help UI is optional, to allow applications to be configured
28   * without one.
29   * </p>
30   * <p>
31   * The various <code>setHelp</code> methods allow context help to be hooked in
32   * to SWT menus, menu items, and controls, and into JFace actions. This involves 
33   * furnishing a help context id. When the user requests help for one of the 
34   * established widgets (for instance, by hitting F1), the context id is
35   * retrieved and passed to the help UI using 
36   * <code>WorkbenchHelp.displayContext(helpContext, xposition, yposition)</code>.
37   * </p>
38   * <p>
39   * In cases more dynamic situations, clients may hook their own help listener
40   * and call <code>WorkbenchHelp.displayContext</code> with an 
41   * <code>IContext</code>.
42   * </p>
43   * <p>
44   * This class provides static methods only; it is not intended to be instantiated
45   * or subclassed.
46   * </p>
47   *
48   * @deprecated clients should use <code>IWorkbenchHelpSystem</code> instead
49   * 
50   * @see org.eclipse.help.HelpSystem
51   * @see org.eclipse.ui.help.IWorkbenchHelpSystem
52   * @see org.eclipse.ui.IWorkbench#getHelpSystem()
53   */
54  public class WorkbenchHelp {
55  
56      /**
57       * This class is not intented to be instantiated
58       */
59      private WorkbenchHelp() {
60      }
61  
62      /**
63       * Displays the entire help bookshelf.
64       * <p>
65       * Ignored if no help UI is available.
66       * </p>
67       * 
68       * @since 3.0
69       */
70      public static void displayHelp() {
71          PlatformUI.getWorkbench().getHelpSystem().displayHelp();
72      }
73  
74      /**
75       * Displays context-sensitive help for the given context.
76       * <p>
77       * (x,y) coordinates specify the location where the context sensitive 
78       * help UI will be presented. These coordinates are screen-relative 
79       * (ie: (0,0) is the top left-most screen corner).
80       * The platform is responsible for calling this method and supplying the 
81       * appropriate location.
82       * </p>
83       * <p>
84       * Ignored if no help UI is available.
85       * </p>
86       * 
87       * @param context the context to display
88       * @param x horizontal position
89       * @param y verifical position
90       * @since 3.0
91       */
92      public static void displayContext(IContext context, int x, int y) {
93          PlatformUI.getWorkbench().getHelpSystem().displayContext(context, x, y);
94      }
95  
96      /**
97       * Displays help content for the help resource with the given URL.
98       * <p>
99       * This method is called by the platform to launch the help system UI, displaying
100      * the documentation identified by the <code>href</code> parameter.
101      * </p> 
102      * <p>
103      * The help system makes no guarantee that all the help resources can be displayed or how they are displayed.
104      * </p>
105      * <p>
106      * Ignored if no help UI is available.
107      * </p>
108      * 
109      * @param href the URL of the help resource.
110      * <p>Valid href are as described in 
111      *  {@link  org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()}
112      * </p>
113      * @since 3.0
114      */
115     public static void displayHelpResource(String   href) {
116         PlatformUI.getWorkbench().getHelpSystem().displayHelpResource(href);
117     }
118 
119     /**
120      * Creates a new help listener for the given command. This retrieves the
121      * help context ID from the command, and creates an appropriate listener
122      * based on this.
123      * 
124      * @param command
125      *            The command for which the listener should be created; must
126      *            not be <code>null</code>.
127      * @return A help listener; never <code>null</code>.
128      */
129     public static HelpListener createHelpListener(ICommand command) {
130         return WorkbenchHelpSystem.getInstance().createHelpListener(command);
131     }
132 
133     /**
134      * Calls the help support system to display the given help context id.
135      * <p>
136      * May only be called from a UI thread.
137      * <p>
138      *
139      * @param contextId the id of the context to display
140      * @since 2.0
141      */
142     public static void displayHelp(String   contextId) {
143         PlatformUI.getWorkbench().getHelpSystem().displayHelp(contextId);       
144     }
145 
146     /**
147      * Displays context-sensitive help for the given context.
148      * <p>
149      * May only be called from a UI thread.
150      * <p>
151      *
152      * @param context the context to display
153      * @since 2.0
154      */
155     public static void displayHelp(IContext context) {
156         PlatformUI.getWorkbench().getHelpSystem().displayHelp(context);
157     }
158 
159     /**
160      * Returns the help contexts on the given control.
161      * <p>
162      * Instances of <code>IContextComputer</code> may use this method
163      * to obtain the previously registered help contexts of a control.
164      * </p>
165      *
166      * @param control the control on which the contexts are registered
167      * @return contexts the contexts to use when F1 help is invoked; a mixed-type
168      *   array of context ids (type <code>String</code>) and/or help contexts (type
169      *   <code>IContext</code>) or an <code>IContextComputer</code> or
170      *   <code>null</code> if no contexts have been set.
171      * @deprecated as context computers are no longer supported
172      */
173     public static Object   getHelp(Control control) {
174         return control.getData(WorkbenchHelpSystem.HELP_KEY);
175     }
176 
177     /**
178      * Returns the help contexts on the given menu.
179      * <p>
180      * Instances of <code>IContextComputer</code> may use this method
181      * to obtain the previously registered help contexts of a menu.
182      * </p>
183      *
184      * @param menu the menu on which the contexts are registered
185      * @return contexts the contexts to use when F1 help is invoked; a mixed-type
186      *   array of context ids (type <code>String</code>) and/or help contexts (type
187      *   <code>IContext</code>) or an <code>IContextComputer</code> or
188      *   <code>null</code> if no contexts have been set.
189      * @deprecated as context computers are no longer supported
190      */
191     public static Object   getHelp(Menu menu) {
192         return menu.getData(WorkbenchHelpSystem.HELP_KEY);
193     }
194 
195     /**
196      * Returns the help contexts on the given menu item.
197      * <p>
198      * Instances of <code>IContextComputer</code> may use this method
199      * to obtain the previously registered help contexts of a menu.
200      * </p>
201      *
202      * @param menuItem the menu item on which the contexts are registered
203      * @return contexts the contexts to use when F1 help is invoked; a mixed-type
204      *   array of context ids (type <code>String</code>) and/or help contexts (type
205      *   <code>IContext</code>) or an <code>IContextComputer</code> or
206      *   <code>null</code> if no contexts have been set.
207      * @deprecated as context computers are no longer supported
208      */
209     public static Object   getHelp(MenuItem menuItem) {
210         return menuItem.getData(WorkbenchHelpSystem.HELP_KEY);
211     }
212 
213     /**
214      * Returns the help support system for the platform, if available.
215      *
216      * @return the help support system, or <code>null</code> if none
217      * @deprecated Use the static methods on this class and on
218      * {@link org.eclipse.help.HelpSystem HelpSystem} instead of the IHelp methods
219      * on the object returned by this method.
220      */
221     public static IHelp getHelpSupport() {
222         return WorkbenchHelpSystem.getInstance().getHelpSupport();
223     }
224 
225     
226     /**
227      * Returns whether the context-sensitive help window is currently being
228      * displayed. Returns <code>false</code> if the help UI has not been
229      * activated yet.
230      * 
231      * @return <code>true</code> if the context-sensitive help
232      * window is currently being displayed, <code>false</code> otherwise
233      */
234     public static boolean isContextHelpDisplayed() {
235         return PlatformUI.getWorkbench().getHelpSystem().isContextHelpDisplayed();
236     }
237 
238     /**
239      * Sets the given help contexts on the given action.
240      * <p>
241      * Use this method when the list of help contexts is known in advance.
242      * Help contexts can either supplied as a static list, or calculated with a
243      * context computer (but not both).
244      * </p>
245      *
246      * @param action the action on which to register the computer
247      * @param contexts the contexts to use when F1 help is invoked; a mixed-type
248      *   array of context ids (type <code>String</code>) and/or help contexts (type
249      *   <code>IContext</code>)
250      * @deprecated use setHelp with a single context id parameter
251      */
252     public static void setHelp(IAction action, final Object  [] contexts) {
253         WorkbenchHelpSystem.getInstance().setHelp(action, contexts);
254     }
255 
256     /**
257      * Sets the given help context computer on the given action.
258      * <p>
259      * Use this method when the help contexts cannot be computed in advance.
260      * Help contexts can either supplied as a static list, or calculated with a
261      * context computer (but not both).
262      * </p>
263      *
264      * @param action the action on which to register the computer
265      * @param computer the computer to determine the help contexts for the control
266      *    when F1 help is invoked
267      * @deprecated context computers are no longer supported, clients should implement
268      *  their own help listener
269      */
270     public static void setHelp(IAction action, final IContextComputer computer) {
271         WorkbenchHelpSystem.getInstance().setHelp(action, computer);
272     }
273 
274     /**
275      * Sets the given help contexts on the given control.
276      * <p>
277      * Use this method when the list of help contexts is known in advance.
278      * Help contexts can either supplied as a static list, or calculated with a
279      * context computer (but not both).
280      * </p>
281      *
282      * @param control the control on which to register the contexts
283      * @param contexts the contexts to use when F1 help is invoked; a mixed-type
284      *   array of context ids (type <code>String</code>) and/or help contexts (type
285      *   <code>IContext</code>)
286      * @deprecated use setHelp with single context id parameter
287      */
288     public static void setHelp(Control control, Object  [] contexts) {
289         WorkbenchHelpSystem.getInstance().setHelp(control, contexts);
290     }
291 
292     /**
293      * Sets the given help context computer on the given control.
294      * <p>
295      * Use this method when the help contexts cannot be computed in advance.
296      * Help contexts can either supplied as a static list, or calculated with a
297      * context computer (but not both).
298      * </p>
299      *
300      * @param control the control on which to register the computer
301      * @param computer the computer to determine the help contexts for the control
302      *    when F1 help is invoked
303      * @deprecated context computers are no longer supported, clients should implement
304      *  their own help listener
305      */
306     public static void setHelp(Control control, IContextComputer computer) {
307         WorkbenchHelpSystem.getInstance().setHelp(control, computer);
308     }
309 
310     /**
311      * Sets the given help contexts on the given menu.
312      * <p>
313      * Use this method when the list of help contexts is known in advance.
314      * Help contexts can either supplied as a static list, or calculated with a
315      * context computer (but not both).
316      * </p>
317      *
318      * @param menu the menu on which to register the context
319      * @param contexts the contexts to use when F1 help is invoked; a mixed-type
320      *   array of context ids (type <code>String</code>) and/or help contexts (type
321      *   <code>IContext</code>)
322      * @deprecated use setHelp with single context id parameter
323      */
324     public static void setHelp(Menu menu, Object  [] contexts) {
325         WorkbenchHelpSystem.getInstance().setHelp(menu, contexts);
326     }
327 
328     /**
329      * Sets the given help context computer on the given menu.
330      * <p>
331      * Use this method when the help contexts cannot be computed in advance.
332      * Help contexts can either supplied as a static list, or calculated with a
333      * context computer (but not both).
334      * </p>
335      *
336      * @param menu the menu on which to register the computer
337      * @param computer the computer to determine the help contexts for the control
338      *    when F1 help is invoked
339      * @deprecated context computers are no longer supported, clients should implement
340      *  their own help listener
341      */
342     public static void setHelp(Menu menu, IContextComputer computer) {
343         WorkbenchHelpSystem.getInstance().setHelp(menu, computer);
344     }
345 
346     /**
347      * Sets the given help contexts on the given menu item.
348      * <p>
349      * Use this method when the list of help contexts is known in advance.
350      * Help contexts can either supplied as a static list, or calculated with a
351      * context computer (but not both).
352      * </p>
353      *
354      * @param item the menu item on which to register the context
355      * @param contexts the contexts to use when F1 help is invoked; a mixed-type
356      *   array of context ids (type <code>String</code>) and/or help contexts (type
357      *   <code>IContext</code>)
358      * @deprecated use setHelp with single context id parameter
359      */
360     public static void setHelp(MenuItem item, Object  [] contexts) {
361         WorkbenchHelpSystem.getInstance().setHelp(item, contexts);
362     }
363 
364     /**
365      * Sets the given help context computer on the given menu item.
366      * <p>
367      * Use this method when the help contexts cannot be computed in advance.
368      * Help contexts can either supplied as a static list, or calculated with a
369      * context computer (but not both).
370      * </p>
371      *
372      * @param item the menu item on which to register the computer
373      * @param computer the computer to determine the help contexts for the control
374      *    when F1 help is invoked
375      * @deprecated context computers are no longer supported, clients should implement
376      *  their own help listener
377      */
378     public static void setHelp(MenuItem item, IContextComputer computer) {
379         WorkbenchHelpSystem.getInstance().setHelp(item, computer);
380     }
381 
382     /**
383      * Sets the given help context id on the given action.
384      *
385      * @param action the action on which to register the context id
386      * @param contextId the context id to use when F1 help is invoked
387      * @since 2.0
388      */
389     public static void setHelp(IAction action, final String   contextId) {
390         PlatformUI.getWorkbench().getHelpSystem().setHelp(action, contextId);
391     }
392 
393     /**
394      * Sets the given help context id on the given control.
395      *
396      * @param control the control on which to register the context id
397      * @param contextId the context id to use when F1 help is invoked
398      * @since 2.0
399      */
400     public static void setHelp(Control control, String   contextId) {
401         PlatformUI.getWorkbench().getHelpSystem().setHelp(control, contextId);      
402     }
403 
404     /**
405      * Sets the given help context id on the given menu.
406      *
407      * @param menu the menu on which to register the context id
408      * @param contextId the context id to use when F1 help is invoked
409      * @since 2.0
410      */
411     public static void setHelp(Menu menu, String   contextId) {
412         PlatformUI.getWorkbench().getHelpSystem().setHelp(menu, contextId);
413     }
414 
415     /**
416      * Sets the given help context id on the given menu item.
417      *
418      * @param item the menu item on which to register the context id
419      * @param contextId the context id to use when F1 help is invoked
420      * @since 2.0
421      */
422     public static void setHelp(MenuItem item, String   contextId) {
423         PlatformUI.getWorkbench().getHelpSystem().setHelp(item, contextId);
424     }
425 }
426
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags