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

   1 /*******************************************************************************
   2  * Copyright (c) 2003, 2009 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.events.*;
  17 import org.eclipse.swt.graphics.*;
  18 import org.eclipse.swt.widgets.*;
  19
  20 /**
  21  * A <code>WindowEvent</code> is sent by a {@link Browser} when
  22  * a new window needs to be created or when an existing window needs to be
  23  * closed. This notification occurs when a javascript command such as
  24  * <code>window.open</code> or <code>window.close</code> gets executed by
  25  * a <code>Browser</code>.
  26  *
  27  * <p>
  28  * The following example shows how <code>WindowEvent</code>'s are typically
  29  * handled.</p>
  30  *
  31  * <pre><code>
  32  *      public static void main(String[] args) {
  33  *              Display display = new Display();
  34  *              Shell shell = new Shell(display);
  35  *              shell.setText("Main Window");
  36  *              shell.setLayout(new FillLayout());
  37  *              Browser browser = new Browser(shell, SWT.NONE);
  38  *              initialize(display, browser);
  39  *              shell.open();
  40  *              browser.setUrl("http://www.eclipse.org");
  41  *              while (!shell.isDisposed()) {
  42  *                      if (!display.readAndDispatch())
  43  *                              display.sleep();
  44  *              }
  45  *              display.dispose();
  46  *      }
  47  *
  48  *      static void initialize(final Display display, Browser browser) {
  49  *              browser.addOpenWindowListener(new OpenWindowListener() {
  50  *                      public void open(WindowEvent event) {
  51  *                              // Certain platforms can provide a default full browser.
  52  *                              // simply return in that case if the application prefers
  53  *                              // the default full browser to the embedded one set below.
  54  *                              if (!event.required) return;
  55  *
  56  *                              // Embed the new window
  57  *                              Shell shell = new Shell(display);
  58  *                              shell.setText("New Window");
  59  *                              shell.setLayout(new FillLayout());
  60  *                              Browser browser = new Browser(shell, SWT.NONE);
  61  *                              initialize(display, browser);
  62  *                              event.browser = browser;
  63  *                      }
  64  *              });
  65  *              browser.addVisibilityWindowListener(new VisibilityWindowListener() {
  66  *                      public void hide(WindowEvent event) {
  67  *                              Browser browser = (Browser)event.widget;
  68  *                              Shell shell = browser.getShell();
  69  *                              shell.setVisible(false);
  70  *                      }
  71  *                      public void show(WindowEvent event) {
  72  *                              Browser browser = (Browser)event.widget;
  73  *                              Shell shell = browser.getShell();
  74  *                              if (event.location != null) shell.setLocation(event.location);
  75  *                              if (event.size != null) {
  76  *                                      Point size = event.size;
  77  *                                      shell.setSize(shell.computeSize(size.x, size.y));
  78  *                              }
  79  *                              if (event.addressBar || event.menuBar || event.statusBar || event.toolBar) {
  80  *                                      // Create widgets for the address bar, menu bar, status bar and/or tool bar
  81  *                                      // leave enough space in the Shell to accommodate a Browser of the size
  82  *                                      // given by event.size
  83  *                              }
  84  *                              shell.open();
  85  *                      }
  86  *              });
  87  *              browser.addCloseWindowListener(new CloseWindowListener() {
  88  *                      public void close(WindowEvent event) {
  89  *                              Browser browser = (Browser)event.widget;
  90  *                              Shell shell = browser.getShell();
  91  *                              shell.close();
  92  *                      }
  93  *              });
  94  *      }
  95  * </code></pre>
  96  *
  97  * The following notifications are emitted when the user selects a hyperlink that targets a new window
  98  * or as the result of a javascript that executes window.open.
  99  *
 100  * <p>Main Browser</p>
 101  * <ul>
 102  *    <li>User selects a link that opens in a new window or javascript requests a new window</li>
 103  *    <li>OpenWindowListener.open() notified
 104  *    <ul>
 105  *              <li>Application creates a new Shell and a second Browser inside that Shell</li>
 106  *              <li>Application registers WindowListener's on that second Browser, such as VisibilityWindowListener</li>
 107  *              <li>Application returns the second Browser as the host for the new window content</li>
 108  *    </ul>
 109  *    </li>
 110  * </ul>
 111  *
 112  * <p>Second Browser</p>
 113  * <ul>
 114  *    <li>VisibilityWindowListener.show() notified
 115  *    <ul>
 116  *              <li>Application sets navigation tool bar, status bar, menu bar and Shell size
 117  *              <li>Application makes the Shell hosting the second Browser visible
 118  *              <li>User now sees the new window
 119  *    </ul>
 120  *    </li>
 121  * </ul>
 122  *
 123  * @see CloseWindowListener
 124  * @see OpenWindowListener
 125  * @see VisibilityWindowListener
 126  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
 127  *
 128  * @since 3.0
 129  */
 130 public class WindowEvent extends TypedEvent {
 131
 132         /**
 133          * Specifies whether the platform requires the user to provide a
 134          * <code>Browser</code> to handle the new window.
 135          *
 136          * @since 3.1
 137          */
 138         public boolean required;
 139
 140
 141         /**
 142          * <code>Browser</code> provided by the application.
 143          */
 144         public Browser browser;
 145
 146         /**
 147          * Requested location for the <code>Shell</code> hosting the <code>Browser</code>.
 148          * It is <code>null</code> if no location has been requested.
 149          */
 150         public Point location;
 151
 152         /**
 153          * Requested <code>Browser</code> size. The client area of the <code>Shell</code>
 154          * hosting the <code>Browser</code> should be large enough to accommodate that size.
 155          * It is <code>null</code> if no size has been requested.
 156          */
 157         public Point size;
 158
 159         /**
 160          * Specifies whether the <code>Shell</code> hosting the <code>Browser</code> should
 161          * display an address bar.
 162          *
 163          * @since 3.1
 164          */
 165         public boolean addressBar;
 166
 167         /**
 168          * Specifies whether the <code>Shell</code> hosting the <code>Browser</code> should
 169          * display a menu bar.  Note that this is always <code>true</code> on OS X.
 170          *
 171          * @since 3.1
 172          */
 173         public boolean menuBar;
 174
 175         /**
 176          * Specifies whether the <code>Shell</code> hosting the <code>Browser</code> should
 177          * display a status bar.
 178          *
 179          * @since 3.1
 180          */
 181         public boolean statusBar;
 182
 183         /**
 184          * Specifies whether the <code>Shell</code> hosting the <code>Browser</code> should
 185          * display a tool bar.
 186          *
 187          * @since 3.1
 188          */
 189         public boolean toolBar;
 190
 191         static final long serialVersionUID = 3617851997387174969L;
 192
 193 /**
 194  * Constructs a new instance of this class.
 195  *
 196  * @param widget the widget that fired the event
 197  *
 198  * @since 3.5
 199  */
 200 public WindowEvent(Widget widget) {
 201         super(widget);
 202 }
 203
 204 /**
 205  * Returns a string containing a concise, human-readable
 206  * description of the receiver.
 207  *
 208  * @return a string representation of the event
 209  */
 210 @Override
 211 public String toString() {
 212         String string = super.toString ();
 213         return string.substring (0, string.length() - 1) // remove trailing '}'
 214                 + " required=" + required
 215                 + " browser=" + browser
 216                 + " location=" + location
 217                 + " size=" + size
 218                 + " addressBar=" + addressBar
 219                 + " menuBar=" + menuBar
 220                 + " statusBar=" + statusBar
 221                 + " toolBar=" + toolBar
 222                 + "}";
 223 }
 224 }