DefaultHelpUI


1   /***************************************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others. All rights reserved. This program and the
3    * accompanying materials are made available under the terms of the Eclipse Public License v1.0
4    * which accompanies this distribution, and is available at
5    * http://www.eclipse.org/legal/epl-v10.html
6    * 
7    * Contributors: IBM Corporation - initial API and implementation Sebastian Davids <sdavids@gmx.de> -
8    * bug 93374
9    **************************************************************************************************/
10  package org.eclipse.help.ui.internal;
11  
12  import java.net.URL  ;
13  
14  import org.eclipse.core.runtime.Platform;
15  import org.eclipse.core.runtime.Preferences;
16  import org.eclipse.help.IContext;
17  import org.eclipse.help.IHelpResource;
18  import org.eclipse.help.browser.IBrowser;
19  import org.eclipse.help.internal.base.BaseHelpSystem;
20  import org.eclipse.help.internal.base.HelpBasePlugin;
21  import org.eclipse.help.internal.base.IHelpBaseConstants;
22  import org.eclipse.help.ui.internal.util.ErrorUtil;
23  import org.eclipse.help.ui.internal.views.ContextHelpPart;
24  import org.eclipse.help.ui.internal.views.HelpTray;
25  import org.eclipse.help.ui.internal.views.HelpView;
26  import org.eclipse.help.ui.internal.views.ReusableHelpPart;
27  import org.eclipse.jface.dialogs.DialogTray;
28  import org.eclipse.jface.dialogs.MessageDialog;
29  import org.eclipse.jface.dialogs.TrayDialog;
30  import org.eclipse.osgi.service.environment.Constants;
31  import org.eclipse.swt.SWT;
32  import org.eclipse.swt.widgets.Control;
33  import org.eclipse.swt.widgets.Display;
34  import org.eclipse.swt.widgets.Shell;
35  import org.eclipse.ui.IViewPart;
36  import org.eclipse.ui.IWorkbenchPage;
37  import org.eclipse.ui.IWorkbenchPart;
38  import org.eclipse.ui.IWorkbenchWindow;
39  import org.eclipse.ui.PartInitException;
40  import org.eclipse.ui.PlatformUI;
41  import org.eclipse.ui.browser.IWebBrowser;
42  import org.eclipse.ui.browser.IWorkbenchBrowserSupport;
43  import org.eclipse.ui.help.AbstractHelpUI;
44  import org.eclipse.ui.intro.IIntroManager;
45  import org.eclipse.ui.intro.IIntroPart;
46  
47  /**
48   * This class is an implementation of the Help UI. In is registered into the helpSupport extension
49   * point, and is responsible for handling requests to display help. The methods on this class
50   * interact with the actual UI component handling the display.
51   * <p>
52   * Most methods delegate most work to HelpDisplay class; only the UI specific ones implemented in
53   * place.
54   * </p>
55   */
56  public class DefaultHelpUI extends AbstractHelpUI {
57  
58      private ContextHelpDialog f1Dialog = null;
59      private static DefaultHelpUI instance;
60  
61      private static final String   HELP_VIEW_ID = "org.eclipse.help.ui.HelpView"; //$NON-NLS-1$
62  
63      class ExternalWorkbenchBrowser implements IBrowser {
64  
65          public ExternalWorkbenchBrowser() {
66          }
67  
68          private IWebBrowser getExternalBrowser() throws PartInitException {
69              IWorkbenchBrowserSupport support = PlatformUI.getWorkbench().getBrowserSupport();
70              return support.getExternalBrowser();
71          }
72  
73          public void close() {
74          }
75  
76          public boolean isCloseSupported() {
77              return false;
78          }
79  
80          public void displayURL(String   url) throws Exception   {
81              try {
82                  IWebBrowser browser = getExternalBrowser();
83                  if (browser != null) {
84                      browser.openURL(new URL  (url));
85                  }
86              } catch (PartInitException pie) {
87                  ErrorUtil.displayErrorDialog(pie.getLocalizedMessage());
88              }
89          }
90  
91          public boolean isSetLocationSupported() {
92              return false;
93          }
94  
95          public boolean isSetSizeSupported() {
96              return false;
97          }
98  
99          public void setLocation(int x, int y) {
100         }
101 
102         public void setSize(int width, int height) {
103         }
104     }
105 
106     /**
107      * Constructor.
108      */
109     public DefaultHelpUI() {
110         super();
111         instance = this;
112         // register external browser. This will cause the help system
113         // to use workbench external browser instead of its own.
114         BaseHelpSystem.getInstance().setBrowserInstance(new ExternalWorkbenchBrowser());
115     }
116 
117     static DefaultHelpUI getInstance() {
118         return instance;
119     }
120 
121     /**
122      * Displays help.
123      */
124     public void displayHelp() {
125         BaseHelpSystem.getHelpDisplay().displayHelp(useExternalBrowser(null));
126     }
127 
128     /**
129      * Displays search.
130      */
131     public void displaySearch() {
132         search(null);
133     }
134 
135     /**
136      * Displays dynamic help.
137      */
138     public void displayDynamicHelp() {
139         IWorkbenchWindow window = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
140         Shell activeShell = getActiveShell();
141         if (window != null && isActiveShell(activeShell, window)) {
142             IIntroManager introMng = PlatformUI.getWorkbench().getIntroManager();
143             IIntroPart intro = introMng.getIntro();
144             if (intro != null && !introMng.isIntroStandby(intro))
145                 introMng.setIntroStandby(intro, true);
146 
147             IWorkbenchPage page = window.getActivePage();
148             Control c = activeShell.getDisplay().getFocusControl();
149             if (page != null) {
150                 IWorkbenchPart activePart = page.getActivePart();
151                 try {
152                     IViewPart part = page.showView(HELP_VIEW_ID, null, IWorkbenchPage.VIEW_VISIBLE);
153                     if (part != null) {
154                         HelpView view = (HelpView) part;
155                         view.showDynamicHelp(activePart, c);
156                     }
157                 } catch (PartInitException e) {
158                 }
159             } else {
160                 // check the dialog
161                 if (activeShell != null) {
162                     Object   data = activeShell.getData();
163                     if (data instanceof TrayDialog) {
164                         IContext context = ContextHelpPart.findHelpContext(c);
165                         displayContextAsHelpTray(activeShell, context);
166                         return;
167                     }
168                 }
169                 warnNoOpenPerspective(window);
170             }
171         }
172     }
173 
174     /**
175      * Starts the search.
176      */
177 
178     public void search(final String   expression) {
179         IWorkbenchWindow window = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
180         Shell activeShell = getActiveShell();
181         if (window != null && isActiveShell(activeShell, window)) {
182             IIntroManager introMng = PlatformUI.getWorkbench().getIntroManager();
183             IIntroPart intro = introMng.getIntro();
184             if (intro != null && !introMng.isIntroStandby(intro))
185                 introMng.setIntroStandby(intro, true);
186 
187             IWorkbenchPage page = window.getActivePage();
188             if (page != null) {
189                 try {
190                     IViewPart part = page.showView(HELP_VIEW_ID);
191                     if (part != null) {
192                         HelpView view = (HelpView) part;
193                         view.startSearch(expression);
194                     }
195                 } catch (PartInitException e) {
196                 }
197             } else {
198                 // check the dialog
199                 if (activeShell != null) {
200                     Object   data = activeShell.getData();
201                     if (data instanceof TrayDialog) {
202                         displayContextAsHelpTray(activeShell, null);
203                         return;
204                     }
205                     else {
206                         // tried to summon help from a non-tray dialog
207                         // not supported
208                         return;
209                     }
210                 }
211                 warnNoOpenPerspective(window);
212             }
213         }
214     }
215 
216     private void warnNoOpenPerspective(IWorkbenchWindow window) {
217         MessageDialog.openInformation(window.getShell(), Messages.DefaultHelpUI_wtitle,
218                 Messages.DefaultHelpUI_noPerspMessage);
219     }
220 
221     /**
222      * Displays a help resource specified as a url.
223      * <ul>
224      * <li>a URL in a format that can be returned by
225      * {@link  org.eclipse.help.IHelpResource#getHref() IHelpResource.getHref()}
226      * <li>a URL query in the format format <em>key=value&amp;key=value ...</em> The valid keys
227      * are: "tab", "toc", "topic", "contextId". For example,
228      * <em>toc="/myplugin/mytoc.xml"&amp;topic="/myplugin/references/myclass.html"</em> is valid.
229      * </ul>
230      */
231     public void displayHelpResource(String   href) {
232         BaseHelpSystem.getHelpDisplay().displayHelpResource(href, useExternalBrowser(href));
233     }
234 
235     /**
236      * Displays context-sensitive help for specified context
237      * 
238      * @param context
239      *            the context to display
240      * @param x
241      *            int positioning information
242      * @param y
243      *            int positioning information
244      */
245     public void displayContext(IContext context, int x, int y) {
246         displayContext(context, x, y, false);
247     }
248 
249     void displayContext(IContext context, int x, int y, boolean noInfopop) {
250         if (context == null)
251             return;
252         Preferences pref = HelpBasePlugin.getDefault().getPluginPreferences();
253         boolean winfopop = pref.getBoolean(IHelpBaseConstants.P_KEY_WINDOW_INFOPOP);
254         boolean dinfopop = pref.getBoolean(IHelpBaseConstants.P_KEY_DIALOG_INFOPOP);
255 
256         IWorkbenchWindow window = PlatformUI.getWorkbench().getActiveWorkbenchWindow();
257         Shell activeShell = getActiveShell();
258         if (window != null && isActiveShell(activeShell, window)) {
259             IWorkbenchPage page = window.getActivePage();
260             if (page != null) {
261                 if (!noInfopop && winfopop) {
262                     displayContextAsInfopop(context, x, y);
263                     return;
264                 }
265                 try {
266                     /*
267                      * If the context help has no description text and exactly one
268                      * topic, go straight to the topic and skip context help.
269                      */
270                     IHelpResource[] topics = context.getRelatedTopics();
271                     boolean openInEditor = pref.getBoolean(IHelpBaseConstants.P_KEY_OPEN_IN_EDITOR);
272                     if (context.getText() == null && topics.length == 1 && openInEditor) {
273                         showInWorkbenchBrowser(topics[0].getHref(), true);
274                     }
275                     else {
276                         IWorkbenchPart activePart = page.getActivePart();
277                         Control c = window.getShell().getDisplay().getFocusControl();
278                         IViewPart part = page.showView(HELP_VIEW_ID, null, IWorkbenchPage.VIEW_VISIBLE);
279                         if (part != null) {
280                             HelpView view = (HelpView) part;
281                             view.displayContext(context, activePart, c);
282                         }
283                     }
284                     return;
285                 } catch (PartInitException e) {
286                     // ignore the exception and let
287                     // the code default to the context
288                     // help dialog
289                 }
290             }
291         }
292         // check the dialog
293         if (HelpTray.isAppropriateFor(activeShell) && (!dinfopop || noInfopop)) {
294             displayContextAsHelpTray(activeShell, context);
295             return;
296         }
297         // we are here either as a fallback or because of the user preferences
298         displayContextAsInfopop(context, x, y);
299     }
300 
301     /*
302      * (non-Javadoc)
303      * 
304      * @see org.eclipse.ui.help.AbstractHelpUI#resolve(java.lang.String, boolean)
305      */
306     public URL   resolve(String   href, boolean documentOnly) {
307         return BaseHelpSystem.resolve(href, documentOnly);
308     }
309 
310     public String   unresolve(URL   url) {
311         return BaseHelpSystem.unresolve(url);
312     }
313 
314     /*
315      * (non-Javadoc)
316      * 
317      * @see org.eclipse.ui.help.AbstractHelpUI#resolve(java.lang.String, boolean)
318      */
319     private static Shell getActiveShell() {
320         Display display = PlatformUI.getWorkbench().getDisplay();
321         return display.getActiveShell();
322     }
323 
324     static boolean isActiveShell(Shell activeShell, IWorkbenchWindow window) {
325         // Test if the active shell belongs to this window
326         return activeShell != null && activeShell.equals(window.getShell());
327     }
328 
329     private void displayContextAsInfopop(IContext context, int x, int y) {
330         if (f1Dialog != null) {
331             f1Dialog.close();
332         }
333         if (context != null) {
334             /*
335              * If the context help has no description text and exactly one
336              * topic, go straight to the topic and skip context help.
337              */
338             IHelpResource[] topics = context.getRelatedTopics();
339             if (context.getText() == null && topics.length == 1) {
340                 try {
341                     PlatformUI.getWorkbench().getHelpSystem().displayHelpResource(topics[0].getHref());
342                 }
343                 catch (Exception   e) {
344                     // should never happen
345                 }
346             }
347             else {
348                 f1Dialog = new ContextHelpDialog(context, x, y);
349                 f1Dialog.open();
350             }
351         }
352     }
353 
354     private void displayContextAsHelpTray(Shell activeShell, IContext context) {
355         Control controlInFocus = activeShell.getDisplay().getFocusControl();
356         TrayDialog dialog = (TrayDialog)activeShell.getData();
357         
358         DialogTray tray = dialog.getTray();
359         if (tray == null) {
360             tray = new HelpTray();
361             dialog.openTray(tray);
362         }
363         if (tray instanceof HelpTray) {
364             ReusableHelpPart helpPart = ((HelpTray)tray).getHelpPart();
365             if (context != null) {
366                 IHelpResource[] topics = context.getRelatedTopics();
367                 if (context.getText() == null && topics.length == 1) {
368                     helpPart.showURL(topics[0].getHref());
369                     helpPart.update(context, null, controlInFocus);
370                 }
371                 else {
372                     helpPart.showPage(IHelpUIConstants.HV_CONTEXT_HELP_PAGE);
373                     helpPart.update(context, null, controlInFocus);
374                 }
375             }
376             else {
377                 helpPart.showPage(IHelpUIConstants.HV_FSEARCH_PAGE, true);
378             }
379         }
380         else {
381             // someone else was occupying the tray; not supported
382         }
383     }
384 
385     /**
386      * Returns <code>true</code> if the context-sensitive help window is currently being
387      * displayed, <code>false</code> if not.
388      */
389     public boolean isContextHelpDisplayed() {
390         if (f1Dialog == null) {
391             return false;
392         }
393         return f1Dialog.isShowing();
394     }
395 
396     private boolean useExternalBrowser(String   url) {
397         // On non Windows platforms, use external when modal window is displayed
398         if (!Constants.OS_WIN32.equalsIgnoreCase(Platform.getOS())) {
399             Display display = Display.getCurrent();
400             if (display != null) {
401                 if (insideModalParent(display))
402                     return true;
403             }
404         }
405 
406         // Use external when no help frames are to be displayed, otherwise no
407         // navigation buttons.
408         if (url != null) {
409             if (url.indexOf("?noframes=true") > 0 //$NON-NLS-1$
410                     || url.indexOf("&noframes=true") > 0) { //$NON-NLS-1$
411                 return true;
412             }
413         }
414         return false;
415     }
416 
417     private boolean insideModalParent(Display display) {
418         return isDisplayModal(display.getActiveShell());
419     }
420 
421     public static boolean isDisplayModal(Shell activeShell) {
422         while (activeShell != null) {
423             if ((activeShell.getStyle() & (SWT.APPLICATION_MODAL | SWT.PRIMARY_MODAL | SWT.SYSTEM_MODAL)) > 0)
424                 return true;
425             activeShell = (Shell) activeShell.getParent();
426         }
427         return false;
428     }
429     
430     public static boolean showInWorkbenchBrowser(String   url, boolean onlyInternal) {
431         IWorkbenchBrowserSupport support = PlatformUI.getWorkbench().getBrowserSupport();
432         if (!onlyInternal || support.isInternalWebBrowserAvailable()) {
433             try {
434                 IWebBrowser browser = support
435                         .createBrowser(
436                                 IWorkbenchBrowserSupport.AS_EDITOR
437                                         | IWorkbenchBrowserSupport.NAVIGATION_BAR
438                                         | IWorkbenchBrowserSupport.STATUS,
439                                 "org.eclipse.help.ui", Messages.ReusableHelpPart_internalBrowserTitle, url); //$NON-NLS-1$
440                 browser.openURL(BaseHelpSystem.resolve(url, "/help/nftopic")); //$NON-NLS-1$
441                 return true;
442             } catch (PartInitException e) {
443                 HelpUIPlugin.logError(
444                         Messages.ReusableHelpPart_internalWebBrowserError, e);
445             }
446         }
447         return false;
448     }
449 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags