KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > openide > DialogDescriptor


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */

19 package org.openide;
20
21 import org.openide.util.HelpCtx;
22 import org.openide.util.NbBundle;
23
24 import java.awt.event.ActionListener JavaDoc;
25
26
27 /** A description of a standard dialog.
28  * It may be built later using {@link DialogDisplayer#createDialog} or shown with {@link DialogDisplayer#notify}.
29 * It extends <code>NotifyDescriptor</code>'s capabilities by allowing specification of the
30 * modal/nonmodal state of the dialog, button behavior and alignment, help, and
31 * a listener on button presses.
32 * Anyone who wants to display some kind of dialog with standard
33 * behavior should use this class to describe it and
34 * use <code>createDialog(d)</code> to build it.
35 * When the dialog is closed you may use {@link #getValue} to determine which button
36 * closed it.
37 * <p>The property <code>message</code> (inherited from <code>NotifyDescriptor</code>) is primarily used here
38 * to specify the inner GUI component of the dialog, in contrast to <code>NotifyDescriptor</code>
39 * which generally uses a <code>String</code> message.
40 * <P>
41 * If you want to set one of the custom Options to be the default Option, it
42 * is possible to call <code>DialogDescriptor.setValue(<i>the button you want to
43 * have default...</i>)</code>
44 *
45 * @author Dafe Simonek
46 */

47 public class DialogDescriptor extends NotifyDescriptor implements HelpCtx.Provider {
48     // Property constants
49

50     /** Name of property for alignment of options. */
51     public static final String JavaDoc PROP_OPTIONS_ALIGN = "optionsAlign"; // NOI18N
52

53     /** Name of property for modality of dialog. */
54     public static final String JavaDoc PROP_MODAL = "modal"; // NOI18N
55

56     /** Name of property whether the dialg is leaf or can be the owner of other one dialog. */
57     public static final String JavaDoc PROP_LEAF = "leaf"; // NOI18N
58

59     /** Name of property for the help context. */
60     public static final String JavaDoc PROP_HELP_CTX = "helpCtx"; // NOI18N
61

62     /** Name of property for the button listener. */
63     public static final String JavaDoc PROP_BUTTON_LISTENER = "buttonListener"; // NOI18N
64

65     /** Name of property for list of closing options. */
66     public static final String JavaDoc PROP_CLOSING_OPTIONS = "closingOptions"; // NOI18N
67
public static final int BOTTOM_ALIGN = 0;
68
69     /** Alignment to place options vertically
70     * in the right part. */

71     public static final int RIGHT_ALIGN = 1;
72
73     /** Alignment to place options in the default manner. */
74     public static final int DEFAULT_ALIGN = BOTTOM_ALIGN;
75
76     /** default closing options */
77     private static final Object JavaDoc[] DEFAULT_CLOSING_OPTIONS = new Object JavaDoc[] { YES_OPTION, NO_OPTION, CANCEL_OPTION, OK_OPTION };
78
79     // Properties
80

81     /** RW property specifies if the dialog can be owner of other dialogs */
82     private boolean leaf = false;
83
84     /** RW property specifying modal status of the dialog */
85     private boolean modal;
86
87     /** RW property specifying options alignment,
88     * possible values today are BOTTOM_ALIGN, RIGHT_ALIGN, DEFAULT_ALIGN */

89     private int optionsAlign;
90
91     /** RW property which specifies help context for the dialog */
92     private HelpCtx helpCtx;
93
94     /** RW property which specifies button listener for notifying
95     * clients about button presses */

96     private ActionListener JavaDoc buttonListener;
97
98     /** array of options that close the dialog when pressed */
99     private Object JavaDoc[] closingOptions = DEFAULT_CLOSING_OPTIONS;
100
101     /** Create modal dialog descriptor with given title and inner part,
102     * with OK/Cancel buttons with default alignment,
103     * no help available. All buttons will close the dialog and the getValue ()
104     * will provide the pressed option.
105     * @param innerPane inner component of the dialog, or String message
106     * @param title title of the dialog
107     */

108     public DialogDescriptor(final Object JavaDoc innerPane, final String JavaDoc title) {
109         this(innerPane, title, true, OK_CANCEL_OPTION, OK_OPTION, DEFAULT_ALIGN, null, null);
110     }
111
112     /** Create dialog descriptor with given title, inner part and modal status,
113     * with OK/Cancel buttons displayed with default alignment, no help available.
114     * If <code>bl</code> is not <code>null</code>, then it will receive notifications when the user
115     * presses the buttons. (If no listener is specified, it's still possible
116     * to retrieve the user-selected button using {@link NotifyDescriptor#getValue}.)
117     *
118     * @param innerPane inner component of the dialog, or String message
119     * @param title title of the dialog
120     * @param isModal modal status
121     * @param bl listener for user's button presses
122     */

123     public DialogDescriptor(final Object JavaDoc innerPane, final String JavaDoc title, final boolean isModal, final ActionListener JavaDoc bl) {
124         this(innerPane, title, isModal, OK_CANCEL_OPTION, OK_OPTION, DEFAULT_ALIGN, null, bl);
125     }
126
127     /** Create dialog descriptor with given title, inner part, modal status,
128     * option type and default option. Options have default alignment, no help available.
129     * If the action listener is null, all option buttons will close the dialog and the
130     * getValue () will provide the pressed option.
131     * @param innerPane inner component of the dialog, or String message
132     * @param title title of the dialog
133     * @param isModal modal status
134     * @param optionType one of the standard options (<code>OK_CANCEL_OPTION</code>, ...)
135     * @param initialValue default option (default button)
136     * @param bl listener for the user's button presses or null for default close action on all options
137     */

138     public DialogDescriptor(
139         final Object JavaDoc innerPane, final String JavaDoc title, final boolean isModal, final int optionType,
140         final Object JavaDoc initialValue, final ActionListener JavaDoc bl
141     ) {
142         this(innerPane, title, isModal, optionType, initialValue, DEFAULT_ALIGN, null, bl);
143     }
144
145     /** Create dialog descriptor; possibility of specifying custom
146     * array of options and their alignment. If the action listener is null,
147     * all option buttons will close the dialog and the getValue ()
148     * will provide the pressed option.
149     * When a custom option set is provided, if any of the standard options
150     * (OK_OPTION, CLOSE_OPTION or CANCEL_OPTION) are used, the dialog will close when
151     * a button for a standard option is pressed; otherwise for custom options, closing the dialog is left
152     * to the <code>ActionListener</code> or <code>setClosingOptions</code>.
153     * @param innerPane inner component of the dialog, or String message
154     * @param title title of the dialog
155     * @param modal modal status
156     * @param options array of custom options (<code>null</code> means no options at all);
157     * may include strings (for button labels; such buttons then do nothing by default)
158     * or components (such as buttons,
159     * in which case you are responsible for listening to the buttons yourself)
160     * @param initialValue default option from custom option array
161     * @param optionsAlign specifies where to place
162     * options in the dialog
163     * @param helpCtx help context specifying help page
164     * @param bl listener for the user's button presses or <code>null</code> for default close action on all options
165     * (unless you specified the options yourself)
166     *
167     * @see #setClosingOptions
168     */

169     public DialogDescriptor(
170         final Object JavaDoc innerPane, final String JavaDoc title, final boolean modal, final Object JavaDoc[] options,
171         final Object JavaDoc initialValue, final int optionsAlign, final HelpCtx helpCtx, final ActionListener JavaDoc bl
172     ) {
173         super(innerPane, title, DEFAULT_OPTION, PLAIN_MESSAGE, options, initialValue);
174         this.modal = modal;
175         this.optionsAlign = optionsAlign;
176         this.helpCtx = (helpCtx == null) ? HelpCtx.DEFAULT_HELP : helpCtx;
177         this.buttonListener = bl;
178
179         if (bl == null) {
180             setClosingOptions(options);
181         }
182     }
183
184     /** Create dialog descriptor; possibility of specifying custom
185     * array of options and their alignment. If the action listener is null,
186     * all option buttons will close the dialog and the getValue ()
187     * will provide the pressed option.
188     * When a custom option set is provided, if any of the standard options
189     * (OK_OPTION, CLOSE_OPTION or CANCEL_OPTION) are used, the dialog will close when
190     * a button for a standard option is pressed; otherwise for custom options, closing the dialog is left
191     * to the <code>ActionListener</code> or <code>setClosingOptions</code>.
192     * @param innerPane inner component of the dialog, or String message
193     * @param title title of the dialog
194     * @param modal modal status
195     * @param options array of custom options (<code>null</code> means no options at all);
196     * may include strings (for button labels; such buttons then do nothing by default)
197     * or components (such as buttons,
198     * in which case you are responsible for listening to the buttons yourself)
199     * @param initialValue default option from custom option array
200     * @param optionsAlign specifies where to place
201     * options in the dialog
202     * @param helpCtx help context specifying help page
203     * @param bl listener for the user's button presses or <code>null</code> for default close action on all options
204     * (unless you specified the options yourself)
205     * @param leaf property specifies whether the dialog can be owner of other dialogs
206     *
207     * @see #setClosingOptions
208     * @since 5.5
209     */

210     public DialogDescriptor(
211         final Object JavaDoc innerPane, final String JavaDoc title, final boolean modal, final Object JavaDoc[] options,
212         final Object JavaDoc initialValue, final int optionsAlign, final HelpCtx helpCtx, final ActionListener JavaDoc bl,
213         final boolean leaf
214     ) {
215         super(innerPane, title, DEFAULT_OPTION, PLAIN_MESSAGE, options, initialValue);
216         this.modal = modal;
217         this.optionsAlign = optionsAlign;
218         this.helpCtx = (helpCtx == null) ? HelpCtx.DEFAULT_HELP : helpCtx;
219         this.buttonListener = bl;
220         this.leaf = leaf;
221
222         if (bl == null) {
223             setClosingOptions(options);
224         }
225     }
226
227     /** Create dialog descriptor.
228     * If the action listener is null, all option buttons will close the dialog and the
229     * getValue () will provide the pressed option.
230     *
231     * @param innerPane inner component of the dialog, or String message
232     * @param title title of the dialog
233     * @param isModal modal status
234     * @param optionType one of the standard options (<code>OK_CANCEL_OPTION</code>, ...)
235     * @param initialValue default option (default button)
236     * @param optionsAlign specifies where to place
237     * options in the dialog
238     * @param helpCtx help context specifying help page
239     * @param bl listener for the user's button presses or <code>null</code> for default close action on all options
240     * (unless you specified the options yourself)
241     */

242     public DialogDescriptor(
243         final Object JavaDoc innerPane, final String JavaDoc title, final boolean isModal, final int optionType,
244         final Object JavaDoc initialValue, final int optionsAlign, final HelpCtx helpCtx, final ActionListener JavaDoc bl
245     ) {
246         super(innerPane, title, optionType, PLAIN_MESSAGE, null, initialValue);
247         this.modal = isModal;
248         this.optionsAlign = optionsAlign;
249         this.helpCtx = (helpCtx == null) ? HelpCtx.DEFAULT_HELP : helpCtx;
250         this.buttonListener = bl;
251
252         if (bl == null) {
253             // if the listener is null all options are closing
254
setClosingOptions(null);
255         }
256     }
257
258     /** Get current option alignment.
259     * @return current option alignment
260     * @see #setOptionsAlign
261     */

262     public int getOptionsAlign() {
263         getterCalled();
264
265         return optionsAlign;
266     }
267
268     /** Set new option alignment. See aligment constants for
269     * possible values.
270     * Fires property change event if successful.
271     *
272     * @param optionsAlign new options alignment
273     * @throws IllegalArgumentException when unknown alignment is given
274     * @see #DEFAULT_ALIGN
275     */

276     public void setOptionsAlign(final int optionsAlign) {
277         if ((optionsAlign != BOTTOM_ALIGN) && (optionsAlign != RIGHT_ALIGN)) {
278             throw new IllegalArgumentException JavaDoc(
279                 NbBundle.getBundle(DialogDescriptor.class).getString("EXC_OptionsAlign")
280             );
281         }
282
283         if (this.optionsAlign == optionsAlign) {
284             return;
285         }
286
287         int oldValue = this.optionsAlign;
288         this.optionsAlign = optionsAlign;
289         firePropertyChange(PROP_OPTIONS_ALIGN, new Integer JavaDoc(oldValue), new Integer JavaDoc(optionsAlign));
290     }
291
292     /** Get modal status.
293     * @return modal status
294     * @see #setModal
295     */

296     public boolean isModal() {
297         getterCalled();
298
299         return modal;
300     }
301
302     /** Set new modal status.
303     * Fires property change event if successful.
304     *
305     * @param modal new modal status
306     * @see #isModal
307     */

308     public void setModal(final boolean modal) {
309         if (this.modal == modal) {
310             return;
311         }
312
313         boolean oldModal = this.modal;
314         this.modal = modal;
315         firePropertyChange(PROP_MODAL, Boolean.valueOf(oldModal), Boolean.valueOf(modal));
316     }
317
318     /** Get leaf status. If is leaf then cannot be the owner to other one dialog.
319     * @return leaf status
320     * @see #setLeaf
321     * @since 5.5
322     */

323     public boolean isLeaf() {
324         getterCalled();
325
326         return leaf;
327     }
328
329     /** Set new leaf status.
330     * Fires property change event if successful.
331     *
332     * @param leaf new leaf status
333     * @see #isLeaf
334     * @since 5.5
335     */

336     public void setLeaf(final boolean leaf) {
337         if (this.leaf == leaf) {
338             return;
339         }
340
341         boolean oldLeaf = this.leaf;
342         this.leaf = leaf;
343         firePropertyChange(PROP_MODAL, Boolean.valueOf(oldLeaf), Boolean.valueOf(leaf));
344     }
345
346     /** Setter for list of options that close the dialog.
347     * Special values are:
348     * <UL>
349     * <LI>null - all options will close the dialog
350     * <LI>empty array - no option will close the dialog
351     * </UL>
352     * @param arr array of options that should close the dialog when pressed
353     * if null then all options close the dialog
354     */

355     public void setClosingOptions(Object JavaDoc[] arr) {
356         Object JavaDoc[] old = closingOptions;
357         closingOptions = arr;
358
359         firePropertyChange(PROP_CLOSING_OPTIONS, old, arr);
360     }
361
362     /** Getter for list of closing options.
363     * @return array of options or null
364     */

365     public Object JavaDoc[] getClosingOptions() {
366         getterCalled();
367
368         return closingOptions;
369     }
370
371     /** Get current help context asociated with this dialog
372     * descriptor.
373     * @return current help context
374     * @see #setHelpCtx
375     */

376     public HelpCtx getHelpCtx() {
377         getterCalled();
378
379         return helpCtx;
380     }
381
382     /** Set new help context for this dialog descriptor.
383     * Fires property change event if successful.
384     * <p>The implementation should automatically display a help
385     * button among the secondary options, without your needing to
386     * specify it, if the help context on the descriptor is neither
387     * <code>null</code> nor {@link HelpCtx#DEFAULT_HELP}. If the
388     * descriptor is <code>null</code>, this feature will be disabled
389     * (you can still add your own help button manually if you wish,
390     * of course). If <code>DEFAULT_HELP</code> (the default), normally the button
391     * will also be disabled, however if the inner pane is a component
392     * and this component has an {@link HelpCtx#findHelp associated}
393     * help ID, that will be used automatically. So most users should never
394     * need to manually add a help button: call this method with the correct
395     * context, or associate an ID with the displayed component. Note that to
396     * set it to <code>null</code> you must explicitly call this method; passing
397     * <code>null</code> in the constructor actually sets it to <code>DEFAULT_HELP</code>.
398     *
399     * @param helpCtx new help context, can be <code>null</code> (no help)
400     * @see #getHelpCtx
401     */

402     public void setHelpCtx(final HelpCtx helpCtx) {
403         if ((this.helpCtx != null) && (this.helpCtx.equals(helpCtx))) {
404             return;
405         }
406
407         HelpCtx oldHelpCtx = this.helpCtx;
408         this.helpCtx = helpCtx;
409         firePropertyChange(PROP_HELP_CTX, oldHelpCtx, helpCtx);
410     }
411
412     /** Get button listener which listens for the user's button presses.
413     * @return current button listener instance or null
414     * @see #setButtonListener
415     */

416     public ActionListener JavaDoc getButtonListener() {
417         getterCalled();
418
419         return buttonListener;
420     }
421
422     /** Set new button listener instance for this dialog descriptor.
423     * Fires property change event if successful.
424     *
425     * @param l new button listener. It may be <code>null</code>, in which case listening is cancelled.
426     * @see #getButtonListener
427     */

428     public void setButtonListener(final ActionListener JavaDoc l) {
429         if (this.buttonListener == l) {
430             return;
431         }
432
433         ActionListener JavaDoc oldButtonListener = this.buttonListener;
434         this.buttonListener = l;
435         firePropertyChange(PROP_BUTTON_LISTENER, oldButtonListener, l);
436     }
437 }
438
Popular Tags