001: /*******************************************************************************
002: * Copyright (c) 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.browser;
011:
012: import org.eclipse.ui.PartInitException;
013:
014: /**
015: * Web browser support. This class allows you to open URLs using internal or
016: * external Web browsers. Implementers may provide varying levels of support.
017: * The most rudimentary support that must be provided is to open URLs in an
018: * external web browser window. Everything else is a hint that browser support
019: * implementation may choose to honor but is not required (although a good
020: * implementation should aspire to support all the styles if possible on the
021: * given platform).
022: * <p>
023: * The support has a two-phase approach to opening URLs. A browser instance is
024: * created first, then <code>openURL</code> is called on it. This provides for
025: * browser instance reuse for as long as needed. The step of creating the
026: * browser instance encourages reuse itself by not creating new instances of
027: * browsers if one with the same id is already open. It also makes it possible
028: * to reuse browser instances restored after workbench is restarted.
029: * <p>
030: * The simplest way to open a URL is:
031: *
032: * <pre>
033: * IWorkbenchSupport.createBrowser("myId").openURL(url);
034: * </pre>
035: *
036: * <p>
037: * The call above will show the provided URL by reusing the browser instance
038: * with the matching id, or creating a new one if one does not exist already.
039: * <p>
040: * When more advanced control over the behavior of a browser instance is
041: * required, it is recommended to create the instance first, then reuse it as
042: * needed.
043: * <p>
044: * This interface is not intended to be implemented by clients.
045: *
046: * @see IWebBrowser
047: * @since 3.1
048: */
049:
050: public interface IWorkbenchBrowserSupport {
051: /**
052: * Style parameter (value 1<<1) indicating that the address combo and
053: * 'Go' button will created for the browser. This style is ignored if the
054: * support is forced to open the browser as external.
055: */
056: int LOCATION_BAR = 1 << 1;
057:
058: /**
059: * Style parameter (value 1<<2) indicating that the navigation bar for
060: * navigating web pages will be created for the web browser. This style is
061: * ignored if the support is forced to open the browser as external.
062: */
063: int NAVIGATION_BAR = 1 << 2;
064:
065: /**
066: * Style constant (value 1<<3) indicating that status will be tracked
067: * and shown for the browser (page loading progress, text messages etc.).
068: */
069: int STATUS = 1 << 3;
070:
071: /**
072: * Style constant (value 1<<4) indicating that the internal web
073: * browser will reopen after restarting the workbench (if used). In
074: * addition, the URLs will appear in the MRU list.
075: */
076: int PERSISTENT = 1 << 4;
077:
078: /**
079: * Style constant (value 1<<5) indicating that the internal web
080: * browser will be hosted in a workbench editor area. This is just a hint -
081: * implementers of the browser support may not honor it.
082: */
083: int AS_EDITOR = 1 << 5;
084:
085: /**
086: * Style constant (value 1<<6) indicating that the internal web
087: * browser will be hosted in a workbench view. This is just a hint -
088: * implementers of the browser support may not honor it.
089: */
090: int AS_VIEW = 1 << 6;
091:
092: /**
093: * Style constant (value 1<<7) indicating that the external web
094: * browser must be used even if the implementation supports internal
095: * browsers and the user didn't set the preference to external browsers.
096: */
097: int AS_EXTERNAL = 1 << 7;
098:
099: /**
100: * Creates the new web browser instance. If the user has chosen to use the
101: * internal Web browser, the given style bits (see class header for values)
102: * will be used to open the browser.
103: * <p>
104: * The method will reuse an existing browser instance if the same
105: * <code>browserId</code> value is passed to it. A persisted browser
106: * instance restored upon startup can be accessed this way. If
107: * <code>null</code> is passed as a browserId, a unique id will be
108: * generated each time method is called.
109: * <p>
110: * If the user has chosen not to use the internal browser or it is not
111: * available on the current platform, an external browser will be used and
112: * all style parameters will be ignored.
113: * </p>
114: *
115: * @param style
116: * the style display constants. Style constants should be
117: * bitwise-ORed together.
118: * @param browserId
119: * if an instance of a browser with the same id is already
120: * opened, it will be returned instead of creating a new one.
121: * Passing <code>null</code> will create a new instance with a
122: * generated id every time.
123: * @param name
124: * a name used for the presentation of the internal browser
125: * @param tooltip
126: * a tooltip used for the presentation of the internal browser
127: * @return the browser instance that can be used to open the URL. Clients
128: * intending to reuse the instance for all the URLs should cache the
129: * instance and call IWebBrowser#openURL() on it. Clients are
130: * responsible for closing the browser instance when not needed.
131: * @exception PartInitException
132: * if the operation failed for some reason
133: */
134: IWebBrowser createBrowser(int style, String browserId, String name,
135: String tooltip) throws PartInitException;
136:
137: /**
138: * Creates the new web browser instance. This is a simplified method that
139: * creates the instance using default values for style, name and tooltip
140: * parameters. The method can be used to quickly open the URL by calling
141: * <code>createBrowser(id).openURL(url)</code>.
142: * <p>
143: *
144: * @param browserId
145: * if an instance of a browser with the same id is already
146: * opened, it will be returned instead of creating a new one.
147: * Passing <code>null</code> will create a new instance with a
148: * generated id every time.
149: * @return the browser instance that can be used to open the URL. Clients
150: * intending to reuse the instance for all the URLs should cache the
151: * instance and call IWebBrowser#openURL() on it. Clients are
152: * responsible for closing the browser instance when not needed.
153: * @exception PartInitException
154: * if the operation failed for some reason
155: */
156: IWebBrowser createBrowser(String browserId)
157: 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: }
|