bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/browser/IWorkbenchBrowserSupport.java - platform/eclipse.platform.ui - Git at Google

 /*******************************************************************************
  * Copyright (c) 2005, 2008 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  *     IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.browser;

 import org.eclipse.ui.PartInitException;

 /**
  * Web browser support. This class allows you to open URLs using internal or
  * external Web browsers. Implementers may provide varying levels of support.
  * The most rudimentary support that must be provided is to open URLs in an
  * external web browser window. Everything else is a hint that browser support
  * implementation may choose to honor but is not required (although a good
  * implementation should aspire to support all the styles if possible on the
  * given platform).
  * <p>
  * The support has a two-phase approach to opening URLs. A browser instance is
  * created first, then <code>openURL</code> is called on it. This provides for
  * browser instance reuse for as long as needed. The step of creating the
  * browser instance encourages reuse itself by not creating new instances of
  * browsers if one with the same id is already open. It also makes it possible
  * to reuse browser instances restored after workbench is restarted.
  * <p>
  * The simplest way to open a URL is:
  *
  * <pre>
  * IWorkbenchSupport.createBrowser(&quot;myId&quot;).openURL(url);
  * </pre>
  *
  * <p>
  * The call above will show the provided URL by reusing the browser instance
  * with the matching id, or creating a new one if one does not exist already.
  * <p>
  * When more advanced control over the behavior of a browser instance is
  * required, it is recommended to create the instance first, then reuse it as
  * needed.
  * <p>
  * This interface is not intended to be implemented by clients.
  *
  * @see IWebBrowser
  * @since 3.1
  * @noimplement This interface is not intended to be implemented by clients.
  */

 public interface IWorkbenchBrowserSupport {
 	/**
 	 * Style parameter (value 1&lt;&lt;1) indicating that the address combo and
 	 * 'Go' button will created for the browser. This style is ignored if the
 	 * support is forced to open the browser as external.
 	 */
 	int LOCATION_BAR = 1 << 1;

 	/**
 	 * Style parameter (value 1&lt;&lt;2) indicating that the navigation bar for
 	 * navigating web pages will be created for the web browser. This style is
 	 * ignored if the support is forced to open the browser as external.
 	 */
 	int NAVIGATION_BAR = 1 << 2;

 	/**
 	 * Style constant (value 1&lt;&lt;3) indicating that status will be tracked
 	 * and shown for the browser (page loading progress, text messages etc.).
 	 */
 	int STATUS = 1 << 3;

 	/**
 	 * Style constant (value 1&lt;&lt;4) indicating that the internal web
 	 * browser will reopen after restarting the workbench (if used). In
 	 * addition, the URLs will appear in the MRU list.
 	 */
 	int PERSISTENT = 1 << 4;

 	/**
 	 * Style constant (value 1&lt;&lt;5) indicating that the internal web
 	 * browser will be hosted in a workbench editor area. This is just a hint -
 	 * implementers of the browser support may not honor it.
 	 */
 	int AS_EDITOR = 1 << 5;

 	/**
 	 * Style constant (value 1&lt;&lt;6) indicating that the internal web
 	 * browser will be hosted in a workbench view. This is just a hint -
 	 * implementers of the browser support may not honor it.
 	 */
 	int AS_VIEW = 1 << 6;

 	/**
 	 * Style constant (value 1&lt;&lt;7) indicating that the external web
 	 * browser must be used even if the implementation supports internal
 	 * browsers and the user didn't set the preference to external browsers.
 	 */
 	int AS_EXTERNAL = 1 << 7;

 	/**
 	 * Creates the new web browser instance. If the user has chosen to use the
 	 * internal Web browser, the given style bits (see class header for values)
 	 * will be used to open the browser.
 	 * <p>
 	 * The method will reuse an existing browser instance if the same
 	 * <code>browserId</code> value is passed to it. A persisted browser
 	 * instance restored upon startup can be accessed this way. If
 	 * <code>null</code> is passed as a browserId, a unique id will be
 	 * generated each time method is called.
 	 * <p>
 	 * If the user has chosen not to use the internal browser or it is not
 	 * available on the current platform, an external browser will be used and
 	 * all style parameters will be ignored.
 	 * </p>
 	 *
 	 * @param style
 	 *            the style display constants. Style constants should be
 	 *            bitwise-ORed together.
 	 * @param browserId
 	 *            if an instance of a browser with the same id is already
 	 *            opened, it will be returned instead of creating a new one.
 	 *            Passing <code>null</code> will create a new instance with a
 	 *            generated id every time.
 	 * @param name
 	 *            a name used for the presentation of the internal browser
 	 * @param tooltip
 	 *            a tooltip used for the presentation of the internal browser
 	 * @return the browser instance that can be used to open the URL. Clients
 	 *         intending to reuse the instance for all the URLs should cache the
 	 *         instance and call IWebBrowser#openURL() on it. Clients are
 	 *         responsible for closing the browser instance when not needed.
 	 * @exception PartInitException
 	 *                if the operation failed for some reason
 	 */
 	IWebBrowser createBrowser(int style, String browserId, String name,
 			String tooltip) throws PartInitException;

 	/**
 	 * Creates the new web browser instance. This is a simplified method that
 	 * creates the instance using default values for style, name and tooltip
 	 * parameters. The method can be used to quickly open the URL by calling
 	 * <code>createBrowser(id).openURL(url)</code>.
 	 * <p>
 	 *
 	 * @param browserId
 	 *            if an instance of a browser with the same id is already
 	 *            opened, it will be returned instead of creating a new one.
 	 *            Passing <code>null</code> will create a new instance with a
 	 *            generated id every time.
 	 * @return the browser instance that can be used to open the URL. Clients
 	 *         intending to reuse the instance for all the URLs should cache the
 	 *         instance and call IWebBrowser#openURL() on it. Clients are
 	 *         responsible for closing the browser instance when not needed.
 	 * @exception PartInitException
 	 *                if the operation failed for some reason
 	 */
 	IWebBrowser createBrowser(String browserId) throws PartInitException;

 	/**
 	 * Returns a shared instance of the external web browser. Clients can use it
 	 * to share one external browser. The external browser that will be used is
 	 * subject to browser support implementation. A suggested implementation is
 	 * to use the operating system's default browser. Implementations that offer
 	 * users a choice of the web browser should honour the users choice of
 	 * external browser, with the initial selection being the system default
 	 * browser.
 	 *
 	 * @return the shared instance of the external browser
 	 * @exception PartInitException
 	 *                if the operation failed for some reason
 	 */
 	IWebBrowser getExternalBrowser() throws PartInitException;

 	/**
 	 * Tests whether web browser as an SWT widget can be created in this
 	 * workbench instance. If this method returns <code>false</code>,
 	 * <code>createBrowser</code> would ignore browser styles
 	 * <code>AS_EDITOR</code> and <code>AS_VIEW</code> and always create an
 	 * external browser.
 	 *
 	 * @return <code>true</code> if internal web browser can be created on
 	 *         this platform, <code>false</code> otherwise.
 	 */
 	boolean isInternalWebBrowserAvailable();
 }
	/*******************************************************************************
	* Copyright (c) 2005, 2008 IBM Corporation and others.
	* All rights reserved. This program and the accompanying materials
	* are made available under the terms of the Eclipse Public License v1.0
	* which accompanies this distribution, and is available at
	* http://www.eclipse.org/legal/epl-v10.html
	*
	* Contributors:
	* IBM Corporation - initial API and implementation
	*******************************************************************************/
	package org.eclipse.ui.browser;

	import org.eclipse.ui.PartInitException;

	/**
	* Web browser support. This class allows you to open URLs using internal or
	* external Web browsers. Implementers may provide varying levels of support.
	* The most rudimentary support that must be provided is to open URLs in an
	* external web browser window. Everything else is a hint that browser support
	* implementation may choose to honor but is not required (although a good
	* implementation should aspire to support all the styles if possible on the
	* given platform).
	* <p>
	* The support has a two-phase approach to opening URLs. A browser instance is
	* created first, then <code>openURL</code> is called on it. This provides for
	* browser instance reuse for as long as needed. The step of creating the
	* browser instance encourages reuse itself by not creating new instances of
	* browsers if one with the same id is already open. It also makes it possible
	* to reuse browser instances restored after workbench is restarted.
	* <p>
	* The simplest way to open a URL is:
	*
	* <pre>
	* IWorkbenchSupport.createBrowser("myId").openURL(url);
	* </pre>
	*
	* <p>
	* The call above will show the provided URL by reusing the browser instance
	* with the matching id, or creating a new one if one does not exist already.
	* <p>
	* When more advanced control over the behavior of a browser instance is
	* required, it is recommended to create the instance first, then reuse it as
	* needed.
	* <p>
	* This interface is not intended to be implemented by clients.
	*
	* @see IWebBrowser
	* @since 3.1
	* @noimplement This interface is not intended to be implemented by clients.
	*/

	public interface IWorkbenchBrowserSupport {
	/**
	* Style parameter (value 1<<1) indicating that the address combo and
	* 'Go' button will created for the browser. This style is ignored if the
	* support is forced to open the browser as external.
	*/
	int LOCATION_BAR = 1 << 1;

	/**
	* Style parameter (value 1<<2) indicating that the navigation bar for
	* navigating web pages will be created for the web browser. This style is
	* ignored if the support is forced to open the browser as external.
	*/
	int NAVIGATION_BAR = 1 << 2;

	/**
	* Style constant (value 1<<3) indicating that status will be tracked
	* and shown for the browser (page loading progress, text messages etc.).
	*/
	int STATUS = 1 << 3;

	/**
	* Style constant (value 1<<4) indicating that the internal web
	* browser will reopen after restarting the workbench (if used). In
	* addition, the URLs will appear in the MRU list.
	*/
	int PERSISTENT = 1 << 4;

	/**
	* Style constant (value 1<<5) indicating that the internal web
	* browser will be hosted in a workbench editor area. This is just a hint -
	* implementers of the browser support may not honor it.
	*/
	int AS_EDITOR = 1 << 5;

	/**
	* Style constant (value 1<<6) indicating that the internal web
	* browser will be hosted in a workbench view. This is just a hint -
	* implementers of the browser support may not honor it.
	*/
	int AS_VIEW = 1 << 6;

	/**
	* Style constant (value 1<<7) indicating that the external web
	* browser must be used even if the implementation supports internal
	* browsers and the user didn't set the preference to external browsers.
	*/
	int AS_EXTERNAL = 1 << 7;

	/**
	* Creates the new web browser instance. If the user has chosen to use the
	* internal Web browser, the given style bits (see class header for values)
	* will be used to open the browser.
	* <p>
	* The method will reuse an existing browser instance if the same
	* <code>browserId</code> value is passed to it. A persisted browser
	* instance restored upon startup can be accessed this way. If
	* <code>null</code> is passed as a browserId, a unique id will be
	* generated each time method is called.
	* <p>
	* If the user has chosen not to use the internal browser or it is not
	* available on the current platform, an external browser will be used and
	* all style parameters will be ignored.
	* </p>
	*
	* @param style
	* the style display constants. Style constants should be
	* bitwise-ORed together.
	* @param browserId
	* if an instance of a browser with the same id is already
	* opened, it will be returned instead of creating a new one.
	* Passing <code>null</code> will create a new instance with a
	* generated id every time.
	* @param name
	* a name used for the presentation of the internal browser
	* @param tooltip
	* a tooltip used for the presentation of the internal browser
	* @return the browser instance that can be used to open the URL. Clients
	* intending to reuse the instance for all the URLs should cache the
	* instance and call IWebBrowser#openURL() on it. Clients are
	* responsible for closing the browser instance when not needed.
	* @exception PartInitException
	* if the operation failed for some reason
	*/
	IWebBrowser createBrowser(int style, String browserId, String name,
	String tooltip) throws PartInitException;

	/**
	* Creates the new web browser instance. This is a simplified method that
	* creates the instance using default values for style, name and tooltip
	* parameters. The method can be used to quickly open the URL by calling
	* <code>createBrowser(id).openURL(url)</code>.
	* <p>
	*
	* @param browserId
	* if an instance of a browser with the same id is already
	* opened, it will be returned instead of creating a new one.
	* Passing <code>null</code> will create a new instance with a
	* generated id every time.
	* @return the browser instance that can be used to open the URL. Clients
	* intending to reuse the instance for all the URLs should cache the
	* instance and call IWebBrowser#openURL() on it. Clients are
	* responsible for closing the browser instance when not needed.
	* @exception PartInitException
	* if the operation failed for some reason
	*/
	IWebBrowser createBrowser(String browserId) throws PartInitException;

	/**
	* Returns a shared instance of the external web browser. Clients can use it
	* to share one external browser. The external browser that will be used is
	* subject to browser support implementation. A suggested implementation is
	* to use the operating system's default browser. Implementations that offer
	* users a choice of the web browser should honour the users choice of
	* external browser, with the initial selection being the system default
	* browser.
	*
	* @return the shared instance of the external browser
	* @exception PartInitException
	* if the operation failed for some reason
	*/
	IWebBrowser getExternalBrowser() throws PartInitException;

	/**
	* Tests whether web browser as an SWT widget can be created in this
	* workbench instance. If this method returns <code>false</code>,
	* <code>createBrowser</code> would ignore browser styles
	* <code>AS_EDITOR</code> and <code>AS_VIEW</code> and always create an
	* external browser.
	*
	* @return <code>true</code> if internal web browser can be created on
	* this platform, <code>false</code> otherwise.
	*/
	boolean isInternalWebBrowserAvailable();
	}