KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > swt > widgets > 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 JavaDoc 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 JavaDoc 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 JavaDoc string) {
245     if (string == null) error (SWT.ERROR_NULL_ARGUMENT);
246     title = string;
247 }
248
249 }
250
Popular Tags