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   title = null;
42  
43      /**
44       * Optional description; <code>null</code> if none.
45       * 
46       * @see #setDescription
47       */
48      private String   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   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   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   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   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   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   getDialogFontName() {
240         return JFaceResources.DIALOG_FONT;
241     }
242 
243     /*
244      * (non-Javadoc) Method declared on IDialogPage.
245      */
246     public String   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   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   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   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   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   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags