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  ;
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   PROP_OPTIONS_ALIGN = "optionsAlign"; // NOI18N
52  
53      /** Name of property for modality of dialog. */
54      public static final String   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   PROP_LEAF = "leaf"; // NOI18N
58  
59      /** Name of property for the help context. */
60      public static final String   PROP_HELP_CTX = "helpCtx"; // NOI18N
61  
62      /** Name of property for the button listener. */
63      public static final String   PROP_BUTTON_LISTENER = "buttonListener"; // NOI18N
64  
65      /** Name of property for list of closing options. */
66      public static final String   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  [] DEFAULT_CLOSING_OPTIONS = new Object  [] { 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   buttonListener;
97  
98      /** array of options that close the dialog when pressed */
99      private Object  [] 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   innerPane, final String   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   innerPane, final String   title, final boolean isModal, final ActionListener   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   innerPane, final String   title, final boolean isModal, final int optionType,
140         final Object   initialValue, final ActionListener   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   innerPane, final String   title, final boolean modal, final Object  [] options,
171         final Object   initialValue, final int optionsAlign, final HelpCtx helpCtx, final ActionListener   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   innerPane, final String   title, final boolean modal, final Object  [] options,
212         final Object   initialValue, final int optionsAlign, final HelpCtx helpCtx, final ActionListener   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   innerPane, final String   title, final boolean isModal, final int optionType,
244         final Object   initialValue, final int optionsAlign, final HelpCtx helpCtx, final ActionListener   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  (
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  (oldValue), new Integer  (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  [] arr) {
356         Object  [] 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  [] 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   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   l) {
429         if (this.buttonListener == l) {
430             return;
431         }
432 
433         ActionListener   oldButtonListener = this.buttonListener;
434         this.buttonListener = l;
435         firePropertyChange(PROP_BUTTON_LISTENER, oldButtonListener, l);
436     }
437 }
438
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags