IWorkbenchBrowserSupport


1   /*******************************************************************************
2    * Copyright (c) 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.browser;
12  
13  import org.eclipse.ui.PartInitException;
14  
15  /**
16   * Web browser support. This class allows you to open URLs using internal or
17   * external Web browsers. Implementers may provide varying levels of support.
18   * The most rudimentary support that must be provided is to open URLs in an
19   * external web browser window. Everything else is a hint that browser support
20   * implementation may choose to honor but is not required (although a good
21   * implementation should aspire to support all the styles if possible on the
22   * given platform).
23   * <p>
24   * The support has a two-phase approach to opening URLs. A browser instance is
25   * created first, then <code>openURL</code> is called on it. This provides for
26   * browser instance reuse for as long as needed. The step of creating the
27   * browser instance encourages reuse itself by not creating new instances of
28   * browsers if one with the same id is already open. It also makes it possible
29   * to reuse browser instances restored after workbench is restarted.
30   * <p>
31   * The simplest way to open a URL is:
32   * 
33   * <pre>
34   * IWorkbenchSupport.createBrowser(&quot;myId&quot;).openURL(url);
35   * </pre>
36   * 
37   * <p>
38   * The call above will show the provided URL by reusing the browser instance
39   * with the matching id, or creating a new one if one does not exist already.
40   * <p>
41   * When more advanced control over the behavior of a browser instance is
42   * required, it is recommended to create the instance first, then reuse it as
43   * needed.
44   * <p>
45   * This interface is not intended to be implemented by clients.
46   * 
47   * @see IWebBrowser
48   * @since 3.1
49   */
50  
51  public interface IWorkbenchBrowserSupport {
52      /**
53       * Style parameter (value 1&lt;&lt;1) indicating that the address combo and
54       * 'Go' button will created for the browser. This style is ignored if the
55       * support is forced to open the browser as external.
56       */
57      int LOCATION_BAR = 1 << 1;
58  
59      /**
60       * Style parameter (value 1&lt;&lt;2) indicating that the navigation bar for
61       * navigating web pages will be created for the web browser. This style is
62       * ignored if the support is forced to open the browser as external.
63       */
64      int NAVIGATION_BAR = 1 << 2;
65  
66      /**
67       * Style constant (value 1&lt;&lt;3) indicating that status will be tracked
68       * and shown for the browser (page loading progress, text messages etc.).
69       */
70      int STATUS = 1 << 3;
71  
72      /**
73       * Style constant (value 1&lt;&lt;4) indicating that the internal web
74       * browser will reopen after restarting the workbench (if used). In
75       * addition, the URLs will appear in the MRU list.
76       */
77      int PERSISTENT = 1 << 4;
78  
79      /**
80       * Style constant (value 1&lt;&lt;5) indicating that the internal web
81       * browser will be hosted in a workbench editor area. This is just a hint -
82       * implementers of the browser support may not honor it.
83       */
84      int AS_EDITOR = 1 << 5;
85  
86      /**
87       * Style constant (value 1&lt;&lt;6) indicating that the internal web
88       * browser will be hosted in a workbench view. This is just a hint -
89       * implementers of the browser support may not honor it.
90       */
91      int AS_VIEW = 1 << 6;
92  
93      /**
94       * Style constant (value 1&lt;&lt;7) indicating that the external web
95       * browser must be used even if the implementation supports internal
96       * browsers and the user didn't set the preference to external browsers.
97       */
98      int AS_EXTERNAL = 1 << 7;
99  
100     /**
101      * Creates the new web browser instance. If the user has chosen to use the
102      * internal Web browser, the given style bits (see class header for values)
103      * will be used to open the browser.
104      * <p>
105      * The method will reuse an existing browser instance if the same
106      * <code>browserId</code> value is passed to it. A persisted browser
107      * instance restored upon startup can be accessed this way. If
108      * <code>null</code> is passed as a browserId, a unique id will be
109      * generated each time method is called.
110      * <p>
111      * If the user has chosen not to use the internal browser or it is not
112      * available on the current platform, an external browser will be used and
113      * all style parameters will be ignored.
114      * </p>
115      * 
116      * @param style
117      *            the style display constants. Style constants should be
118      *            bitwise-ORed together.
119      * @param browserId
120      *            if an instance of a browser with the same id is already
121      *            opened, it will be returned instead of creating a new one.
122      *            Passing <code>null</code> will create a new instance with a
123      *            generated id every time.
124      * @param name
125      *            a name used for the presentation of the internal browser
126      * @param tooltip
127      *            a tooltip used for the presentation of the internal browser
128      * @return the browser instance that can be used to open the URL. Clients
129      *         intending to reuse the instance for all the URLs should cache the
130      *         instance and call IWebBrowser#openURL() on it. Clients are
131      *         responsible for closing the browser instance when not needed.
132      * @exception PartInitException
133      *                if the operation failed for some reason
134      */
135     IWebBrowser createBrowser(int style, String   browserId, String   name,
136             String   tooltip) throws PartInitException;
137 
138     /**
139      * Creates the new web browser instance. This is a simplified method that
140      * creates the instance using default values for style, name and tooltip
141      * parameters. The method can be used to quickly open the URL by calling
142      * <code>createBrowser(id).openURL(url)</code>.
143      * <p>
144      * 
145      * @param browserId
146      *            if an instance of a browser with the same id is already
147      *            opened, it will be returned instead of creating a new one.
148      *            Passing <code>null</code> will create a new instance with a
149      *            generated id every time.
150      * @return the browser instance that can be used to open the URL. Clients
151      *         intending to reuse the instance for all the URLs should cache the
152      *         instance and call IWebBrowser#openURL() on it. Clients are
153      *         responsible for closing the browser instance when not needed.
154      * @exception PartInitException
155      *                if the operation failed for some reason
156      */
157     IWebBrowser createBrowser(String   browserId) throws PartInitException;
158 
159     /**
160      * Returns a shared instance of the external web browser. Clients can use it
161      * to share one external browser. The external browser that will be used is
162      * subject to browser support implementation. A suggested implementation is
163      * to use the operating system's default browser. Implementations that offer
164      * users a choice of the web browser should honour the users choice of
165      * external browser, with the initial selection being the system default
166      * browser.
167      * 
168      * @return the shared instance of the external browser
169      * @exception PartInitException
170      *                if the operation failed for some reason
171      */
172     IWebBrowser getExternalBrowser() throws PartInitException;
173 
174     /**
175      * Tests whether web browser as an SWT widget can be created in this
176      * workbench instance. If this method returns <code>false</code>,
177      * <code>createBrowser</code> would ignore browser styles
178      * <code>AS_EDITOR</code> and <code>AS_VIEW</code> and always create an
179      * external browser.
180      * 
181      * @return <code>true</code> if internal web browser can be created on
182      *         this platform, <code>false</code> otherwise.
183      */
184     boolean isInternalWebBrowserAvailable();
185 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags