libjava/java/awt/Toolkit.java

   1 /* Toolkit.java -- AWT Toolkit superclass
   2    Copyright (C) 1999, 2000, 2001, 2002 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.event.*;
  42 import java.awt.peer.*;
  43 import java.awt.image.*;
  44 import java.awt.datatransfer.Clipboard;
  45 import java.util.Properties;
  46 import java.net.URL;
  47 import java.beans.*;
  48
  49 /**
  50   * The AWT system uses a set of native peer objects to implement its
  51   * widgets.  These peers are provided by a peer toolkit, that is accessed
  52   * via a subclass of this superclass.  The system toolkit is retrieved
  53   * by the static methods <code>getDefaultToolkit</code>.  This method
  54   * determines the system toolkit by examining the system property
  55   * <code>awt.toolkit</code>.  That property is set to the name of the
  56   * <code>Toolkit</code> subclass for the specified peer set.  If the
  57   * <code>awt.toolkit</code> property is not set, then the default
  58   * toolkit <code>gnu.java.awt.peer.gtk.GtkToolkit</code> is used.  This
  59   * toolkit creates its peers using the GTK+ toolkit.
  60   *
  61   * @author Aaron M. Renn (arenn@urbanophile.com)
  62   */
  63 public abstract class Toolkit
  64 {
  65
  66 /*
  67  * Static Variables
  68  */
  69
  70 // The default toolkit name.
  71 private static String default_toolkit_name =
  72   "gnu.java.awt.peer.gtk.GtkToolkit";
  73
  74 // The toolkit in use.  Once we load it, we don't ever change it
  75 // if the awt.toolkit propert is set.
  76 private static Toolkit toolkit;
  77
  78 // The toolkit properties
  79 private static Properties props = new Properties();
  80
  81 private PropertyChangeSupport changeSupport = new PropertyChangeSupport(this);
  82
  83 private Properties desktopProperties = new Properties();
  84
  85 /*************************************************************************/
  86
  87 /*
  88  * Static Methods
  89  */
  90
  91 /**
  92   * Returns an instance of the default toolkit.  The default toolkit is
  93   * the subclass of <code>Toolkit</code> specified in the system property
  94   * <code>awt.toolkit</code>, or <code>gnu.java.awt.peer.gtk.GtkToolkit</code>
  95   * if the property is not set.
  96   *
  97   * @return An instance of the system default toolkit.
  98   *
  99   * @error AWTError If the toolkit cannot be loaded.
 100   */
 101 public static Toolkit
 102 getDefaultToolkit()
 103 {
 104   if (toolkit != null)
 105     return(toolkit);
 106
 107   String toolkit_name = System.getProperty("awt.toolkit",
 108                                            default_toolkit_name);
 109
 110   try
 111     {
 112       Class cls = Class.forName(toolkit_name);
 113       Object obj = cls.newInstance();
 114
 115       if (!(obj instanceof Toolkit))
 116         throw new AWTError(toolkit_name + " is not a subclass of " +
 117                            "java.awt.Toolkit");
 118
 119       toolkit = (Toolkit)obj;
 120       return(toolkit);
 121     }
 122   catch(Exception e)
 123     {
 124       throw new AWTError("Cannot load AWT toolkit: " + e.getMessage());
 125     }
 126 }
 127
 128 /*************************************************************************/
 129
 130 /**
 131   * Returns the value of the property with the specified name, or the
 132   * default value if the property does not exist.
 133   *
 134   * @param key The name of the property to retrieve.
 135   * @param defThe default value of the property.
 136   */
 137 public static String
 138 getProperty(String key, String def)
 139 {
 140   return(props.getProperty(key, def));
 141 }
 142
 143 /*************************************************************************/
 144
 145 /**
 146   * Returns the native container object of the specified component.  This
 147   * method is necessary because the parent component might be a lightweight
 148   * component.
 149   *
 150   * @param component The component to fetch the native container for.
 151   *
 152   * @return The native container object for this component.
 153   */
 154 protected static Container
 155 getNativeContainer(Component component)
 156 {
 157   component = component.getParent();
 158
 159   for(;;)
 160     {
 161       if (component == null)
 162         return(null);
 163
 164       if (!(component instanceof Container))
 165         {
 166           component = component.getParent();
 167           continue;
 168         }
 169
 170       if (component.getPeer() instanceof LightweightPeer)
 171         {
 172           component = component.getParent();
 173           continue;
 174         }
 175
 176       return((Container)component);
 177     }
 178 }
 179
 180 /*************************************************************************/
 181
 182 /*
 183  * Constructors
 184  */
 185
 186 /**
 187   * Default constructor for subclasses.
 188   */
 189 public
 190 Toolkit()
 191 {
 192 }
 193
 194 /*************************************************************************/
 195
 196 /*
 197  * Instance Methods
 198  */
 199
 200 /**
 201   * Creates a peer object for the specified <code>Button</code>.
 202   *
 203   * @param target The <code>Button</code> to create the peer for.
 204   *
 205   * @return The peer for the specified <code>Button</code> object.
 206   */
 207 protected abstract ButtonPeer
 208 createButton(Button target);
 209
 210 /*************************************************************************/
 211
 212 /**
 213   * Creates a peer object for the specified <code>TextField</code>.
 214   *
 215   * @param target The <code>TextField</code> to create the peer for.
 216   *
 217   * @return The peer for the specified <code>TextField</code> object.
 218   */
 219 protected abstract TextFieldPeer
 220 createTextField(TextField target);
 221
 222 /*************************************************************************/
 223
 224 /**
 225   * Creates a peer object for the specified <code>Label</code>.
 226   *
 227   * @param target The <code>Label</code> to create the peer for.
 228   *
 229   * @return The peer for the specified <code>Label</code> object.
 230   */
 231 protected abstract LabelPeer
 232 createLabel(Label target);
 233
 234 /*************************************************************************/
 235
 236 /**
 237   * Creates a peer object for the specified <code>List</code>.
 238   *
 239   * @param target The <code>List</code> to create the peer for.
 240   *
 241   * @return The peer for the specified <code>List</code> object.
 242   */
 243 protected abstract ListPeer
 244 createList(List target);
 245
 246 /*************************************************************************/
 247
 248 /**
 249   * Creates a peer object for the specified <code>Checkbox</code>.
 250   *
 251   * @param target The <code>Checkbox</code> to create the peer for.
 252   *
 253   * @return The peer for the specified <code>Checkbox</code> object.
 254   */
 255 protected abstract CheckboxPeer
 256 createCheckbox(Checkbox target);
 257
 258 /*************************************************************************/
 259
 260 /**
 261   * Creates a peer object for the specified <code>Scrollbar</code>.
 262   *
 263   * @param target The <code>Scrollbar</code> to create the peer for.
 264   *
 265   * @return The peer for the specified <code>Scrollbar</code> object.
 266   */
 267 protected abstract ScrollbarPeer
 268 createScrollbar(Scrollbar target);
 269
 270 /*************************************************************************/
 271
 272 /**
 273   * Creates a peer object for the specified <code>ScrollPane</code>.
 274   *
 275   * @param target The <code>ScrollPane</code> to create the peer for.
 276   *
 277   * @return The peer for the specified <code>ScrollPane</code> object.
 278   */
 279 protected abstract ScrollPanePeer
 280 createScrollPane(ScrollPane target);
 281
 282 /*************************************************************************/
 283
 284 /**
 285   * Creates a peer object for the specified <code>TextArea</code>.
 286   *
 287   * @param target The <code>TextArea</code> to create the peer for.
 288   *
 289   * @return The peer for the specified <code>TextArea</code> object.
 290   */
 291 protected abstract TextAreaPeer
 292 createTextArea(TextArea target);
 293
 294 /*************************************************************************/
 295
 296 /**
 297   * Creates a peer object for the specified <code>Choice</code>.
 298   *
 299   * @param target The <code>Choice</code> to create the peer for.
 300   *
 301   * @return The peer for the specified <code>Choice</code> object.
 302   */
 303 protected abstract ChoicePeer
 304 createChoice(Choice target);
 305
 306 /*************************************************************************/
 307
 308 /**
 309   * Creates a peer object for the specified <code>Frame</code>.
 310   *
 311   * @param target The <code>Frame</code> to create the peer for.
 312   *
 313   * @return The peer for the specified <code>Frame</code> object.
 314   */
 315 protected abstract FramePeer
 316 createFrame(Frame target);
 317
 318 /*************************************************************************/
 319
 320 /**
 321   * Creates a peer object for the specified <code>Canvas</code>.
 322   *
 323   * @param target The <code>Canvas</code> to create the peer for.
 324   *
 325   * @return The peer for the specified <code>Canvas</code> object.
 326   */
 327 protected abstract CanvasPeer
 328 createCanvas(Canvas target);
 329
 330 /*************************************************************************/
 331
 332 /**
 333   * Creates a peer object for the specified <code>Panel</code>.
 334   *
 335   * @param target The <code>Panel</code> to create the peer for.
 336   *
 337   * @return The peer for the specified <code>Panel</code> object.
 338   */
 339 protected abstract PanelPeer
 340 createPanel(Panel target);
 341
 342 /*************************************************************************/
 343
 344 /**
 345   * Creates a peer object for the specified <code>Window</code>.
 346   *
 347   * @param target The <code>Window</code> to create the peer for.
 348   *
 349   * @return The peer for the specified <code>Window</code> object.
 350   */
 351 protected abstract WindowPeer
 352 createWindow(Window target);
 353
 354 /*************************************************************************/
 355
 356 /**
 357   * Creates a peer object for the specified <code>Dialog</code>.
 358   *
 359   * @param target The dialog to create the peer for
 360   *
 361   * @return The peer for the specified font name.
 362   */
 363 protected abstract DialogPeer
 364 createDialog(Dialog target);
 365
 366 /*************************************************************************/
 367
 368 /**
 369   * Creates a peer object for the specified <code>MenuBar</code>.
 370   *
 371   * @param target The <code>MenuBar</code> to create the peer for.
 372   *
 373   * @return The peer for the specified <code>MenuBar</code> object.
 374   */
 375 protected abstract MenuBarPeer
 376 createMenuBar(MenuBar target);
 377
 378 /*************************************************************************/
 379
 380 /**
 381   * Creates a peer object for the specified <code>Menu</code>.
 382   *
 383   * @param target The <code>Menu</code> to create the peer for.
 384   *
 385   * @return The peer for the specified <code>Menu</code> object.
 386   */
 387 protected abstract MenuPeer
 388 createMenu(Menu target);
 389
 390 /*************************************************************************/
 391
 392 /**
 393   * Creates a peer object for the specified <code>PopupMenu</code>.
 394   *
 395   * @param target The <code>PopupMenu</code> to create the peer for.
 396   *
 397   * @return The peer for the specified <code>PopupMenu</code> object.
 398   */
 399 protected abstract PopupMenuPeer
 400 createPopupMenu(PopupMenu target);
 401
 402 /*************************************************************************/
 403
 404 /**
 405   * Creates a peer object for the specified <code>MenuItem</code>.
 406   *
 407   * @param target The <code>MenuItem</code> to create the peer for.
 408   *
 409   * @return The peer for the specified <code>MenuItem</code> object.
 410   */
 411 protected abstract MenuItemPeer
 412 createMenuItem(MenuItem target);
 413
 414 /*************************************************************************/
 415
 416 /**
 417   * Creates a peer object for the specified <code>FileDialog</code>.
 418   *
 419   * @param target The <code>FileDialog</code> to create the peer for.
 420   *
 421   * @return The peer for the specified <code>FileDialog</code> object.
 422   */
 423 protected abstract FileDialogPeer
 424 createFileDialog(FileDialog target);
 425
 426 /*************************************************************************/
 427
 428 /**
 429   * Creates a peer object for the specified <code>CheckboxMenuItem</code>.
 430   *
 431   * @param target The <code>CheckboxMenuItem</code> to create the peer for.
 432   *
 433   * @return The peer for the specified <code>CheckboxMenuItem</code> object.
 434   */
 435 protected abstract CheckboxMenuItemPeer
 436 createCheckboxMenuItem(CheckboxMenuItem target);
 437
 438 /*************************************************************************/
 439
 440 /**
 441   * Creates a peer object for the specified <code>Component</code>.  The
 442   * peer returned by this method is not a native windowing system peer
 443   * with its own native window.  Instead, this method allows the component
 444   * to draw on its parent window as a "lightweight" widget.
 445   *
 446   * XXX: FIXME
 447   *
 448   * @param target The <code>Component</code> to create the peer for.
 449   *
 450   * @return The peer for the specified <code>Component</code> object.
 451   */
 452 protected LightweightPeer
 453 createComponent(Component target)
 454 {
 455   return null;
 456 }
 457
 458 /*************************************************************************/
 459
 460 /**
 461   * Creates a peer object for the specified font name.
 462   *
 463   * @param name The font to create the peer for.
 464   * @param style The font style to create the peer for.
 465   *
 466   * @return The peer for the specified font name.
 467   */
 468 protected abstract FontPeer
 469 getFontPeer(String name, int style);
 470
 471 /*************************************************************************/
 472
 473 /**
 474   * Copies the current system colors into the specified array.  This is
 475   * the interface used by the <code>SystemColors</code> class.
 476   *
 477   * @param colors The array to copy the system colors into.
 478   */
 479 protected void
 480 loadSystemColors(int systemColors[])
 481 {
 482 }
 483
 484 /*************************************************************************/
 485
 486 /**
 487   * Returns the dimensions of the screen in pixels.
 488   *
 489   * @return The dimensions of the screen in pixels.
 490   */
 491 public abstract Dimension
 492 getScreenSize();
 493
 494 /*************************************************************************/
 495
 496 /**
 497   * Returns the screen resolution in dots per square inch.
 498   *
 499   * @return The screen resolution in dots per square inch.
 500   */
 501 public abstract int
 502 getScreenResolution();
 503
 504 /*************************************************************************/
 505
 506 /**
 507   * Returns the color model of the screen.
 508   *
 509   * @return The color model of the screen.
 510   */
 511 public abstract ColorModel
 512 getColorModel();
 513
 514 /*************************************************************************/
 515
 516 /**
 517   * Returns the names of the available fonts.
 518   *
 519   * @return The names of the available fonts.
 520   */
 521 public abstract String[]
 522 getFontList();
 523
 524 /*************************************************************************/
 525
 526 /**
 527   * Return the font metrics for the specified font
 528   *
 529   * @param name The name of the font to return metrics for.
 530   *
 531   * @return The requested font metrics.
 532   */
 533 public abstract FontMetrics
 534 getFontMetrics(Font name);
 535
 536 /*************************************************************************/
 537
 538 /**
 539   * Flushes any buffered data to the screen so that it is in sync with
 540   * what the AWT system has drawn to it.
 541   */
 542 public abstract void
 543 sync();
 544
 545 /*************************************************************************/
 546
 547 /**
 548   * Returns an image from the specified file, which must be in a
 549   * recognized format.  Supported formats vary from toolkit to toolkit.
 550   *
 551   * @return name The name of the file to read the image from.
 552   */
 553 public abstract Image
 554 getImage(String name);
 555
 556 /*************************************************************************/
 557
 558 /**
 559   * Returns an image from the specified URL, which must be in a
 560   * recognized format.  Supported formats vary from toolkit to toolkit.
 561   *
 562   * @return url The URl to read the image from.
 563   */
 564 public abstract Image
 565 getImage(URL url);
 566
 567 /*************************************************************************/
 568
 569 /**
 570   * Readies an image to be rendered on the screen.  The width and height
 571   * values can be set to the default sizes for the image by passing -1
 572   * in those parameters.
 573   *
 574   * @param image The image to prepare for rendering.
 575   * @param width The width of the image.
 576   * @param height The height of the image.
 577   * @param observer The observer to receive events about the preparation
 578   * process.
 579   *
 580   * @return <code>true</code> if the image is already prepared for rendering,
 581   * <code>false</code> otherwise.
 582   */
 583 public abstract boolean
 584 prepareImage(Image image, int width, int height, ImageObserver observer);
 585
 586 /*************************************************************************/
 587
 588 /**
 589   * Checks the status of specified image as it is being readied for
 590   * rendering.
 591   *
 592   * @param image The image to prepare for rendering.
 593   * @param width The width of the image.
 594   * @param height The height of the image.
 595   * @param observer The observer to receive events about the preparation
 596   * process.
 597   *
 598   * @return A union of the bitmasks from
 599   * <code>java.awt.image.ImageObserver</code> that indicates the current
 600   * state of the imaging readying process.
 601   */
 602 public abstract int
 603 checkImage(Image image, int width, int height, ImageObserver observer);
 604
 605 /*************************************************************************/
 606
 607 /**
 608   * Creates an image using the specified <code>ImageProducer</code>
 609   *
 610   * @param producer The <code>ImageProducer</code> to create the image from.
 611   *
 612   * @return The created image.
 613   */
 614 public abstract Image
 615 createImage(ImageProducer producer);
 616
 617 /*************************************************************************/
 618
 619 /**
 620   * Creates an image from the specified portion of the byte array passed.
 621   * The array must be in a recognized format.  Supported formats vary from
 622   * toolkit to toolkit.
 623   *
 624   * @param data The raw image data.
 625   * @param offset The offset into the data where the image data starts.
 626   * @param len The length of the image data.
 627   *
 628   * @return The created image.
 629   */
 630 public abstract Image
 631 createImage(byte[] data, int offset, int len);
 632
 633 /*************************************************************************/
 634
 635 /**
 636   * Creates an image from the specified byte array. The array must be in
 637   * a recognized format.  Supported formats vary from toolkit to toolkit.
 638   *
 639   * @param data The raw image data.
 640   *
 641   * @return The created image.
 642   */
 643 public Image
 644 createImage(byte[] data)
 645 {
 646   return(createImage(data, 0, data.length));
 647 }
 648
 649 public abstract Image
 650 createImage(String filename);
 651
 652 public abstract Image
 653 createImage(URL url);
 654
 655
 656 /*************************************************************************/
 657
 658 /**
 659   * Returns a instance of <code>PrintJob</code> for the specified
 660   * arguments.
 661   *
 662   * @param frame The window initiating the print job.
 663   * @param title The print job title.
 664   * @param props The print job properties.
 665   *
 666   * @return The requested print job, or <code>null</code> if the job
 667   * was cancelled.
 668   */
 669 public abstract PrintJob
 670 getPrintJob(Frame frame, String title, Properties props);
 671
 672 /*************************************************************************/
 673
 674 /**
 675   * Returns the system clipboard.
 676   *
 677   * @return THe system clipboard.
 678   */
 679 public abstract Clipboard
 680 getSystemClipboard();
 681
 682 /*************************************************************************/
 683
 684 /**
 685   * Returns the accelerator key mask for menu shortcuts. The default is
 686   * <code>Event.CTRL_MASK</code>.  A toolkit must override this method
 687   * to change the default.
 688   *
 689   * @return The key mask for the menu accelerator key.
 690   */
 691 public int
 692 getMenuShortcutKeyMask()
 693 {
 694   return Event.CTRL_MASK;
 695 }
 696
 697 public boolean
 698 getLockingKeyState(int keyCode)
 699 {
 700   if (keyCode != KeyEvent.VK_CAPS_LOCK
 701       && keyCode != KeyEvent.VK_NUM_LOCK
 702       && keyCode != KeyEvent.VK_SCROLL_LOCK)
 703     throw new IllegalArgumentException();
 704
 705   throw new UnsupportedOperationException();
 706 }
 707
 708 public void
 709 setLockingKeyState(int keyCode, boolean on)
 710 {
 711   if (keyCode != KeyEvent.VK_CAPS_LOCK
 712       && keyCode != KeyEvent.VK_NUM_LOCK
 713       && keyCode != KeyEvent.VK_SCROLL_LOCK)
 714     throw new IllegalArgumentException();
 715
 716   throw new UnsupportedOperationException();
 717 }
 718
 719 /*************************************************************************/
 720
 721 /**
 722   * Returns the event queue for the applet.  Despite the word "System"
 723   * in the name of this method, there is no guarantee that the same queue
 724   * is shared system wide.
 725   *
 726   * @return The event queue for this applet (or application)
 727   */
 728 public final EventQueue
 729 getSystemEventQueue()
 730 {
 731   return(getSystemEventQueueImpl());
 732 }
 733
 734 /*************************************************************************/
 735
 736 /**
 737   * // FIXME: What does this do?
 738   */
 739 protected abstract EventQueue
 740 getSystemEventQueueImpl();
 741
 742 /*************************************************************************/
 743
 744 /**
 745   * Causes a "beep" tone to be generated.
 746   */
 747 public abstract void
 748 beep();
 749
 750 public Cursor
 751 createCustomCursor(Image cursor, Point hotSpot, String name)
 752   throws IndexOutOfBoundsException
 753 {
 754   // Presumably the only reason this isn't abstract is for backwards
 755   // compatibility? FIXME?
 756   return null;
 757 }
 758
 759 public Dimension
 760 getBestCursorSize(int preferredWidth, int preferredHeight)
 761 {
 762   return new Dimension (0,0);
 763 }
 764
 765 public int
 766 getMaximumCursorColors()
 767 {
 768   return 0;
 769 }
 770
 771 public final Object
 772 getDesktopProperty(String propertyName)
 773 {
 774   return desktopProperties.get(propertyName);
 775 }
 776
 777 protected final void
 778 setDesktopProperty(String name, Object newValue)
 779 {
 780   Object oldValue = getDesktopProperty(name);
 781   desktopProperties.put(name, newValue);
 782   changeSupport.firePropertyChange(name, oldValue, newValue);
 783 }
 784 protected Object
 785 lazilyLoadDesktopProperty(String name)
 786 {
 787   // FIXME - what is this??
 788   return null;
 789 }
 790
 791 protected void
 792 initializeDesktopProperties()
 793 {
 794   // Overridden by toolkit implementation?
 795 }
 796
 797 public void
 798 addPropertyChangeListener(String name, PropertyChangeListener pcl)
 799 {
 800   changeSupport.addPropertyChangeListener(name, pcl);
 801 }
 802
 803 public void
 804 removePropertyChangeListener(String name, PropertyChangeListener pcl)
 805 {
 806   changeSupport.removePropertyChangeListener(name, pcl);
 807 }
 808
 809 public void
 810 addAWTEventListener(AWTEventListener listener, long eventMask)
 811 {
 812   // SecurityManager s = System.getSecurityManager();
 813   // if (s != null)
 814   //  s.checkPermission(AWTPermission("listenToAllAWTEvents"));
 815
 816   // FIXME
 817 }
 818
 819 public void
 820 removeAWTEventListener(AWTEventListener listener)
 821 {
 822   // FIXME
 823 }
 824
 825 } // class Toolkit