All Known Implementing Classes:: AbstractWorkbenchBrowserSupport

public interface IWorkbenchBrowserSupport

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).

The support has a two-phase approach to opening URLs. A browser instance is created first, then openURL 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.

The simplest way to open a URL is:

 IWorkbenchSupport.createBrowser("myId").openURL(url);

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.

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.

This interface is not intended to be implemented by clients.

Since:

3.1

See Also:

IWebBrowser

Restriction:

This interface is not intended to be implemented by clients.

Restriction:

This interface is not intended to be extended by clients.

Field Summary

Fields

Modifier and Type

Field

Description

static final int

AS_EDITOR

Style constant (value 1<<5) indicating that the internal web browser will be hosted in a workbench editor area.

static final int

AS_EXTERNAL

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.

static final int

AS_VIEW

Style constant (value 1<<6) indicating that the internal web browser will be hosted in a workbench view.

static final int

LOCATION_BAR

Style parameter (value 1<<1) indicating that the address combo and 'Go' button will created for the browser.

static final int

NAVIGATION_BAR

Style parameter (value 1<<2) indicating that the navigation bar for navigating web pages will be created for the web browser.

static final int

PERSISTENT

Style constant (value 1<<4) indicating that the internal web browser will reopen after restarting the workbench (if used).

static final int

STATUS

Style constant (value 1<<3) indicating that status will be tracked and shown for the browser (page loading progress, text messages etc.).
Method Summary

Modifier and Type

Method

Description

IWebBrowser

createBrowser(int style, String browserId, String name, String tooltip)

Creates the new web browser instance.

IWebBrowser

createBrowser(String browserId)

Creates the new web browser instance.

IWebBrowser

getExternalBrowser()

Returns a shared instance of the external web browser.

boolean

isInternalWebBrowserAvailable()

Tests whether web browser as an SWT widget can be created in this workbench instance.

Field Details
- LOCATION_BAR
  
  static final int LOCATION_BAR
  
  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.
  See Also:
  
  Constant Field Values
- NAVIGATION_BAR
  
  static final int NAVIGATION_BAR
  
  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.
  See Also:
  
  Constant Field Values
- STATUS
  
  static final int STATUS
  
  Style constant (value 1<<3) indicating that status will be tracked and shown for the browser (page loading progress, text messages etc.).
  See Also:
  
  Constant Field Values
- PERSISTENT
  
  static final int PERSISTENT
  
  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.
  See Also:
  
  Constant Field Values
- AS_EDITOR
  
  static final int AS_EDITOR
  
  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.
  See Also:
  
  Constant Field Values
- AS_VIEW
  
  static final int AS_VIEW
  
  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.
  See Also:
  
  Constant Field Values
- AS_EXTERNAL
  
  static final int AS_EXTERNAL
  
  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.
  See Also:
  
  Constant Field Values
Method Details
- createBrowser
  
  IWebBrowser createBrowser(int style, String browserId, String name, String tooltip) throws PartInitException
  
  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.
  The method will reuse an existing browser instance if the same browserId value is passed to it. A persisted browser instance restored upon startup can be accessed this way. If null is passed as a browserId, a unique id will be generated each time method is called.
  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.
  
  Parameters:
  
  style - the style display constants. Style constants should be bitwise-ORed together.
  
  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 null will create a new instance with a generated id every time.
  
  name - a name used for the presentation of the internal browser
  
  tooltip - a tooltip used for the presentation of the internal browser
  
  Returns:
  
  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.
  
  Throws:
  
  PartInitException - if the operation failed for some reason
- createBrowser
  
  IWebBrowser createBrowser(String browserId) 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 createBrowser(id).openURL(url).
  
  Parameters:
  
  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 null will create a new instance with a generated id every time.
  
  Returns:
  
  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.
  
  Throws:
  
  PartInitException - if the operation failed for some reason
- getExternalBrowser
  
  IWebBrowser getExternalBrowser() 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.
  
  Returns:
  
  the shared instance of the external browser
  
  Throws:
  
  PartInitException - if the operation failed for some reason
- isInternalWebBrowserAvailable
  
  boolean isInternalWebBrowserAvailable()
  
  Tests whether web browser as an SWT widget can be created in this workbench instance. If this method returns false, createBrowser would ignore browser styles AS_EDITOR and AS_VIEW and always create an external browser.
  
  Returns:
  
  true if internal web browser can be created on this platform, false otherwise.

Interface IWorkbenchBrowserSupport

Field Summary

Method Summary

Field Details

LOCATION_BAR

NAVIGATION_BAR

STATUS

PERSISTENT

AS_EDITOR

AS_VIEW

AS_EXTERNAL

Method Details

createBrowser

createBrowser

getExternalBrowser

isInternalWebBrowserAvailable