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


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
12 package org.eclipse.jface.dialogs;
13
14 import org.eclipse.jface.preference.IPreferenceStore;
15 import org.eclipse.jface.resource.JFaceResources;
16 import org.eclipse.swt.SWT;
17 import org.eclipse.swt.events.SelectionAdapter;
18 import org.eclipse.swt.events.SelectionEvent;
19 import org.eclipse.swt.graphics.Image;
20 import org.eclipse.swt.layout.GridData;
21 import org.eclipse.swt.widgets.Button;
22 import org.eclipse.swt.widgets.Composite;
23 import org.eclipse.swt.widgets.Control;
24 import org.eclipse.swt.widgets.Shell;
25
26 /**
27  * <p>
28  * A message dialog which also allows the user to adjust a toggle setting. If a
29  * preference store is provided and the user selects the toggle, then the user's
30  * answer (yes/ok or no) will be persisted in the store. If no store is
31  * provided, then this information can be queried after the dialog closes.
32  * </p>
33  * <p>
34  * This type of dialog should be used whenever you want to user to be able to
35  * avoid being prompted in the future. It is <strong>strongly </strong>
36  * recommended that a cancel option be provided, so that the user has the option
37  * of making the decision at a later point in time. The semantic for a cancel
38  * button should be to cancel the operation (if it has not yet started), or stop
39  * the operation (if it has already started).
40  * </p>
41  * <p>
42  * It is the responsibility of the developer to provide a mechanism for the user
43  * to change this preference at some later point in time (e.g., through a
44  * preference page).
45  * </p>
46  *
47  * @since 3.0
48  */
49 public class MessageDialogWithToggle extends MessageDialog {
50
51     /**
52      * The value of the preference when the user has asked that the answer to
53      * the question always be "okay" or "yes".
54      */
55     public static final String ALWAYS = "always"; //$NON-NLS-1$
56
57     /**
58      * The value of the preference when the user has asked that the answer to
59      * the question always be "no".
60      */
61     public static final String NEVER = "never"; //$NON-NLS-1$
62
63     /**
64      * The value of the preference when the user wishes to prompted for an
65      * answer every time the question is to be asked.
66      */
67     public static final String PROMPT = "prompt"; //$NON-NLS-1$
68
69     /**
70      * Convenience method to open a standard error dialog.
71      *
72      * @param parent
73      * the parent shell of the dialog, or <code>null</code> if none
74      * @param title
75      * the dialog's title, or <code>null</code> if none
76      * @param message
77      * the message
78      * @param toggleMessage
79      * the message for the toggle control, or <code>null</code> for
80      * the default message
81      * @param toggleState
82      * the initial state for the toggle
83      * @param store
84      * the IPreference store in which the user's preference should be
85      * persisted; <code>null</code> if you don't want it persisted
86      * automatically.
87      * @param key
88      * the key to use when persisting the user's preference;
89      * <code>null</code> if you don't want it persisted.
90      * @return the dialog, after being closed by the user, which the client can
91      * only call <code>getReturnCode()</code> or
92      * <code>getToggleState()</code>
93      */
94     public static MessageDialogWithToggle openError(Shell parent, String title,
95             String message, String toggleMessage, boolean toggleState,
96             IPreferenceStore store, String key) {
97         MessageDialogWithToggle dialog = new MessageDialogWithToggle(parent,
98                 title, null, // accept the default window icon
99 message, ERROR, new String [] { IDialogConstants.OK_LABEL }, 0, // ok
100 // is
101 // the
102 // default
103 toggleMessage, toggleState);
104         dialog.prefStore = store;
105         dialog.prefKey = key;
106         dialog.open();
107         return dialog;
108     }
109
110     /**
111      * Convenience method to open a standard information dialog.
112      *
113      * @param parent
114      * the parent shell of the dialog, or <code>null</code> if none
115      * @param title
116      * the dialog's title, or <code>null</code> if none
117      * @param message
118      * the message
119      * @param toggleMessage
120      * the message for the toggle control, or <code>null</code> for
121      * the default message
122      * @param toggleState
123      * the initial state for the toggle
124      * @param store
125      * the IPreference store in which the user's preference should be
126      * persisted; <code>null</code> if you don't want it persisted
127      * automatically.
128      * @param key
129      * the key to use when persisting the user's preference;
130      * <code>null</code> if you don't want it persisted.
131      *
132      * @return the dialog, after being closed by the user, which the client can
133      * only call <code>getReturnCode()</code> or
134      * <code>getToggleState()</code>
135      */
136     public static MessageDialogWithToggle openInformation(Shell parent,
137             String title, String message, String toggleMessage,
138             boolean toggleState, IPreferenceStore store, String key) {
139         MessageDialogWithToggle dialog = new MessageDialogWithToggle(parent,
140                 title, null, // accept the default window icon
141 message, INFORMATION,
142                 new String [] { IDialogConstants.OK_LABEL }, 0, // ok is the
143 // default
144 toggleMessage, toggleState);
145         dialog.prefStore = store;
146         dialog.prefKey = key;
147         dialog.open();
148         return dialog;
149     }
150
151     /**
152      * Convenience method to open a simple confirm (OK/Cancel) dialog.
153      *
154      * @param parent
155      * the parent shell of the dialog, or <code>null</code> if none
156      * @param title
157      * the dialog's title, or <code>null</code> if none
158      * @param message
159      * the message
160      * @param toggleMessage
161      * the message for the toggle control, or <code>null</code> for
162      * the default message
163      * @param toggleState
164      * the initial state for the toggle
165      * @param store
166      * the IPreference store in which the user's preference should be
167      * persisted; <code>null</code> if you don't want it persisted
168      * automatically.
169      * @param key
170      * the key to use when persisting the user's preference;
171      * <code>null</code> if you don't want it persisted.
172      * @return the dialog, after being closed by the user, which the client can
173      * only call <code>getReturnCode()</code> or
174      * <code>getToggleState()</code>
175      */
176     public static MessageDialogWithToggle openOkCancelConfirm(Shell parent,
177             String title, String message, String toggleMessage,
178             boolean toggleState, IPreferenceStore store, String key) {
179         MessageDialogWithToggle dialog = new MessageDialogWithToggle(parent,
180                 title, null, // accept the default window icon
181 message, QUESTION, new String [] { IDialogConstants.OK_LABEL,
182                         IDialogConstants.CANCEL_LABEL }, 0, // OK is the default
183 toggleMessage, toggleState);
184         dialog.prefStore = store;
185         dialog.prefKey = key;
186         dialog.open();
187         return dialog;
188     }
189
190     /**
191      * Convenience method to open a standard warning dialog.
192      *
193      * @param parent
194      * the parent shell of the dialog, or <code>null</code> if none
195      * @param title
196      * the dialog's title, or <code>null</code> if none
197      * @param message
198      * the message
199      * @param toggleMessage
200      * the message for the toggle control, or <code>null</code> for
201      * the default message
202      * @param toggleState
203      * the initial state for the toggle
204      * @param store
205      * the IPreference store in which the user's preference should be
206      * persisted; <code>null</code> if you don't want it persisted
207      * automatically.
208      * @param key
209      * the key to use when persisting the user's preference;
210      * <code>null</code> if you don't want it persisted.
211      * @return the dialog, after being closed by the user, which the client can
212      * only call <code>getReturnCode()</code> or
213      * <code>getToggleState()</code>
214      */
215     public static MessageDialogWithToggle openWarning(Shell parent,
216             String title, String message, String toggleMessage,
217             boolean toggleState, IPreferenceStore store, String key) {
218         MessageDialogWithToggle dialog = new MessageDialogWithToggle(parent,
219                 title, null, // accept the default window icon
220 message, WARNING, new String [] { IDialogConstants.OK_LABEL },
221                 0, // ok is the default
222 toggleMessage, toggleState);
223         dialog.prefStore = store;
224         dialog.prefKey = key;
225         dialog.open();
226         return dialog;
227     }
228
229     /**
230      * Convenience method to open a simple question Yes/No/Cancel dialog.
231      *
232      * @param parent
233      * the parent shell of the dialog, or <code>null</code> if none
234      * @param title
235      * the dialog's title, or <code>null</code> if none
236      * @param message
237      * the message
238      * @param toggleMessage
239      * the message for the toggle control, or <code>null</code> for
240      * the default message
241      * @param toggleState
242      * the initial state for the toggle
243      * @param store
244      * the IPreference store in which the user's preference should be
245      * persisted; <code>null</code> if you don't want it persisted
246      * automatically.
247      * @param key
248      * the key to use when persisting the user's preference;
249      * <code>null</code> if you don't want it persisted.
250      * @return the dialog, after being closed by the user, which the client can
251      * only call <code>getReturnCode()</code> or
252      * <code>getToggleState()</code>
253      */
254     public static MessageDialogWithToggle openYesNoCancelQuestion(Shell parent,
255             String title, String message, String toggleMessage,
256             boolean toggleState, IPreferenceStore store, String key) {
257         MessageDialogWithToggle dialog = new MessageDialogWithToggle(parent,
258                 title, null, // accept the default window icon
259 message, QUESTION, new String [] { IDialogConstants.YES_LABEL,
260                         IDialogConstants.NO_LABEL,
261                         IDialogConstants.CANCEL_LABEL }, 0, // YES is the
262 // default
263 toggleMessage, toggleState);
264         dialog.prefStore = store;
265         dialog.prefKey = key;
266         dialog.open();
267         return dialog;
268     }
269
270     /**
271      * Convenience method to open a simple Yes/No question dialog.
272      *
273      * @param parent
274      * the parent shell of the dialog, or <code>null</code> if none
275      * @param title
276      * the dialog's title, or <code>null</code> if none
277      * @param message
278      * the message
279      * @param toggleMessage
280      * the message for the toggle control, or <code>null</code> for
281      * the default message
282      * @param toggleState
283      * the initial state for the toggle
284      * @param store
285      * the IPreference store in which the user's preference should be
286      * persisted; <code>null</code> if you don't want it persisted
287      * automatically.
288      * @param key
289      * the key to use when persisting the user's preference;
290      * <code>null</code> if you don't want it persisted.
291      *
292      * @return the dialog, after being closed by the user, which the client can
293      * only call <code>getReturnCode()</code> or
294      * <code>getToggleState()</code>
295      */
296     public static MessageDialogWithToggle openYesNoQuestion(Shell parent,
297             String title, String message, String toggleMessage,
298             boolean toggleState, IPreferenceStore store, String key) {
299         MessageDialogWithToggle dialog = new MessageDialogWithToggle(parent,
300                 title, null, // accept the default window icon
301 message, QUESTION, new String [] { IDialogConstants.YES_LABEL,
302                         IDialogConstants.NO_LABEL }, 0, // yes is the default
303 toggleMessage, toggleState);
304         dialog.prefStore = store;
305         dialog.prefKey = key;
306         dialog.open();
307         return dialog;
308     }
309
310     /**
311      * The key at which the toggle state should be stored within the
312      * preferences. This value may be <code>null</code>, which indicates that
313      * no preference should be updated automatically. It is then the
314      * responsibility of the user of this API to use the information from the
315      * toggle. Note: a <code>prefStore</code> is also needed.
316      */
317     private String prefKey = null;
318
319     /**
320      * The preference store which will be affected by the toggle button. This
321      * value may be <code>null</code>, which indicates that no preference
322      * should be updated automatically. It is then the responsibility of the
323      * user of this API to use the information from the toggle. Note: a
324      * <code>prefKey</code> is also needed.
325      */
326     private IPreferenceStore prefStore = null;
327
328     /**
329      * The toggle button (widget). This value is <code>null</code> until the
330      * dialog is created.
331      */
332     private Button toggleButton = null;
333
334     /**
335      * The message displayed to the user, with the toggle button. This is the
336      * text besides the toggle. If it is <code>null</code>, this means that
337      * the default text for the toggle should be used.
338      */
339     private String toggleMessage;
340
341     /**
342      * The initial selected state of the toggle.
343      */
344     private boolean toggleState;
345
346     /**
347      * Creates a message dialog with a toggle. See the superclass constructor
348      * for info on the other parameters.
349      *
350      * @param parentShell
351      * the parent shell
352      * @param dialogTitle
353      * the dialog title, or <code>null</code> if none
354      * @param image
355      * the dialog title image, or <code>null</code> if none
356      * @param message
357      * the dialog message
358      * @param dialogImageType
359      * one of the following values:
360      * <ul>
361      * <li><code>MessageDialog.NONE</code> for a dialog with no
362      * image</li>
363      * <li><code>MessageDialog.ERROR</code> for a dialog with an
364      * error image</li>
365      * <li><code>MessageDialog.INFORMATION</code> for a dialog
366      * with an information image</li>
367      * <li><code>MessageDialog.QUESTION </code> for a dialog with a
368      * question image</li>
369      * <li><code>MessageDialog.WARNING</code> for a dialog with a
370      * warning image</li>
371      * </ul>
372      * @param dialogButtonLabels
373      * an array of labels for the buttons in the button bar
374      * @param defaultIndex
375      * the index in the button label array of the default button
376      * @param toggleMessage
377      * the message for the toggle control, or <code>null</code> for
378      * the default message
379      * @param toggleState
380      * the initial state for the toggle
381      *
382      */
383     public MessageDialogWithToggle(Shell parentShell, String dialogTitle,
384             Image image, String message, int dialogImageType,
385             String [] dialogButtonLabels, int defaultIndex,
386             String toggleMessage, boolean toggleState) {
387         super(parentShell, dialogTitle, image, message, dialogImageType,
388                 dialogButtonLabels, defaultIndex);
389         this.toggleMessage = toggleMessage;
390         this.toggleState = toggleState;
391         setButtonLabels(dialogButtonLabels);
392     }
393
394     /**
395      * @see org.eclipse.jface.dialogs.Dialog#buttonPressed(int)
396      */
397     protected void buttonPressed(int buttonId) {
398         super.buttonPressed(buttonId);
399
400         if (buttonId != IDialogConstants.CANCEL_ID && toggleState
401                 && prefStore != null && prefKey != null) {
402             switch (buttonId) {
403             case IDialogConstants.YES_ID:
404             case IDialogConstants.YES_TO_ALL_ID:
405             case IDialogConstants.PROCEED_ID:
406             case IDialogConstants.OK_ID:
407                 prefStore.setValue(prefKey, ALWAYS);
408                 break;
409             case IDialogConstants.NO_ID:
410             case IDialogConstants.NO_TO_ALL_ID:
411                 prefStore.setValue(prefKey, NEVER);
412                 break;
413             }
414         }
415     }
416
417     /**
418      * @see Dialog#createButtonBar(Composite)
419      */
420     protected void createButtonsForButtonBar(Composite parent) {
421         final String [] buttonLabels = getButtonLabels();
422         final Button[] buttons = new Button[buttonLabels.length];
423         final int defaultButtonIndex = getDefaultButtonIndex();
424
425         int suggestedId = IDialogConstants.INTERNAL_ID;
426         for (int i = 0; i < buttonLabels.length; i++) {
427             String label = buttonLabels[i];
428             // get the JFace button ID that matches the label, or use the specified
429 // id if there is no match.
430 int id = mapButtonLabelToButtonID(label, suggestedId);
431             
432             // if the suggested id was used, increment the default for next use
433 if (id == suggestedId) {
434                 suggestedId++;
435             }
436  
437             Button button = createButton(parent, id, label,
438                     defaultButtonIndex == i);
439             buttons[i] = button;
440  
441         }
442         setButtons(buttons);
443     }
444
445     /**
446      * @see Dialog#createDialogArea(Composite)
447      */
448     protected Control createDialogArea(Composite parent) {
449         Composite dialogAreaComposite = (Composite) super
450                 .createDialogArea(parent);
451         setToggleButton(createToggleButton(dialogAreaComposite));
452         return dialogAreaComposite;
453     }
454
455     /**
456      * Creates a toggle button without any text or state. The text and state
457      * will be created by <code>createDialogArea</code>.
458      *
459      * @param parent
460      * The composite in which the toggle button should be placed;
461      * must not be <code>null</code>.
462      * @return The added toggle button; never <code>null</code>.
463      */
464     protected Button createToggleButton(Composite parent) {
465         final Button button = new Button(parent, SWT.CHECK | SWT.LEFT);
466
467         GridData data = new GridData(SWT.NONE);
468         data.horizontalSpan = 2;
469         button.setLayoutData(data);
470         button.setFont(parent.getFont());
471
472         button.addSelectionListener(new SelectionAdapter() {
473
474             public void widgetSelected(SelectionEvent e) {
475                 toggleState = button.getSelection();
476             }
477
478         });
479
480         return button;
481     }
482
483     /**
484      * Returns the toggle button.
485      *
486      * @return the toggle button
487      */
488     protected Button getToggleButton() {
489         return toggleButton;
490     }
491
492     /**
493      * An accessor for the current preference store for this dialog.
494      *
495      * @return The preference store; this value may be <code>null</code> if no
496      * preference is being used.
497      */
498     public IPreferenceStore getPrefStore() {
499         return prefStore;
500     }
501
502     /**
503      * An accessor for the current key of the toggle preference.
504      *
505      * @return The preference key; this value may be <code>null</code> if no
506      * preference is being used.
507      */
508     public String getPrefKey() {
509         return prefKey;
510     }
511
512     /**
513      * Returns the toggle state. This can be called even after the dialog is
514      * closed.
515      *
516      * @return <code>true</code> if the toggle button is checked,
517      * <code>false</code> if not
518      */
519     public boolean getToggleState() {
520         return toggleState;
521     }
522
523     /**
524      * A mutator for the key of the preference to be modified by the toggle
525      * button.
526      *
527      * @param prefKey
528      * The prefKey to set. If this value is <code>null</code>,
529      * then no preference will be modified.
530      */
531     public void setPrefKey(String prefKey) {
532         this.prefKey = prefKey;
533     }
534
535     /**
536      * A mutator for the preference store to be modified by the toggle button.
537      *
538      * @param prefStore
539      * The prefStore to set. If this value is <code>null</code>,
540      * then no preference will be modified.
541      */
542     public void setPrefStore(IPreferenceStore prefStore) {
543         this.prefStore = prefStore;
544     }
545
546     /**
547      * A mutator for the button providing the toggle option. If the button
548      * exists, then it will automatically get the text set to the current toggle
549      * message, and its selection state set to the current selection state.
550      *
551      * @param button
552      * The button to use; must not be <code>null</code>.
553      */
554     protected void setToggleButton(Button button) {
555         if (button == null) {
556             throw new NullPointerException (
557                     "A message dialog with toggle may not have a null toggle button.");} //$NON-NLS-1$
558
559         if (!button.isDisposed()) {
560             final String text;
561             if (toggleMessage == null) {
562                 text = JFaceResources
563                         .getString("MessageDialogWithToggle.defaultToggleMessage"); //$NON-NLS-1$
564 } else {
565                 text = toggleMessage;
566             }
567             button.setText(text);
568             button.setSelection(toggleState);
569         }
570
571         this.toggleButton = button;
572     }
573
574     /**
575      * A mutator for the text on the toggle button. The button will
576      * automatically get updated with the new text, if it exists.
577      *
578      * @param message
579      * The new text of the toggle button; if it is <code>null</code>,
580      * then used the default toggle message.
581      */
582     protected void setToggleMessage(String message) {
583         this.toggleMessage = message;
584
585         if ((toggleButton != null) && (!toggleButton.isDisposed())) {
586             final String text;
587             if (toggleMessage == null) {
588                 text = JFaceResources
589                         .getString("MessageDialogWithToggle.defaultToggleMessage"); //$NON-NLS-1$
590 } else {
591                 text = toggleMessage;
592             }
593             toggleButton.setText(text);
594         }
595     }
596
597     /**
598      * A mutator for the state of the toggle button. This method will update the
599      * button, if it exists.
600      *
601      * @param toggleState
602      * The desired state of the toggle button (<code>true</code>
603      * means the toggle should be selected).
604      */
605     public void setToggleState(boolean toggleState) {
606         this.toggleState = toggleState;
607
608         // Update the button, if it exists.
609 if ((toggleButton != null) && (!toggleButton.isDisposed())) {
610             toggleButton.setSelection(toggleState);
611         }
612     }
613     
614     /**
615      * Attempt to find a standard JFace button id that matches the specified button
616      * label. If no match can be found, use the default id provided.
617      *
618      * @param buttonLabel the button label whose id is sought
619      * @param defaultId the id to use for the button if there is no standard id
620      * @return the id for the specified button label
621      */
622     private int mapButtonLabelToButtonID(String buttonLabel, int defaultId) {
623         // Not pretty but does the job...
624 if (IDialogConstants.OK_LABEL.equals(buttonLabel)) {
625             return IDialogConstants.OK_ID;
626         }
627         
628         if (IDialogConstants.YES_LABEL.equals(buttonLabel)) {
629             return IDialogConstants.YES_ID;
630         }
631         
632         if (IDialogConstants.NO_LABEL.equals(buttonLabel)) {
633             return IDialogConstants.NO_ID;
634         }
635         
636         if (IDialogConstants.CANCEL_LABEL.equals(buttonLabel)) {
637             return IDialogConstants.CANCEL_ID;
638         }
639         
640         if (IDialogConstants.YES_TO_ALL_LABEL.equals(buttonLabel)) {
641             return IDialogConstants.YES_TO_ALL_ID;
642         }
643         
644         if (IDialogConstants.SKIP_LABEL.equals(buttonLabel)) {
645             return IDialogConstants.SKIP_ID;
646         }
647         
648         if (IDialogConstants.STOP_LABEL.equals(buttonLabel)) {
649             return IDialogConstants.STOP_ID;
650         }
651         
652         if (IDialogConstants.ABORT_LABEL.equals(buttonLabel)) {
653             return IDialogConstants.ABORT_ID;
654         }
655         
656         if (IDialogConstants.RETRY_LABEL.equals(buttonLabel)) {
657             return IDialogConstants.RETRY_ID;
658         }
659         
660         if (IDialogConstants.IGNORE_LABEL.equals(buttonLabel)) {
661             return IDialogConstants.IGNORE_ID;
662         }
663         
664         if (IDialogConstants.PROCEED_LABEL.equals(buttonLabel)) {
665             return IDialogConstants.PROCEED_ID;
666         }
667         
668         if (IDialogConstants.OPEN_LABEL.equals(buttonLabel)) {
669             return IDialogConstants.OPEN_ID;
670         }
671         
672         if (IDialogConstants.CLOSE_LABEL.equals(buttonLabel)) {
673             return IDialogConstants.CLOSE_ID;
674         }
675         
676         if (IDialogConstants.BACK_LABEL.equals(buttonLabel)) {
677             return IDialogConstants.BACK_ID;
678         }
679         
680         if (IDialogConstants.NEXT_LABEL.equals(buttonLabel)) {
681             return IDialogConstants.NEXT_ID;
682         }
683         
684         if (IDialogConstants.FINISH_LABEL.equals(buttonLabel)) {
685             return IDialogConstants.FINISH_ID;
686         }
687         
688         if (IDialogConstants.HELP_LABEL.equals(buttonLabel)) {
689             return IDialogConstants.HELP_ID;
690         }
691         
692         if (IDialogConstants.NO_TO_ALL_LABEL.equals(buttonLabel)) {
693             return IDialogConstants.NO_TO_ALL_ID;
694         }
695         
696         // No XXX_LABEL in IDialogConstants for these. Unlikely
697 // they would be used in a message dialog though.
698 // public int DETAILS_ID = 13;
699 // public int SELECT_ALL_ID = 18;
700 // public int DESELECT_ALL_ID = 19;
701 // public int SELECT_TYPES_ID = 20;
702
703         return defaultId;
704     }
705 }
706

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags