libjava/java/awt/Toolkit.java

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