home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / Toolkit.java < prev    next >
Encoding:
Java Source  |  1998-03-20  |  38.6 KB  |  1,077 lines
  1. /*
  2.  * @(#)Toolkit.java    1.92 98/03/18
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.awt;
  16.  
  17. import java.util.Properties;
  18. import java.util.StringTokenizer;
  19. import java.awt.peer.*;
  20. import java.awt.image.ImageObserver;
  21. import java.awt.image.ImageProducer;
  22. import java.awt.image.ColorModel;
  23. import java.awt.datatransfer.Clipboard;
  24. import java.awt.dnd.DnDConstants;
  25. import java.awt.dnd.DragSource;
  26. import java.awt.dnd.InvalidDnDOperationException;
  27. import java.awt.dnd.peer.DragSourceContextPeer;
  28. import java.net.URL;
  29. import java.io.BufferedInputStream;
  30. import java.io.File;
  31. import java.io.FileInputStream;
  32. import java.awt.print.PageFormat;
  33.  
  34. import java.util.HashMap;
  35. import java.util.Map;
  36.  
  37. import java.beans.PropertyChangeListener;
  38. import java.beans.PropertyChangeSupport;
  39.  
  40. /**
  41.  * This class is the abstract superclass of all actual
  42.  * implementations of the Abstract Window Toolkit. Subclasses of 
  43.  * <code>Toolkit</code> are used to bind the various components 
  44.  * to particular native toolkit implementations.
  45.  * <p>
  46.  * Most applications should not call any of the methods in this
  47.  * class directly. The methods defined by <code>Toolkit</code> are 
  48.  * the "glue" that joins the platform-independent classes in the 
  49.  * <code>java.awt</code> package with their counterparts in 
  50.  * <code>java.awt.peer</code>. Some methods defined by 
  51.  * <code>Toolkit</code> query the native operating system directly.
  52.  *
  53.  * @version     1.92, 03/18/98
  54.  * @author    Sami Shaio
  55.  * @author    Arthur van Hoff
  56.  * @since       JDK1.0
  57.  */
  58. public abstract class  Toolkit {
  59.  
  60.     /**
  61.      * Creates this toolkit's implementation of <code>Button</code> using 
  62.      * the specified peer interface.
  63.      * @param     target the button to be implemented.
  64.      * @return    this toolkit's implementation of <code>Button</code>.
  65.      * @see       java.awt.Button
  66.      * @see       java.awt.peer.ButtonPeer
  67.      */
  68.     protected abstract ButtonPeer     createButton(Button target);
  69.  
  70.     /**
  71.      * Creates this toolkit's implementation of <code>TextField</code> using 
  72.      * the specified peer interface.
  73.      * @param     target the text field to be implemented.
  74.      * @return    this toolkit's implementation of <code>TextField</code>.
  75.      * @see       java.awt.TextField
  76.      * @see       java.awt.peer.TextFieldPeer
  77.      */
  78.     protected abstract TextFieldPeer     createTextField(TextField target);
  79.  
  80.     /**
  81.      * Creates this toolkit's implementation of <code>Label</code> using 
  82.      * the specified peer interface.
  83.      * @param     target the label to be implemented.
  84.      * @return    this toolkit's implementation of <code>Label</code>.
  85.      * @see       java.awt.Label
  86.      * @see       java.awt.peer.LabelPeer
  87.      */
  88.     protected abstract LabelPeer     createLabel(Label target);
  89.  
  90.     /**
  91.      * Creates this toolkit's implementation of <code>List</code> using 
  92.      * the specified peer interface.
  93.      * @param     target the list to be implemented.
  94.      * @return    this toolkit's implementation of <code>List</code>.
  95.      * @see       java.awt.List
  96.      * @see       java.awt.peer.ListPeer
  97.      */
  98.     protected abstract ListPeer     createList(List target);
  99.  
  100.     /**
  101.      * Creates this toolkit's implementation of <code>Checkbox</code> using 
  102.      * the specified peer interface.
  103.      * @param     target the check box to be implemented.
  104.      * @return    this toolkit's implementation of <code>Checkbox</code>.
  105.      * @see       java.awt.Checkbox
  106.      * @see       java.awt.peer.CheckboxPeer
  107.      */
  108.     protected abstract CheckboxPeer     createCheckbox(Checkbox target);
  109.  
  110.     /**
  111.      * Creates this toolkit's implementation of <code>Scrollbar</code> using 
  112.      * the specified peer interface.
  113.      * @param     target the scroll bar to be implemented.
  114.      * @return    this toolkit's implementation of <code>Scrollbar</code>.
  115.      * @see       java.awt.Scrollbar
  116.      * @see       java.awt.peer.ScrollbarPeer
  117.      */
  118.     protected abstract ScrollbarPeer     createScrollbar(Scrollbar target);
  119.  
  120.     /**
  121.      * Creates this toolkit's implementation of <code>ScrollPane</code> using 
  122.      * the specified peer interface.
  123.      * @param     target the scroll pane to be implemented.
  124.      * @return    this toolkit's implementation of <code>ScrollPane</code>.
  125.      * @see       java.awt.ScrollPane
  126.      * @see       java.awt.peer.ScrollPanePeer
  127.      * @since     JDK1.1
  128.      */
  129.     protected abstract ScrollPanePeer     createScrollPane(ScrollPane target);
  130.  
  131.     /**
  132.      * Creates this toolkit's implementation of <code>TextArea</code> using 
  133.      * the specified peer interface.
  134.      * @param     target the text area to be implemented.
  135.      * @return    this toolkit's implementation of <code>TextArea</code>.
  136.      * @see       java.awt.TextArea
  137.      * @see       java.awt.peer.TextAreaPeer
  138.      */
  139.     protected abstract TextAreaPeer      createTextArea(TextArea target);
  140.  
  141.     /**
  142.      * Creates this toolkit's implementation of <code>Choice</code> using 
  143.      * the specified peer interface.
  144.      * @param     target the choice to be implemented.
  145.      * @return    this toolkit's implementation of <code>Choice</code>.
  146.      * @see       java.awt.Choice
  147.      * @see       java.awt.peer.ChoicePeer
  148.      */
  149.     protected abstract ChoicePeer    createChoice(Choice target);
  150.  
  151.     /**
  152.      * Creates this toolkit's implementation of <code>Frame</code> using 
  153.      * the specified peer interface.
  154.      * @param     target the frame to be implemented.
  155.      * @return    this toolkit's implementation of <code>Frame</code>.
  156.      * @see       java.awt.Frame
  157.      * @see       java.awt.peer.FramePeer
  158.      */
  159.     protected abstract FramePeer      createFrame(Frame target);
  160.  
  161.     /**
  162.      * Creates this toolkit's implementation of <code>Canvas</code> using 
  163.      * the specified peer interface.
  164.      * @param     target the canvas to be implemented.
  165.      * @return    this toolkit's implementation of <code>Canvas</code>.
  166.      * @see       java.awt.Canvas
  167.      * @see       java.awt.peer.CanvasPeer
  168.      */
  169.     protected abstract CanvasPeer     createCanvas(Canvas target);
  170.  
  171.     /**
  172.      * Creates this toolkit's implementation of <code>Panel</code> using 
  173.      * the specified peer interface.
  174.      * @param     target the panel to be implemented.
  175.      * @return    this toolkit's implementation of <code>Panel</code>.
  176.      * @see       java.awt.Panel
  177.      * @see       java.awt.peer.PanelPeer
  178.      */
  179.     protected abstract PanelPeer      createPanel(Panel target);
  180.  
  181.     /**
  182.      * Creates this toolkit's implementation of <code>Window</code> using 
  183.      * the specified peer interface.
  184.      * @param     target the window to be implemented.
  185.      * @return    this toolkit's implementation of <code>Window</code>.
  186.      * @see       java.awt.Window
  187.      * @see       java.awt.peer.WindowPeer
  188.      */
  189.     protected abstract WindowPeer      createWindow(Window target);
  190.  
  191.     /**
  192.      * Creates this toolkit's implementation of <code>Dialog</code> using 
  193.      * the specified peer interface.
  194.      * @param     target the dialog to be implemented.
  195.      * @return    this toolkit's implementation of <code>Dialog</code>.
  196.      * @see       java.awt.Dialog
  197.      * @see       java.awt.peer.DialogPeer
  198.      */
  199.     protected abstract DialogPeer      createDialog(Dialog target);
  200.  
  201.     /**
  202.      * Creates this toolkit's implementation of <code>MenuBar</code> using 
  203.      * the specified peer interface.
  204.      * @param     target the menu bar to be implemented.
  205.      * @return    this toolkit's implementation of <code>MenuBar</code>.
  206.      * @see       java.awt.MenuBar
  207.      * @see       java.awt.peer.MenuBarPeer
  208.      */
  209.     protected abstract MenuBarPeer      createMenuBar(MenuBar target);
  210.  
  211.     /**
  212.      * Creates this toolkit's implementation of <code>Menu</code> using 
  213.      * the specified peer interface.
  214.      * @param     target the menu to be implemented.
  215.      * @return    this toolkit's implementation of <code>Menu</code>.
  216.      * @see       java.awt.Menu
  217.      * @see       java.awt.peer.MenuPeer
  218.      */
  219.     protected abstract MenuPeer      createMenu(Menu target);
  220.  
  221.     /**
  222.      * Creates this toolkit's implementation of <code>PopupMenu</code> using 
  223.      * the specified peer interface.
  224.      * @param     target the popup menu to be implemented.
  225.      * @return    this toolkit's implementation of <code>PopupMenu</code>.
  226.      * @see       java.awt.PopupMenu
  227.      * @see       java.awt.peer.PopupMenuPeer
  228.      * @since     JDK1.1
  229.      */
  230.     protected abstract PopupMenuPeer    createPopupMenu(PopupMenu target);
  231.  
  232.     /**
  233.      * Creates this toolkit's implementation of <code>MenuItem</code> using 
  234.      * the specified peer interface.
  235.      * @param     target the menu item to be implemented.
  236.      * @return    this toolkit's implementation of <code>MenuItem</code>.
  237.      * @see       java.awt.MenuItem
  238.      * @see       java.awt.peer.MenuItemPeer
  239.      */
  240.     protected abstract MenuItemPeer      createMenuItem(MenuItem target);
  241.  
  242.     /**
  243.      * Creates this toolkit's implementation of <code>FileDialog</code> using 
  244.      * the specified peer interface.
  245.      * @param     target the file dialog to be implemented.
  246.      * @return    this toolkit's implementation of <code>FileDialog</code>.
  247.      * @see       java.awt.FileDialog
  248.      * @see       java.awt.peer.FileDialogPeer
  249.      */
  250.     protected abstract FileDialogPeer    createFileDialog(FileDialog target);
  251.  
  252.     /**
  253.      * Creates this toolkit's implementation of <code>CheckboxMenuItem</code> using 
  254.      * the specified peer interface.
  255.      * @param     target the checkbox menu item to be implemented.
  256.      * @return    this toolkit's implementation of <code>CheckboxMenuItem</code>.
  257.      * @see       java.awt.CheckboxMenuItem
  258.      * @see       java.awt.peer.CheckboxMenuItemPeer
  259.      */
  260.     protected abstract CheckboxMenuItemPeer    createCheckboxMenuItem(CheckboxMenuItem target);
  261.  
  262.     private static java.awt.LightweightPeer lightweightMarker;
  263.  
  264.     /**
  265.      * Creates a peer for a component or container.  This peer is windowless
  266.      * and allows the Component and Container classes to be extended directly
  267.      * to create windowless components that are defined entirely in java.
  268.      *
  269.      * @param target The Component to be created.
  270.      */
  271.     protected java.awt.peer.LightweightPeer createComponent(Component target) {
  272.         if (lightweightMarker == null) {
  273.             lightweightMarker = new java.awt.LightweightPeer(target);
  274.         }
  275.     return lightweightMarker;
  276.     }
  277.  
  278.     /**
  279.      * Creates this toolkit's implementation of <code>Font</code> using 
  280.      * the specified peer interface.
  281.      * @param     target the font to be implemented.
  282.      * @return    this toolkit's implementation of <code>Font</code>.
  283.      * @see       java.awt.Font
  284.      * @see       java.awt.peer.FontPeer
  285.      */
  286.     protected abstract FontPeer getFontPeer(String name, int style);
  287.  
  288.     /**
  289.      * Fills in the integer array that is supplied as an argument 
  290.      * with the current system color values.
  291.      * <p>
  292.      * This method is called by the method <code>updateSystemColors</code>
  293.      * in the <code>SystemColor</code> class.
  294.      * @param     an integer array.
  295.      * @see       java.awt.SystemColor#updateSystemColors
  296.      * @since     JDK1.1
  297.      */
  298.     protected void loadSystemColors(int[] systemColors) {
  299.     }
  300.  
  301.     /**
  302.      * Gets the size of the screen.
  303.      * @return    the size of this toolkit's screen, in pixels.
  304.      */
  305.     public abstract Dimension getScreenSize();
  306.  
  307.     /**
  308.      * Returns the screen resolution in dots-per-inch.
  309.      * @return    this toolkit's screen resolution, in dots-per-inch.
  310.      */
  311.     public abstract int getScreenResolution();
  312.  
  313.     /**
  314.      * Determines the color model of this toolkit's screen. 
  315.      * <p>
  316.      * <code>ColorModel</code> is an abstract class that 
  317.      * encapsulates the ability to translate between the 
  318.      * pixel values of an image and its red, green, blue, 
  319.      * and alpha components. 
  320.      * <p>
  321.      * This toolkit method is called by the 
  322.      * <code>getColorModel</code> method 
  323.      * of the <code>Component</code> class. 
  324.      * @return    the color model of this toolkit's screen.
  325.      * @see       java.awt.image.ColorModel
  326.      * @see       java.awt.Component#getColorModel
  327.      */
  328.     public abstract ColorModel getColorModel();
  329.  
  330.     /**
  331.      * Returns the names of the available fonts in this toolkit.<p>
  332.      * For 1.1, the following font names are deprecated (the replacement
  333.      * name follows):
  334.      * <ul>
  335.      * <li>TimesRoman (use Serif)
  336.      * <li>Helvetica (use SansSerif)
  337.      * <li>Courier (use Monospaced)
  338.      * </ul><p>
  339.      * The ZapfDingbats font is also deprecated in 1.1, but only as a
  340.      * separate fontname.  Unicode defines the ZapfDingbat characters
  341.      * starting at \u2700, and as of 1.1 Java supports those characters.
  342.      * @return    the names of the available fonts in this toolkit.
  343.      */
  344.     public abstract String[] getFontList();
  345.  
  346.     /**
  347.      * Gets the screen metrics of the font.
  348.      * @param     font   a font.
  349.      * @return    the screen metrics of the specified font in this toolkit.
  350.      */
  351.     public abstract FontMetrics getFontMetrics(Font font);
  352.  
  353.     /**
  354.      * Synchronizes this toolkit's graphics state. Some window systems 
  355.      * may do buffering of graphics events. 
  356.      * <p>
  357.      * This method ensures that the display is up-to-date. It is useful
  358.      * for animation.
  359.      */
  360.     public abstract void sync();
  361.  
  362.     /**
  363.      * The default toolkit.
  364.      */
  365.     private static Toolkit toolkit;
  366.  
  367.     /**
  368.      * Loads additional classes into the VM, using the property
  369.      * 'AWT.assistive_technologies' specified in the Sun
  370.      * reference implementation by a line in the 'awt.properties'
  371.      * file.  The form is "AWT.assistive_technologies=..." where
  372.      * the "..." is a comma-separated list of assistive technology
  373.      * classes to load.  Each class is loaded in the order given
  374.      * and a single instance of each is created using 
  375.      * Class.forName(class).newInstance().  All errors are handles
  376.      * via an AWTError exception.
  377.      */
  378.     private static void loadAssistiveTechnologies() {
  379.         String atNames = getProperty("AWT.assistive_technologies",null);
  380.  
  381.         if (atNames != null) {
  382.             StringTokenizer parser = new StringTokenizer(atNames,",");
  383.         String atName;
  384.             while (parser.hasMoreTokens()) {
  385.         atName = parser.nextToken();
  386.                 try {
  387.                     Class.forName(atName).newInstance();
  388.                 } catch (ClassNotFoundException e) {
  389.                     throw new AWTError("Assistive Technology not found: "
  390.                 + atName);
  391.                 } catch (InstantiationException e) {
  392.                     throw new AWTError("Could not instantiate Assistive"
  393.                 + " Technology: " + atName);
  394.                 } catch (IllegalAccessException e) {
  395.                     throw new AWTError("Could not access Assistive"
  396.                 + " Technology: " + atName);
  397.                 } catch (Exception e) {
  398.                     throw new AWTError("Error trying to install Assistive"
  399.                 + " Technology: " + atName + " " + e);
  400.                 }
  401.             }
  402.         }
  403.     }
  404.  
  405.     /**
  406.      * Gets the default toolkit. 
  407.      * <p>
  408.      * If there is a system property named <code>"awt.toolkit"</code>, 
  409.      * that property is treated as the name of a class that is a subclass 
  410.      * of <code>Toolkit</code>. 
  411.      * <p>
  412.      * If the system property does not exist, then the default toolkit 
  413.      * used is the class named <code>"sun.awt.motif.MToolkit"</code>, 
  414.      * which is a motif implementation of the Abstract Window Toolkit. 
  415.      * <p>
  416.      * Also loads additional classes into the VM using the property
  417.      * 'AWT.assistive_technologies' specified in the 'awt.properties'
  418.      * file.  The form is "AWT.assistive_technologies=..." where
  419.      * the "..." is a comma-separated list of assistive technology
  420.      * classes to load.  Each class is loaded in the order given
  421.      * and a single instance of each is created using 
  422.      * Class.forName(class).newInstance().  This is done just after 
  423.      * the AWT toolkit is created.  All errors are handled via an 
  424.      * AWTError exception.
  425.      * @return    the default toolkit.
  426.      * @exception  AWTError  if a toolkit could not be found, or 
  427.      *                 if one could not be accessed or instantiated.
  428.      */
  429.     public static synchronized Toolkit getDefaultToolkit() {
  430.     if (toolkit == null) {
  431.         String nm;
  432.         try {
  433.           java.security.AccessController.beginPrivileged();
  434.           nm = System.getProperty("awt.toolkit", "sun.awt.motif.MToolkit");
  435.         } finally {
  436.           java.security.AccessController.endPrivileged();
  437.         }
  438.         try {
  439.         java.security.AccessController.beginPrivileged();
  440.         toolkit = (Toolkit)Class.forName(nm).newInstance();
  441.         } catch (ClassNotFoundException e) {
  442.         throw new AWTError("Toolkit not found: " + nm);
  443.         } catch (InstantiationException e) {
  444.         throw new AWTError("Could not instantiate Toolkit: " + nm);
  445.         } catch (IllegalAccessException e) {
  446.         throw new AWTError("Could not access Toolkit: " + nm);
  447.         } finally {
  448.           java.security.AccessController.endPrivileged();
  449.           loadAssistiveTechnologies();
  450.         }
  451.     }
  452.     return toolkit;
  453.     }
  454.  
  455.     /**
  456.      * Returns an image which gets pixel data from the specified file.
  457.      * @param     filename   the name of a file containing pixel data 
  458.      *                         in a recognized file format.
  459.      * @return    an image which gets its pixel data from 
  460.      *                         the specified file.
  461.      */
  462.     public abstract Image getImage(String filename);
  463.  
  464.     /**
  465.      * Returns an image which gets pixel data from the specified URL.
  466.      * @param     url   the URL to use in fetching the pixel data.
  467.      * @return    an image which gets its pixel data from 
  468.      *                         the specified URL.
  469.      */
  470.     public abstract Image getImage(URL url);
  471.  
  472.     /**
  473.      * Prepares an image for rendering. 
  474.      * <p>
  475.      * If the values of the width and height arguments are both 
  476.      * <code>-1</code>, this method prepares the image for rendering 
  477.      * on the default screen; otherwise, this method prepares an image 
  478.      * for rendering on the default screen at the specified width and height. 
  479.      * <p>
  480.      * The image data is downloaded asynchronously in another thread, 
  481.      * and an appropriately scaled screen representation of the image is 
  482.      * generated. 
  483.      * <p>
  484.      * This method is called by components <code>prepareImage</code> 
  485.      * methods. 
  486.      * <p>
  487.      * Information on the flags returned by this method can be found 
  488.      * with the definition of the <code>ImageObserver</code> interface. 
  489.  
  490.      * @param     image      the image for which to prepare a  
  491.      *                           screen representation.
  492.      * @param     width      the width of the desired screen 
  493.      *                           representation, or <code>-1</code>.
  494.      * @param     height     the height of the desired screen 
  495.      *                           representation, or <code>-1</code>.
  496.      * @param     observer   the <code>ImageObserver</code> 
  497.      *                           object to be notified as the 
  498.      *                           image is being prepared.
  499.      * @return    <code>true</code> if the image has already been 
  500.      *                 fully prepared; <code>false</code> otherwise.
  501.      * @see       java.awt.Component#prepareImage(java.awt.Image, 
  502.      *                 java.awt.image.ImageObserver)
  503.      * @see       java.awt.Component#prepareImage(java.awt.Image, 
  504.      *                 int, int, java.awt.image.ImageObserver)
  505.      * @see       java.awt.image.ImageObserver
  506.      */
  507.     public abstract boolean prepareImage(Image image, int width, int height,
  508.                      ImageObserver observer);
  509.  
  510.     /**
  511.      * Indicates the construction status of a specified image that is
  512.      * being prepared for display.
  513.      * <p>
  514.      * If the values of the width and height arguments are both 
  515.      * <code>-1</code>, this method returns the construction status of 
  516.      * a screen representation of the specified image in this toolkit. 
  517.      * Otherwise, this method returns the construction status of a
  518.      * scaled representation of the image at the specified width 
  519.      * and height.
  520.      * <p>
  521.      * This method does not cause the image to begin loading. 
  522.      * An application must call <code>prepareImage</code> to force 
  523.      * the loading of an image.
  524.      * <p>
  525.      * This method is called by the component's <code>checkImage</code>
  526.      * methods.
  527.      * <p>
  528.      * Information on the flags returned by this method can be found
  529.      * with the definition of the <code>ImageObserver</code> interface.
  530.      * @param     image   the image whose status is being checked.
  531.      * @param     width   the width of the scaled version whose status is
  532.      *                 being checked, or <code>-1</code>.
  533.      * @param     height  the height of the scaled version whose status
  534.      *                 is being checked, or <code>-1</code>.
  535.      * @param     observer   the <code>ImageObserver</code> object to be
  536.      *                 notified as the image is being prepared.
  537.      * @return    the bitwise inclusive <strong>OR</strong> of the
  538.      *                 <code>ImageObserver</code> flags for the 
  539.      *                 image data that is currently available.
  540.      * @see       java.awt.Toolkit#prepareImage(java.awt.Image, 
  541.      *                 int, int, java.awt.image.ImageObserver)
  542.      * @see       java.awt.Component#checkImage(java.awt.Image, 
  543.      *                 java.awt.image.ImageObserver)
  544.      * @see       java.awt.Component#checkImage(java.awt.Image, 
  545.      *                 int, int, java.awt.image.ImageObserver)
  546.      * @see       java.awt.image.ImageObserver
  547.      */
  548.     public abstract int checkImage(Image image, int width, int height,
  549.                    ImageObserver observer);
  550.  
  551.     /**
  552.      * Creates an image with the specified image producer.
  553.      * @param     producer the image producer to be used.
  554.      * @return    an image with the specified image producer.
  555.      * @see       java.awt.Image
  556.      * @see       java.awt.image.ImageProducer
  557.      * @see       java.awt.Component#createImage(java.awt.image.ImageProducer)
  558.      */
  559.     public abstract Image createImage(ImageProducer producer);
  560.  
  561.     /**
  562.      * Creates an image which decodes the image stored in the specified
  563.      * byte array.
  564.      * <p>
  565.      * The data must be in some image format, such as GIF or JPEG, 
  566.      * that is supported by this toolkit.
  567.      * @param     imagedata   an array of bytes, representing 
  568.      *                         image data in a supported image format.
  569.      * @return    an image.
  570.      * @since     JDK1.1
  571.      */
  572.     public Image createImage(byte[] imagedata) {
  573.     return createImage(imagedata, 0, imagedata.length);
  574.     }
  575.  
  576.     /**
  577.      * Creates an image which decodes the image stored in the specified
  578.      * byte array, and at the specified offset and length.
  579.      * The data must be in some image format, such as GIF or JPEG, 
  580.      * that is supported by this toolkit. 
  581.      * @param     imagedata   an array of bytes, representing 
  582.      *                         image data in a supported image format.
  583.      * @param     imageoffset  the offset of the beginning 
  584.      *                         of the data in the array.
  585.      * @param     imagelength  the length of the data in the array.
  586.      * @return    an image.
  587.      * @since     JDK1.1
  588.      */
  589.     public abstract Image createImage(byte[] imagedata,
  590.                       int imageoffset,
  591.                       int imagelength);
  592.  
  593.     /**
  594.      * Gets a <code>PrintJob</code> object which is the result 
  595.      * of initiating a print operation on the toolkit's platform. 
  596.      * @return    a <code>PrintJob</code> object, or 
  597.      *                  <code>null</code> if the user 
  598.      *                  cancelled the print job.
  599.      * @see       java.awt.PrintJob
  600.      * @since     JDK1.1
  601.      */
  602.     public abstract PrintJob getPrintJob(Frame frame, String jobtitle, Properties props);
  603.  
  604.     /**
  605.      * Display a dialog to the user allowing the modification of a
  606.      * PageFormat instance.
  607.      * The <code>page</code> argument is used to initialize controls
  608.      * in the page setup dialog.
  609.      * If the user cancels the dialog, then the method returns the
  610.      * original <code>page</code> object unmodified.
  611.      * If the user okays the dialog then the method returns a new
  612.      * PageFormat object with the indicated changes.
  613.      * In either case the original <code>page</code> object will
  614.      * not be modified.
  615.      * If the OS does not support a setup page
  616.      * dialog then the dialog will act as if the user
  617.      * cancelled the dialog.
  618.      * @param     page    the default PageFormat presented to the user
  619.      *                    for modification
  620.      * @return    the original <code>page</code> object if the dialog
  621.      *            is cancelled, or a new PageFormat object containing
  622.      *            the format indicated by the user if the dialog is
  623.      *            acknowledged
  624.      * @since     JDK1.2
  625.      */
  626.     public PageFormat setupPage(PageFormat page) {
  627.     return page;
  628.     }
  629.  
  630.     /**
  631.      * Returns true if this Toolkit supports a Page Setup dialog for
  632.      * allowing a user to modify a PageFormat in the setupPage() method.
  633.      */
  634.     public boolean hasSetupPage() {
  635.     return false;
  636.     }
  637.  
  638.     /**
  639.      * Emits an audio beep.
  640.      * @since     JDK1.1
  641.      */
  642.     public abstract void beep();
  643.  
  644.     /**
  645.      * Gets an instance of the system clipboard which interfaces 
  646.      * with clipboard facilities provided by the native platform. 
  647.      * <p>
  648.      * This clipboard enables data transfer between Java programs 
  649.      * and native applications which use native clipboard facilities.
  650.      * @return    an instance of the system clipboard.
  651.      * @see       java.awt.datatransfer.Clipboard
  652.      * @since     JDK1.1
  653.      */
  654.     public abstract Clipboard getSystemClipboard();
  655.  
  656.     /**
  657.      * Determines which modifier key is the appropriate accelerator
  658.      * key for menu shortcuts.
  659.      * <p>
  660.      * Menu shortcuts, which are embodied in the 
  661.      * <code>MenuShortcut</code> class, are handled by the 
  662.      * <code>MenuBar</code> class.
  663.      * <p>
  664.      * By default, this method returns <code>Event.CTRL_MASK</code>.
  665.      * Toolkit implementations should override this method if the
  666.      * <b>Control</b> key isn't the correct key for accelerators.
  667.      * @return    the modifier mask on the <code>Event</code> class 
  668.      *                 that is used for menu shortcuts on this toolkit. 
  669.      * @see       java.awt.MenuBar
  670.      * @see       java.awt.MenuShortcut
  671.      * @since     JDK1.1
  672.      */
  673.     public int getMenuShortcutKeyMask() {
  674.         return Event.CTRL_MASK;
  675.     }
  676.  
  677.     /**
  678.      * Give native peers the ability to query the native container 
  679.      * given a native component (eg the direct parent may be lightweight).
  680.      */
  681.     protected static Container getNativeContainer(Component c) {
  682.     return c.getNativeContainer();
  683.     }
  684.  
  685.     /**
  686.      * Creates a new custom cursor object.
  687.      * @param image the image to display when the cursor is active.
  688.      * @param hotSpot the X and Y of the large cursor's hot spot.  The
  689.      * hotSpot values must be less than the Dimension returned by 
  690.      * getBestCursorSize().
  691.      * @param     name a localized description of the cursor, for Java Accessibility use.
  692.      * @exception IndexOutOfBoundsException if the hotSpot values are outside
  693.      * the bounds of the cursor.
  694.      * @since     JDK1.2
  695.      */
  696.     public Cursor createCustomCursor(Image cursor, Point hotSpot, String name)
  697.         throws IndexOutOfBoundsException {
  698.         // Override to implement custom cursor support.
  699.         return new Cursor(Cursor.DEFAULT_CURSOR);
  700.     }
  701.  
  702.     /**
  703.      * Returns the supported cursor dimension which is closest to the desired
  704.      * sizes.  Systems which only support a single cursor size will return that
  705.      * size regardless of the desired sizes.  Systems which don't support custom
  706.      * cursors will return a dimension of 0, 0. <p>
  707.      * Note:  if an image is used whose dimensions don't match a supported size
  708.      * (as returned by this method), the Toolkit implementation will attempt to
  709.      * resize the image to a supported size.  
  710.      * Since converting low-resolution images is difficult,
  711.      * no guarantees are made as to the quality of a cursor image which isn't a
  712.      * supported size.  It is therefore recommended that this method
  713.      * be called and an appropriate image used so no image conversion is made.
  714.      *
  715.      * @param     desiredWidth the preferred cursor width the component would like 
  716.      * to use.
  717.      * @param     desiredHeight the preferred cursor height the component would like 
  718.      * to use.
  719.      * @return    the closest matching supported cursor size, or a dimension of 0,0 if 
  720.      * the Toolkit implementation doesn't support custom cursors.
  721.      * @since     JDK1.2
  722.      */
  723.     public Dimension getBestCursorSize(int preferredWidth, int preferredHeight) {
  724.         // Override to implement custom cursor support.
  725.         return new Dimension(0, 0);
  726.     }
  727.  
  728.     /**
  729.      * Returns the maximum number of colors the Toolkit supports in a custom cursor
  730.      * palette.<p>
  731.      * Note: if an image is used which has more colors in its palette than 
  732.      * the supported maximum, the Toolkit implementation will attempt to flatten the
  733.      * palette to the maximum.  Since converting low-resolution images is difficult,
  734.      * no guarantees are made as to the quality of a cursor image which has more
  735.      * colors than the system supports.  It is therefore recommended that this method
  736.      * be called and an appropriate image used so no image conversion is made.
  737.      *
  738.      * @return    the maximum number of colors, or zero if custom cursors are not
  739.      * supported by this Toolkit implementation.
  740.      * @since     JDK1.2
  741.      */
  742.     public int getMaximumCursorColors() {
  743.         // Override to implement custom cursor support.
  744.         return 0;
  745.     }
  746.  
  747.     /* Support for I18N: any visible strings should be stored in 
  748.      * lib/awt.properties.  The Properties list is stored here, so
  749.      * that only one copy is maintained.
  750.      */
  751.     private static Properties properties;
  752.  
  753.     /**
  754.      * Initialize JNI field and method ids
  755.      */
  756.     private static native void initIDs();
  757.  
  758.     /**
  759.      * WARNING: This is a temporary workaround for a problem in the
  760.      * way the AWT loads native libraries. A number of classes in the
  761.      * AWT package have a native method, initIDs(), which initializes
  762.      * the JNI field and method ids used in the native portion of
  763.      * their implementation.
  764.      *
  765.      * Since the use and storage of these ids is done by the
  766.      * implementation libraries, the implementation of these method is
  767.      * provided by the particular AWT implementations
  768.      * (i.e. "Toolkit"s/Peer), such as Motif, Win32 or Tiny. The
  769.      * problem is that this means that the native libraries must be
  770.      * loaded by the java.* classes, which do not necessarily know the
  771.      * names of the libraries to load. A better way of doing this
  772.      * would be to provide a separate library which defines java.awt.*
  773.      * initIDs, and exports the relevant symbols out to the
  774.      * implementation libraries.
  775.      * 
  776.      * For now, we know it's done by the implementation, and we assume
  777.      * that the name of the library is "awt".  -br.
  778.      *
  779.      * If you change loadLibraries(), please add the change to
  780.      * java.awt.image.ColorModel.loadLibraries(). Unfortunately,
  781.      * classes can be loaded in java.awt.image that depend on
  782.      * libawt and there is no way to call Toolkit.loadLibraries()
  783.      * directly.  -hung
  784.      */
  785.     static void loadLibraries() {
  786.         try {
  787.         java.security.AccessController.beginPrivileged();
  788.         System.loadLibrary("fontmanager");
  789.         System.loadLibrary("awt");
  790.     } finally {
  791.         java.security.AccessController.endPrivileged();
  792.     }
  793.     }
  794.  
  795.     static {
  796.         String sep = File.separator;
  797.         properties = new Properties();
  798.     try {
  799.         try {
  800.         java.security.AccessController.beginPrivileged();
  801.         File propsFile = new File(
  802.              System.getProperty("java.home") + sep + "lib" +
  803.              sep + "awt.properties");
  804.  
  805.         FileInputStream in = new FileInputStream(propsFile);
  806.         properties.load(new BufferedInputStream(in));
  807.         in.close();
  808.         } finally {
  809.         java.security.AccessController.endPrivileged();
  810.         }
  811.     } catch (Exception e) {
  812.             // No properties, defaults will be used.
  813.     }
  814.     /* ensure that the proper libraries are loaded */
  815.         loadLibraries();
  816.     initIDs();
  817.     }
  818.  
  819.     /**
  820.      * Gets a property with the specified key and default. 
  821.      * This method returns defaultValue if the property is not found.
  822.      */
  823.     public static String getProperty(String key, String defaultValue) {
  824.     String val = properties.getProperty(key);
  825.     return (val == null) ? defaultValue : val;
  826.     }
  827.  
  828.     /**
  829.      * Get the application's or applet's EventQueue instance.  
  830.      * Depending on the Toolkit implementation, different EventQueues 
  831.      * may be returned for different applets.  Applets should 
  832.      * therefore not assume that the EventQueue instance returned
  833.      * by this method will be shared by other applets or the system.
  834.      * A SecurityException is thrown if the security
  835.      * manager does not allow access to the EventQue.
  836.      */
  837.     public final EventQueue getSystemEventQueue() {
  838.         SecurityManager security = System.getSecurityManager();
  839.         if (security != null) {
  840.       security.checkAwtEventQueueAccess();
  841.         }
  842.         return getSystemEventQueueImpl();
  843.     }
  844.  
  845.     /*
  846.      * Get the application's or applet's EventQueue instance, without
  847.      * checking access.  For security reasons, this can only be called 
  848.      * from a Toolkit subclass.  Implementations wishing to modify
  849.      * the default EventQueue support should subclass this method.
  850.      */
  851.     protected abstract EventQueue getSystemEventQueueImpl();
  852.  
  853.     /* Accessor method for use by AWT package routines. */
  854.     static EventQueue getEventQueue() {
  855.         return toolkit.getSystemEventQueueImpl();
  856.     }
  857.  
  858.     /**
  859.      * create the peer for a DragSourceContext
  860.      */
  861.  
  862.     public abstract DragSourceContextPeer createDragSourceContextPeer(DragSource ds, Component c) throws InvalidDnDOperationException;
  863.  
  864.     /**
  865.      * obtain a value for the specified desktop property.
  866.      *
  867.      * A desktop property is a uniquely named value for a resource that
  868.      * is Toolkit global in nature. Usually it also is an abstract representation
  869.      * for an underlying platform dependent desktop setting.
  870.      */
  871.  
  872.     public final synchronized Object getDesktopProperty(String propertyName) {
  873.  
  874.     if (desktopProperties.isEmpty()) {
  875.         initializeDesktopProperties();
  876.     }
  877.  
  878.     Object value = desktopProperties.get(propertyName);
  879.  
  880.     if (value == null) {
  881.         value = lazilyLoadDesktopProperty(propertyName);
  882.  
  883.         if (value != null) {
  884.         setDesktopProperty(propertyName, value);
  885.         }
  886.     }
  887.  
  888.     return value;
  889.     }
  890.  
  891.     /**
  892.      * set the named desktop property to the specified value and fire a
  893.      * property change event to notify any listeners that the value has changed
  894.      */
  895.  
  896.     protected final synchronized void setDesktopProperty(String name, Object newValue) {
  897.     Object oldValue = desktopProperties.get(name);
  898.  
  899.     desktopProperties.put(name, newValue);
  900.  
  901.     desktopPropsSupport.firePropertyChange(name, oldValue, newValue);
  902.     }
  903.  
  904.     /**
  905.      * an opportunity to lazily evaluate desktop property values.
  906.      */
  907.  
  908.     protected Object lazilyLoadDesktopProperty(String name) {
  909.     return null;
  910.     }
  911.  
  912.     /**
  913.      * initializeDesktopProperties
  914.      */
  915.  
  916.     protected void initializeDesktopProperties() {
  917.     }
  918.  
  919.     /**
  920.      * add the specified property change listener for the named desktop property
  921.      */
  922.  
  923.     public synchronized void addPropertyChangeListener(String name, PropertyChangeListener pcl) {
  924.     desktopPropsSupport.addPropertyChangeListener(name, pcl);
  925.     }
  926.  
  927.     /**
  928.      * remove the specified property change listener for the named desktop property
  929.      */
  930.  
  931.     public synchronized void removePropertyChangeListener(String name, PropertyChangeListener pcl) {
  932.     desktopPropsSupport.removePropertyChangeListener(name, pcl);
  933.     }
  934.  
  935.     protected final Map                  desktopProperties   = new HashMap();
  936.     protected final PropertyChangeSupport desktopPropsSupport = new PropertyChangeSupport(this);
  937. }
  938.  
  939.  
  940.  
  941. /**
  942.  * Implements the LightweightPeer interface for use in lightweight components
  943.  * that have no native window associated with them.  This gets created by
  944.  * default in Component so that Component and Container can be directly
  945.  * extended to create useful components written entirely in java.  These 
  946.  * components must be hosted somewhere higher up in the component tree by a 
  947.  * native container (such as a Frame).
  948.  *
  949.  * This implementation provides no useful semantics and serves only as a
  950.  * marker.  One could provide alternative implementations in java that do
  951.  * something useful for some of the other peer interfaces to minimize the
  952.  * native code.
  953.  *
  954.  * @author Timothy Prinzing
  955.  */
  956. class LightweightPeer implements java.awt.peer.LightweightPeer {
  957.  
  958.     public LightweightPeer(Component target) {
  959.     }
  960.  
  961.     public boolean isFocusTraversable() {
  962.     return false;
  963.     }
  964.  
  965.     public void setVisible(boolean b) {
  966.     }
  967.  
  968.     public void show() {
  969.     }
  970.  
  971.     public void hide() {
  972.     }
  973.  
  974.     public void setEnabled(boolean b) {
  975.     }
  976.  
  977.     public void enable() {
  978.     }
  979.  
  980.     public void disable() {
  981.     }
  982.  
  983.     public void paint(Graphics g) {
  984.     }
  985.  
  986.     public void repaint(long tm, int x, int y, int width, int height) {
  987.     }
  988.  
  989.     public void print(Graphics g) {
  990.     }
  991.  
  992.     public void setBounds(int x, int y, int width, int height) {
  993.     }
  994.  
  995.     public void reshape(int x, int y, int width, int height) {
  996.     }
  997.  
  998.     public boolean handleEvent(Event e) {
  999.     return false;
  1000.     }
  1001.  
  1002.     public void handleEvent(java.awt.AWTEvent arg0) {
  1003.     }
  1004.  
  1005.     public Dimension getPreferredSize() {
  1006.     return new Dimension(1,1);
  1007.     }
  1008.  
  1009.     public Dimension getMinimumSize() {
  1010.     return new Dimension(1,1);
  1011.     }
  1012.  
  1013.     public java.awt.Toolkit getToolkit() {
  1014.     return null;
  1015.     }
  1016.  
  1017.     public ColorModel getColorModel() {
  1018.     return null;
  1019.     }
  1020.  
  1021.     public Graphics getGraphics() {
  1022.     return null;
  1023.     }
  1024.  
  1025.     public FontMetrics    getFontMetrics(Font font) {
  1026.     return null;
  1027.     }
  1028.  
  1029.     public void dispose() {
  1030.     // no native code
  1031.     }
  1032.  
  1033.     public void setForeground(Color c) {
  1034.     }
  1035.  
  1036.     public void setBackground(Color c) {
  1037.     }
  1038.  
  1039.     public void setFont(Font f) {
  1040.     }
  1041.  
  1042.     public void setCursor(Cursor cursor) {
  1043.     }
  1044.  
  1045.     public void requestFocus() {
  1046.     }
  1047.  
  1048.     public Image createImage(ImageProducer producer) {
  1049.     return null;
  1050.     }
  1051.  
  1052.     public Image createImage(int width, int height) {
  1053.     return null;
  1054.     }
  1055.  
  1056.     public boolean prepareImage(Image img, int w, int h, ImageObserver o) {
  1057.     return false;
  1058.     }
  1059.  
  1060.     public int    checkImage(Image img, int w, int h, ImageObserver o) {
  1061.     return 0;
  1062.     }
  1063.  
  1064.     public Dimension preferredSize() {
  1065.     return getPreferredSize();
  1066.     }
  1067.  
  1068.     public Dimension minimumSize() {
  1069.     return getMinimumSize();
  1070.     }
  1071.  
  1072.     public Point getLocationOnScreen() {
  1073.     return null;
  1074.     }
  1075.  
  1076. }
  1077.