Mercurial > projects > dwt-mac

comparison dwt/widgets/Dialog.d @ 0:380af2bdd8e5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Upload of whole dwt tree
author Jacob Carlborg <doob@me.com> <jacob.carlborg@gmail.com>
date Sat, 09 Aug 2008 17:00:02 +0200
parents
children 1a8b3cb347e0 2952d5604c0a
comparison
equal deleted inserted replaced
-1:000000000000 0:380af2bdd8e5
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 module dwt.widgets.Dialog;
12
13 import dwt.dwthelper.utils;
14
15
16 import dwt.DWT;
17 import dwt.DWTException;
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:
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, DWT.DIALOG_TRIM | DWT.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 * </pre></code>
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 * <dl>
66 * <dt><b>Styles:</b></dt>
67 * <dd>APPLICATION_MODAL, PRIMARY_MODAL, SYSTEM_MODAL</dd>
68 * <dt><b>Events:</b></dt>
69 * <dd>(none)</dd>
70 * </dl>
71 * <p>
72 * Note: Only one of the styles APPLICATION_MODAL, PRIMARY_MODAL,
73 * and SYSTEM_MODAL may be specified.
74 * </p>
75 *
76 * @see Shell
77 */
78
79 public abstract class Dialog {
80 int style;
81 Shell parent;
82 String title;
83
84 /**
85 * Constructs a new instance of this class given only its
86 * parent.
87 *
88 * @param parent a shell which will be the parent of the new instance
89 *
90 * @exception IllegalArgumentException <ul>
91 * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
92 * </ul>
93 * @exception DWTException <ul>
94 * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
95 * </ul>
96 */
97 public Dialog (Shell parent) {
98 this (parent, DWT.PRIMARY_MODAL);
99 }
100
101 /**
102 * Constructs a new instance of this class given its parent
103 * and a style value describing its behavior and appearance.
104 * <p>
105 * The style value is either one of the style constants defined in
106 * class <code>DWT</code> which is applicable to instances of this
107 * class, or must be built by <em>bitwise OR</em>'ing together
108 * (that is, using the <code>int</code> "|" operator) two or more
109 * of those <code>DWT</code> style constants. The class description
110 * lists the style constants that are applicable to the class.
111 * Style bits are also inherited from superclasses.
112 *
113 * @param parent a shell which will be the parent of the new instance
114 * @param style the style of dialog to construct
115 *
116 * @exception IllegalArgumentException <ul>
117 * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
118 * </ul>
119 * @exception DWTException <ul>
120 * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
121 * </ul>
122 *
123 * @see DWT#PRIMARY_MODAL
124 * @see DWT#APPLICATION_MODAL
125 * @see DWT#SYSTEM_MODAL
126 */
127 public Dialog (Shell parent, int style) {
128 checkParent (parent);
129 this.parent = parent;
130 this.style = style;
131 title = "";
132 }
133
134 /**
135 * Checks that this class can be subclassed.
136 * <p>
137 * IMPORTANT: See the comment in <code>Widget.checkSubclass()</code>.
138 * </p>
139 *
140 * @exception DWTException <ul>
141 * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
142 * </ul>
143 *
144 * @see Widget#checkSubclass
145 */
146 protected void checkSubclass () {
147 if (!Display.isValidClass (getClass ())) {
148 error (DWT.ERROR_INVALID_SUBCLASS);
149 }
150 }
151
152 /**
153 * Throws an exception if the specified widget can not be
154 * used as a parent for the receiver.
155 *
156 * @exception IllegalArgumentException <ul>
157 * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
158 * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
159 * </ul>
160 * @exception DWTException <ul>
161 * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
162 * </ul>
163 */
164 void checkParent (Shell parent) {
165 if (parent is null) error (DWT.ERROR_NULL_ARGUMENT);
166 parent.checkWidget ();
167 }
168
169 static int checkStyle (Shell parent, int style) {
170 style &= ~DWT.MIRRORED;
171 if ((style & (DWT.LEFT_TO_RIGHT | DWT.RIGHT_TO_LEFT)) is 0) {
172 if (parent !is null) {
173 if ((parent.style & DWT.LEFT_TO_RIGHT) !is 0) style |= DWT.LEFT_TO_RIGHT;
174 if ((parent.style & DWT.RIGHT_TO_LEFT) !is 0) style |= DWT.RIGHT_TO_LEFT;
175 }
176 }
177 return Widget.checkBits (style, DWT.LEFT_TO_RIGHT, DWT.RIGHT_TO_LEFT, 0, 0, 0, 0);
178 }
179
180 /**
181 * Does whatever dialog specific cleanup is required, and then
182 * uses the code in <code>DWTError.error</code> to handle the error.
183 *
184 * @param code the descriptive error code
185 *
186 * @see DWT#error(int)
187 */
188 void error (int code) {
189 DWT.error(code);
190 }
191
192 /**
193 * Returns the receiver's parent, which must be a <code>Shell</code>
194 * or null.
195 *
196 * @return the receiver's parent
197 *
198 * @exception DWTException <ul>
199 * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
200 * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
201 * </ul>
202 */
203 public Shell getParent () {
204 return parent;
205 }
206
207 /**
208 * Returns the receiver's style information.
209 * <p>
210 * Note that, the value which is returned by this method <em>may
211 * not match</em> the value which was provided to the constructor
212 * when the receiver was created.
213 * </p>
214 *
215 * @return the style bits
216 *
217 * @exception DWTException <ul>
218 * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
219 * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
220 * </ul>
221 */
222 public int getStyle () {
223 return style;
224 }
225
226 /**
227 * Returns the receiver's text, which is the string that the
228 * window manager will typically display as the receiver's
229 * <em>title</em>. If the text has not previously been set,
230 * returns an empty string.
231 *
232 * @return the text
233 *
234 * @exception DWTException <ul>
235 * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
236 * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
237 * </ul>
238 */
239 public String getText () {
240 return title;
241 }
242
243 /**
244 * Sets the receiver's text, which is the string that the
245 * window manager will typically display as the receiver's
246 * <em>title</em>, to the argument, which must not be null.
247 *
248 * @param string the new text
249 *
250 * @exception IllegalArgumentException <ul>
251 * <li>ERROR_NULL_ARGUMENT - if the text is null</li>
252 * </ul>
253 * @exception DWTException <ul>
254 * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
255 * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
256 * </ul>
257 */
258 public void setText (String string) {
259 if (string is null) error (DWT.ERROR_NULL_ARGUMENT);
260 title = string;
261 }
262
263 }