Dialog


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