bundles/org.eclipse.swt.win32.win32.x86_64/src/org/eclipse/swt/widgets/Dialog.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2011 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.widgets;
  15
  16
  17 import org.eclipse.swt.*;
  18
  19 /**
  20  * This class is the abstract superclass of the classes
  21  * that represent the built in platform dialogs.
  22  * A <code>Dialog</code> typically contains other widgets
  23  * that are not accessible. A <code>Dialog</code> is not
  24  * a <code>Widget</code>.
  25  * <p>
  26  * This class can also be used as the abstract superclass
  27  * for user-designed dialogs. Such dialogs usually consist
  28  * of a Shell with child widgets. The basic template for a
  29  * user-defined dialog typically looks something like this:</p>
  30  * <pre><code>
  31  * public class MyDialog extends Dialog {
  32  *      Object result;
  33  *
  34  *      public MyDialog (Shell parent, int style) {
  35  *              super (parent, style);
  36  *      }
  37  *      public MyDialog (Shell parent) {
  38  *              this (parent, 0); // your default style bits go here (not the Shell's style bits)
  39  *      }
  40  *      public Object open () {
  41  *              Shell parent = getParent();
  42  *              Shell shell = new Shell(parent, SWT.DIALOG_TRIM | SWT.APPLICATION_MODAL);
  43  *              shell.setText(getText());
  44  *              // Your code goes here (widget creation, set result, etc).
  45  *              shell.open();
  46  *              Display display = parent.getDisplay();
  47  *              while (!shell.isDisposed()) {
  48  *                      if (!display.readAndDispatch()) display.sleep();
  49  *              }
  50  *              return result;
  51  *      }
  52  * }
  53  * </code></pre>
  54  * <p>
  55  * Note: The <em>modality</em> styles supported by this class
  56  * are treated as <em>HINT</em>s, because not all are supported
  57  * by every subclass on every platform. If a modality style is
  58  * not supported, it is "upgraded" to a more restrictive modality
  59  * style that is supported.  For example, if <code>PRIMARY_MODAL</code>
  60  * is not supported by a particular dialog, it would be upgraded to
  61  * <code>APPLICATION_MODAL</code>. In addition, as is the case
  62  * for shells, the window manager for the desktop on which the
  63  * instance is visible has ultimate control over the appearance
  64  * and behavior of the instance, including its modality.
  65  * </p>
  66  * <dl>
  67  * <dt><b>Styles:</b></dt>
  68  * <dd>APPLICATION_MODAL, PRIMARY_MODAL, SYSTEM_MODAL, SHEET</dd>
  69  * <dt><b>Events:</b></dt>
  70  * <dd>(none)</dd>
  71  * </dl>
  72  * <p>
  73  * Note: Only one of the styles APPLICATION_MODAL, PRIMARY_MODAL,
  74  * and SYSTEM_MODAL may be specified.
  75  * </p>
  76  *
  77  * @see Shell
  78  * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a>
  79  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  80  */
  81
  82 public abstract class Dialog {
  83         int style;
  84         Shell parent;
  85         String title;
  86
  87 /**
  88  * Constructs a new instance of this class given only its
  89  * parent.
  90  *
  91  * @param parent a shell which will be the parent of the new instance
  92  *
  93  * @exception IllegalArgumentException <ul>
  94  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
  95  * </ul>
  96  * @exception SWTException <ul>
  97  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
  98  * </ul>
  99  */
 100 public Dialog (Shell parent) {
 101         this (parent, SWT.PRIMARY_MODAL);
 102 }
 103
 104 /**
 105  * Constructs a new instance of this class given its parent
 106  * and a style value describing its behavior and appearance.
 107  * <p>
 108  * The style value is either one of the style constants defined in
 109  * class <code>SWT</code> which is applicable to instances of this
 110  * class, or must be built by <em>bitwise OR</em>'ing together
 111  * (that is, using the <code>int</code> "|" operator) two or more
 112  * of those <code>SWT</code> style constants. The class description
 113  * lists the style constants that are applicable to the class.
 114  * Style bits are also inherited from superclasses.
 115  *
 116  * @param parent a shell which will be the parent of the new instance
 117  * @param style the style of dialog to construct
 118  *
 119  * @exception IllegalArgumentException <ul>
 120  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
 121  * </ul>
 122  * @exception SWTException <ul>
 123  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
 124  * </ul>
 125  *
 126  * @see SWT#PRIMARY_MODAL
 127  * @see SWT#APPLICATION_MODAL
 128  * @see SWT#SYSTEM_MODAL
 129  */
 130 public Dialog (Shell parent, int style) {
 131         checkParent (parent);
 132         this.parent = parent;
 133         this.style = style;
 134         title = "";
 135 }
 136
 137 /**
 138  * Checks that this class can be subclassed.
 139  * <p>
 140  * IMPORTANT: See the comment in <code>Widget.checkSubclass()</code>.
 141  * </p>
 142  *
 143  * @exception SWTException <ul>
 144  *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
 145  * </ul>
 146  *
 147  * @see Widget#checkSubclass
 148  */
 149 protected void checkSubclass () {
 150         if (!Display.isValidClass (getClass ())) {
 151                 error (SWT.ERROR_INVALID_SUBCLASS);
 152         }
 153 }
 154
 155 /**
 156  * Throws an exception if the specified widget can not be
 157  * used as a parent for the receiver.
 158  *
 159  * @exception IllegalArgumentException <ul>
 160  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
 161  *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
 162  * </ul>
 163  * @exception SWTException <ul>
 164  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
 165  * </ul>
 166  */
 167 void checkParent (Shell parent) {
 168         if (parent == null) error (SWT.ERROR_NULL_ARGUMENT);
 169         parent.checkWidget ();
 170 }
 171
 172 static int checkStyle (Shell parent, int style) {
 173         int mask = SWT.PRIMARY_MODAL | SWT.APPLICATION_MODAL | SWT.SYSTEM_MODAL;
 174         if ((style & SWT.SHEET) != 0) {
 175                 style &= ~SWT.SHEET;
 176                 if ((style & mask) == 0) {
 177                         style |= parent == null ? SWT.APPLICATION_MODAL : SWT.PRIMARY_MODAL;
 178                 }
 179         }
 180         if ((style & mask) == 0) {
 181                 style |= SWT.APPLICATION_MODAL;
 182         }
 183         style &= ~SWT.MIRRORED;
 184         if ((style & (SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT)) == 0) {
 185                 if (parent != null) {
 186                         if ((parent.style & SWT.LEFT_TO_RIGHT) != 0) style |= SWT.LEFT_TO_RIGHT;
 187                         if ((parent.style & SWT.RIGHT_TO_LEFT) != 0) style |= SWT.RIGHT_TO_LEFT;
 188                 }
 189         }
 190         return Widget.checkBits (style, SWT.LEFT_TO_RIGHT, SWT.RIGHT_TO_LEFT, 0, 0, 0, 0);
 191 }
 192
 193 /**
 194  * Does whatever dialog specific cleanup is required, and then
 195  * uses the code in <code>SWTError.error</code> to handle the error.
 196  *
 197  * @param code the descriptive error code
 198  *
 199  * @see SWT#error(int)
 200  */
 201 void error (int code) {
 202         SWT.error(code);
 203 }
 204
 205 /**
 206  * Returns the receiver's parent, which must be a <code>Shell</code>
 207  * or null.
 208  *
 209  * @return the receiver's parent
 210  *
 211  * @exception SWTException <ul>
 212  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
 213  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 214  * </ul>
 215  */
 216 public Shell getParent () {
 217         return parent;
 218 }
 219
 220 /**
 221  * Returns the receiver's style information.
 222  * <p>
 223  * Note that, the value which is returned by this method <em>may
 224  * not match</em> the value which was provided to the constructor
 225  * when the receiver was created.
 226  * </p>
 227  *
 228  * @return the style bits
 229  *
 230  * @exception SWTException <ul>
 231  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
 232  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 233  * </ul>
 234  */
 235 public int getStyle () {
 236         return style;
 237 }
 238
 239 /**
 240  * Returns the receiver's text, which is the string that the
 241  * window manager will typically display as the receiver's
 242  * <em>title</em>. If the text has not previously been set,
 243  * returns an empty string.
 244  *
 245  * @return the text
 246  *
 247  * @exception SWTException <ul>
 248  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
 249  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 250  * </ul>
 251  */
 252 public String getText () {
 253         return title;
 254 }
 255
 256 /**
 257  * Sets the receiver's text, which is the string that the
 258  * window manager will typically display as the receiver's
 259  * <em>title</em>, to the argument, which must not be null.
 260  *
 261  * @param string the new text
 262  *
 263  * @exception IllegalArgumentException <ul>
 264  *    <li>ERROR_NULL_ARGUMENT - if the text is null</li>
 265  * </ul>
 266  * @exception SWTException <ul>
 267  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
 268  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
 269  * </ul>
 270  */
 271 public void setText (String string) {
 272         if (string == null) error (SWT.ERROR_NULL_ARGUMENT);
 273         title = string;
 274 }
 275
 276 }