MessageDialog


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 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.swt.SWT;
14  import org.eclipse.swt.custom.CLabel;
15  import org.eclipse.swt.graphics.Image;
16  import org.eclipse.swt.layout.GridData;
17  import org.eclipse.swt.layout.GridLayout;
18  import org.eclipse.swt.widgets.Button;
19  import org.eclipse.swt.widgets.Composite;
20  import org.eclipse.swt.widgets.Control;
21  import org.eclipse.swt.widgets.Label;
22  import org.eclipse.swt.widgets.Shell;
23  
24  /**
25   * A dialog for showing messages to the user.
26   * <p>
27   * This concrete dialog class can be instantiated as is, or further subclassed
28   * as required.
29   * </p>
30   */
31  public class MessageDialog extends IconAndMessageDialog {
32      /**
33       * Constant for a dialog with no image (value 0).
34       */
35      public final static int NONE = 0;
36  
37      /**
38       * Constant for a dialog with an error image (value 1).
39       */
40      public final static int ERROR = 1;
41  
42      /**
43       * Constant for a dialog with an info image (value 2).
44       */
45      public final static int INFORMATION = 2;
46  
47      /**
48       * Constant for a dialog with a question image (value 3).
49       */
50      public final static int QUESTION = 3;
51  
52      /**
53       * Constant for a dialog with a warning image (value 4).
54       */
55      public final static int WARNING = 4;
56  
57      /**
58       * Labels for buttons in the button bar (localized strings).
59       */
60      private String  [] buttonLabels;
61  
62      /**
63       * The buttons. Parallels <code>buttonLabels</code>.
64       */
65      private Button[] buttons;
66  
67      /**
68       * Index into <code>buttonLabels</code> of the default button.
69       */
70      private int defaultButtonIndex;
71  
72      /**
73       * Dialog title (a localized string).
74       */
75      private String   title;
76  
77      /**
78       * Dialog title image.
79       */
80      private Image titleImage;
81  
82      /**
83       * Image, or <code>null</code> if none.
84       */
85      private Image image = null;
86  
87      /**
88       * The custom dialog area.
89       */
90      private Control customArea;
91  
92      /**
93       * Create a message dialog. Note that the dialog will have no visual
94       * representation (no widgets) until it is told to open.
95       * <p>
96       * The labels of the buttons to appear in the button bar are supplied in
97       * this constructor as an array. The <code>open</code> method will return
98       * the index of the label in this array corresponding to the button that was
99       * pressed to close the dialog. If the dialog was dismissed without pressing
100      * a button (ESC, etc.) then -1 is returned. Note that the <code>open</code>
101      * method blocks.
102      * </p>
103      * 
104      * @param parentShell
105      *            the parent shell
106      * @param dialogTitle
107      *            the dialog title, or <code>null</code> if none
108      * @param dialogTitleImage
109      *            the dialog title image, or <code>null</code> if none
110      * @param dialogMessage
111      *            the dialog message
112      * @param dialogImageType
113      *            one of the following values:
114      *            <ul>
115      *            <li><code>MessageDialog.NONE</code> for a dialog with no
116      *            image</li>
117      *            <li><code>MessageDialog.ERROR</code> for a dialog with an
118      *            error image</li>
119      *            <li><code>MessageDialog.INFORMATION</code> for a dialog
120      *            with an information image</li>
121      *            <li><code>MessageDialog.QUESTION </code> for a dialog with a
122      *            question image</li>
123      *            <li><code>MessageDialog.WARNING</code> for a dialog with a
124      *            warning image</li>
125      *            </ul>
126      * @param dialogButtonLabels
127      *            an array of labels for the buttons in the button bar
128      * @param defaultIndex
129      *            the index in the button label array of the default button
130      */
131     public MessageDialog(Shell parentShell, String   dialogTitle,
132             Image dialogTitleImage, String   dialogMessage, int dialogImageType,
133             String  [] dialogButtonLabels, int defaultIndex) {
134         super(parentShell);
135         this.title = dialogTitle;
136         this.titleImage = dialogTitleImage;
137         this.message = dialogMessage;
138 
139         switch (dialogImageType) {
140         case ERROR: {
141             this.image = getErrorImage();
142             break;
143         }
144         case INFORMATION: {
145             this.image = getInfoImage();
146             break;
147         }
148         case QUESTION: {
149             this.image = getQuestionImage();
150             break;
151         }
152         case WARNING: {
153             this.image = getWarningImage();
154             break;
155         }
156         }
157         this.buttonLabels = dialogButtonLabels;
158         this.defaultButtonIndex = defaultIndex;
159     }
160 
161     /*
162      *  (non-Javadoc)
163      * @see org.eclipse.jface.dialogs.Dialog#buttonPressed(int)
164      */
165     protected void buttonPressed(int buttonId) {
166         setReturnCode(buttonId);
167         close();
168     }
169 
170     /*
171      *  (non-Javadoc)
172      * @see org.eclipse.jface.window.Window#configureShell(org.eclipse.swt.widgets.Shell)
173      */
174     protected void configureShell(Shell shell) {
175         super.configureShell(shell);
176         if (title != null) {
177             shell.setText(title);
178         }
179         if (titleImage != null) {
180             shell.setImage(titleImage);
181         }
182     }
183 
184     /*
185      * (non-Javadoc) Method declared on Dialog.
186      */
187     protected void createButtonsForButtonBar(Composite parent) {
188         buttons = new Button[buttonLabels.length];
189         for (int i = 0; i < buttonLabels.length; i++) {
190             String   label = buttonLabels[i];
191             Button button = createButton(parent, i, label,
192                     defaultButtonIndex == i);
193             buttons[i] = button;
194         }
195     }
196 
197     /**
198      * Creates and returns the contents of an area of the dialog which appears
199      * below the message and above the button bar.
200      * <p>
201      * The default implementation of this framework method returns
202      * <code>null</code>. Subclasses may override.
203      * </p>
204      * 
205      * @param parent
206      *            parent composite to contain the custom area
207      * @return the custom area control, or <code>null</code>
208      */
209     protected Control createCustomArea(Composite parent) {
210         return null;
211     }
212 
213     /**
214      * This implementation of the <code>Dialog</code> framework method creates
215      * and lays out a composite and calls <code>createMessageArea</code> and
216      * <code>createCustomArea</code> to populate it. Subclasses should
217      * override <code>createCustomArea</code> to add contents below the
218      * message.
219      */
220     protected Control createDialogArea(Composite parent) {
221         // create message area
222         createMessageArea(parent);
223         // create the top level composite for the dialog area
224         Composite composite = new Composite(parent, SWT.NONE);
225         GridLayout layout = new GridLayout();
226         layout.marginHeight = 0;
227         layout.marginWidth = 0;
228         composite.setLayout(layout);
229         GridData data = new GridData(GridData.FILL_BOTH);
230         data.horizontalSpan = 2;
231         composite.setLayoutData(data);
232         // allow subclasses to add custom controls
233         customArea = createCustomArea(composite);
234         //If it is null create a dummy label for spacing purposes
235         if (customArea == null) {
236             customArea = new Label(composite, SWT.NULL);
237         }
238         return composite;
239     }
240 
241     /**
242      * Gets a button in this dialog's button bar.
243      * 
244      * @param index
245      *            the index of the button in the dialog's button bar
246      * @return a button in the dialog's button bar
247      */
248     protected Button getButton(int index) {
249         return buttons[index];
250     }
251 
252     /**
253      * Returns the minimum message area width in pixels This determines the
254      * minimum width of the dialog.
255      * <p>
256      * Subclasses may override.
257      * </p>
258      * 
259      * @return the minimum message area width (in pixels)
260      */
261     protected int getMinimumMessageWidth() {
262         return convertHorizontalDLUsToPixels(IDialogConstants.MINIMUM_MESSAGE_AREA_WIDTH);
263     }
264 
265     /**
266      * Handle the shell close. Set the return code to <code>SWT.DEFAULT</code>
267      * as there has been no explicit close by the user.
268      * 
269      * @see org.eclipse.jface.window.Window#handleShellCloseEvent()
270      */
271     protected void handleShellCloseEvent() {
272         //Sets a return code of SWT.DEFAULT since none of the dialog buttons
273         // were pressed to close the dialog.
274         super.handleShellCloseEvent();
275         setReturnCode(SWT.DEFAULT);
276     }
277 
278     /**
279      * Convenience method to open a simple confirm (OK/Cancel) dialog.
280      * 
281      * @param parent
282      *            the parent shell of the dialog, or <code>null</code> if none
283      * @param title
284      *            the dialog's title, or <code>null</code> if none
285      * @param message
286      *            the message
287      * @return <code>true</code> if the user presses the OK button,
288      *         <code>false</code> otherwise
289      */
290     public static boolean openConfirm(Shell parent, String   title, String   message) {
291         MessageDialog dialog = new MessageDialog(parent, title, null, // accept
292                 // the
293                 // default
294                 // window
295                 // icon
296                 message, QUESTION, new String  [] { IDialogConstants.OK_LABEL,
297                         IDialogConstants.CANCEL_LABEL }, 0); // OK is the
298         // default
299         return dialog.open() == 0;
300     }
301 
302     /**
303      * Convenience method to open a standard error dialog.
304      * 
305      * @param parent
306      *            the parent shell of the dialog, or <code>null</code> if none
307      * @param title
308      *            the dialog's title, or <code>null</code> if none
309      * @param message
310      *            the message
311      */
312     public static void openError(Shell parent, String   title, String   message) {
313         MessageDialog dialog = new MessageDialog(parent, title, null, // accept
314                 // the
315                 // default
316                 // window
317                 // icon
318                 message, ERROR, new String  [] { IDialogConstants.OK_LABEL }, 0); // ok
319         // is
320         // the
321         // default
322         dialog.open();
323         return;
324     }
325 
326     /**
327      * Convenience method to open a standard information dialog.
328      * 
329      * @param parent
330      *            the parent shell of the dialog, or <code>null</code> if none
331      * @param title
332      *            the dialog's title, or <code>null</code> if none
333      * @param message
334      *            the message
335      */
336     public static void openInformation(Shell parent, String   title,
337             String   message) {
338         MessageDialog dialog = new MessageDialog(parent, title, null, // accept
339                 // the
340                 // default
341                 // window
342                 // icon
343                 message, INFORMATION,
344                 new String  [] { IDialogConstants.OK_LABEL }, 0);
345         // ok is the default
346         dialog.open();
347         return;
348     }
349 
350     /**
351      * Convenience method to open a simple Yes/No question dialog.
352      * 
353      * @param parent
354      *            the parent shell of the dialog, or <code>null</code> if none
355      * @param title
356      *            the dialog's title, or <code>null</code> if none
357      * @param message
358      *            the message
359      * @return <code>true</code> if the user presses the OK button,
360      *         <code>false</code> otherwise
361      */
362     public static boolean openQuestion(Shell parent, String   title,
363             String   message) {
364         MessageDialog dialog = new MessageDialog(parent, title, null, // accept
365                 // the
366                 // default
367                 // window
368                 // icon
369                 message, QUESTION, new String  [] { IDialogConstants.YES_LABEL,
370                         IDialogConstants.NO_LABEL }, 0); // yes is the default
371         return dialog.open() == 0;
372     }
373 
374     /**
375      * Convenience method to open a standard warning dialog.
376      * 
377      * @param parent
378      *            the parent shell of the dialog, or <code>null</code> if none
379      * @param title
380      *            the dialog's title, or <code>null</code> if none
381      * @param message
382      *            the message
383      */
384     public static void openWarning(Shell parent, String   title, String   message) {
385         MessageDialog dialog = new MessageDialog(parent, title, null, // accept
386                 // the
387                 // default
388                 // window
389                 // icon
390                 message, WARNING, new String  [] { IDialogConstants.OK_LABEL }, 0); // ok
391         // is
392         // the
393         // default
394         dialog.open();
395         return;
396     }
397 
398     /*
399      * @see org.eclipse.jface.dialogs.Dialog#createButton(org.eclipse.swt.widgets.Composite,
400      *      int, java.lang.String, boolean)
401      */
402     protected Button createButton(Composite parent, int id, String   label,
403             boolean defaultButton) {
404         Button button = super.createButton(parent, id, label, defaultButton);
405         //Be sure to set the focus if the custom area cannot so as not
406         //to lose the defaultButton.
407         if (defaultButton && !customShouldTakeFocus()) {
408             button.setFocus();
409         }
410         return button;
411     }
412 
413     /**
414      * Return whether or not we should apply the workaround where we take focus
415      * for the default button or if that should be determined by the dialog. By
416      * default only return true if the custom area is a label or CLabel that
417      * cannot take focus.
418      * 
419      * @return boolean
420      */
421     protected boolean customShouldTakeFocus() {
422         if (customArea instanceof Label) {
423             return false;
424         }
425         if (customArea instanceof CLabel) {
426             return (customArea.getStyle() & SWT.NO_FOCUS) > 0;
427         }
428         return true;
429     }
430 
431     /*
432      *  (non-Javadoc)
433      * @see org.eclipse.jface.dialogs.IconAndMessageDialog#getImage()
434      */
435     public Image getImage() {
436         return image;
437     }
438 
439     /**
440      * An accessor for the labels to use on the buttons.
441      * 
442      * @return The button labels to used; never <code>null</code>.
443      */
444     protected String  [] getButtonLabels() {
445         return buttonLabels;
446     }
447 
448     /**
449      * An accessor for the index of the default button in the button array.
450      * 
451      * @return The default button index.
452      */
453     protected int getDefaultButtonIndex() {
454         return defaultButtonIndex;
455     }
456 
457     /**
458      * A mutator for the array of buttons in the button bar.
459      * 
460      * @param buttons
461      *            The buttons in the button bar; must not be <code>null</code>.
462      */
463     protected void setButtons(Button[] buttons) {
464         if (buttons == null) {
465             throw new NullPointerException  (
466                     "The array of buttons cannot be null.");} //$NON-NLS-1$
467         this.buttons = buttons;
468     }
469 
470     /**
471      * A mutator for the button labels.
472      * 
473      * @param buttonLabels
474      *            The button labels to use; must not be <code>null</code>.
475      */
476     protected void setButtonLabels(String  [] buttonLabels) {
477         if (buttonLabels == null) {
478             throw new NullPointerException  (
479                     "The array of button labels cannot be null.");} //$NON-NLS-1$
480         this.buttonLabels = buttonLabels;
481     }
482 }
483
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags