Merge branch '3989' into 'master'

AF3 Help: Use an external browser in linux

See merge request !28

org.fortiss.af3.rcp.application/src/org/fortiss/af3/rcp/application/advisors/.ratings

-ApplicationActionBarAdvisor.java 881198ff05ab14110efef1673f0914725348442b GREEN
+ApplicationActionBarAdvisor.java 3fe306058f621c9939d86984199522e47b3c1cbd GREEN
 ApplicationWorkbenchAdvisor.java 5d1792809c752bedc08b6d9d993ecbf70b40982c GREEN
 ApplicationWorkbenchWindowAdvisor.java da5cb38300b384579532c678fbc9faa961c2ca6b GREEN

org.fortiss.af3.rcp.application/src/org/fortiss/af3/rcp/application/advisors/ApplicationActionBarAdvisor.java

@@ -16,12 +16,19 @@
 
 package org.fortiss.af3.rcp.application.advisors;
 
+import static org.apache.commons.lang3.SystemUtils.IS_OS_LINUX;
 import static org.eclipse.wb.swt.ResourceManager.getPluginImageDescriptor;
 import static org.fortiss.tooling.kernel.ui.util.TutorialUIServiceUtils.createTutorialMenu;
+import static org.fortiss.tooling.kernel.utils.LoggingUtils.showError;
 
+import java.io.IOException;
+import java.net.MalformedURLException;
+import java.net.URL;
 import java.util.Map;
 
 import org.eclipse.core.commands.IHandler;
+import org.eclipse.core.runtime.FileLocator;
+import org.eclipse.core.runtime.Platform;
 import org.eclipse.jface.action.IAction;
 import org.eclipse.jface.action.ICoolBarManager;
 import org.eclipse.jface.action.IMenuManager;
@@ -30,13 +37,18 @@ import org.eclipse.jface.action.Separator;
 import org.eclipse.jface.action.ToolBarManager;
 import org.eclipse.jface.resource.ImageDescriptor;
 import org.eclipse.ui.IWorkbenchActionConstants;
+import org.eclipse.ui.IWorkbenchCommandConstants;
 import org.eclipse.ui.IWorkbenchWindow;
+import org.eclipse.ui.PartInitException;
 import org.eclipse.ui.actions.ActionFactory;
 import org.eclipse.ui.actions.ActionFactory.IWorkbenchAction;
 import org.eclipse.ui.application.ActionBarAdvisor;
 import org.eclipse.ui.application.IActionBarConfigurer;
+import org.eclipse.ui.browser.IWebBrowser;
 import org.eclipse.ui.internal.actions.CommandAction;
+import org.eclipse.ui.internal.actions.HelpContentsAction;
 import org.eclipse.ui.internal.ide.IDEWorkbenchMessages;
+import org.fortiss.af3.rcp.help.AF3HelpActivator;
 
 /**
  * Action bar advisor for AF3 RCP.
@@ -319,13 +331,70 @@ public class ApplicationActionBarAdvisor extends ActionBarAdvisor {
 	 * Registers the "AF3 Help" action and attaches it to the corresponding button.
 	 */
 	private void registerHelpContentsAction(IWorkbenchWindow window) {
-		helpContentsAction = ActionFactory.HELP_CONTENTS.create(window);
+		if(IS_OS_LINUX) {
+			// Closing the help browser freezes the application.
+			// See https://af3-developer.fortiss.org/issues/3989
+			// Note: eclipse upstream issues exist with firefox:
+			// https://bugs.eclipse.org/bugs/show_bug.cgi?id=187332
+			helpContentsAction = createHelpInBrowserAction(window).create(window);
+		} else {
+			helpContentsAction = ActionFactory.HELP_CONTENTS.create(window);
+		}
 		helpContentsAction.setId("helpContentsAction");
 		helpContentsAction.setToolTipText("AF3 Help");
 		helpContentsAction.setText("AF3 &Help");
 		register(helpContentsAction);
 	}
 
+	/** Creates an action that launches the external browser to display the help pages. */
+	private ActionFactory createHelpInBrowserAction(IWorkbenchWindow window) {
+		if(window == null) {
+			throw new IllegalArgumentException();
+		}
+
+		// A non-anonymous class would just increase the code size.
+		@SuppressWarnings("restriction") IWorkbenchAction openExtHelpAction =
+				new HelpContentsAction(window) {
+					@Override
+					public void run() {
+
+						String errMsg = null;
+						try {
+							URL helpPluginURL = FileLocator.toFileURL(
+									Platform.getBundle(AF3HelpActivator.PLUGIN_ID).getEntry("/"));
+							URL helpIndexURL = new URL("file:/" + helpPluginURL.getPath() +
+									"html/getting_started.html");
+
+							final IWebBrowser browser = window.getWorkbench().getBrowserSupport()
+									.createBrowser("dummyID");
+							browser.openURL(helpIndexURL);
+						} catch(PartInitException e) {
+							errMsg = "Could not open browser.\n\n" + e.getLocalizedMessage();
+						} catch(MalformedURLException e) {
+							errMsg = "URL to user documentation is not correct.\n\n" +
+									e.getLocalizedMessage();
+						} catch(IOException e) {
+							errMsg = "I/O error: Could not access the user documentation.\n\n" +
+									e.getLocalizedMessage();
+						} finally {
+							if(errMsg != null) {
+								showError(errMsg);
+							}
+						}
+					}
+				};
+
+		return new ActionFactory("helpContents", //$NON-NLS-1$
+				IWorkbenchCommandConstants.HELP_HELP_CONTENTS) {
+			@Override
+			public IWorkbenchAction create(IWorkbenchWindow window) {
+				IWorkbenchAction action = openExtHelpAction;
+				action.setId(getId());
+				return action;
+			}
+		};
+	}
+
 	/**
 	 * Registers the "New AF3 Project" action and attaches it to the corresponding button.
 	 */