Source for java.awt.Dialog

   1: /* Dialog.java -- An AWT dialog box
   2:  Copyright (C) 1999, 2000, 2001, 2002, 2005, 2006  
   3:  Free Software Foundation, Inc.
   4: 
   5:  This file is part of GNU Classpath.
   6: 
   7:  GNU Classpath is free software; you can redistribute it and/or modify
   8:  it under the terms of the GNU General Public License as published by
   9:  the Free Software Foundation; either version 2, or (at your option)
  10:  any later version.
  11: 
  12:  GNU Classpath is distributed in the hope that it will be useful, but
  13:  WITHOUT ANY WARRANTY; without even the implied warranty of
  14:  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15:  General Public License for more details.
  16: 
  17:  You should have received a copy of the GNU General Public License
  18:  along with GNU Classpath; see the file COPYING.  If not, write to the
  19:  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20:  02110-1301 USA.
  21: 
  22:  Linking this library statically or dynamically with other modules is
  23:  making a combined work based on this library.  Thus, the terms and
  24:  conditions of the GNU General Public License cover the whole
  25:  combination.
  26: 
  27:  As a special exception, the copyright holders of this library give you
  28:  permission to link this library with independent modules to produce an
  29:  executable, regardless of the license terms of these independent
  30:  modules, and to copy and distribute the resulting executable under
  31:  terms of your choice, provided that you also meet, for each linked
  32:  independent module, the terms and conditions of the license of that
  33:  module.  An independent module is a module which is not derived from
  34:  or based on this library.  If you modify this library, you may extend
  35:  this exception to your version of the library, but you are not
  36:  obligated to do so.  If you do not wish to do so, delete this
  37:  exception statement from your version. */
  38: 
  39: 
  40: package java.awt;
  41: 
  42: import java.awt.peer.DialogPeer;
  43: 
  44: import javax.accessibility.AccessibleContext;
  45: import javax.accessibility.AccessibleRole;
  46: import javax.accessibility.AccessibleState;
  47: import javax.accessibility.AccessibleStateSet;
  48: 
  49: /**
  50:  * <code>Dialog</code> provides a top-level window normally used to receive 
  51:  * user input in applications.
  52:  * <p>
  53:  * A dialog always has another top-level window as owner and is only visible
  54:  * if this owner is visible to the user. The default layout of dialogs is the 
  55:  * <code>BorderLayout</code>. Dialogs can be modal (blocks user input to other
  56:  * components) or non-modal (user input in other components are allowed).
  57:  * </p> 
  58:  * 
  59:  * @author Aaron M. Renn (arenn@urbanophile.com)
  60:  * @author Tom Tromey (tromey@redhat.com)
  61:  */
  62: public class Dialog extends Window
  63: {
  64:   // Serialization constant
  65:   private static final long serialVersionUID = 5920926903803293709L;
  66: 
  67:   /**
  68:    * @serial Indicates whether or not this dialog box is modal.
  69:    */
  70:   private boolean modal;
  71: 
  72:   /**
  73:    * @serial Indicates whether or not this dialog box is resizable.
  74:    */
  75:   private boolean resizable = true;
  76: 
  77:   /**
  78:    * @serial The title string for this dialog box, which can be
  79:    *         <code>null</code>.
  80:    */
  81:   private String title;
  82: 
  83:   /**
  84:    * This field indicates whether the dialog is undecorated or not.
  85:    */
  86:   private boolean undecorated = false;
  87: 
  88:   /**
  89:    * Indicates that we are blocked for modality in show
  90:    */
  91:   private boolean blocked = false;
  92: 
  93:   /**
  94:    * Secondary EventQueue to handle AWT events while we are blocked for 
  95:    * modality in show.
  96:    */
  97:   private EventQueue eq2 = null;
  98: 
  99:   /**
 100:    * Initializes a new instance of <code>Dialog</code> with the specified
 101:    * parent, that is resizable and not modal, and which has no title.
 102:    * 
 103:    * @param parent The parent frame of this dialog box.
 104:    * @exception IllegalArgumentException If the owner's GraphicsConfiguration 
 105:    * is not from a screen device, or if owner is null. This exception is 
 106:    * always thrown when GraphicsEnvironment.isHeadless() returns true.
 107:    */
 108:   public Dialog(Frame parent)
 109:   {
 110:     this(parent, "", false);
 111:   }
 112: 
 113:   /**
 114:    * Initializes a new instance of <code>Dialog</code> with the specified
 115:    * parent and modality, that is resizable and which has no title.
 116:    * 
 117:    * @param parent The parent frame of this dialog box.
 118:    * @param modal <code>true</code> if this dialog box is modal,
 119:    * <code>false</code> otherwise.
 120:    * 
 121:    * @exception IllegalArgumentException If the owner's GraphicsConfiguration
 122:    * is not from a screen device, or if owner is null. This exception is 
 123:    * always thrown when GraphicsEnvironment.isHeadless() returns true.
 124:    */
 125:   public Dialog(Frame parent, boolean modal)
 126:   {
 127:     this(parent, "", modal);
 128:   }
 129: 
 130:   /**
 131:    * Initializes a new instance of <code>Dialog</code> with the specified
 132:    * parent, that is resizable and not modal, and which has the specified 
 133:    * title.
 134:    * 
 135:    * @param parent The parent frame of this dialog box.
 136:    * @param title The title string for this dialog box.
 137:    * 
 138:    * @exception IllegalArgumentException If the owner's GraphicsConfiguration
 139:    * is not from a screen device, or if owner is null. This exceptionnis 
 140:    * always thrown when GraphicsEnvironment.isHeadless() returns true.
 141:    */
 142:   public Dialog(Frame parent, String title)
 143:   {
 144:     this(parent, title, false);
 145:   }
 146: 
 147:   /**
 148:    * Initializes a new instance of <code>Dialog</code> with the specified,
 149:    * parent, title, and modality, that is resizable.
 150:    * 
 151:    * @param parent The parent frame of this dialog box.
 152:    * @param title The title string for this dialog box.
 153:    * @param modal <code>true</code> if this dialog box is modal,
 154:    * <code>false</code> otherwise.
 155:    *          
 156:    * @exception IllegalArgumentException If owner is null or
 157:    *              GraphicsEnvironment.isHeadless() returns true.
 158:    */
 159:   public Dialog(Frame parent, String title, boolean modal)
 160:   {
 161:     this(parent, title, modal, parent.getGraphicsConfiguration());
 162:   }
 163: 
 164:   /**
 165:    * Initializes a new instance of <code>Dialog</code> with the specified,
 166:    * parent, title, modality and <code>GraphicsConfiguration</code>, that is
 167:    * resizable.
 168:    * 
 169:    * @param parent The parent frame of this dialog box.
 170:    * @param title The title string for this dialog box.
 171:    * @param modal <code>true</code> if this dialog box is modal,
 172:    * <code>false</code> otherwise.
 173:    * @param gc The <code>GraphicsConfiguration</code> object to use. If 
 174:    * <code>null</code> the <code>GraphicsConfiguration</code> of the target 
 175:    * frame is used.
 176:    * 
 177:    * @exception IllegalArgumentException If owner is null, the
 178:    *              GraphicsConfiguration is not a screen device or
 179:    *              GraphicsEnvironment.isHeadless() returns true.
 180:    * @since 1.4
 181:    */
 182:   public Dialog(Frame parent, String title, boolean modal,
 183:                 GraphicsConfiguration gc)
 184:   {
 185:     super(parent, (gc == null) ? parent.getGraphicsConfiguration() : gc);
 186: 
 187:     // A null title is equivalent to an empty title
 188:     this.title = (title != null) ? title : "";
 189:     this.modal = modal;
 190:     visible = false;
 191: 
 192:     setLayout(new BorderLayout());
 193:   }
 194: 
 195:   /**
 196:    * Initializes a new instance of <code>Dialog</code> with the specified,
 197:    * parent, that is resizable.
 198:    * 
 199:    * @param owner The parent frame of this dialog box.
 200:    * 
 201:    * @exception IllegalArgumentException If parent is null. This exception is
 202:    * always thrown when GraphicsEnvironment.isHeadless() returns true.
 203:    * 
 204:    * @since 1.2
 205:    */
 206:   public Dialog(Dialog owner)
 207:   {
 208:     this(owner, "", false, owner.getGraphicsConfiguration());
 209:   }
 210: 
 211:   /**
 212:    * Initializes a new instance of <code>Dialog</code> with the specified,
 213:    * parent and title, that is resizable.
 214:    * 
 215:    * @param owner The parent frame of this dialog box.
 216:    * @param title The title string for this dialog box.
 217:    * 
 218:    * @exception IllegalArgumentException If parent is null. This exception is
 219:    *              always thrown when GraphicsEnvironment.isHeadless() returns
 220:    *              true.
 221:    * @since 1.2
 222:    */
 223:   public Dialog(Dialog owner, String title)
 224:   {
 225:     this(owner, title, false, owner.getGraphicsConfiguration());
 226:   }
 227: 
 228:   /**
 229:    * Initializes a new instance of <code>Dialog</code> with the specified,
 230:    * parent, title and modality, that is resizable.
 231:    * 
 232:    * @param owner The parent frame of this dialog box.
 233:    * @param title The title string for this dialog box.
 234:    * @param modal <code>true</code> if this dialog box is modal,
 235:    * <code>false</code> otherwise.
 236:    * 
 237:    * @exception IllegalArgumentException If parent is null. This exception is
 238:    * always thrown when GraphicsEnvironment.isHeadless() returns true.
 239:    * @since 1.2
 240:    */
 241:   public Dialog(Dialog owner, String title, boolean modal)
 242:   {
 243:     this(owner, title, modal, owner.getGraphicsConfiguration());
 244:   }
 245: 
 246:   /**
 247:    * Initializes a new instance of <code>Dialog</code> with the specified,
 248:    * parent, title, modality and <code>GraphicsConfiguration</code>, that is
 249:    * resizable.
 250:    * 
 251:    * @param parent The parent frame of this dialog box.
 252:    * @param title The title string for this dialog box.
 253:    * @param modal <code>true</code> if this dialog box is modal,
 254:    * <code>false</code> otherwise.
 255:    * @param gc The <code>GraphicsConfiguration</code> object to use. If 
 256:    * <code>null</code> the <code>GraphicsConfiguration</code> of the target 
 257:    * frame is used.
 258:    * 
 259:    * @exception IllegalArgumentException If parent is null, the
 260:    * GraphicsConfiguration is not a screen device or 
 261:    * GraphicsEnvironment.isHeadless() returns true.
 262:    * 
 263:    * @since 1.4
 264:    */
 265:   public Dialog(Dialog parent, String title, boolean modal,
 266:                 GraphicsConfiguration gc)
 267:   {
 268:     super(parent, (gc == null) ? parent.getGraphicsConfiguration() : gc);
 269: 
 270:     // A null title is equivalent to an empty title
 271:     this.title = (title != null) ? title : "";
 272:     this.modal = modal;
 273:     visible = false;
 274: 
 275:     setLayout(new BorderLayout());
 276:   }
 277: 
 278:   /**
 279:    * Returns the title of this dialog box.
 280:    * 
 281:    * @return The title of this dialog box.
 282:    */
 283:   public String getTitle()
 284:   {
 285:     return title;
 286:   }
 287: 
 288:   /**
 289:    * Sets the title of this dialog box to the specified string.
 290:    * 
 291:    * @param title the new title. If <code>null</code> an empty
 292:    * title will be set.
 293:    */
 294:   public synchronized void setTitle(String title)
 295:   {
 296:     // A null title is equivalent to an empty title
 297:     this.title = (title != null) ? title : "";
 298: 
 299:     if (peer != null)
 300:       {
 301:         DialogPeer d = (DialogPeer) peer;
 302:         d.setTitle(title);
 303:       }
 304:   }
 305: 
 306:   /**
 307:    * Tests whether or not this dialog box is modal.
 308:    * 
 309:    * @return <code>true</code> if this dialog box is modal, <code>false</code>
 310:    * otherwise.
 311:    */
 312:   public boolean isModal()
 313:   {
 314:     return modal;
 315:   }
 316: 
 317:   /**
 318:    * Changes the modality of this dialog box. This can only be done before the
 319:    * peer is created.
 320:    * 
 321:    * @param modal <code>true</code> to make this dialog box modal,
 322:    * <code>false</code> to make it non-modal. 
 323:    */
 324:   public void setModal(boolean modal)
 325:   {
 326:     this.modal = modal;
 327:   }
 328: 
 329:   /**
 330:    * Tests whether or not this dialog box is resizable.
 331:    * 
 332:    * @return <code>true</code> if this dialog is resizable,
 333:    * <code>false</code> otherwise.
 334:    */
 335:   public boolean isResizable()
 336:   {
 337:     return resizable;
 338:   }
 339: 
 340:   /**
 341:    * Changes the resizability of this dialog box.
 342:    * 
 343:    * @param resizable <code>true</code> to make this dialog resizable,
 344:    * <code>false</code> to make it non-resizable.
 345:    */
 346:   public synchronized void setResizable(boolean resizable)
 347:   {
 348:     this.resizable = resizable;
 349:     if (peer != null)
 350:       {
 351:         DialogPeer d = (DialogPeer) peer;
 352:         d.setResizable(resizable);
 353:       }
 354:   }
 355: 
 356:   /**
 357:    * Creates this object's native peer.
 358:    */
 359:   public synchronized void addNotify()
 360:   {
 361:     if (peer == null)
 362:       peer = getToolkit().createDialog(this);
 363:     super.addNotify();
 364:   }
 365: 
 366:   /**
 367:    * Makes this dialog visible and brings it to the front. If the dialog is
 368:    * modal and is not already visible, this call will not return until the
 369:    * dialog is hidden by someone calling hide or dispose. If this is the event
 370:    * dispatching thread we must ensure that another event thread runs while the
 371:    * one which invoked this method is blocked.
 372:    * 
 373:    * @deprecated Use {@link Component#setVisible(boolean)} instead.
 374:    */
 375:   public synchronized void show()
 376:   {
 377:     super.show();
 378: 
 379:     if (isModal())
 380:       {
 381:         // If already shown (and blocked) just return
 382:         if (blocked)
 383:           return;
 384: 
 385:         /*
 386:          * If show is called in the dispatch thread for a modal dialog it will
 387:          * block so we must run another thread so the events keep being
 388:          * dispatched.
 389:          */
 390:         if (EventQueue.isDispatchThread())
 391:           {
 392:             EventQueue eq = Toolkit.getDefaultToolkit().getSystemEventQueue();
 393:             eq2 = new EventQueue();
 394:             eq.push(eq2);
 395:           }
 396: 
 397:         try
 398:           {
 399:             blocked = true;
 400:             wait();
 401:             blocked = false;
 402:           }
 403:         catch (InterruptedException e)
 404:           {
 405:             blocked = false;
 406:           }
 407: 
 408:         if (eq2 != null)
 409:           {
 410:             eq2.pop();
 411:             eq2 = null;
 412:           }
 413:       }
 414:   }
 415: 
 416:   /**
 417:    * Hides the Dialog and then causes show() to return if it is currently
 418:    * blocked.
 419:    * 
 420:    * @deprecated Use {@link Component#setVisible(boolean)} instead.
 421:    */
 422:   public synchronized void hide()
 423:   {
 424:     if (blocked)
 425:       {
 426:         notifyAll();
 427:       }
 428: 
 429:     super.hide();
 430:   }
 431: 
 432:   /**
 433:    * Disposes the Dialog and then causes show() to return if it is currently
 434:    * blocked.
 435:    */
 436:   public synchronized void dispose()
 437:   {
 438:     if (blocked)
 439:       {
 440:         notifyAll();
 441:       }
 442: 
 443:     super.dispose();
 444:   }
 445: 
 446:   /**
 447:    * Returns a debugging string for this component.
 448:    * 
 449:    * @return A debugging string for this component.
 450:    */
 451:   protected String paramString()
 452:   {
 453:     return "title+" + title + ",modal=" + modal + ",resizable=" + resizable
 454:             + "," + super.paramString();
 455:   }
 456: 
 457:   /**
 458:    * Returns whether this frame is undecorated or not.
 459:    * 
 460:    * @return <code>true</code> if this dialog is undecorated,
 461:    * <code>false</code> otherwise.
 462:    * 
 463:    * @since 1.4
 464:    */
 465:   public boolean isUndecorated()
 466:   {
 467:     return undecorated;
 468:   }
 469: 
 470:   /**
 471:    * Disables or enables decorations for this frame. This method can only be
 472:    * called while the frame is not displayable.
 473:    * 
 474:    * @param undecorated <code>true</code> to disable dialog decorations,
 475:    * <code>false</code> otherwise.
 476:    * 
 477:    * @exception IllegalComponentStateException If this frame is displayable.
 478:    * @since 1.4
 479:    */
 480:   public void setUndecorated(boolean undecorated)
 481:   {
 482:     if (isDisplayable())
 483:       throw new IllegalComponentStateException();
 484: 
 485:     this.undecorated = undecorated;
 486:   }
 487: 
 488:   /**
 489:    * Accessibility support for <code>Dialog</code>.
 490:    */
 491:   protected class AccessibleAWTDialog
 492:       extends AccessibleAWTWindow
 493:   {
 494:     private static final long serialVersionUID = 4837230331833941201L;
 495: 
 496:     /**
 497:      * Gets the role of this object.
 498:      * @return AccessibleRole.DIALOG 
 499:      */
 500:     public AccessibleRole getAccessibleRole()
 501:     {
 502:       return AccessibleRole.DIALOG;
 503:     }
 504: 
 505:     /**
 506:      * Gets the state set of this object.
 507:      * @return The current state of this dialog.
 508:      */
 509:     public AccessibleStateSet getAccessibleStateSet()
 510:     {
 511:       AccessibleStateSet states = super.getAccessibleStateSet();
 512:       if (isResizable())
 513:         states.add(AccessibleState.RESIZABLE);
 514:       if (isModal())
 515:         states.add(AccessibleState.MODAL);
 516:       return states;
 517:     }
 518:   }
 519: 
 520:   /**
 521:    * Gets the AccessibleContext associated with this <code>Dialog</code>. The
 522:    * context is created, if necessary.
 523:    * 
 524:    * @return the associated context
 525:    */
 526:   public AccessibleContext getAccessibleContext()
 527:   {
 528:     /* Create the context if this is the first request */
 529:     if (accessibleContext == null)
 530:       accessibleContext = new AccessibleAWTDialog();
 531:     return accessibleContext;
 532:   }
 533: 
 534: }