KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > dialogs > DialogPage


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 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.jface.dialogs;
12
13 import org.eclipse.jface.resource.ImageDescriptor;
14 import org.eclipse.jface.resource.JFaceResources;
15 import org.eclipse.swt.SWT;
16 import org.eclipse.swt.graphics.Font;
17 import org.eclipse.swt.graphics.FontMetrics;
18 import org.eclipse.swt.graphics.GC;
19 import org.eclipse.swt.graphics.Image;
20 import org.eclipse.swt.graphics.Point;
21 import org.eclipse.swt.layout.GridData;
22 import org.eclipse.swt.widgets.Button;
23 import org.eclipse.swt.widgets.Control;
24 import org.eclipse.swt.widgets.Shell;
25
26 /**
27  * Abstract base implementation of a dialog page. All dialog pages are
28  * subclasses of this one.
29  */

30 public abstract class DialogPage implements IDialogPage, IMessageProvider {
31     /**
32      * The control for this dialog page.
33      */

34     private Control control;
35
36     /**
37      * Optional title; <code>null</code> if none.
38      *
39      * @see #setTitle
40      */

41     private String JavaDoc title = null;
42
43     /**
44      * Optional description; <code>null</code> if none.
45      *
46      * @see #setDescription
47      */

48     private String JavaDoc description = null;
49
50     /**
51      * Cached image; <code>null</code> if none.
52      *
53      * @see #setImageDescriptor(ImageDescriptor)
54      */

55     private Image image = null;
56
57     /**
58      * Optional image; <code>null</code> if none.
59      *
60      * @see #setImageDescriptor(ImageDescriptor)
61      */

62     private ImageDescriptor imageDescriptor = null;
63
64     /**
65      * The current message; <code>null</code> if none.
66      */

67     private String JavaDoc message = null;
68
69     /**
70      * The current message type; default value <code>NONE</code>.
71      */

72     private int messageType = NONE;
73
74     /**
75      * The current error message; <code>null</code> if none.
76      */

77     private String JavaDoc errorMessage = null;
78
79     /**
80      * Font metrics to use for determining pixel sizes.
81      */

82     private FontMetrics fontMetrics;
83
84     /**
85      * Creates a new empty dialog page.
86      */

87     protected DialogPage() {
88         //No initial behaviour
89
}
90
91     /**
92      * Creates a new dialog page with the given title.
93      *
94      * @param title
95      * the title of this dialog page, or <code>null</code> if none
96      */

97     protected DialogPage(String JavaDoc title) {
98         this.title = title;
99     }
100
101     /**
102      * Creates a new dialog page with the given title and image.
103      *
104      * @param title
105      * the title of this dialog page, or <code>null</code> if none
106      * @param image
107      * the image for this dialog page, or <code>null</code> if none
108      */

109     protected DialogPage(String JavaDoc title, ImageDescriptor image) {
110         this(title);
111         imageDescriptor = image;
112     }
113
114     /**
115      * Returns the number of pixels corresponding to the height of the given
116      * number of characters.
117      * <p>
118      * This method may only be called after <code>initializeDialogUnits</code>
119      * has been called.
120      * </p>
121      * <p>
122      * Clients may call this framework method, but should not override it.
123      * </p>
124      *
125      * @param chars
126      * the number of characters
127      * @return the number of pixels
128      */

129     protected int convertHeightInCharsToPixels(int chars) {
130         // test for failure to initialize for backward compatibility
131
if (fontMetrics == null) {
132             return 0;
133         }
134         return Dialog.convertHeightInCharsToPixels(fontMetrics, chars);
135     }
136
137     /**
138      * Returns the number of pixels corresponding to the given number of
139      * horizontal dialog units.
140      * <p>
141      * This method may only be called after <code>initializeDialogUnits</code>
142      * has been called.
143      * </p>
144      * <p>
145      * Clients may call this framework method, but should not override it.
146      * </p>
147      *
148      * @param dlus
149      * the number of horizontal dialog units
150      * @return the number of pixels
151      */

152     protected int convertHorizontalDLUsToPixels(int dlus) {
153         // test for failure to initialize for backward compatibility
154
if (fontMetrics == null) {
155             return 0;
156         }
157         return Dialog.convertHorizontalDLUsToPixels(fontMetrics, dlus);
158     }
159
160     /**
161      * Returns the number of pixels corresponding to the given number of
162      * vertical dialog units.
163      * <p>
164      * This method may only be called after <code>initializeDialogUnits</code>
165      * has been called.
166      * </p>
167      * <p>
168      * Clients may call this framework method, but should not override it.
169      * </p>
170      *
171      * @param dlus
172      * the number of vertical dialog units
173      * @return the number of pixels
174      */

175     protected int convertVerticalDLUsToPixels(int dlus) {
176         // test for failure to initialize for backward compatibility
177
if (fontMetrics == null) {
178             return 0;
179         }
180         return Dialog.convertVerticalDLUsToPixels(fontMetrics, dlus);
181     }
182
183     /**
184      * Returns the number of pixels corresponding to the width of the given
185      * number of characters.
186      * <p>
187      * This method may only be called after <code>initializeDialogUnits</code>
188      * has been called.
189      * </p>
190      * <p>
191      * Clients may call this framework method, but should not override it.
192      * </p>
193      *
194      * @param chars
195      * the number of characters
196      * @return the number of pixels
197      */

198     protected int convertWidthInCharsToPixels(int chars) {
199         // test for failure to initialize for backward compatibility
200
if (fontMetrics == null) {
201             return 0;
202         }
203         return Dialog.convertWidthInCharsToPixels(fontMetrics, chars);
204     }
205
206     /**
207      * The <code>DialogPage</code> implementation of an
208      * <code>IDialogPage</code> method does nothing. Subclasses may extend.
209      */

210     public void dispose() {
211         // deallocate SWT resources
212
if (image != null) {
213             image.dispose();
214             image = null;
215         }
216     }
217
218     /**
219      * Returns the top level control for this dialog page.
220      *
221      * @return the top level control
222      */

223     public Control getControl() {
224         return control;
225     }
226
227     /*
228      * (non-Javadoc) Method declared on IDialogPage.
229      */

230     public String JavaDoc getDescription() {
231         return description;
232     }
233
234     /**
235      * Returns the symbolic font name used by dialog pages.
236      *
237      * @return the symbolic font name
238      */

239     protected String JavaDoc getDialogFontName() {
240         return JFaceResources.DIALOG_FONT;
241     }
242
243     /*
244      * (non-Javadoc) Method declared on IDialogPage.
245      */

246     public String JavaDoc getErrorMessage() {
247         return errorMessage;
248     }
249
250     /**
251      * Returns the default font to use for this dialog page.
252      *
253      * @return the font
254      */

255     protected Font getFont() {
256         return JFaceResources.getFontRegistry().get(getDialogFontName());
257     }
258
259     /*
260      * (non-Javadoc) Method declared on IDialogPage.
261      */

262     public Image getImage() {
263         if (image == null) {
264             if (imageDescriptor != null) {
265                 image = imageDescriptor.createImage();
266             }
267         }
268         return image;
269     }
270
271     /*
272      * (non-Javadoc) Method declared on IDialogPage.
273      */

274     public String JavaDoc getMessage() {
275         return message;
276     }
277
278     /*
279      * (non-Javadoc) Method declared on IMessageProvider.
280      */

281     public int getMessageType() {
282         return messageType;
283     }
284
285     /**
286      * Returns this dialog page's shell. Convenience method for
287      * <code>getControl().getShell()</code>. This method may only be called
288      * after the page's control has been created.
289      *
290      * @return the shell
291      */

292     public Shell getShell() {
293         return getControl().getShell();
294     }
295
296     /*
297      * (non-Javadoc) Method declared on IDialogPage.
298      */

299     public String JavaDoc getTitle() {
300         return title;
301     }
302
303     /**
304      * Returns the tool tip text for the widget with the given id.
305      * <p>
306      * The default implementation of this framework method does nothing and
307      * returns <code>null</code>. Subclasses may override.
308      * </p>
309      *
310      * @param widgetId
311      * the id of the widget for which hover help is requested
312      * @return the tool tip text, or <code>null</code> if none
313      * @deprecated
314      */

315     protected final String JavaDoc getToolTipText(int widgetId) {
316         // return nothing by default
317
return null;
318     }
319
320     /**
321      * Initializes the computation of horizontal and vertical dialog units based
322      * on the size of current font.
323      * <p>
324      * This method must be called before any of the dialog unit based conversion
325      * methods are called.
326      * </p>
327      *
328      * @param testControl
329      * a control from which to obtain the current font
330      */

331     protected void initializeDialogUnits(Control testControl) {
332         // Compute and store a font metric
333
GC gc = new GC(testControl);
334         gc.setFont(JFaceResources.getDialogFont());
335         fontMetrics = gc.getFontMetrics();
336         gc.dispose();
337     }
338
339     /**
340      * Sets the <code>GridData</code> on the specified button to be one that
341      * is spaced for the current dialog page units. The method
342      * <code>initializeDialogUnits</code> must be called once before calling
343      * this method for the first time.
344      *
345      * @param button
346      * the button to set the <code>GridData</code>
347      * @return the <code>GridData</code> set on the specified button
348      */

349     protected GridData setButtonLayoutData(Button button) {
350         GridData data = new GridData(GridData.HORIZONTAL_ALIGN_FILL);
351         int widthHint = convertHorizontalDLUsToPixels(IDialogConstants.BUTTON_WIDTH);
352         Point minSize = button.computeSize(SWT.DEFAULT, SWT.DEFAULT, true);
353         data.widthHint = Math.max(widthHint, minSize.x);
354         button.setLayoutData(data);
355         return data;
356     }
357
358     /**
359      * Tests whether this page's UI content has already been created.
360      *
361      * @return <code>true</code> if the control has been created, and
362      * <code>false</code> if not
363      */

364     protected boolean isControlCreated() {
365         return control != null;
366     }
367
368     /**
369      * This default implementation of an <code>IDialogPage</code> method does
370      * nothing. Subclasses should override to take some action in response to a
371      * help request.
372      */

373     public void performHelp() {
374         //No default help
375
}
376
377     /**
378      * Set the control for the receiver.
379      * @param newControl
380      */

381     protected void setControl(Control newControl) {
382         control = newControl;
383     }
384
385     /*
386      * (non-Javadoc) Method declared on IDialogPage.
387      */

388     public void setDescription(String JavaDoc description) {
389         this.description = description;
390     }
391
392     /**
393      * Sets or clears the error message for this page.
394      *
395      * @param newMessage
396      * the message, or <code>null</code> to clear the error message
397      */

398     public void setErrorMessage(String JavaDoc newMessage) {
399         errorMessage = newMessage;
400     }
401
402     /*
403      * (non-Javadoc) Method declared on IDialogPage.
404      */

405     public void setImageDescriptor(ImageDescriptor desc) {
406         imageDescriptor = desc;
407         if (image != null) {
408             image.dispose();
409             image = null;
410         }
411     }
412
413     /**
414      * Sets or clears the message for this page.
415      * <p>
416      * This is a shortcut for <code>setMessage(newMesasge, NONE)</code>
417      * </p>
418      *
419      * @param newMessage
420      * the message, or <code>null</code> to clear the message
421      */

422     public void setMessage(String JavaDoc newMessage) {
423         setMessage(newMessage, NONE);
424     }
425
426     /**
427      * Sets the message for this page with an indication of what type of message
428      * it is.
429      * <p>
430      * The valid message types are one of <code>NONE</code>,
431      * <code>INFORMATION</code>,<code>WARNING</code>, or
432      * <code>ERROR</code>.
433      * </p>
434      * <p>
435      * Note that for backward compatibility, a message of type
436      * <code>ERROR</code> is different than an error message (set using
437      * <code>setErrorMessage</code>). An error message overrides the current
438      * message until the error message is cleared. This method replaces the
439      * current message and does not affect the error message.
440      * </p>
441      *
442      * @param newMessage
443      * the message, or <code>null</code> to clear the message
444      * @param newType
445      * the message type
446      * @since 2.0
447      */

448     public void setMessage(String JavaDoc newMessage, int newType) {
449         message = newMessage;
450         messageType = newType;
451     }
452
453     /**
454      * The <code>DialogPage</code> implementation of this
455      * <code>IDialogPage</code> method remembers the title in an internal
456      * state variable. Subclasses may extend.
457      */

458     public void setTitle(String JavaDoc title) {
459         this.title = title;
460     }
461
462     /**
463      * The <code>DialogPage</code> implementation of this
464      * <code>IDialogPage</code> method sets the control to the given
465      * visibility state. Subclasses may extend.
466      */

467     public void setVisible(boolean visible) {
468         control.setVisible(visible);
469     }
470 }
471
Popular Tags