bundles/org.eclipse.swt.win32.win32.x86_64/src/org/eclipse/swt/browser/Browser.java

   1 /*******************************************************************************
   2  * Copyright (c) 2003, 2018 IBM Corporation and others.
   3  *
   4  * This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License 2.0
   6  * which accompanies this distribution, and is available at
   7  * https://www.eclipse.org/legal/epl-2.0/
   8  *
   9  * SPDX-License-Identifier: EPL-2.0
  10  *
  11  * Contributors:
  12  *     IBM Corporation - initial API and implementation
  13  *******************************************************************************/
  14 package org.eclipse.swt.browser;
  15
  16 import org.eclipse.swt.*;
  17 import org.eclipse.swt.widgets.*;
  18
  19 /**
  20  * Instances of this class implement the browser user interface
  21  * metaphor.  It allows the user to visualize and navigate through
  22  * HTML documents.
  23  * <p>
  24  * Note that although this class is a subclass of <code>Composite</code>,
  25  * it does not make sense to set a layout on it.
  26  * </p>
  27  * <dl>
  28  * <dt><b>Styles:</b></dt>
  29  * <dd>NONE, WEBKIT</dd>
  30  * <dt><b>Events:</b></dt>
  31  * <dd>CloseWindowListener, LocationListener, OpenWindowListener, ProgressListener, StatusTextListener, TitleListener, VisibilityWindowListener</dd>
  32  * </dl>
  33  * <p>
  34  * Note: MOZILLA is deprecated and is no longer supported.
  35  * </p>
  36  * <p>
  37  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
  38  * </p>
  39  *
  40  * @see <a href="http://www.eclipse.org/swt/snippets/#browser">Browser snippets</a>
  41  * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Examples: ControlExample, BrowserExample</a>
  42  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  43  *
  44  * @since 3.0
  45  * @noextend This class is not intended to be subclassed by clients.
  46  */
  47
  48 public class Browser extends Composite {
  49         WebBrowser webBrowser;
  50         int userStyle;
  51         boolean isClosing;
  52
  53         static int DefaultType = SWT.DEFAULT;
  54
  55         static final String NO_INPUT_METHOD = "org.eclipse.swt.internal.gtk.noInputMethod"; //$NON-NLS-1$
  56         static final String PACKAGE_PREFIX = "org.eclipse.swt.browser."; //$NON-NLS-1$
  57         static final String PROPERTY_DEFAULTTYPE = "org.eclipse.swt.browser.DefaultType"; //$NON-NLS-1$
  58
  59 /**
  60  * Constructs a new instance of this class given its parent
  61  * and a style value describing its behavior and appearance.
  62  * <p>
  63  * The style value is either one of the style constants defined in
  64  * class <code>SWT</code> which is applicable to instances of this
  65  * class, or must be built by <em>bitwise OR</em>'ing together
  66  * (that is, using the <code>int</code> "|" operator) two or more
  67  * of those <code>SWT</code> style constants. The class description
  68  * lists the style constants that are applicable to the class.
  69  * Style bits are also inherited from superclasses.
  70  * </p>
  71  *
  72  * @param parent a widget which will be the parent of the new instance (cannot be null)
  73  * @param style the style of widget to construct
  74  *
  75  * @exception IllegalArgumentException <ul>
  76  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
  77  * </ul>
  78  * @exception SWTException <ul>
  79  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
  80  * </ul>
  81  * @exception SWTError <ul>
  82  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for browser creation</li>
  83  * </ul>
  84  *
  85  * @see Widget#getStyle
  86  *
  87  * @since 3.0
  88  */
  89 public Browser (Composite parent, int style) {
  90         super (checkParent (parent), checkStyle (style));
  91         userStyle = style;
  92
  93         String platform = SWT.getPlatform ();
  94         if ("gtk".equals (platform)) { //$NON-NLS-1$
  95                 parent.getDisplay ().setData (NO_INPUT_METHOD, null);
  96         }
  97
  98         style = getStyle ();
  99         webBrowser = new BrowserFactory ().createWebBrowser (style);
 100         if (webBrowser != null) {
 101                 webBrowser.setBrowser (this);
 102                 webBrowser.create (parent, style);
 103                 return;
 104         }
 105         dispose ();
 106
 107         String errMsg = " because there is no underlying browser available.\n";
 108         switch (SWT.getPlatform()) {
 109         case "gtk":
 110                 errMsg = errMsg + "Please ensure that WebKit with its GTK 3.x bindings is installed (WebKit2 API level is preferred)."
 111                                 + " Additionally, please note that GTK4 does not currently have Browser support.\n";
 112                 break;
 113         case "cocoa":
 114                 errMsg = errMsg + "SWT failed to load the WebKit library.\n";
 115                 break;
 116         case "win32":
 117                 errMsg = errMsg + "SWT uses either IE or WebKit. Either the SWT.WEBKIT flag is passed and the WebKit library was not "
 118                                 + "loaded properly by SWT, or SWT failed to load IE.\n";
 119                 break;
 120         default:
 121                 break;
 122         }
 123         SWT.error (SWT.ERROR_NO_HANDLES, null, errMsg);
 124 }
 125
 126 static Composite checkParent (Composite parent) {
 127         String platform = SWT.getPlatform ();
 128         if (!"gtk".equals (platform)) return parent; //$NON-NLS-1$
 129
 130         /*
 131         * Note.  Mozilla provides all IM support needed for text input in web pages.
 132         * If SWT creates another input method context for the widget it will cause
 133         * indeterminate results to happen (hangs and crashes). The fix is to prevent
 134         * SWT from creating an input method context for the  Browser widget.
 135         */
 136         if (parent != null && !parent.isDisposed ()) {
 137                 Display display = parent.getDisplay ();
 138                 if (display != null) {
 139                         if (display.getThread () == Thread.currentThread ()) {
 140                                 display.setData (NO_INPUT_METHOD, "true"); //$NON-NLS-1$
 141                         }
 142                 }
 143         }
 144         return parent;
 145 }
 146
 147 @SuppressWarnings("deprecation")
 148 static int checkStyle(int style) {
 149         String platform = SWT.getPlatform ();
 150         if (DefaultType == SWT.DEFAULT) {
 151                 /*
 152                 * Some Browser clients that explicitly specify the native renderer to use (by
 153                 * creating a Browser with SWT.WEBKIT) may also need to specify that all
 154                 * "default" Browser instances (those created with style SWT.NONE) should use
 155                 * this renderer as well. This may be needed in order to avoid incompatibilities
 156                 * that can arise from having multiple native renderers loaded within the same
 157                 * process. A client can do this by setting the
 158                 * "org.eclipse.swt.browser.DefaultType" java system property to a value like
 159                 * "ie" or "webkit". Value "mozilla" is ignored now.
 160                 */
 161
 162                 /*
 163                 * Plug-ins need an opportunity to set the org.eclipse.swt.browser.DefaultType
 164                 * system property before the first Browser is created.  To facilitate this,
 165                 * reflection is used to reference non-existent class
 166                 * org.eclipse.swt.browser.BrowserInitializer the first time a Browser is created.
 167                 * A client wishing to use this hook can do so by creating a fragment of
 168                 * org.eclipse.swt that implements this class and sets the system property in its
 169                 * static initializer.
 170                 */
 171                 try {
 172                         Class.forName ("org.eclipse.swt.browser.BrowserInitializer"); //$NON-NLS-1$
 173                 } catch (ClassNotFoundException e) {
 174                         /* no fragment is providing this class, which is the typical case */
 175                 }
 176
 177                 String value = System.getProperty (PROPERTY_DEFAULTTYPE);
 178                 if (value != null) {
 179                         int index = 0;
 180                         int length = value.length();
 181                         do {
 182                                 int newIndex = value.indexOf(',', index);
 183                                 if (newIndex == -1) {
 184                                         newIndex = length;
 185                                 }
 186                                 String current = value.substring(index, newIndex).trim();
 187                                 if (current.equalsIgnoreCase ("webkit")) { //$NON-NLS-1$
 188                                         DefaultType = SWT.WEBKIT;
 189                                         break;
 190                                 } else if (current.equalsIgnoreCase ("ie") && "win32".equals (platform)) { //$NON-NLS-1$ //$NON-NLS-2$
 191                                         DefaultType = SWT.NONE;
 192                                         break;
 193                                 }
 194                                 index = newIndex + 1;
 195                         } while (index < length);
 196                 }
 197                 if (DefaultType == SWT.DEFAULT) {
 198                         DefaultType = SWT.NONE;
 199                 }
 200         }
 201
 202         /* remove SWT.MOZILLA style if specified */
 203         if ((style & SWT.MOZILLA) != 0) {
 204                 System.err.println ("Unsupported Browser Type: SWT.MOZILLA style is deprecated.\n" //$NON-NLS-1$
 205                                 + "It'll be removed from the user specified style. Browser will be created with the modified style " //$NON-NLS-1$
 206                                 + "and if no other style bit is specified, browser with SWT.NONE style will be created"); //$NON-NLS-1$
 207                 style &= ~SWT.MOZILLA;
 208         }
 209
 210         if ((style & SWT.WEBKIT) == 0) {
 211                 style |= DefaultType;
 212         }
 213         if ((style & SWT.WEBKIT) != 0) {
 214                 return style;
 215         }
 216         if ("win32".equals (platform)) { //$NON-NLS-1$
 217                 /*
 218                 * For IE on win32 the border is supplied by the embedded browser, so remove
 219                 * the style so that the parent Composite will not draw a second border.
 220                 */
 221                 return style & ~SWT.BORDER;
 222         }
 223         return style;
 224 }
 225
 226 @Override
 227 protected void checkWidget () {
 228         super.checkWidget ();
 229 }
 230
 231 /**
 232  * Clears all session cookies from all current Browser instances.
 233  *
 234  * @since 3.2
 235  */
 236 public static void clearSessions () {
 237         WebBrowser.clearSessions ();
 238 }
 239
 240 /**
 241  * Returns the value of a cookie that is associated with a URL.
 242  * Note that cookies are shared amongst all Browser instances.
 243  *
 244  * @param name the cookie name
 245  * @param url the URL that the cookie is associated with
 246  * @return the cookie value, or <code>null</code> if no such cookie exists
 247  *
 248  * @exception IllegalArgumentException <ul>
 249  *    <li>ERROR_NULL_ARGUMENT - if the name is null</li>
 250  *    <li>ERROR_NULL_ARGUMENT - if the url is null</li>
 251  * </ul>
 252  *
 253  * @since 3.5
 254  */
 255 public static String getCookie (String name, String url) {
 256         if (name == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 257         if (url == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 258         return WebBrowser.GetCookie (name, url);
 259 }
 260
 261 /**
 262  * Sets a cookie on a URL.  Note that cookies are shared amongst all Browser instances.
 263  *
 264  * The <code>value</code> parameter must be a cookie header string that
 265  * complies with <a href="http://www.ietf.org/rfc/rfc2109.txt">RFC 2109</a>.
 266  * The value is passed through to the native browser unchanged.
 267  * <p>
 268  * Example value strings:
 269  * <code>foo=bar</code> (basic session cookie)
 270  * <code>foo=bar; path=/; domain=.eclipse.org</code> (session cookie)
 271  * <code>foo=bar; expires=Thu, 01-Jan-2030 00:00:01 GMT</code> (persistent cookie)
 272  * <code>foo=; expires=Thu, 01-Jan-1970 00:00:01 GMT</code> (deletes cookie <code>foo</code>)
 273  *
 274  * @param value the cookie value
 275  * @param url the URL to associate the cookie with
 276  * @return <code>true</code> if the cookie was successfully set and <code>false</code> otherwise
 277  *
 278  * @exception IllegalArgumentException <ul>
 279  *    <li>ERROR_NULL_ARGUMENT - if the value is null</li>
 280  *    <li>ERROR_NULL_ARGUMENT - if the url is null</li>
 281  * </ul>
 282  *
 283  * @since 3.5
 284  */
 285 public static boolean setCookie (String value, String url) {
 286         if (value == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 287         if (url == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 288         return WebBrowser.SetCookie (value, url, true);
 289 }
 290
 291 /**
 292  * Adds the listener to the collection of listeners who will be
 293  * notified when authentication is required.
 294  * <p>
 295  * This notification occurs when a page requiring authentication is
 296  * encountered.
 297  * </p>
 298  *
 299  * @param listener the listener which should be notified
 300  *
 301  * @exception IllegalArgumentException <ul>
 302  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 303  * </ul>
 304  *
 305  * @exception SWTException <ul>
 306  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 307  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 308  * </ul>
 309  *
 310  * @since 3.5
 311  */
 312 public void addAuthenticationListener (AuthenticationListener listener) {
 313         checkWidget();
 314         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 315         webBrowser.addAuthenticationListener (listener);
 316 }
 317
 318 /**
 319  * Adds the listener to the collection of listeners who will be
 320  * notified when the window hosting the receiver should be closed.
 321  * <p>
 322  * This notification occurs when a javascript command such as
 323  * <code>window.close</code> gets executed by a <code>Browser</code>.
 324  * </p>
 325  *
 326  * @param listener the listener which should be notified
 327  *
 328  * @exception IllegalArgumentException <ul>
 329  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 330  * </ul>
 331  *
 332  * @exception SWTException <ul>
 333  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 334  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 335  * </ul>
 336  *
 337  * @since 3.0
 338  */
 339 public void addCloseWindowListener (CloseWindowListener listener) {
 340         checkWidget();
 341         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 342         webBrowser.addCloseWindowListener (listener);
 343 }
 344
 345 /**
 346  * Adds the listener to the collection of listeners who will be
 347  * notified when the current location has changed or is about to change.
 348  * <p>
 349  * This notification typically occurs when the application navigates
 350  * to a new location with {@link #setUrl(String)} or when the user
 351  * activates a hyperlink.
 352  * </p>
 353  *
 354  * @param listener the listener which should be notified
 355  *
 356  * @exception IllegalArgumentException <ul>
 357  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 358  * </ul>
 359  *
 360  * @exception SWTException <ul>
 361  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 362  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 363  * </ul>
 364  *
 365  * @since 3.0
 366  */
 367 public void addLocationListener (LocationListener listener) {
 368         checkWidget();
 369         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 370         webBrowser.addLocationListener (listener);
 371 }
 372
 373 /**
 374  * Adds the listener to the collection of listeners who will be
 375  * notified when a new window needs to be created.
 376  * <p>
 377  * This notification occurs when a javascript command such as
 378  * <code>window.open</code> gets executed by a <code>Browser</code>.
 379  * </p>
 380  *
 381  * @param listener the listener which should be notified
 382  *
 383  * @exception IllegalArgumentException <ul>
 384  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 385  * </ul>
 386  *
 387  * @exception SWTException <ul>
 388  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 389  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 390  * </ul>
 391  *
 392  * @since 3.0
 393  */
 394 public void addOpenWindowListener (OpenWindowListener listener) {
 395         checkWidget();
 396         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 397         webBrowser.addOpenWindowListener (listener);
 398 }
 399
 400 /**
 401  * Adds the listener to the collection of listeners who will be
 402  * notified when a progress is made during the loading of the current
 403  * URL or when the loading of the current URL has been completed.
 404  *
 405  * @param listener the listener which should be notified
 406  *
 407  * @exception IllegalArgumentException <ul>
 408  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 409  * </ul>
 410  *
 411  * @exception SWTException <ul>
 412  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 413  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 414  * </ul>
 415  *
 416  * @since 3.0
 417  */
 418 public void addProgressListener (ProgressListener listener) {
 419         checkWidget();
 420         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 421         webBrowser.addProgressListener (listener);
 422 }
 423
 424 /**
 425  * Adds the listener to the collection of listeners who will be
 426  * notified when the status text is changed.
 427  * <p>
 428  * The status text is typically displayed in the status bar of
 429  * a browser application.
 430  * </p>
 431  *
 432  * @param listener the listener which should be notified
 433  *
 434  * @exception IllegalArgumentException <ul>
 435  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 436  * </ul>
 437  *
 438  * @exception SWTException <ul>
 439  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 440  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 441  * </ul>
 442  *
 443  * @since 3.0
 444  */
 445 public void addStatusTextListener (StatusTextListener listener) {
 446         checkWidget();
 447         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 448         webBrowser.addStatusTextListener (listener);
 449 }
 450
 451 /**
 452  * Adds the listener to the collection of listeners who will be
 453  * notified when the title of the current document is available
 454  * or has changed.
 455  *
 456  * @param listener the listener which should be notified
 457  *
 458  * @exception IllegalArgumentException <ul>
 459  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 460  * </ul>
 461  *
 462  * @exception SWTException <ul>
 463  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 464  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 465  * </ul>
 466  *
 467  * @since 3.0
 468  */
 469 public void addTitleListener (TitleListener listener) {
 470         checkWidget();
 471         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 472         webBrowser.addTitleListener (listener);
 473 }
 474
 475 /**
 476  * Adds the listener to the collection of listeners who will be
 477  * notified when a window hosting the receiver needs to be displayed
 478  * or hidden.
 479  *
 480  * @param listener the listener which should be notified
 481  *
 482  * @exception IllegalArgumentException <ul>
 483  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 484  * </ul>
 485  *
 486  * @exception SWTException <ul>
 487  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 488  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 489  * </ul>
 490  *
 491  * @since 3.0
 492  */
 493 public void addVisibilityWindowListener (VisibilityWindowListener listener) {
 494         checkWidget();
 495         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 496         webBrowser.addVisibilityWindowListener (listener);
 497 }
 498
 499 /**
 500  * Navigate to the previous session history item.
 501  *
 502  * @return <code>true</code> if the operation was successful and <code>false</code> otherwise
 503  *
 504  * @exception SWTException <ul>
 505  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 506  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 507  * </ul>
 508  *
 509  * @see #forward
 510  *
 511  * @since 3.0
 512  */
 513 public boolean back () {
 514         checkWidget();
 515         return webBrowser.back ();
 516 }
 517
 518 @Override
 519 protected void checkSubclass () {
 520         String name = getClass ().getName ();
 521         int index = name.lastIndexOf ('.');
 522         if (!name.substring (0, index + 1).equals (PACKAGE_PREFIX)) {
 523                 SWT.error (SWT.ERROR_INVALID_SUBCLASS);
 524         }
 525 }
 526
 527 /**
 528  * Executes the specified script.
 529  * <p>
 530  * Executes a script containing javascript commands in the context of the current document.
 531  * If document-defined functions or properties are accessed by the script then this method
 532  * should not be invoked until the document has finished loading (<code>ProgressListener.completed()</code>
 533  * gives notification of this).
 534  *
 535  * @param script the script with javascript commands
 536  *
 537  * @return <code>true</code> if the operation was successful and <code>false</code> otherwise
 538  *
 539  * @exception IllegalArgumentException <ul>
 540  *    <li>ERROR_NULL_ARGUMENT - if the script is null</li>
 541  * </ul>
 542  *
 543  * @exception SWTException <ul>
 544  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 545  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 546  * </ul>
 547  *
 548  * @see ProgressListener#completed(ProgressEvent)
 549  *
 550  * @since 3.1
 551  */
 552 public boolean execute (String script) {
 553         checkWidget();
 554         if (script == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 555         return webBrowser.execute (script);
 556 }
 557
 558 /**
 559  * Attempts to dispose the receiver, but allows the dispose to be vetoed
 560  * by the user in response to an <code>onbeforeunload</code> listener
 561  * in the Browser's current page.
 562  *
 563  * @return <code>true</code> if the receiver was disposed, and <code>false</code> otherwise
 564  *
 565  * @exception SWTException <ul>
 566  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
 567  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 568  * </ul>
 569  *
 570  * @see #dispose()
 571  *
 572  * @since 3.6
 573  */
 574 public boolean close () {
 575         checkWidget();
 576         if (webBrowser.close ()) {
 577                 isClosing = true;
 578                 dispose ();
 579                 isClosing = false;
 580                 return true;
 581         }
 582         return false;
 583 }
 584
 585 /**
 586  * Returns the result, if any, of executing the specified script.
 587  * <p>
 588  * Evaluates a script containing javascript commands in the context of
 589  * the current document.  If document-defined functions or properties
 590  * are accessed by the script then this method should not be invoked
 591  * until the document has finished loading (<code>ProgressListener.completed()</code>
 592  * gives notification of this).
 593  * </p><p>
 594  * If the script returns a value with a supported type then a java
 595  * representation of the value is returned.  The supported
 596  * javascript -&gt; java mappings are:
 597  * <ul>
 598  * <li>javascript null or undefined -&gt; <code>null</code></li>
 599  * <li>javascript number -&gt; <code>java.lang.Double</code></li>
 600  * <li>javascript string -&gt; <code>java.lang.String</code></li>
 601  * <li>javascript boolean -&gt; <code>java.lang.Boolean</code></li>
 602  * <li>javascript array whose elements are all of supported types -&gt; <code>java.lang.Object[]</code></li>
 603  * </ul>
 604  *
 605  * An <code>SWTException</code> is thrown if the return value has an
 606  * unsupported type, or if evaluating the script causes a javascript
 607  * error to be thrown.
 608  *
 609  * @param script the script with javascript commands
 610  *
 611  * @return the return value, if any, of executing the script
 612  *
 613  * @exception IllegalArgumentException <ul>
 614  *    <li>ERROR_NULL_ARGUMENT - if the script is null</li>
 615  * </ul>
 616  *
 617  * @exception SWTException <ul>
 618  *    <li>ERROR_FAILED_EVALUATE when the script evaluation causes a javascript error to be thrown</li>
 619  *    <li>ERROR_INVALID_RETURN_VALUE when the script returns a value of unsupported type</li>
 620  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 621  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 622  * </ul>
 623  *
 624  * @see Browser#evaluate(String,boolean)
 625  * @see ProgressListener#completed(ProgressEvent)
 626  *
 627  * @since 3.5
 628  */
 629 public Object evaluate (String script) throws SWTException {
 630         checkWidget();
 631         return evaluate (script, false);
 632 }
 633
 634 /**
 635  * Returns the result, if any, of executing the specified script.
 636  * <p>
 637  * Evaluates a script containing javascript commands.
 638  * When <code>trusted</code> is <code>true</code> script is executed in the context of Chrome
 639  * with Chrome security privileges.
 640  * When <code>trusted</code> is <code>false</code> script is executed in the context of the
 641  * current document with normal privileges.
 642  * </p><p>
 643  * If document-defined functions or properties are accessed by the script then
 644  * this method should not be invoked until the document has finished loading
 645  * (<code>ProgressListener.completed()</code> gives notification of this).
 646  * </p><p>
 647  * If the script returns a value with a supported type then a java
 648  * representation of the value is returned.  The supported
 649  * javascript -&gt; java mappings are:
 650  * <ul>
 651  * <li>javascript null or undefined -&gt; <code>null</code></li>
 652  * <li>javascript number -&gt; <code>java.lang.Double</code></li>
 653  * <li>javascript string -&gt; <code>java.lang.String</code></li>
 654  * <li>javascript boolean -&gt; <code>java.lang.Boolean</code></li>
 655  * <li>javascript array whose elements are all of supported types -&gt; <code>java.lang.Object[]</code></li>
 656  * </ul>
 657  * An <code>SWTException</code> is thrown if the return value has an
 658  * unsupported type, or if evaluating the script causes a javascript
 659  * error to be thrown.
 660  * <p>
 661  * Note: Chrome security context is applicable only to Browsers with style <code>SWT.Mozilla</code>.
 662  * </p>
 663  * @param script the script with javascript commands
 664  * @param trusted <code>true</code> or <code>false</code> depending on the security context to be used
 665  *
 666  * @return the return value, if any, of executing the script
 667  *
 668  * @exception IllegalArgumentException <ul>
 669  *    <li>ERROR_NULL_ARGUMENT - if the script is null</li>
 670  * </ul>
 671  *
 672  * @exception SWTException <ul>
 673  *    <li>ERROR_FAILED_EVALUATE when the script evaluation causes a javascript error to be thrown</li>
 674  *    <li>ERROR_INVALID_RETURN_VALUE when the script returns a value of unsupported type</li>
 675  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 676  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 677  * </ul>
 678  *
 679  * @see ProgressListener#completed(ProgressEvent)
 680  */
 681 public Object evaluate (String script, boolean trusted) throws SWTException {
 682         checkWidget();
 683         if (script == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 684         return webBrowser.evaluate (script, trusted);
 685 }
 686
 687 /**
 688  * Navigate to the next session history item.
 689  *
 690  * @return <code>true</code> if the operation was successful and <code>false</code> otherwise
 691  *
 692  * @exception SWTException <ul>
 693  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 694  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 695  * </ul>
 696  *
 697  * @see #back
 698  *
 699  * @since 3.0
 700  */
 701 public boolean forward () {
 702         checkWidget();
 703         return webBrowser.forward ();
 704 }
 705
 706 /**
 707  * Returns the type of native browser being used by this instance.
 708  * Examples: "ie", "mozilla", "voyager", "webkit"
 709  *
 710  * @return the type of the native browser
 711  *
 712  * @since 3.5
 713  */
 714 public String getBrowserType () {
 715         checkWidget();
 716         return webBrowser.getBrowserType ();
 717 }
 718
 719 /**
 720  * Returns <code>true</code> if javascript will be allowed to run in pages
 721  * subsequently viewed in the receiver, and <code>false</code> otherwise.
 722  * Note that this may not reflect the javascript enablement on the currently-
 723  * viewed page if <code>setJavascriptEnabled()</code> has been invoked during
 724  * its lifetime.
 725  *
 726  * @return the receiver's javascript enabled state
 727  *
 728  * @exception SWTException <ul>
 729  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
 730  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 731  * </ul>
 732  *
 733  * @see #setJavascriptEnabled
 734  *
 735  * @since 3.5
 736  */
 737 public boolean getJavascriptEnabled () {
 738         checkWidget();
 739         return webBrowser.jsEnabledOnNextPage;
 740 }
 741
 742 @Override
 743 public int getStyle () {
 744         /*
 745         * If SWT.BORDER was specified at creation time then getStyle() should answer
 746         * it even though it is removed for IE on win32 in checkStyle().
 747         */
 748         return super.getStyle () | (userStyle & SWT.BORDER);
 749 }
 750
 751 /**
 752  * Returns a string with HTML that represents the content of the current page.
 753  *
 754  * @return HTML representing the current page or an empty <code>String</code>
 755  * if this is empty.<br>
 756  * <p> Note, the exact return value is platform dependent.
 757  * For example on Windows, the returned string is the proccessed webpage
 758  * with javascript executed and missing html tags added.
 759  * On Linux and OS X, this returns the original HTML before the browser has
 760  * processed it.</p>
 761  *
 762  * @exception SWTException <ul>
 763  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 764  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 765  * </ul>
 766  *
 767  * @since 3.4
 768  */
 769 public String getText () {
 770         checkWidget();
 771         return webBrowser.getText ();
 772 }
 773
 774 /**
 775  * Returns the current URL.
 776  *
 777  * @return the current URL or an empty <code>String</code> if there is no current URL
 778  *
 779  * @exception SWTException <ul>
 780  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 781  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 782  * </ul>
 783  *
 784  * @see #setUrl
 785  *
 786  * @since 3.0
 787  */
 788 public String getUrl () {
 789         checkWidget();
 790         return webBrowser.getUrl ();
 791 }
 792
 793 /**
 794  * Returns the JavaXPCOM <code>nsIWebBrowser</code> for the receiver, or <code>null</code>
 795  * if it is not available.  In order for an <code>nsIWebBrowser</code> to be returned all
 796  * of the following must be true: <ul>
 797  *    <li>the receiver's style must be <code>SWT.MOZILLA</code></li>
 798  *    <li>the classes from JavaXPCOM &gt;= 1.8.1.2 must be resolvable at runtime</li>
 799  *    <li>the version of the underlying XULRunner must be &gt;= 1.8.1.2</li>
 800  * </ul>
 801  *
 802  * @return the receiver's JavaXPCOM <code>nsIWebBrowser</code> or <code>null</code>
 803  *
 804  * @since 3.3
 805  * @deprecated SWT.MOZILLA is deprecated and XULRunner as a browser renderer is no longer supported.
 806  */
 807 @Deprecated
 808 public Object getWebBrowser () {
 809         checkWidget();
 810         return webBrowser.getWebBrowser ();
 811 }
 812
 813 /**
 814  * Returns <code>true</code> if the receiver can navigate to the
 815  * previous session history item, and <code>false</code> otherwise.
 816  *
 817  * @return the receiver's back command enabled state
 818  *
 819  * @exception SWTException <ul>
 820  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
 821  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 822  * </ul>
 823  *
 824  * @see #back
 825  */
 826 public boolean isBackEnabled () {
 827         checkWidget();
 828         return webBrowser.isBackEnabled ();
 829 }
 830
 831 @Override
 832 public boolean isFocusControl () {
 833         checkWidget();
 834         if (webBrowser.isFocusControl ()) return true;
 835         return super.isFocusControl ();
 836 }
 837
 838 /**
 839  * Returns <code>true</code> if the receiver can navigate to the
 840  * next session history item, and <code>false</code> otherwise.
 841  *
 842  * @return the receiver's forward command enabled state
 843  *
 844  * @exception SWTException <ul>
 845  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
 846  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 847  * </ul>
 848  *
 849  * @see #forward
 850  */
 851 public boolean isForwardEnabled () {
 852         checkWidget();
 853         return webBrowser.isForwardEnabled ();
 854 }
 855
 856 /**
 857  * Refresh the current page.
 858  *
 859  * @exception SWTException <ul>
 860  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 861  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 862  * </ul>
 863  *
 864  * @since 3.0
 865  */
 866 public void refresh () {
 867         checkWidget();
 868         webBrowser.refresh ();
 869 }
 870
 871 /**
 872  * Removes the listener from the collection of listeners who will
 873  * be notified when authentication is required.
 874  *
 875  * @param listener the listener which should no longer be notified
 876  *
 877  * @exception IllegalArgumentException <ul>
 878  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 879  * </ul>
 880  *
 881  * @exception SWTException <ul>
 882  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 883  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 884  * </ul>
 885  *
 886  * @since 3.5
 887  */
 888 public void removeAuthenticationListener (AuthenticationListener listener) {
 889         checkWidget();
 890         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 891         webBrowser.removeAuthenticationListener (listener);
 892 }
 893
 894 /**
 895  * Removes the listener from the collection of listeners who will
 896  * be notified when the window hosting the receiver should be closed.
 897  *
 898  * @param listener the listener which should no longer be notified
 899  *
 900  * @exception IllegalArgumentException <ul>
 901  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 902  * </ul>
 903  *
 904  * @exception SWTException <ul>
 905  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 906  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 907  * </ul>
 908  *
 909  * @since 3.0
 910  */
 911 public void removeCloseWindowListener (CloseWindowListener listener) {
 912         checkWidget();
 913         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 914         webBrowser.removeCloseWindowListener (listener);
 915 }
 916
 917 /**
 918  * Removes the listener from the collection of listeners who will
 919  * be notified when the current location is changed or about to be changed.
 920  *
 921  * @param listener the listener which should no longer be notified
 922  *
 923  * @exception IllegalArgumentException <ul>
 924  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 925  * </ul>
 926  *
 927  * @exception SWTException <ul>
 928  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 929  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 930  * </ul>
 931  *
 932  * @since 3.0
 933  */
 934 public void removeLocationListener (LocationListener listener) {
 935         checkWidget();
 936         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 937         webBrowser.removeLocationListener (listener);
 938 }
 939
 940 /**
 941  * Removes the listener from the collection of listeners who will
 942  * be notified when a new window needs to be created.
 943  *
 944  * @param listener the listener which should no longer be notified
 945  *
 946  * @exception IllegalArgumentException <ul>
 947  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 948  * </ul>
 949  *
 950  * @exception SWTException <ul>
 951  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 952  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 953  * </ul>
 954  *
 955  * @since 3.0
 956  */
 957 public void removeOpenWindowListener (OpenWindowListener listener) {
 958         checkWidget();
 959         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 960         webBrowser.removeOpenWindowListener (listener);
 961 }
 962
 963 /**
 964  * Removes the listener from the collection of listeners who will
 965  * be notified when a progress is made during the loading of the current
 966  * URL or when the loading of the current URL has been completed.
 967  *
 968  * @param listener the listener which should no longer be notified
 969  *
 970  * @exception IllegalArgumentException <ul>
 971  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 972  * </ul>
 973  *
 974  * @exception SWTException <ul>
 975  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 976  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
 977  * </ul>
 978  *
 979  * @since 3.0
 980  */
 981 public void removeProgressListener (ProgressListener listener) {
 982         checkWidget();
 983         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 984         webBrowser.removeProgressListener (listener);
 985 }
 986
 987 /**
 988  * Removes the listener from the collection of listeners who will
 989  * be notified when the status text is changed.
 990  *
 991  * @param listener the listener which should no longer be notified
 992  *
 993  * @exception IllegalArgumentException <ul>
 994  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
 995  * </ul>
 996  *
 997  * @exception SWTException <ul>
 998  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
 999  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
1000  * </ul>
1001  *
1002  * @since 3.0
1003  */
1004 public void removeStatusTextListener (StatusTextListener listener) {
1005         checkWidget();
1006         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
1007         webBrowser.removeStatusTextListener (listener);
1008 }
1009
1010 /**
1011  * Removes the listener from the collection of listeners who will
1012  * be notified when the title of the current document is available
1013  * or has changed.
1014  *
1015  * @param listener the listener which should no longer be notified
1016  *
1017  * @exception IllegalArgumentException <ul>
1018  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
1019  * </ul>
1020  *
1021  * @exception SWTException <ul>
1022  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
1023  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
1024  * </ul>
1025  *
1026  * @since 3.0
1027  */
1028 public void removeTitleListener (TitleListener listener) {
1029         checkWidget();
1030         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
1031         webBrowser.removeTitleListener (listener);
1032 }
1033
1034 /**
1035  * Removes the listener from the collection of listeners who will
1036  * be notified when a window hosting the receiver needs to be displayed
1037  * or hidden.
1038  *
1039  * @param listener the listener which should no longer be notified
1040  *
1041  * @exception IllegalArgumentException <ul>
1042  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
1043  * </ul>
1044  *
1045  * @exception SWTException <ul>
1046  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
1047  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
1048  * </ul>
1049  *
1050  * @since 3.0
1051  */
1052 public void removeVisibilityWindowListener (VisibilityWindowListener listener) {
1053         checkWidget();
1054         if (listener == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
1055         webBrowser.removeVisibilityWindowListener (listener);
1056 }
1057
1058 /**
1059  * Sets whether javascript will be allowed to run in pages subsequently
1060  * viewed in the receiver.  Note that setting this value does not affect
1061  * the running of javascript in the current page.
1062  *
1063  * @param enabled the receiver's new javascript enabled state
1064  *
1065  * @exception SWTException <ul>
1066  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
1067  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
1068  * </ul>
1069  *
1070  * @since 3.5
1071  */
1072 public void setJavascriptEnabled (boolean enabled) {
1073         checkWidget();
1074         webBrowser.jsEnabledOnNextPage = enabled;
1075 }
1076
1077 /**
1078  * Renders a string containing HTML.  The rendering of the content occurs asynchronously.
1079  * The rendered page will be given trusted permissions; to render the page with untrusted
1080  * permissions use <code>setText(String html, boolean trusted)</code> instead.
1081  * <p>
1082  * The html parameter is Unicode-encoded since it is a java <code>String</code>.
1083  * As a result, the HTML meta tag charset should not be set. The charset is implied
1084  * by the <code>String</code> itself.
1085  *
1086  * @param html the HTML content to be rendered
1087  *
1088  * @return true if the operation was successful and false otherwise.
1089  *
1090  * @exception IllegalArgumentException <ul>
1091  *    <li>ERROR_NULL_ARGUMENT - if the html is null</li>
1092  * </ul>
1093  *
1094  * @exception SWTException <ul>
1095  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
1096  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
1097  * </ul>
1098  *
1099  * @see #setText(String,boolean)
1100  * @see #setUrl
1101  *
1102  * @since 3.0
1103  */
1104 public boolean setText (String html) {
1105         checkWidget();
1106         return setText (html, true);
1107 }
1108
1109 /**
1110  * Renders a string containing HTML.  The rendering of the content occurs asynchronously.
1111  * The rendered page can be given either trusted or untrusted permissions.
1112  * <p>
1113  * The <code>html</code> parameter is Unicode-encoded since it is a java <code>String</code>.
1114  * As a result, the HTML meta tag charset should not be set. The charset is implied
1115  * by the <code>String</code> itself.
1116  * <p>
1117  * The <code>trusted</code> parameter affects the permissions that will be granted to the rendered
1118  * page.  Specifying <code>true</code> for trusted gives the page permissions equivalent
1119  * to a page on the local file system, while specifying <code>false</code> for trusted
1120  * gives the page permissions equivalent to a page from the internet.  Page content should
1121  * be specified as trusted if the invoker created it or trusts its source, since this would
1122  * allow (for instance) style sheets on the local file system to be referenced.  Page
1123  * content should be specified as untrusted if its source is not trusted or is not known.
1124  *
1125  * @param html the HTML content to be rendered
1126  * @param trusted <code>false</code> if the rendered page should be granted restricted
1127  * permissions and <code>true</code> otherwise
1128  *
1129  * @return <code>true</code> if the operation was successful and <code>false</code> otherwise.
1130  *
1131  * @exception IllegalArgumentException <ul>
1132  *    <li>ERROR_NULL_ARGUMENT - if the html is null</li>
1133  * </ul>
1134  *
1135  * @exception SWTException <ul>
1136  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
1137  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
1138  * </ul>
1139  *
1140  * @see #setText(String)
1141  * @see #setUrl
1142  *
1143  * @since 3.6
1144  */
1145 public boolean setText (String html, boolean trusted) {
1146         checkWidget();
1147         if (html == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
1148         return webBrowser.setText (html, trusted);
1149 }
1150
1151 /**
1152  * Begins loading a URL.  The loading of its content occurs asynchronously.
1153  *
1154  * @param url the URL to be loaded
1155  *
1156  * @return true if the operation was successful and false otherwise.
1157  *
1158  * @exception IllegalArgumentException <ul>
1159  *    <li>ERROR_NULL_ARGUMENT - if the url is null</li>
1160  * </ul>
1161  *
1162  * @exception SWTException <ul>
1163  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
1164  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
1165  * </ul>
1166  *
1167  * @see #getUrl
1168  * @see #setUrl(String,String,String[])
1169  *
1170  * @since 3.0
1171  */
1172 public boolean setUrl (String url) {
1173         checkWidget();
1174         return setUrl (url, null, null);
1175 }
1176
1177 /**
1178  * Begins loading a URL.  The loading of its content occurs asynchronously.
1179  * <p>
1180  * If the URL causes an HTTP request to be initiated then the provided
1181  * <code>postData</code> and <code>header</code> arguments, if any, are
1182  * sent with the request.  A value in the <code>headers</code> argument
1183  * must be a name-value pair with a colon separator in order to be sent
1184  * (for example: "<code>user-agent: custom</code>").
1185  *
1186  * @param url the URL to be loaded
1187  * @param postData post data to be sent with the request, or <code>null</code>
1188  * @param headers header lines to be sent with the request, or <code>null</code>
1189  *
1190  * @return <code>true</code> if the operation was successful and <code>false</code> otherwise.
1191  *
1192  * @exception IllegalArgumentException <ul>
1193  *    <li>ERROR_NULL_ARGUMENT - if the url is null</li>
1194  * </ul>
1195  *
1196  * @exception SWTException <ul>
1197  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
1198  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
1199  * </ul>
1200  *
1201  * @since 3.6
1202  */
1203 public boolean setUrl (String url, String postData, String[] headers) {
1204         checkWidget();
1205         if (url == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
1206         return webBrowser.setUrl (url, postData, headers);
1207 }
1208
1209 /**
1210  * Stop any loading and rendering activity.
1211  *
1212  * @exception SWTException <ul>
1213  *    <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
1214  *    <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
1215  * </ul>
1216  *
1217  * @since 3.0
1218  */
1219 public void stop () {
1220         checkWidget();
1221         webBrowser.stop ();
1222 }
1223 }