libjava/java/awt/Toolkit.java

   1 /* Toolkit.java -- AWT Toolkit superclass
   2    Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004
   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., 59 Temple Place, Suite 330, Boston, MA
  20 02111-1307 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.datatransfer.Clipboard;
  43 import java.awt.dnd.DragGestureEvent;
  44 import java.awt.dnd.DragGestureListener;
  45 import java.awt.dnd.DragGestureRecognizer;
  46 import java.awt.dnd.DragSource;
  47 import java.awt.dnd.peer.DragSourceContextPeer;
  48 import java.awt.event.AWTEventListener;
  49 import java.awt.event.KeyEvent;
  50 import java.awt.im.InputMethodHighlight;
  51 import java.awt.image.ColorModel;
  52 import java.awt.image.ImageObserver;
  53 import java.awt.image.ImageProducer;
  54 import java.awt.peer.ButtonPeer;
  55 import java.awt.peer.CanvasPeer;
  56 import java.awt.peer.CheckboxMenuItemPeer;
  57 import java.awt.peer.CheckboxPeer;
  58 import java.awt.peer.ChoicePeer;
  59 import java.awt.peer.DialogPeer;
  60 import java.awt.peer.FileDialogPeer;
  61 import java.awt.peer.FontPeer;
  62 import java.awt.peer.FramePeer;
  63 import java.awt.peer.LabelPeer;
  64 import java.awt.peer.LightweightPeer;
  65 import java.awt.peer.ListPeer;
  66 import java.awt.peer.MenuBarPeer;
  67 import java.awt.peer.MenuItemPeer;
  68 import java.awt.peer.MenuPeer;
  69 import java.awt.peer.PanelPeer;
  70 import java.awt.peer.PopupMenuPeer;
  71 import java.awt.peer.ScrollPanePeer;
  72 import java.awt.peer.ScrollbarPeer;
  73 import java.awt.peer.TextAreaPeer;
  74 import java.awt.peer.TextFieldPeer;
  75 import java.awt.peer.WindowPeer;
  76 import java.beans.PropertyChangeListener;
  77 import java.beans.PropertyChangeSupport;
  78 import java.net.URL;
  79 import java.util.Map;
  80 import java.util.Properties;
  81
  82 /**
  83  * The AWT system uses a set of native peer objects to implement its
  84  * widgets.  These peers are provided by a peer toolkit, that is accessed
  85  * via a subclass of this superclass.  The system toolkit is retrieved
  86  * by the static methods <code>getDefaultToolkit</code>.  This method
  87  * determines the system toolkit by examining the system property
  88  * <code>awt.toolkit</code>.  That property is set to the name of the
  89  * <code>Toolkit</code> subclass for the specified peer set.  If the
  90  * <code>awt.toolkit</code> property is not set, then the default
  91  * toolkit <code>gnu.java.awt.peer.gtk.GtkToolkit</code> is used.  This
  92  * toolkit creates its peers using the GTK+ toolkit.
  93  *
  94  * @author Aaron M. Renn <arenn@urbanophile.com>
  95  */
  96 public abstract class Toolkit
  97 {
  98   /** The default toolkit name. */
  99   private static String default_toolkit_name
 100     = gnu.classpath.Configuration.default_awt_peer_toolkit;
 101
 102   /**
 103    * The toolkit in use.  Once we load it, we don't ever change it
 104    * if the awt.toolkit property is set.
 105    */
 106   private static Toolkit toolkit;
 107
 108   /** The toolkit properties. */
 109   private static Properties props = new Properties();
 110
 111   protected final Map desktopProperties = new Properties();
 112
 113   protected final PropertyChangeSupport desktopPropsSupport
 114     = new PropertyChangeSupport(this);
 115
 116   /**
 117    * Default constructor for subclasses.
 118    */
 119   public Toolkit()
 120   {
 121   }
 122
 123   /**
 124    * Creates a peer object for the specified <code>Button</code>.
 125    *
 126    * @param target The <code>Button</code> to create the peer for.
 127    *
 128    * @return The peer for the specified <code>Button</code> object.
 129    *
 130    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 131    */
 132   protected abstract ButtonPeer createButton(Button target);
 133
 134   /**
 135    * Creates a peer object for the specified <code>TextField</code>.
 136    *
 137    * @param target The <code>TextField</code> to create the peer for.
 138    *
 139    * @return The peer for the specified <code>TextField</code> object.
 140    *
 141    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 142    */
 143   protected abstract TextFieldPeer createTextField(TextField target);
 144
 145   /**
 146    * Creates a peer object for the specified <code>Label</code>.
 147    *
 148    * @param target The <code>Label</code> to create the peer for.
 149    *
 150    * @return The peer for the specified <code>Label</code> object.
 151    *
 152    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 153    */
 154   protected abstract LabelPeer createLabel(Label target);
 155
 156   /**
 157    * Creates a peer object for the specified <code>List</code>.
 158    *
 159    * @param target The <code>List</code> to create the peer for.
 160    *
 161    * @return The peer for the specified <code>List</code> object.
 162    *
 163    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 164    */
 165   protected abstract ListPeer createList(List target);
 166
 167   /**
 168    * Creates a peer object for the specified <code>Checkbox</code>.
 169    *
 170    * @param target The <code>Checkbox</code> to create the peer for.
 171    *
 172    * @return The peer for the specified <code>Checkbox</code> object.
 173    *
 174    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 175    */
 176   protected abstract CheckboxPeer createCheckbox(Checkbox target);
 177
 178   /**
 179    * Creates a peer object for the specified <code>Scrollbar</code>.
 180    *
 181    * @param target The <code>Scrollbar</code> to create the peer for.
 182    *
 183    * @return The peer for the specified <code>Scrollbar</code> object.
 184    *
 185    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 186    */
 187   protected abstract ScrollbarPeer createScrollbar(Scrollbar target);
 188
 189   /**
 190    * Creates a peer object for the specified <code>ScrollPane</code>.
 191    *
 192    * @param target The <code>ScrollPane</code> to create the peer for.
 193    *
 194    * @return The peer for the specified <code>ScrollPane</code> object.
 195    *
 196    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 197    */
 198   protected abstract ScrollPanePeer createScrollPane(ScrollPane target);
 199
 200   /**
 201    * Creates a peer object for the specified <code>TextArea</code>.
 202    *
 203    * @param target The <code>TextArea</code> to create the peer for.
 204    *
 205    * @return The peer for the specified <code>TextArea</code> object.
 206    *
 207    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 208    */
 209   protected abstract TextAreaPeer createTextArea(TextArea target);
 210
 211   /**
 212    * Creates a peer object for the specified <code>Choice</code>.
 213    *
 214    * @param target The <code>Choice</code> to create the peer for.
 215    *
 216    * @return The peer for the specified <code>Choice</code> object.
 217    *
 218    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 219    */
 220   protected abstract ChoicePeer createChoice(Choice target);
 221
 222   /**
 223    * Creates a peer object for the specified <code>Frame</code>.
 224    *
 225    * @param target The <code>Frame</code> to create the peer for.
 226    *
 227    * @return The peer for the specified <code>Frame</code> object.
 228    *
 229    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 230    */
 231   protected abstract FramePeer createFrame(Frame target);
 232
 233   /**
 234    * Creates a peer object for the specified <code>Canvas</code>.
 235    *
 236    * @param target The <code>Canvas</code> to create the peer for.
 237    *
 238    * @return The peer for the specified <code>Canvas</code> object.
 239    */
 240   protected abstract CanvasPeer createCanvas(Canvas target);
 241
 242   /**
 243    * Creates a peer object for the specified <code>Panel</code>.
 244    *
 245    * @param target The <code>Panel</code> to create the peer for.
 246    *
 247    * @return The peer for the specified <code>Panel</code> object.
 248    */
 249   protected abstract PanelPeer createPanel(Panel target);
 250
 251   /**
 252    * Creates a peer object for the specified <code>Window</code>.
 253    *
 254    * @param target The <code>Window</code> to create the peer for.
 255    *
 256    * @return The peer for the specified <code>Window</code> object.
 257    *
 258    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 259    */
 260   protected abstract WindowPeer createWindow(Window target);
 261
 262   /**
 263    * Creates a peer object for the specified <code>Dialog</code>.
 264    *
 265    * @param target The dialog to create the peer for
 266    *
 267    * @return The peer for the specified font name.
 268    *
 269    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 270    */
 271   protected abstract DialogPeer createDialog(Dialog target);
 272
 273   /**
 274    * Creates a peer object for the specified <code>MenuBar</code>.
 275    *
 276    * @param target The <code>MenuBar</code> to create the peer for.
 277    *
 278    * @return The peer for the specified <code>MenuBar</code> object.
 279    *
 280    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 281    */
 282   protected abstract MenuBarPeer createMenuBar(MenuBar target);
 283
 284   /**
 285    * Creates a peer object for the specified <code>Menu</code>.
 286    *
 287    * @param target The <code>Menu</code> to create the peer for.
 288    *
 289    * @return The peer for the specified <code>Menu</code> object.
 290    *
 291    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 292    */
 293   protected abstract MenuPeer createMenu(Menu target);
 294
 295   /**
 296    * Creates a peer object for the specified <code>PopupMenu</code>.
 297    *
 298    * @param target The <code>PopupMenu</code> to create the peer for.
 299    *
 300    * @return The peer for the specified <code>PopupMenu</code> object.
 301    *
 302    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 303    */
 304   protected abstract PopupMenuPeer createPopupMenu(PopupMenu target);
 305
 306   /**
 307    * Creates a peer object for the specified <code>MenuItem</code>.
 308    *
 309    * @param target The <code>MenuItem</code> to create the peer for.
 310    *
 311    * @return The peer for the specified <code>MenuItem</code> object.
 312    *
 313    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 314    */
 315   protected abstract MenuItemPeer createMenuItem(MenuItem target);
 316
 317   /**
 318    * Creates a peer object for the specified <code>FileDialog</code>.
 319    *
 320    * @param target The <code>FileDialog</code> to create the peer for.
 321    *
 322    * @return The peer for the specified <code>FileDialog</code> object.
 323    *
 324    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 325    */
 326   protected abstract FileDialogPeer createFileDialog(FileDialog target);
 327
 328   /**
 329    * Creates a peer object for the specified <code>CheckboxMenuItem</code>.
 330    *
 331    * @param target The <code>CheckboxMenuItem</code> to create the peer for.
 332    *
 333    * @return The peer for the specified <code>CheckboxMenuItem</code> object.
 334    *
 335    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 336    */
 337   protected abstract CheckboxMenuItemPeer
 338     createCheckboxMenuItem(CheckboxMenuItem target);
 339
 340   /**
 341    * Creates a peer object for the specified <code>Component</code>.  The
 342    * peer returned by this method is not a native windowing system peer
 343    * with its own native window.  Instead, this method allows the component
 344    * to draw on its parent window as a "lightweight" widget.
 345    *
 346    * @param target The <code>Component</code> to create the peer for.
 347    *
 348    * @return The peer for the specified <code>Component</code> object.
 349    */
 350   protected LightweightPeer createComponent(Component target)
 351   {
 352     return new gnu.java.awt.peer.GLightweightPeer (target);
 353   }
 354
 355   /**
 356    * Creates a peer object for the specified font name.
 357    *
 358    * @param name The font to create the peer for.
 359    * @param style The font style to create the peer for.
 360    *
 361    * @return The peer for the specified font name.
 362    *
 363    * @deprecated
 364    */
 365   protected abstract FontPeer getFontPeer(String name, int style);
 366
 367   /**
 368    * Copies the current system colors into the specified array.  This is
 369    * the interface used by the <code>SystemColor</code> class.  Although
 370    * this method fills in the array with some default colors a real Toolkit
 371    * should override this method and provide real system colors for the
 372    * native GUI platform.
 373    *
 374    * @param systemColors The array to copy the system colors into.
 375    * It must be at least 26 elements.
 376    *
 377    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 378    *
 379    * @see java.awt.SystemColor
 380    */
 381   protected void loadSystemColors(int systemColors[])
 382   {
 383     systemColors[SystemColor.DESKTOP]                 = 0xFF005C5C;
 384     systemColors[SystemColor.ACTIVE_CAPTION]          = 0xFF000080;
 385     systemColors[SystemColor.ACTIVE_CAPTION_TEXT]     = 0xFFFFFFFF;
 386     systemColors[SystemColor.ACTIVE_CAPTION_BORDER]   = 0xFFC0C0C0;
 387     systemColors[SystemColor.INACTIVE_CAPTION]        = 0xFF808080;
 388     systemColors[SystemColor.INACTIVE_CAPTION_TEXT]   = 0xFFC0C0C0;
 389     systemColors[SystemColor.INACTIVE_CAPTION_BORDER] = 0xFFC0C0C0;
 390     systemColors[SystemColor.WINDOW]                  = 0xFFFFFFFF;
 391     systemColors[SystemColor.WINDOW_BORDER]           = 0xFF000000;
 392     systemColors[SystemColor.WINDOW_TEXT]             = 0xFF000000;
 393     systemColors[SystemColor.MENU]                    = 0xFFC0C0C0;
 394     systemColors[SystemColor.MENU_TEXT]               = 0xFF000000;
 395     systemColors[SystemColor.TEXT]                    = 0xFFC0C0C0;
 396     systemColors[SystemColor.TEXT_TEXT]               = 0xFF000000;
 397     systemColors[SystemColor.TEXT_HIGHLIGHT]          = 0xFF000090;
 398     systemColors[SystemColor.TEXT_HIGHLIGHT_TEXT]     = 0xFFFFFFFF;
 399     systemColors[SystemColor.TEXT_INACTIVE_TEXT]      = 0xFF808080;
 400     systemColors[SystemColor.CONTROL]                 = 0xFFC0C0C0;
 401     systemColors[SystemColor.CONTROL_TEXT]            = 0xFF000000;
 402     systemColors[SystemColor.CONTROL_HIGHLIGHT]       = 0xFFFFFFFF;
 403     systemColors[SystemColor.CONTROL_LT_HIGHLIGHT]    = 0xFFE0E0E0;
 404     systemColors[SystemColor.CONTROL_SHADOW]          = 0xFF808080;
 405     systemColors[SystemColor.CONTROL_DK_SHADOW]       = 0xFF000000;
 406     systemColors[SystemColor.SCROLLBAR]               = 0xFFE0E0E0;
 407     systemColors[SystemColor.INFO]                    = 0xFFE0E000;
 408     systemColors[SystemColor.INFO_TEXT]               = 0xFF000000;
 409   }
 410
 411   /**
 412    * @since 1.4
 413    *
 414    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 415    */
 416   public void setDynamicLayout(boolean dynamic)
 417   {
 418   }
 419
 420   /**
 421    * @since 1.4
 422    *
 423    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 424    */
 425   protected boolean isDynamicLayoutSet()
 426   {
 427     return false;
 428   }
 429
 430   /**
 431    * @since 1.4
 432    *
 433    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 434    */
 435   public boolean isDynamicLayoutActive()
 436   {
 437     return false;
 438   }
 439
 440   /**
 441    * Returns the dimensions of the screen in pixels.
 442    *
 443    * @return The dimensions of the screen in pixels.
 444    *
 445    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 446    */
 447   public abstract Dimension getScreenSize();
 448
 449   /**
 450    * Returns the screen resolution in dots per square inch.
 451    *
 452    * @return The screen resolution in dots per square inch.
 453    *
 454    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 455    */
 456   public abstract int getScreenResolution();
 457
 458   /**
 459    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 460    *
 461    * @since 1.4
 462    */
 463   public Insets getScreenInsets(GraphicsConfiguration gc)
 464   {
 465     return null;
 466   }
 467
 468   /**
 469    * Returns the color model of the screen.
 470    *
 471    * @return The color model of the screen.
 472    *
 473    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 474    */
 475   public abstract ColorModel getColorModel();
 476
 477   /**
 478    * Returns the names of the available fonts.
 479    *
 480    * @return The names of the available fonts.
 481    *
 482    * @deprecated
 483    */
 484   public abstract String[] getFontList();
 485
 486   /**
 487    * Return the font metrics for the specified font
 488    *
 489    * @param name The name of the font to return metrics for.
 490    *
 491    * @return The requested font metrics.
 492    *
 493    * @deprecated
 494    */
 495   public abstract FontMetrics getFontMetrics(Font name);
 496
 497   /**
 498    * Flushes any buffered data to the screen so that it is in sync with
 499    * what the AWT system has drawn to it.
 500    */
 501   public abstract void sync();
 502
 503   /**
 504    * Returns an instance of the default toolkit.  The default toolkit is
 505    * the subclass of <code>Toolkit</code> specified in the system property
 506    * <code>awt.toolkit</code>, or <code>gnu.java.awt.peer.gtk.GtkToolkit</code>
 507    * if the property is not set.
 508    *
 509    * @return An instance of the system default toolkit.
 510    *
 511    * @throws AWTError If the toolkit cannot be loaded.
 512    */
 513   public static Toolkit getDefaultToolkit()
 514   {
 515     if (toolkit != null)
 516       return toolkit;
 517     String toolkit_name = System.getProperty("awt.toolkit",
 518                                              default_toolkit_name);
 519     try
 520       {
 521         Class cls = Class.forName(toolkit_name);
 522         Object obj = cls.newInstance();
 523         if (!(obj instanceof Toolkit))
 524           throw new AWTError(toolkit_name + " is not a subclass of " +
 525                              "java.awt.Toolkit");
 526         toolkit = (Toolkit) obj;
 527         return toolkit;
 528       }
 529     catch (Throwable t)
 530       {
 531         AWTError e = new AWTError("Cannot load AWT toolkit: " + toolkit_name);
 532         throw (AWTError) e.initCause(t);
 533       }
 534   }
 535
 536   /**
 537    * Returns an image from the specified file, which must be in a
 538    * recognized format.  Supported formats vary from toolkit to toolkit.
 539    *
 540    * @return name The name of the file to read the image from.
 541    */
 542   public abstract Image getImage(String name);
 543
 544   /**
 545    * Returns an image from the specified URL, which must be in a
 546    * recognized format.  Supported formats vary from toolkit to toolkit.
 547    *
 548    * @return url The URl to read the image from.
 549    */
 550   public abstract Image getImage(URL url);
 551
 552   public abstract Image createImage(String filename);
 553
 554   public abstract Image createImage(URL url);
 555
 556   /**
 557    * Readies an image to be rendered on the screen.  The width and height
 558    * values can be set to the default sizes for the image by passing -1
 559    * in those parameters.
 560    *
 561    * @param image The image to prepare for rendering.
 562    * @param width The width of the image.
 563    * @param height The height of the image.
 564    * @param observer The observer to receive events about the preparation
 565    * process.
 566    *
 567    * @return <code>true</code> if the image is already prepared for rendering,
 568    * <code>false</code> otherwise.
 569    */
 570   public abstract boolean prepareImage(Image image, int width, int height,
 571                                        ImageObserver observer);
 572
 573   /**
 574    * Checks the status of specified image as it is being readied for
 575    * rendering.
 576    *
 577    * @param image The image to prepare for rendering.
 578    * @param width The width of the image.
 579    * @param height The height of the image.
 580    * @param observer The observer to receive events about the preparation
 581    * process.
 582    *
 583    * @return A union of the bitmasks from
 584    * <code>java.awt.image.ImageObserver</code> that indicates the current
 585    * state of the imaging readying process.
 586    */
 587   public abstract int checkImage(Image image, int width, int height,
 588                                  ImageObserver observer);
 589
 590   /**
 591    * Creates an image using the specified <code>ImageProducer</code>
 592    *
 593    * @param producer The <code>ImageProducer</code> to create the image from.
 594    *
 595    * @return The created image.
 596    */
 597   public abstract Image createImage(ImageProducer producer);
 598
 599   /**
 600    * Creates an image from the specified byte array. The array must be in
 601    * a recognized format.  Supported formats vary from toolkit to toolkit.
 602    *
 603    * @param data The raw image data.
 604    *
 605    * @return The created image.
 606    */
 607   public Image createImage(byte[] data)
 608   {
 609     return createImage(data, 0, data.length);
 610   }
 611
 612   /**
 613    * Creates an image from the specified portion of the byte array passed.
 614    * The array must be in a recognized format.  Supported formats vary from
 615    * toolkit to toolkit.
 616    *
 617    * @param data The raw image data.
 618    * @param offset The offset into the data where the image data starts.
 619    * @param len The length of the image data.
 620    *
 621    * @return The created image.
 622    */
 623   public abstract Image createImage(byte[] data, int offset, int len);
 624
 625   /**
 626    * Returns a instance of <code>PrintJob</code> for the specified
 627    * arguments.
 628    *
 629    * @param frame The window initiating the print job.
 630    * @param title The print job title.
 631    * @param props The print job properties.
 632    *
 633    * @return The requested print job, or <code>null</code> if the job
 634    * was cancelled.
 635    *
 636    * @exception NullPointerException If frame is null,
 637    * or GraphicsEnvironment.isHeadless() returns true.
 638    * @exception SecurityException If this thread is not allowed to initiate
 639    * a print job request.
 640    */
 641   public abstract PrintJob getPrintJob(Frame frame, String title,
 642                                        Properties props);
 643
 644   /**
 645    * Returns a instance of <code>PrintJob</code> for the specified
 646    * arguments.
 647    *
 648    * @param frame The window initiating the print job.
 649    * @param title The print job title.
 650    * @param jobAttr A set of job attributes which will control the print job.
 651    * @param pageAttr A set of page attributes which will control the print job.
 652    *
 653    * @exception NullPointerException If frame is null, and either jobAttr is null
 654    * or jobAttr.getDialog() returns JobAttributes.DialogType.NATIVE.
 655    * @exception IllegalArgumentException If pageAttrspecifies differing cross
 656    * feed and feed resolutions, or when GraphicsEnvironment.isHeadless() returns
 657    * true.
 658    * @exception SecurityException If this thread is not allowed to initiate
 659    * a print job request.
 660    *
 661    * @since 1.3
 662    */
 663   public PrintJob getPrintJob(Frame frame, String title,
 664                               JobAttributes jobAttr, PageAttributes pageAttr)
 665   {
 666     return null;
 667   }
 668
 669   /**
 670    * Causes a "beep" tone to be generated.
 671    */
 672   public abstract void beep();
 673
 674   /**
 675    * Returns the system clipboard.
 676    *
 677    * @return THe system clipboard.
 678    *
 679    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 680    */
 681   public abstract Clipboard getSystemClipboard();
 682
 683   /**
 684    * Gets the singleton instance of the system selection as a Clipboard object.
 685    *
 686    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 687    *
 688    * @since 1.4
 689    */
 690   public Clipboard getSystemSelection()
 691   {
 692     return null;
 693   }
 694
 695   /**
 696    * Returns the accelerator key mask for menu shortcuts. The default is
 697    * <code>Event.CTRL_MASK</code>.  A toolkit must override this method
 698    * to change the default.
 699    *
 700    * @return The key mask for the menu accelerator key.
 701    *
 702    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 703    */
 704   public int getMenuShortcutKeyMask()
 705   {
 706     return Event.CTRL_MASK;
 707   }
 708
 709   /**
 710    * Returns whether the given locking key on the keyboard is currently in its
 711    * "on" state.
 712    *
 713    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 714    * @exception IllegalArgumentException If keyCode is not one of the valid keys.
 715    * @exception UnsupportedOperationException If the host system doesn't allow
 716    * getting the state of this key programmatically, or if the keyboard doesn't
 717    * have this key.
 718    */
 719   public boolean getLockingKeyState(int keyCode)
 720   {
 721     if (keyCode != KeyEvent.VK_CAPS_LOCK
 722         && keyCode != KeyEvent.VK_NUM_LOCK
 723         && keyCode != KeyEvent.VK_SCROLL_LOCK)
 724       throw new IllegalArgumentException();
 725
 726     throw new UnsupportedOperationException();
 727   }
 728
 729   /**
 730    * Sets the state of the given locking key on the keyboard.
 731    *
 732    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 733    * @exception IllegalArgumentException If keyCode is not one of the valid keys.
 734    * @exception UnsupportedOperationException If the host system doesn't allow
 735    * getting the state of this key programmatically, or if the keyboard doesn't
 736    * have this key.
 737    */
 738   public void setLockingKeyState(int keyCode, boolean on)
 739   {
 740     if (keyCode != KeyEvent.VK_CAPS_LOCK
 741         && keyCode != KeyEvent.VK_NUM_LOCK
 742         && keyCode != KeyEvent.VK_SCROLL_LOCK)
 743       throw new IllegalArgumentException();
 744
 745     throw new UnsupportedOperationException();
 746   }
 747
 748   /**
 749    * Returns the native container object of the specified component.  This
 750    * method is necessary because the parent component might be a lightweight
 751    * component.
 752    *
 753    * @param component The component to fetch the native container for.
 754    *
 755    * @return The native container object for this component.
 756    */
 757   protected static Container getNativeContainer(Component component)
 758   {
 759     component = component.getParent();
 760     while (true)
 761       {
 762         if (component == null)
 763           return null;
 764         if (! (component instanceof Container))
 765           {
 766             component = component.getParent();
 767             continue;
 768           }
 769         if (component.getPeer() instanceof LightweightPeer)
 770           {
 771             component = component.getParent();
 772             continue;
 773           }
 774         return (Container) component;
 775       }
 776   }
 777
 778   /**
 779    * Creates a new custom cursor object.
 780    *
 781    * @exception IndexOutOfBoundsException If the hotSpot values are outside
 782    * the bounds of the cursor.
 783    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 784    */
 785   public Cursor createCustomCursor(Image cursor, Point hotSpot, String name)
 786   {
 787     // Presumably the only reason this isn't abstract is for backwards
 788     // compatibility? FIXME?
 789     return null;
 790   }
 791
 792   /**
 793    * Returns the supported cursor dimension which is closest to the
 794    * desired sizes.
 795    *
 796    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 797    */
 798   public Dimension getBestCursorSize(int preferredWidth, int preferredHeight)
 799   {
 800     return new Dimension (0,0);
 801   }
 802
 803   /**
 804    * Returns the maximum number of colors the Toolkit supports in a custom
 805    * cursor palette.
 806    *
 807    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 808    */
 809   public int getMaximumCursorColors()
 810   {
 811     return 0;
 812   }
 813
 814   /**
 815    * Returns whether Toolkit supports this state for Frames.
 816    *
 817    * @exception HeadlessException If GraphicsEnvironment.isHeadless() is true.
 818    *
 819    * @since 1.4
 820    */
 821   public boolean isFrameStateSupported(int state)
 822   {
 823     return false;
 824   }
 825
 826   /**
 827    * Returns the value of the property with the specified name, or the
 828    * default value if the property does not exist.
 829    *
 830    * @param key The name of the property to retrieve.
 831    * @param def The default value of the property.
 832    */
 833   public static String getProperty(String key, String def)
 834   {
 835     return props.getProperty(key, def);
 836   }
 837
 838
 839   /**
 840    * Returns the event queue that is suitable for the calling context.
 841    *
 842    * <p>Despite the word &#x201c;System&#x201d; in the name of this
 843    * method, a toolkit may provide different event queues for each
 844    * applet. There is no guarantee that the same queue is shared
 845    * system-wide.
 846    *
 847    * <p>The implementation first checks whether a
 848    * SecurityManager has been installed. If so, its {@link
 849    * java.lang.SecurityManager#checkAwtEventQueueAccess()} method gets
 850    * called. The security manager will throw a SecurityException if it
 851    * does not grant the permission to access the event queue.
 852    *
 853    * <p>Next, the call is delegated to {@link
 854    * #getSystemEventQueueImpl()}.
 855    *
 856    * @return The event queue for this applet (or application).
 857    *
 858    * @throws SecurityException if a security manager has been
 859    * installed, and it does not grant the permission to access the
 860    * event queue.
 861    */
 862   public final EventQueue getSystemEventQueue()
 863   {
 864     SecurityManager sm;
 865
 866     sm = System.getSecurityManager();
 867     if (sm != null)
 868       sm.checkAwtEventQueueAccess();
 869
 870     return getSystemEventQueueImpl();
 871   }
 872
 873
 874   /**
 875    * Returns the event queue that is suitable for the calling context.
 876    *
 877    * <p>Despite the word &#x201c;System&#x201d; in the name of this
 878    * method, a toolkit may provide different event queues for each
 879    * applet. There is no guarantee that the same queue is shared
 880    * system-wide.
 881    *
 882    * <p>No security checks are performed, which is why this method
 883    * may only be called by Toolkits.
 884    *
 885    * @see #getSystemEventQueue()
 886    */
 887   protected abstract EventQueue getSystemEventQueueImpl();
 888
 889
 890   /**
 891    * @since 1.3
 892    */
 893   public abstract DragSourceContextPeer
 894     createDragSourceContextPeer(DragGestureEvent e);
 895
 896   /**
 897    * @since 1.3
 898    */
 899   public DragGestureRecognizer
 900     createDragGestureRecognizer(Class recognizer, DragSource ds,
 901                                 Component comp, int actions,
 902                                 DragGestureListener l)
 903   {
 904     return null;
 905   }
 906
 907   public final Object getDesktopProperty(String propertyName)
 908   {
 909     return desktopProperties.get(propertyName);
 910   }
 911
 912   protected final void setDesktopProperty(String name, Object newValue)
 913   {
 914     Object oldValue = getDesktopProperty(name);
 915     desktopProperties.put(name, newValue);
 916     desktopPropsSupport.firePropertyChange(name, oldValue, newValue);
 917   }
 918
 919   protected Object lazilyLoadDesktopProperty(String name)
 920   {
 921     // FIXME - what is this??
 922     return null;
 923   }
 924
 925   protected void initializeDesktopProperties()
 926   {
 927     // Overridden by toolkit implementation?
 928   }
 929
 930   public void addPropertyChangeListener(String name,
 931                                         PropertyChangeListener pcl)
 932   {
 933     desktopPropsSupport.addPropertyChangeListener(name, pcl);
 934   }
 935
 936   public void removePropertyChangeListener(String name,
 937                                            PropertyChangeListener pcl)
 938   {
 939     desktopPropsSupport.removePropertyChangeListener(name, pcl);
 940   }
 941
 942   /**
 943    * @since 1.4
 944    */
 945   public PropertyChangeListener[] getPropertyChangeListeners()
 946   {
 947     return desktopPropsSupport.getPropertyChangeListeners();
 948   }
 949
 950   /**
 951    * @since 1.4
 952    */
 953   public PropertyChangeListener[] getPropertyChangeListeners(String name)
 954   {
 955     return desktopPropsSupport.getPropertyChangeListeners(name);
 956   }
 957
 958   public void addAWTEventListener(AWTEventListener listener, long eventMask)
 959   {
 960     // SecurityManager s = System.getSecurityManager();
 961     // if (s != null)
 962     //  s.checkPermission(AWTPermission("listenToAllAWTEvents"));
 963     // FIXME
 964   }
 965
 966   public void removeAWTEventListener(AWTEventListener listener)
 967   {
 968     // FIXME
 969   }
 970
 971   /**
 972    * @since 1.4
 973    */
 974   public AWTEventListener[] getAWTEventListeners()
 975   {
 976     return null;
 977   }
 978
 979   /**
 980    * @since 1.4
 981    */
 982   public AWTEventListener[] getAWTEventListeners(long mask)
 983   {
 984     return null;
 985   }
 986
 987   /**
 988    * @since 1.3
 989    */
 990   public abstract Map mapInputMethodHighlight(InputMethodHighlight highlight);
 991 } // class Toolkit