WorkbenchHelpSystem


1   /*******************************************************************************
2    * Copyright (c) 2004, 2007 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.internal.help;
12  
13  import java.net.URL  ;
14  
15  import org.eclipse.core.runtime.Assert;
16  import org.eclipse.core.runtime.CoreException;
17  import org.eclipse.core.runtime.IConfigurationElement;
18  import org.eclipse.core.runtime.IExtension;
19  import org.eclipse.core.runtime.IExtensionPoint;
20  import org.eclipse.core.runtime.Platform;
21  import org.eclipse.core.runtime.dynamichelpers.IExtensionChangeHandler;
22  import org.eclipse.core.runtime.dynamichelpers.IExtensionTracker;
23  import org.eclipse.help.HelpSystem;
24  import org.eclipse.help.IContext;
25  import org.eclipse.help.IContext2;
26  import org.eclipse.help.IHelp;
27  import org.eclipse.help.IHelpResource;
28  import org.eclipse.help.IToc;
29  import org.eclipse.jface.action.IAction;
30  import org.eclipse.swt.custom.BusyIndicator;
31  import org.eclipse.swt.events.HelpEvent;
32  import org.eclipse.swt.events.HelpListener;
33  import org.eclipse.swt.graphics.Point;
34  import org.eclipse.swt.widgets.Control;
35  import org.eclipse.swt.widgets.Display;
36  import org.eclipse.swt.widgets.Menu;
37  import org.eclipse.swt.widgets.MenuItem;
38  import org.eclipse.ui.PlatformUI;
39  import org.eclipse.ui.commands.ICommand;
40  import org.eclipse.ui.help.AbstractHelpUI;
41  import org.eclipse.ui.help.IContextComputer;
42  import org.eclipse.ui.help.IWorkbenchHelpSystem;
43  import org.eclipse.ui.internal.IWorkbenchHelpContextIds;
44  import org.eclipse.ui.internal.WorkbenchPlugin;
45  import org.eclipse.ui.internal.registry.IWorkbenchRegistryConstants;
46  
47  /**
48   * This class represents a refactoring of the functionality previously contained
49   * in <code>WorkbenchHelp</code>.
50   * 
51   * @since 3.1
52   */
53  public final class WorkbenchHelpSystem implements IWorkbenchHelpSystem {
54  
55      /**
56       * Key used for stashing help-related data on SWT widgets.
57       * 
58       * @see org.eclipse.swt.widgets.Widget#getData(java.lang.String)
59       */
60      public static final String   HELP_KEY = "org.eclipse.ui.help";//$NON-NLS-1$
61  
62      /**
63       * Id of extension point where the help UI is contributed.
64       */
65      private static final String   HELP_SYSTEM_EXTENSION_ID = PlatformUI.PLUGIN_ID + '.' + IWorkbenchRegistryConstants.PL_HELPSUPPORT;
66  
67      /**
68       * Attribute id for class attribute of help UI extension point.
69       */
70      private static final String   HELP_SYSTEM_CLASS_ATTRIBUTE = "class";//$NON-NLS-1$
71  
72      /**
73       * Singleton.
74       */
75      private static WorkbenchHelpSystem instance;
76  
77      /**
78       * The help listener.
79       */
80      private static class WorkbenchHelpListener implements HelpListener {
81          public void helpRequested(HelpEvent event) {
82  
83              if (getInstance().getHelpUI() == null) {
84                  return;
85              }
86  
87              // get the help context from the widget
88              Object   object = event.widget.getData(HELP_KEY);
89  
90              // Since 2.0 we can expect that object is a String, however
91              // for backward compatability we handle context computers and
92              // arrays.
93              IContext context = null;
94              if (object instanceof String  ) {
95                  // context id - this is the norm
96                  context = HelpSystem.getContext((String  ) object);
97              } else if (object instanceof IContext) {
98                  // already resolved context (pre 2.0)
99                  context = (IContext) object;
100             } else if (object instanceof IContextComputer) {
101                 // a computed context (pre 2.0) - compute it now
102                 Object  [] helpContexts = ((IContextComputer) object)
103                         .computeContexts(event);
104                 // extract the first entry
105                 if (helpContexts != null && helpContexts.length > 0) {
106                     Object   primaryEntry = helpContexts[0];
107                     if (primaryEntry instanceof String  ) {
108                         context = HelpSystem.getContext((String  ) primaryEntry);
109                     } else if (primaryEntry instanceof IContext) {
110                         context = (IContext) primaryEntry;
111                     }
112                 }
113             } else if (object instanceof Object  []) {
114                 // mixed array of String or IContext (pre 2.0) - extract the
115                 // first entry
116                 Object  [] helpContexts = (Object  []) object;
117                 // extract the first entry
118                 if (helpContexts.length > 0) {
119                     Object   primaryEntry = helpContexts[0];
120                     if (primaryEntry instanceof String  ) {
121                         context = HelpSystem.getContext((String  ) primaryEntry);
122                     } else if (primaryEntry instanceof IContext) {
123                         context = (IContext) primaryEntry;
124                     }
125                 }
126             }
127             
128             /*
129              * If can't find it, show the "context is missing" context.
130              */
131             if (context == null) {
132                 context = HelpSystem.getContext(IWorkbenchHelpContextIds.MISSING);
133             }
134             
135             if (context != null) {
136                 // determine a location in the upper right corner of the
137                 // widget
138                 Point point = computePopUpLocation(event.widget.getDisplay());
139                 // display the help
140                 getInstance().displayContext(context, point.x, point.y);
141             }
142         }
143     }
144 
145     /**
146      * Whether the help system has been initialized.
147      */
148     private boolean isInitialized;
149 
150     /**
151      * Pluggable help UI, or <code>null</code> if none (or unknown).
152      */
153     private AbstractHelpUI pluggableHelpUI = null;
154 
155     /**
156      * The id of the help extension that should be used. This is used only for
157      * debugging purposes.
158      */
159     private String   desiredHelpSystemId;
160 
161     /**
162      * Handles dynamic removal of the help system.
163      * 
164      * @since 3.1
165      */
166     /**
167      * Handles dynamic removal of the help system.
168      * 
169      * @since 3.1
170      */
171     private IExtensionChangeHandler handler = new IExtensionChangeHandler() {
172         
173         /* (non-Javadoc)
174          * @see org.eclipse.core.runtime.dynamicHelpers.IExtensionChangeHandler#addExtension(org.eclipse.core.runtime.dynamicHelpers.IExtensionTracker, org.eclipse.core.runtime.IExtension)
175          */
176         public void addExtension(IExtensionTracker tracker,IExtension extension) {
177             //Do nothing
178         }
179         
180         /* (non-Javadoc)
181          * @see org.eclipse.core.runtime.dynamicHelpers.IExtensionChangeHandler#removeExtension(org.eclipse.core.runtime.IExtension, java.lang.Object[])
182          */
183         public void removeExtension(IExtension source, Object  [] objects) {
184             for (int i = 0; i < objects.length; i++) {
185                 if (objects[i] == pluggableHelpUI) {
186                     isInitialized = false;
187                     pluggableHelpUI = null;
188                     helpCompatibilityWrapper = null;
189                     // remove ourselves - we'll be added again in initalize if
190                     // needed
191                     PlatformUI.getWorkbench().getExtensionTracker()
192                             .unregisterHandler(handler);
193                 }
194             }
195         }
196     };
197     
198     /**
199      * Compatibility implementation of old IHelp interface.
200      * WorkbenchHelp.getHelpSupport and IHelp were deprecated in 3.0.
201      */
202     private class CompatibilityIHelpImplementation implements IHelp {
203 
204         /** @deprecated */
205         public void displayHelp() {
206             // real method - forward to help UI if available
207             AbstractHelpUI helpUI = getHelpUI();
208             if (helpUI != null) {
209                 helpUI.displayHelp();
210             }
211         }
212 
213         /** @deprecated */
214         public void displayContext(IContext context, int x, int y) {
215             // real method - forward to help UI if available
216             AbstractHelpUI helpUI = getHelpUI();
217             if (helpUI != null) {
218                 helpUI.displayContext(context, x, y);
219             }
220         }
221 
222         /** @deprecated */
223         public void displayContext(String   contextId, int x, int y) {
224             // convenience method - funnel through the real method
225             IContext context = HelpSystem.getContext(contextId);
226             if (context != null) {
227                 displayContext(context, x, y);
228             }
229         }
230 
231         /** @deprecated */
232         public void displayHelpResource(String   href) {
233             // real method - forward to help UI if available
234             AbstractHelpUI helpUI = getHelpUI();
235             if (helpUI != null) {
236                 helpUI.displayHelpResource(href);
237             }
238         }
239 
240         /** @deprecated */
241         public void displayHelpResource(IHelpResource helpResource) {
242             // convenience method - funnel through the real method
243             displayHelpResource(helpResource.getHref());
244         }
245 
246         /** @deprecated */
247         public void displayHelp(String   toc) {
248             // deprecated method - funnel through the real method
249             displayHelpResource(toc);
250         }
251 
252         /** @deprecated */
253         public void displayHelp(String   toc, String   selectedTopic) {
254             // deprecated method - funnel through the real method
255             displayHelpResource(selectedTopic);
256         }
257 
258         /** @deprecated */
259         public void displayHelp(String   contextId, int x, int y) {
260             // deprecated method - funnel through the real method
261             displayContext(contextId, x, y);
262         }
263 
264         /** @deprecated */
265         public void displayHelp(IContext context, int x, int y) {
266             // deprecated method - funnel through the real method
267             displayContext(context, x, y);
268         }
269 
270         /** @deprecated */
271         public IContext getContext(String   contextId) {
272             // non-UI method - forward to HelpSystem
273             return HelpSystem.getContext(contextId);
274         }
275 
276         /** @deprecated */
277         public IToc[] getTocs() {
278             // non-UI method - forward to HelpSystem
279             return HelpSystem.getTocs();
280         }
281 
282         /** @deprecated */
283         public boolean isContextHelpDisplayed() {
284             // real method - forward to pluggedhelp UI
285             return isContextHelpDisplayed();
286         }
287     }
288 
289     /**
290      * A wrapper for action help context that passes the action
291      * text to be used as a title. 
292      * @since 3.1
293      */
294     private static class ContextWithTitle implements IContext2 {
295         private IContext context;
296         private String   title;
297 
298         ContextWithTitle(IContext context, String   title) {
299             this.context = context;
300             this.title = title;
301         }
302 
303         public String   getTitle() {
304             if (context instanceof IContext2) {
305                 String   ctitle = ((IContext2)context).getTitle();
306                 if (ctitle!=null) {
307                     return ctitle;
308                 }
309             }
310             return title;
311         }
312 
313         public String   getStyledText() {
314             if (context instanceof IContext2) {
315                 return ((IContext2)context).getStyledText();
316             }
317             return context.getText();
318         }
319 
320         public String   getCategory(IHelpResource topic) {
321             if (context instanceof IContext2) {
322                 return ((IContext2)context).getCategory(topic);
323             }
324             return null;
325         }
326 
327         public IHelpResource[] getRelatedTopics() {
328             return context.getRelatedTopics();
329         }
330 
331         public String   getText() {
332             return context.getText();
333         }
334     }
335     
336     /**
337      * Compatibility wrapper, or <code>null</code> if none. Do not access
338      * directly; see getHelpSupport().
339      */
340     private IHelp helpCompatibilityWrapper = null;
341 
342     /**
343      * The listener to attach to various widgets.
344      */
345     private static HelpListener helpListener;
346 
347     /**
348      * For debug purposes only.  
349      * 
350      * @return the desired help system id
351      */
352     public String   getDesiredHelpSystemId() {
353         return desiredHelpSystemId;
354     }
355     
356     /**
357      * For debug purposes only.
358      * 
359      * @param desiredHelpSystemId the desired help system id
360      */
361     public void setDesiredHelpSystemId(String   desiredHelpSystemId) {
362         dispose(); // prep for a new help system
363         this.desiredHelpSystemId = desiredHelpSystemId;
364     }
365     
366     /**
367      * Singleton Constructor.
368      */
369     private WorkbenchHelpSystem() {
370     }
371 
372     /**
373      * Return the singleton instance of this class.
374      * 
375      * @return the singleton instance
376      */
377     public static WorkbenchHelpSystem getInstance() {
378         if (instance == null) {
379             instance = new WorkbenchHelpSystem();
380         }
381 
382         return instance;
383     }
384 
385     /**
386      * Disposed of the singleton of this class if it has been created.
387      */
388     public static void disposeIfNecessary() {
389         if (instance != null) {
390             instance.dispose();
391             instance = null;
392         }
393     }
394 
395     /**
396      * Dispose of any resources allocated by this instance.
397      */
398     public void dispose() {
399         pluggableHelpUI = null;
400         helpCompatibilityWrapper = null;
401         isInitialized = false;
402         PlatformUI.getWorkbench().getExtensionTracker()
403                 .unregisterHandler(handler);
404     }
405 
406     /**
407      * Returns the help UI for the platform, if available. This method will
408      * initialize the help UI if necessary.
409      * 
410      * @return the help UI, or <code>null</code> if none
411      */
412     private AbstractHelpUI getHelpUI() {
413         if (!isInitialized) {
414             isInitialized = initializePluggableHelpUI();
415         }
416         return pluggableHelpUI;
417     }
418 
419     /**
420      * Initializes the pluggable help UI by getting an instance via the
421      * extension point.
422      */
423     private boolean initializePluggableHelpUI() {
424         final boolean[] ret = new boolean[] { false };
425 
426         BusyIndicator.showWhile(Display.getCurrent(), new Runnable  () {
427 
428             /*
429              * (non-Javadoc)
430              * 
431              * @see java.lang.Runnable#run()
432              */
433             public void run() {
434                 // get the help UI extension from the registry
435                 IExtensionPoint point = Platform.getExtensionRegistry()
436                         .getExtensionPoint(HELP_SYSTEM_EXTENSION_ID);
437                 if (point == null) {
438                     // our extension point is missing (!) - act like there was
439                     // no help UI
440                     return;
441                 }
442                 IExtension[] extensions = point.getExtensions();
443                 if (extensions.length == 0) {
444                     // no help UI present
445                     return;
446                 }
447 
448                 IConfigurationElement elementToUse = null;
449                 if (desiredHelpSystemId == null) {
450                     elementToUse = getFirstElement(extensions);
451                 } else {
452                     elementToUse = findElement(desiredHelpSystemId, extensions);
453                 }
454 
455                 if (elementToUse != null) {
456                     ret[0] = initializePluggableHelpUI(elementToUse);
457                 }
458             }
459 
460             private IConfigurationElement findElement(
461                     String   desiredHelpSystemId, IExtension[] extensions) {
462                 for (int i = 0; i < extensions.length; i++) {
463                     IExtension extension = extensions[i];
464                     if (desiredHelpSystemId.equals(extension.getUniqueIdentifier())) {
465                         IConfigurationElement[] elements = extensions[0]
466                                 .getConfigurationElements();
467                         if (elements.length == 0) {
468                             // help UI present but mangled - act like there was
469                             // no help
470                             // UI
471                             return null;
472                         }
473                         return elements[0];
474                     }
475 
476                 }
477                 return null;
478             }
479 
480             private IConfigurationElement getFirstElement(
481                     IExtension[] extensions) {
482                 // There should only be one extension/config element so we just
483                 // take the first
484                 IConfigurationElement[] elements = extensions[0]
485                         .getConfigurationElements();
486                 if (elements.length == 0) {
487                     // help UI present but mangled - act like there was no help
488                     // UI
489                     return null;
490                 }
491                 return elements[0];
492             }
493 
494             private boolean initializePluggableHelpUI(
495                     IConfigurationElement element) {
496                 // Instantiate the help UI
497                 try {
498                     pluggableHelpUI = (AbstractHelpUI) WorkbenchPlugin
499                             .createExtension(element,
500                                     HELP_SYSTEM_CLASS_ATTRIBUTE);
501                     // start listening for removals
502                     PlatformUI.getWorkbench().getExtensionTracker()
503                             .registerHandler(handler, null);
504                     // register the new help UI for removal notification
505                     PlatformUI
506                             .getWorkbench()
507                             .getExtensionTracker()
508                             .registerObject(element.getDeclaringExtension(),
509                                     pluggableHelpUI, IExtensionTracker.REF_WEAK);
510                     return true;
511                 } catch (CoreException e) {
512                     WorkbenchPlugin.log(
513                             "Unable to instantiate help UI" + e.getStatus(), e);//$NON-NLS-1$
514                 }
515                 return false;
516             }
517 
518         });
519         return ret[0];
520     }
521 
522     /**
523      * Determines the location for the help popup shell given the widget which
524      * orginated the request for help.
525      * 
526      * @param display
527      *            the display where the help will appear
528      */
529     private static Point computePopUpLocation(Display display) {
530         Point point = display.getCursorLocation();
531         return new Point(point.x + 15, point.y);
532     }
533 
534     /**
535      * Returns the help listener which activates the help support system.
536      * 
537      * @return the help listener
538      */
539     private HelpListener getHelpListener() {
540         if (helpListener == null) {
541             helpListener = new WorkbenchHelpListener();
542         }
543         return helpListener;
544     }
545 
546     /**
547      * Returns the help support system for the platform, if available.
548      * 
549      * @return the help support system, or <code>null</code> if none
550      * @deprecated Use the static methods on this class and on
551      *             {@link org.eclipse.help.HelpSystem HelpSystem}instead of the
552      *             IHelp methods on the object returned by this method.
553      */
554     public IHelp getHelpSupport() {
555         AbstractHelpUI helpUI = getHelpUI();
556         if (helpUI != null && helpCompatibilityWrapper == null) {
557             // create instance only once, and only if needed
558             helpCompatibilityWrapper = new CompatibilityIHelpImplementation();
559         }
560         return helpCompatibilityWrapper;
561 
562     }
563 
564     /**
565      * Sets the given help contexts on the given action.
566      * <p>
567      * Use this method when the list of help contexts is known in advance. Help
568      * contexts can either supplied as a static list, or calculated with a
569      * context computer (but not both).
570      * </p>
571      * 
572      * @param action
573      *            the action on which to register the computer
574      * @param contexts
575      *            the contexts to use when F1 help is invoked; a mixed-type
576      *            array of context ids (type <code>String</code>) and/or help
577      *            contexts (type <code>IContext</code>)
578      * @deprecated use setHelp with a single context id parameter
579      */
580     public void setHelp(IAction action, final Object  [] contexts) {
581         for (int i = 0; i < contexts.length; i++) {
582             Assert.isTrue(contexts[i] instanceof String  
583                     || contexts[i] instanceof IContext);
584         }
585         action.setHelpListener(new HelpListener() {
586             public void helpRequested(HelpEvent event) {
587                 if (contexts != null && contexts.length > 0
588                         && getHelpUI() != null) {
589                     // determine the context
590                     IContext context = null;
591                     if (contexts[0] instanceof String  ) {
592                         context = HelpSystem.getContext((String  ) contexts[0]);
593                     } else if (contexts[0] instanceof IContext) {
594                         context = (IContext) contexts[0];
595                     }
596                     if (context != null) {
597                         Point point = computePopUpLocation(event.widget
598                                 .getDisplay());
599                         displayContext(context, point.x, point.y);
600                     }
601                 }
602             }
603         });
604     }
605 
606     /**
607      * Sets the given help context computer on the given action.
608      * <p>
609      * Use this method when the help contexts cannot be computed in advance.
610      * Help contexts can either supplied as a static list, or calculated with a
611      * context computer (but not both).
612      * </p>
613      * 
614      * @param action
615      *            the action on which to register the computer
616      * @param computer
617      *            the computer to determine the help contexts for the control
618      *            when F1 help is invoked
619      * @deprecated context computers are no longer supported, clients should
620      *             implement their own help listener
621      */
622     public void setHelp(IAction action, final IContextComputer computer) {
623         action.setHelpListener(new HelpListener() {
624             public void helpRequested(HelpEvent event) {
625                 Object  [] helpContexts = computer.computeContexts(event);
626                 if (helpContexts != null && helpContexts.length > 0
627                         && getHelpUI() != null) {
628                     // determine the context
629                     IContext context = null;
630                     if (helpContexts[0] instanceof String  ) {
631                         context = HelpSystem
632                                 .getContext((String  ) helpContexts[0]);
633                     } else if (helpContexts[0] instanceof IContext) {
634                         context = (IContext) helpContexts[0];
635                     }
636                     if (context != null) {
637                         Point point = computePopUpLocation(event.widget
638                                 .getDisplay());
639                         displayContext(context, point.x, point.y);
640                     }
641                 }
642             }
643         });
644     }
645 
646     /**
647      * Sets the given help contexts on the given control.
648      * <p>
649      * Use this method when the list of help contexts is known in advance. Help
650      * contexts can either supplied as a static list, or calculated with a
651      * context computer (but not both).
652      * </p>
653      * 
654      * @param control
655      *            the control on which to register the contexts
656      * @param contexts
657      *            the contexts to use when F1 help is invoked; a mixed-type
658      *            array of context ids (type <code>String</code>) and/or help
659      *            contexts (type <code>IContext</code>)
660      * @deprecated use setHelp with single context id parameter
661      */
662     public void setHelp(Control control, Object  [] contexts) {
663         for (int i = 0; i < contexts.length; i++) {
664             Assert.isTrue(contexts[i] instanceof String  
665                     || contexts[i] instanceof IContext);
666         }
667 
668         control.setData(HELP_KEY, contexts);
669         // ensure that the listener is only registered once
670         control.removeHelpListener(getHelpListener());
671         control.addHelpListener(getHelpListener());
672     }
673 
674     /**
675      * Sets the given help context computer on the given control.
676      * <p>
677      * Use this method when the help contexts cannot be computed in advance.
678      * Help contexts can either supplied as a static list, or calculated with a
679      * context computer (but not both).
680      * </p>
681      * 
682      * @param control
683      *            the control on which to register the computer
684      * @param computer
685      *            the computer to determine the help contexts for the control
686      *            when F1 help is invoked
687      * @deprecated context computers are no longer supported, clients should
688      *             implement their own help listener
689      */
690     public void setHelp(Control control, IContextComputer computer) {
691         control.setData(HELP_KEY, computer);
692         // ensure that the listener is only registered once
693         control.removeHelpListener(getHelpListener());
694         control.addHelpListener(getHelpListener());
695     }
696 
697     /**
698      * Sets the given help contexts on the given menu.
699      * <p>
700      * Use this method when the list of help contexts is known in advance. Help
701      * contexts can either supplied as a static list, or calculated with a
702      * context computer (but not both).
703      * </p>
704      * 
705      * @param menu
706      *            the menu on which to register the context
707      * @param contexts
708      *            the contexts to use when F1 help is invoked; a mixed-type
709      *            array of context ids (type <code>String</code>) and/or help
710      *            contexts (type <code>IContext</code>)
711      * @deprecated use setHelp with single context id parameter
712      */
713     public void setHelp(Menu menu, Object  [] contexts) {
714         for (int i = 0; i < contexts.length; i++) {
715             Assert.isTrue(contexts[i] instanceof String  
716                     || contexts[i] instanceof IContext);
717         }
718         menu.setData(HELP_KEY, contexts);
719         // ensure that the listener is only registered once
720         menu.removeHelpListener(getHelpListener());
721         menu.addHelpListener(getHelpListener());
722     }
723 
724     /**
725      * Sets the given help context computer on the given menu.
726      * <p>
727      * Use this method when the help contexts cannot be computed in advance.
728      * Help contexts can either supplied as a static list, or calculated with a
729      * context computer (but not both).
730      * </p>
731      * 
732      * @param menu
733      *            the menu on which to register the computer
734      * @param computer
735      *            the computer to determine the help contexts for the control
736      *            when F1 help is invoked
737      * @deprecated context computers are no longer supported, clients should
738      *             implement their own help listener
739      */
740     public void setHelp(Menu menu, IContextComputer computer) {
741         menu.setData(HELP_KEY, computer);
742         // ensure that the listener is only registered once
743         menu.removeHelpListener(getHelpListener());
744         menu.addHelpListener(getHelpListener());
745     }
746 
747     /**
748      * Sets the given help contexts on the given menu item.
749      * <p>
750      * Use this method when the list of help contexts is known in advance. Help
751      * contexts can either supplied as a static list, or calculated with a
752      * context computer (but not both).
753      * </p>
754      * 
755      * @param item
756      *            the menu item on which to register the context
757      * @param contexts
758      *            the contexts to use when F1 help is invoked; a mixed-type
759      *            array of context ids (type <code>String</code>) and/or help
760      *            contexts (type <code>IContext</code>)
761      * @deprecated use setHelp with single context id parameter
762      */
763     public void setHelp(MenuItem item, Object  [] contexts) {
764         for (int i = 0; i < contexts.length; i++) {
765             Assert.isTrue(contexts[i] instanceof String  
766                     || contexts[i] instanceof IContext);
767         }
768         item.setData(HELP_KEY, contexts);
769         // ensure that the listener is only registered once
770         item.removeHelpListener(getHelpListener());
771         item.addHelpListener(getHelpListener());
772     }
773 
774     /**
775      * Sets the given help context computer on the given menu item.
776      * <p>
777      * Use this method when the help contexts cannot be computed in advance.
778      * Help contexts can either supplied as a static list, or calculated with a
779      * context computer (but not both).
780      * </p>
781      * 
782      * @param item
783      *            the menu item on which to register the computer
784      * @param computer
785      *            the computer to determine the help contexts for the control
786      *            when F1 help is invoked
787      * @deprecated context computers are no longer supported, clients should
788      *             implement their own help listener
789      */
790     public void setHelp(MenuItem item, IContextComputer computer) {
791         item.setData(HELP_KEY, computer);
792         // ensure that the listener is only registered once
793         item.removeHelpListener(getHelpListener());
794         item.addHelpListener(getHelpListener());
795     }
796     
797     /**
798      * Creates a new help listener for the given command. This retrieves the
799      * help context ID from the command, and creates an appropriate listener
800      * based on this.
801      * 
802      * @param command
803      *            The command for which the listener should be created; must
804      *            not be <code>null</code>.
805      * @return A help listener; never <code>null</code>.
806      */
807     public HelpListener createHelpListener(ICommand command) {
808         // TODO Need a help ID from the context
809         // final String contextId = command.getHelpId();
810         final String   contextId = ""; //$NON-NLS-1$
811         return new HelpListener() {
812             public void helpRequested(HelpEvent event) {
813                 if (getHelpUI() != null) {
814                     IContext context = HelpSystem.getContext(contextId);
815                     if (context != null) {
816                         Point point = computePopUpLocation(event.widget
817                                 .getDisplay());
818                         displayContext(context, point.x, point.y);
819                     }
820                 }
821             }
822         };
823     }
824 
825     /*
826      * (non-Javadoc)
827      * 
828      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayHelp()
829      */
830     public void displayHelp() {
831         AbstractHelpUI helpUI = getHelpUI();
832         if (helpUI != null) {
833             helpUI.displayHelp();
834         }
835     }
836     
837     /*
838      * (non-Javadoc)
839      * 
840      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displaySearch()
841      */
842     public void displaySearch() {
843         AbstractHelpUI helpUI = getHelpUI();
844         if (helpUI != null) {
845             helpUI.displaySearch();
846         }
847     }
848     
849     /*
850      * (non-Javadoc)
851      * 
852      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displaySearch()
853      */
854     public void displayDynamicHelp() {
855         AbstractHelpUI helpUI = getHelpUI();
856         if (helpUI != null) {
857             helpUI.displayDynamicHelp();
858         }
859     }
860     
861     /*
862      * (non-Javadoc)
863      * 
864      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#search(java.lang.String)
865      */
866     public void search(String   expression) {
867         AbstractHelpUI helpUI = getHelpUI();
868         if (helpUI != null) {
869             helpUI.search(expression);
870         }
871     }
872     
873     /* (non-Javadoc)
874      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#resolve(java.lang.String, boolean)
875      */
876     public URL   resolve(String   href, boolean documentOnly) {
877         AbstractHelpUI helpUI = getHelpUI();
878         if (helpUI != null) {
879             return helpUI.resolve(href, documentOnly);
880         }
881         return null;
882     }
883     
884     /*
885      * (non-Javadoc)
886      * 
887      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayContext(org.eclipse.help.IContext,
888      *      int, int)
889      */
890     public void displayContext(IContext context, int x, int y) {
891         if (context == null) {
892             throw new IllegalArgumentException  ();
893         }
894         AbstractHelpUI helpUI = getHelpUI();
895         if (helpUI != null) {
896             helpUI.displayContext(context, x, y);
897         }
898     }
899 
900     /*
901      * (non-Javadoc)
902      * 
903      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayHelpResource(java.lang.String)
904      */
905     public void displayHelpResource(String   href) {
906         if (href == null) {
907             throw new IllegalArgumentException  ();
908         }
909         AbstractHelpUI helpUI = getHelpUI();
910         if (helpUI != null) {
911             helpUI.displayHelpResource(href);
912         }
913     }
914 
915     /*
916      * (non-Javadoc)
917      * 
918      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayHelp(java.lang.String)
919      */
920     public void displayHelp(String   contextId) {
921         IContext context = HelpSystem.getContext(contextId);
922         if (context != null) {
923             Point point = computePopUpLocation(Display.getCurrent());
924             displayContext(context, point.x, point.y);
925         }
926     }
927 
928     /*
929      * (non-Javadoc)
930      * 
931      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#displayHelp(org.eclipse.help.IContext)
932      */
933     public void displayHelp(IContext context) {
934         Point point = computePopUpLocation(Display.getCurrent());
935         AbstractHelpUI helpUI = getHelpUI();
936         if (helpUI != null) {
937             helpUI.displayContext(context, point.x, point.y);
938         }
939     }
940 
941     /*
942      * (non-Javadoc)
943      * 
944      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#isContextHelpDisplayed()
945      */
946     public boolean isContextHelpDisplayed() {
947         if (!isInitialized) {
948             return false;
949         }
950         AbstractHelpUI helpUI = getHelpUI();
951         return helpUI != null && helpUI.isContextHelpDisplayed();
952     }
953 
954     /*
955      * (non-Javadoc)
956      * 
957      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#setHelp(org.eclipse.jface.action.IAction,
958      *      java.lang.String)
959      */
960     public void setHelp(final IAction action, final String   contextId) {
961         action.setHelpListener(new HelpListener() {
962             public void helpRequested(HelpEvent event) {
963                 if (getHelpUI() != null) {
964                     IContext context = HelpSystem.getContext(contextId);
965                     if (context != null) {
966                         Point point = computePopUpLocation(event.widget
967                                 .getDisplay());
968                         displayContext(new ContextWithTitle(context, action.getText()), point.x, point.y);
969                     }
970                 }
971             }
972         });
973     }
974 
975     /*
976      * (non-Javadoc)
977      * 
978      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#setHelp(org.eclipse.swt.widgets.Control,
979      *      java.lang.String)
980      */
981     public void setHelp(Control control, String   contextId) {
982         control.setData(HELP_KEY, contextId);
983         // ensure that the listener is only registered once
984         control.removeHelpListener(getHelpListener());
985         control.addHelpListener(getHelpListener());
986     }
987 
988     /*
989      * (non-Javadoc)
990      * 
991      * @see org.eclipse.ui.help.IWorkbenchHelpSystem#setHelp(org.eclipse.swt.widgets.Menu,
992      *      java.lang.String)
993      */
994     public void setHelp(Menu menu, String   contextId) {
995         menu.setData(HELP_KEY, contextId);
996         // ensure that the listener is only registered once
997         menu.removeHelpListener(getHelpListener());
998         menu.addHelpListener(getHelpListener());
999     }
1000
1001    /*
1002     * (non-Javadoc)
1003     * 
1004     * @see org.eclipse.ui.help.IWorkbenchHelpSystem#setHelp(org.eclipse.swt.widgets.MenuItem,
1005     *      java.lang.String)
1006     */
1007    public void setHelp(MenuItem item, String   contextId) {
1008        item.setData(HELP_KEY, contextId);
1009        // ensure that the listener is only registered once
1010        item.removeHelpListener(getHelpListener());
1011        item.addHelpListener(getHelpListener());
1012    }
1013
1014    /* (non-Javadoc)
1015     * @see org.eclipse.ui.help.IWorkbenchHelpSystem#hasHelpUI()
1016     */
1017    public boolean hasHelpUI() {
1018        return getHelpUI() != null;
1019    }
1020}
1021
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags