org.eclipse.ui.browser
Interface IWorkbenchBrowserSupport
-
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
|
static int
|
AS_EDITOR
Style constant (value 1<<5) indicating that the internal web
browser will be hosted in a workbench editor area. |
static 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 int
|
AS_VIEW
Style constant (value 1<<6) indicating that the internal web
browser will be hosted in a workbench view. |
static int
|
LOCATION_BAR
Style parameter (value 1<<1) indicating that the address combo and
'Go' button will created for the browser. |
static 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 int
|
PERSISTENT
Style constant (value 1<<4) indicating that the internal web
browser will reopen after restarting the workbench (if used). |
static int
|
STATUS
Style constant (value 1<<3) indicating that status will be tracked
and shown for the browser (page loading progress, text messages etc.). |
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
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.
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
