1. /*

  2.  * @(#)Toolkit.java	1.189 03/01/23

  3.  *

  4.  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.awt;

  9. 

  10. import java.util.MissingResourceException;

  11. import java.util.Properties;

  12. import java.util.ResourceBundle;

  13. import java.util.StringTokenizer;

  14. import java.awt.event.*;

  15. import java.awt.peer.*;

  16. import java.awt.*;

  17. import java.awt.im.InputMethodHighlight;

  18. import java.awt.image.ImageObserver;

  19. import java.awt.image.ImageProducer;

  20. import java.awt.image.ColorModel;

  21. import java.awt.datatransfer.Clipboard;

  22. import java.awt.dnd.DnDConstants;

  23. import java.awt.dnd.DragSource;

  24. import java.awt.dnd.DragGestureRecognizer;

  25. import java.awt.dnd.DragGestureEvent;

  26. import java.awt.dnd.DragGestureListener;

  27. import java.awt.dnd.InvalidDnDOperationException;

  28. import java.awt.dnd.peer.DragSourceContextPeer;

  29. import java.net.URL;

  30. import java.io.BufferedInputStream;

  31. import java.io.File;

  32. import java.io.FileInputStream;

  33. import java.security.AccessController;

  34. import java.security.PrivilegedAction;

  35. 

  36. import java.util.EventListener;

  37. import java.util.Map;

  38. import java.util.HashMap;

  39. import java.util.WeakHashMap;

  40. import java.util.List;

  41. import java.util.ArrayList;

  42. 

  43. import java.beans.PropertyChangeListener;

  44. import java.beans.PropertyChangeSupport;

  45. 

  46. import sun.awt.DebugHelper;

  47. import sun.awt.HeadlessToolkit;

  48. import sun.awt.NullComponentPeer;

  49. import sun.security.util.SecurityConstants;

  50. /**

  51.  * This class is the abstract superclass of all actual

  52.  * implementations of the Abstract Window Toolkit. Subclasses of

  53.  * <code>Toolkit</code> are used to bind the various components

  54.  * to particular native toolkit implementations.

  55.  * <p>

  56.  * Most applications should not call any of the methods in this

  57.  * class directly. The methods defined by <code>Toolkit</code> are

  58.  * the "glue" that joins the platform-independent classes in the

  59.  * <code>java.awt</code> package with their counterparts in

  60.  * <code>java.awt.peer</code>. Some methods defined by

  61.  * <code>Toolkit</code> query the native operating system directly.

  62.  *

  63.  * @version 	1.189, 01/23/03

  64.  * @author	Sami Shaio

  65.  * @author	Arthur van Hoff

  66.  * @author	Fred Ecks

  67.  * @since       JDK1.0

  68.  */

  69. public abstract class  Toolkit {

  70. 

  71.     /**

  72.      * Creates this toolkit's implementation of <code>Button</code> using

  73.      * the specified peer interface.

  74.      * @param     target the button to be implemented.

  75.      * @return    this toolkit's implementation of <code>Button</code>.

  76.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  77.      * returns true

  78.      * @see       java.awt.GraphicsEnvironment#isHeadless

  79.      * @see       java.awt.Button

  80.      * @see       java.awt.peer.ButtonPeer

  81.      */

  82.     protected abstract ButtonPeer createButton(Button target)

  83.         throws HeadlessException;

  84. 

  85.     /**

  86.      * Creates this toolkit's implementation of <code>TextField</code> using

  87.      * the specified peer interface.

  88.      * @param     target the text field to be implemented.

  89.      * @return    this toolkit's implementation of <code>TextField</code>.

  90.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  91.      * returns true

  92.      * @see       java.awt.GraphicsEnvironment#isHeadless

  93.      * @see       java.awt.TextField

  94.      * @see       java.awt.peer.TextFieldPeer

  95.      */

  96.     protected abstract TextFieldPeer createTextField(TextField target)

  97.         throws HeadlessException;

  98. 

  99.     /**

  100.      * Creates this toolkit's implementation of <code>Label</code> using

  101.      * the specified peer interface.

  102.      * @param     target the label to be implemented.

  103.      * @return    this toolkit's implementation of <code>Label</code>.

  104.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  105.      * returns true

  106.      * @see       java.awt.GraphicsEnvironment#isHeadless

  107.      * @see       java.awt.Label

  108.      * @see       java.awt.peer.LabelPeer

  109.      */

  110.     protected abstract LabelPeer createLabel(Label target)

  111.         throws HeadlessException;

  112. 

  113.     /**

  114.      * Creates this toolkit's implementation of <code>List</code> using

  115.      * the specified peer interface.

  116.      * @param     target the list to be implemented.

  117.      * @return    this toolkit's implementation of <code>List</code>.

  118.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  119.      * returns true

  120.      * @see       java.awt.GraphicsEnvironment#isHeadless

  121.      * @see       java.awt.List

  122.      * @see       java.awt.peer.ListPeer

  123.      */

  124.     protected abstract ListPeer createList(java.awt.List target)

  125.         throws HeadlessException;

  126. 

  127.     /**

  128.      * Creates this toolkit's implementation of <code>Checkbox</code> using

  129.      * the specified peer interface.

  130.      * @param     target the check box to be implemented.

  131.      * @return    this toolkit's implementation of <code>Checkbox</code>.

  132.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  133.      * returns true

  134.      * @see       java.awt.GraphicsEnvironment#isHeadless

  135.      * @see       java.awt.Checkbox

  136.      * @see       java.awt.peer.CheckboxPeer

  137.      */

  138.     protected abstract CheckboxPeer createCheckbox(Checkbox target)

  139.         throws HeadlessException;

  140. 

  141.     /**

  142.      * Creates this toolkit's implementation of <code>Scrollbar</code> using

  143.      * the specified peer interface.

  144.      * @param     target the scroll bar to be implemented.

  145.      * @return    this toolkit's implementation of <code>Scrollbar</code>.

  146.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  147.      * returns true

  148.      * @see       java.awt.GraphicsEnvironment#isHeadless

  149.      * @see       java.awt.Scrollbar

  150.      * @see       java.awt.peer.ScrollbarPeer

  151.      */

  152.     protected abstract ScrollbarPeer createScrollbar(Scrollbar target)

  153.         throws HeadlessException;

  154. 

  155.     /**

  156.      * Creates this toolkit's implementation of <code>ScrollPane</code> using

  157.      * the specified peer interface.

  158.      * @param     target the scroll pane to be implemented.

  159.      * @return    this toolkit's implementation of <code>ScrollPane</code>.

  160.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  161.      * returns true

  162.      * @see       java.awt.GraphicsEnvironment#isHeadless

  163.      * @see       java.awt.ScrollPane

  164.      * @see       java.awt.peer.ScrollPanePeer

  165.      * @since     JDK1.1

  166.      */

  167.     protected abstract ScrollPanePeer createScrollPane(ScrollPane target)

  168.         throws HeadlessException;

  169. 

  170.     /**

  171.      * Creates this toolkit's implementation of <code>TextArea</code> using

  172.      * the specified peer interface.

  173.      * @param     target the text area to be implemented.

  174.      * @return    this toolkit's implementation of <code>TextArea</code>.

  175.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  176.      * returns true

  177.      * @see       java.awt.GraphicsEnvironment#isHeadless

  178.      * @see       java.awt.TextArea

  179.      * @see       java.awt.peer.TextAreaPeer

  180.      */

  181.     protected abstract TextAreaPeer createTextArea(TextArea target)

  182.         throws HeadlessException;

  183. 

  184.     /**

  185.      * Creates this toolkit's implementation of <code>Choice</code> using

  186.      * the specified peer interface.

  187.      * @param     target the choice to be implemented.

  188.      * @return    this toolkit's implementation of <code>Choice</code>.

  189.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  190.      * returns true

  191.      * @see       java.awt.GraphicsEnvironment#isHeadless

  192.      * @see       java.awt.Choice

  193.      * @see       java.awt.peer.ChoicePeer

  194.      */

  195.     protected abstract ChoicePeer createChoice(Choice target)

  196.         throws HeadlessException;

  197. 

  198.     /**

  199.      * Creates this toolkit's implementation of <code>Frame</code> using

  200.      * the specified peer interface.

  201.      * @param     target the frame to be implemented.

  202.      * @return    this toolkit's implementation of <code>Frame</code>.

  203.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  204.      * returns true

  205.      * @see       java.awt.GraphicsEnvironment#isHeadless

  206.      * @see       java.awt.Frame

  207.      * @see       java.awt.peer.FramePeer

  208.      */

  209.     protected abstract FramePeer createFrame(Frame target)

  210.         throws HeadlessException;

  211. 

  212.     /**

  213.      * Creates this toolkit's implementation of <code>Canvas</code> using

  214.      * the specified peer interface.

  215.      * @param     target the canvas to be implemented.

  216.      * @return    this toolkit's implementation of <code>Canvas</code>.

  217.      * @see       java.awt.Canvas

  218.      * @see       java.awt.peer.CanvasPeer

  219.      */

  220.     protected abstract CanvasPeer 	createCanvas(Canvas target);

  221. 

  222.     /**

  223.      * Creates this toolkit's implementation of <code>Panel</code> using

  224.      * the specified peer interface.

  225.      * @param     target the panel to be implemented.

  226.      * @return    this toolkit's implementation of <code>Panel</code>.

  227.      * @see       java.awt.Panel

  228.      * @see       java.awt.peer.PanelPeer

  229.      */

  230.     protected abstract PanelPeer  	createPanel(Panel target);

  231. 

  232.     /**

  233.      * Creates this toolkit's implementation of <code>Window</code> using

  234.      * the specified peer interface.

  235.      * @param     target the window to be implemented.

  236.      * @return    this toolkit's implementation of <code>Window</code>.

  237.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  238.      * returns true

  239.      * @see       java.awt.GraphicsEnvironment#isHeadless

  240.      * @see       java.awt.Window

  241.      * @see       java.awt.peer.WindowPeer

  242.      */

  243.     protected abstract WindowPeer createWindow(Window target)

  244.         throws HeadlessException;

  245. 

  246.     /**

  247.      * Creates this toolkit's implementation of <code>Dialog</code> using

  248.      * the specified peer interface.

  249.      * @param     target the dialog to be implemented.

  250.      * @return    this toolkit's implementation of <code>Dialog</code>.

  251.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  252.      * returns true

  253.      * @see       java.awt.GraphicsEnvironment#isHeadless

  254.      * @see       java.awt.Dialog

  255.      * @see       java.awt.peer.DialogPeer

  256.      */

  257.     protected abstract DialogPeer createDialog(Dialog target)

  258.         throws HeadlessException;

  259. 

  260.     /**

  261.      * Creates this toolkit's implementation of <code>MenuBar</code> using

  262.      * the specified peer interface.

  263.      * @param     target the menu bar to be implemented.

  264.      * @return    this toolkit's implementation of <code>MenuBar</code>.

  265.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  266.      * returns true

  267.      * @see       java.awt.GraphicsEnvironment#isHeadless

  268.      * @see       java.awt.MenuBar

  269.      * @see       java.awt.peer.MenuBarPeer

  270.      */

  271.     protected abstract MenuBarPeer createMenuBar(MenuBar target)

  272.         throws HeadlessException;

  273. 

  274.     /**

  275.      * Creates this toolkit's implementation of <code>Menu</code> using

  276.      * the specified peer interface.

  277.      * @param     target the menu to be implemented.

  278.      * @return    this toolkit's implementation of <code>Menu</code>.

  279.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  280.      * returns true

  281.      * @see       java.awt.GraphicsEnvironment#isHeadless

  282.      * @see       java.awt.Menu

  283.      * @see       java.awt.peer.MenuPeer

  284.      */

  285.     protected abstract MenuPeer createMenu(Menu target)

  286.         throws HeadlessException;

  287. 

  288.     /**

  289.      * Creates this toolkit's implementation of <code>PopupMenu</code> using

  290.      * the specified peer interface.

  291.      * @param     target the popup menu to be implemented.

  292.      * @return    this toolkit's implementation of <code>PopupMenu</code>.

  293.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  294.      * returns true

  295.      * @see       java.awt.GraphicsEnvironment#isHeadless

  296.      * @see       java.awt.PopupMenu

  297.      * @see       java.awt.peer.PopupMenuPeer

  298.      * @since     JDK1.1

  299.      */

  300.     protected abstract PopupMenuPeer createPopupMenu(PopupMenu target)

  301.         throws HeadlessException;

  302. 

  303.     /**

  304.      * Creates this toolkit's implementation of <code>MenuItem</code> using

  305.      * the specified peer interface.

  306.      * @param     target the menu item to be implemented.

  307.      * @return    this toolkit's implementation of <code>MenuItem</code>.

  308.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  309.      * returns true

  310.      * @see       java.awt.GraphicsEnvironment#isHeadless

  311.      * @see       java.awt.MenuItem

  312.      * @see       java.awt.peer.MenuItemPeer

  313.      */

  314.     protected abstract MenuItemPeer createMenuItem(MenuItem target)

  315.         throws HeadlessException;

  316. 

  317.     /**

  318.      * Creates this toolkit's implementation of <code>FileDialog</code> using

  319.      * the specified peer interface.

  320.      * @param     target the file dialog to be implemented.

  321.      * @return    this toolkit's implementation of <code>FileDialog</code>.

  322.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  323.      * returns true

  324.      * @see       java.awt.GraphicsEnvironment#isHeadless

  325.      * @see       java.awt.FileDialog

  326.      * @see       java.awt.peer.FileDialogPeer

  327.      */

  328.     protected abstract FileDialogPeer createFileDialog(FileDialog target)

  329.         throws HeadlessException;

  330. 

  331.     /**

  332.      * Creates this toolkit's implementation of <code>CheckboxMenuItem</code> using

  333.      * the specified peer interface.

  334.      * @param     target the checkbox menu item to be implemented.

  335.      * @return    this toolkit's implementation of <code>CheckboxMenuItem</code>.

  336.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  337.      * returns true

  338.      * @see       java.awt.GraphicsEnvironment#isHeadless

  339.      * @see       java.awt.CheckboxMenuItem

  340.      * @see       java.awt.peer.CheckboxMenuItemPeer

  341.      */

  342.     protected abstract CheckboxMenuItemPeer createCheckboxMenuItem(

  343.         CheckboxMenuItem target) throws HeadlessException;

  344. 

  345.     private static LightweightPeer lightweightMarker;

  346. 

  347.     /**

  348.      * Creates a peer for a component or container.  This peer is windowless

  349.      * and allows the Component and Container classes to be extended directly

  350.      * to create windowless components that are defined entirely in java.

  351.      *

  352.      * @param target The Component to be created.

  353.      */

  354.     protected LightweightPeer createComponent(Component target) {

  355.         if (lightweightMarker == null) {

  356.             lightweightMarker = new NullComponentPeer();

  357.         }

  358.         return lightweightMarker;

  359.     }

  360. 

  361.     /**

  362.      * Creates this toolkit's implementation of <code>Font</code> using

  363.      * the specified peer interface.

  364.      * @param     name the font to be implemented

  365.      * @param     style the style of the font, such as <code>PLAIN</code>,

  366.      *            <code>BOLD</code>, <code>ITALIC</code>, or a combination

  367.      * @return    this toolkit's implementation of <code>Font</code>

  368.      * @see       java.awt.Font

  369.      * @see       java.awt.peer.FontPeer

  370.      * @see       java.awt.GraphicsEnvironment#getAllFonts

  371.      * @deprecated  see java.awt.GraphicsEnvironment#getAllFonts

  372.      */

  373.     protected abstract FontPeer getFontPeer(String name, int style);

  374. 

  375.     // The following method is called by the private method

  376.     // <code>updateSystemColors</code> in <code>SystemColor</code>.

  377. 

  378.     /**

  379.      * Fills in the integer array that is supplied as an argument

  380.      * with the current system color values.

  381.      *

  382.      * @param     systemColors an integer array.

  383.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  384.      * returns true

  385.      * @see       java.awt.GraphicsEnvironment#isHeadless

  386.      * @since     JDK1.1

  387.      */

  388.     protected void loadSystemColors(int[] systemColors)

  389.         throws HeadlessException {

  390.     }

  391. 

  392.     /**

  393.      * Controls whether the layout of Containers is validated dynamically

  394.      * during resizing, or statically, after resizing is complete.

  395.      * Note that this feature is not supported on all platforms, and

  396.      * conversely, that this feature cannot be turned off on some platforms.

  397.      * On platforms where dynamic layout during resize is not supported

  398.      * (or is always supported), setting this property has no effect.

  399.      * Note that this feature can be set or unset as a property of the

  400.      * operating system or window manager on some platforms.  On such

  401.      * platforms, the dynamic resize property must be set at the operating

  402.      * system or window manager level before this method can take effect.

  403.      * This method does not change the underlying operating system or

  404.      * window manager support or settings.  The OS/WM support can be

  405.      * queried using getDesktopProperty("awt.dynamicLayoutSupported").

  406.      *

  407.      * @param     dynamic  If true, Containers should re-layout their

  408.      *            components as the Container is being resized.  If false,

  409.      *            the layout will be validated after resizing is finished.

  410.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  411.      *            returns true

  412.      * @see       #isDynamicLayoutSet()

  413.      * @see       #isDynamicLayoutActive()

  414.      * @see       #getDesktopProperty(String propertyName)

  415.      * @see       java.awt.GraphicsEnvironment#isHeadless

  416.      * @since     1.4

  417.      */

  418.     public void setDynamicLayout(boolean dynamic)

  419.         throws HeadlessException {

  420.     }

  421. 

  422.     /**

  423.      * Returns whether the layout of Containers is validated dynamically

  424.      * during resizing, or statically, after resizing is complete.

  425.      * Note: this method returns the value that was set programmatically;

  426.      * it does not reflect support at the level of the operating system

  427.      * or window manager for dynamic layout on resizing, or the current

  428.      * operating system or window manager settings.  The OS/WM support can

  429.      * be queried using getDesktopProperty("awt.dynamicLayoutSupported").

  430.      *

  431.      * @return    true if validation of Containers is done dynamically,

  432.      *            false if validation is done after resizing is finished.

  433.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  434.      *            returns true

  435.      * @see       #setDynamicLayout(boolean dynamic)

  436.      * @see       #isDynamicLayoutActive()

  437.      * @see       #getDesktopProperty(String propertyName)

  438.      * @see       java.awt.GraphicsEnvironment#isHeadless

  439.      * @since     1.4

  440.      */

  441.     protected boolean isDynamicLayoutSet()

  442.         throws HeadlessException {

  443.         if (this != Toolkit.getDefaultToolkit()) {

  444.             return Toolkit.getDefaultToolkit().isDynamicLayoutSet();

  445.         } else {

  446.             return false;

  447.         }

  448.     }

  449. 

  450.     /**

  451.      * Returns whether dynamic layout of Containers on resize is

  452.      * currently active (both set programmatically, and supported

  453.      * by the underlying operating system and/or window manager).

  454.      * The OS/WM support can be queried using 

  455.      * getDesktopProperty("awt.dynamicLayoutSupported").

  456.      *

  457.      * @return    true if dynamic layout of Containers on resize is

  458.      *            currently active, false otherwise.

  459.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  460.      *            returns true

  461.      * @see       #setDynamicLayout(boolean dynamic)

  462.      * @see       #isDynamicLayoutSet()

  463.      * @see       #getDesktopProperty(String propertyName)

  464.      * @see       java.awt.GraphicsEnvironment#isHeadless

  465.      * @since     1.4

  466.      */

  467.     public boolean isDynamicLayoutActive()

  468.         throws HeadlessException {

  469.         if (this != Toolkit.getDefaultToolkit()) {

  470.             return Toolkit.getDefaultToolkit().isDynamicLayoutActive();

  471.         } else {

  472.             return false;

  473.         }

  474.     }

  475. 

  476.     /**

  477.      * Gets the size of the screen.  On systems with multiple displays, the

  478.      * primary display is used.  Multi-screen aware display dimensions are

  479.      * available from <code>GraphicsConfiguration</code> and

  480.      * <code>GraphicsDevice</code>.

  481.      * @return    the size of this toolkit's screen, in pixels.

  482.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  483.      * returns true

  484.      * @see       java.awt.GraphicsConfiguration#getBounds

  485.      * @see       java.awt.GraphicsDevice#getDisplayMode

  486.      * @see       java.awt.GraphicsEnvironment#isHeadless

  487.      */

  488.     public abstract Dimension getScreenSize()

  489.         throws HeadlessException;

  490. 

  491.     /**

  492.      * Returns the screen resolution in dots-per-inch.

  493.      * @return    this toolkit's screen resolution, in dots-per-inch.

  494.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  495.      * returns true

  496.      * @see       java.awt.GraphicsEnvironment#isHeadless

  497.      */

  498.     public abstract int getScreenResolution()

  499.         throws HeadlessException;

  500. 

  501.     /**

  502.      * Gets the insets of the screen.

  503.      * @param     gc a <code>GraphicsConfiguration</code>

  504.      * @return    the insets of this toolkit's screen, in pixels.

  505.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  506.      * returns true

  507.      * @see       java.awt.GraphicsEnvironment#isHeadless

  508.      * @since     1.4

  509.      */

  510.     public Insets getScreenInsets(GraphicsConfiguration gc)

  511.         throws HeadlessException {

  512.         if (this != Toolkit.getDefaultToolkit()) {

  513.             return Toolkit.getDefaultToolkit().getScreenInsets(gc);

  514.         } else {

  515.             return new Insets(0, 0, 0, 0);

  516.         }

  517.     }

  518.     

  519.     /**

  520.      * Determines the color model of this toolkit's screen.

  521.      * <p>

  522.      * <code>ColorModel</code> is an abstract class that

  523.      * encapsulates the ability to translate between the

  524.      * pixel values of an image and its red, green, blue,

  525.      * and alpha components.

  526.      * <p>

  527.      * This toolkit method is called by the

  528.      * <code>getColorModel</code> method

  529.      * of the <code>Component</code> class.

  530.      * @return    the color model of this toolkit's screen.

  531.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  532.      * returns true

  533.      * @see       java.awt.GraphicsEnvironment#isHeadless

  534.      * @see       java.awt.image.ColorModel

  535.      * @see       java.awt.Component#getColorModel

  536.      */

  537.     public abstract ColorModel getColorModel()

  538.         throws HeadlessException;

  539. 

  540.     /**

  541.      * Returns the names of the available fonts in this toolkit.<p>

  542.      * For 1.1, the following font names are deprecated (the replacement

  543.      * name follows):

  544.      * <ul>

  545.      * <li>TimesRoman (use Serif)

  546.      * <li>Helvetica (use SansSerif)

  547.      * <li>Courier (use Monospaced)

  548.      * </ul><p>

  549.      * The ZapfDingbats fontname is also deprecated in 1.1 but the characters

  550.      * are defined in Unicode starting at 0x2700, and as of 1.1 Java supports

  551.      * those characters.

  552.      * @return    the names of the available fonts in this toolkit.

  553.      * @deprecated see {@link java.awt.GraphicsEnvironment#getAvailableFontFamilyNames()}

  554.      * @see java.awt.GraphicsEnvironment#getAvailableFontFamilyNames()

  555.      */

  556.     public abstract String[] getFontList();

  557. 

  558.     /**

  559.      * Gets the screen device metrics for rendering of the font.

  560.      * @param     font   a font

  561.      * @return    the screen metrics of the specified font in this toolkit

  562.      * @deprecated  As of JDK version 1.2, replaced by the <code>Font</code>

  563.      *		method <code>getLineMetrics</code>.

  564.      * @see java.awt.font.LineMetrics

  565.      * @see java.awt.Font#getLineMetrics

  566.      * @see java.awt.GraphicsEnvironment#getScreenDevices

  567.      */

  568.     public abstract FontMetrics getFontMetrics(Font font);

  569. 

  570.     /**

  571.      * Synchronizes this toolkit's graphics state. Some window systems

  572.      * may do buffering of graphics events.

  573.      * <p>

  574.      * This method ensures that the display is up-to-date. It is useful

  575.      * for animation.

  576.      */

  577.     public abstract void sync();

  578. 

  579.     /**

  580.      * The default toolkit.

  581.      */

  582.     private static Toolkit toolkit;

  583. 

  584.     /**

  585.      * Loads additional classes into the VM, using the property

  586.      * 'assistive_technologies' specified in the Sun reference

  587.      * implementation by a line in the 'accessibility.properties'

  588.      * file.  The form is "assistive_technologies=..." where

  589.      * the "..." is a comma-separated list of assistive technology

  590.      * classes to load.  Each class is loaded in the order given

  591.      * and a single instance of each is created using

  592.      * Class.forName(class).newInstance().  All errors are handled

  593.      * via an AWTError exception.

  594.      *

  595.      * <p>The assumption is made that assistive technology classes are supplied

  596.      * as part of INSTALLED (as opposed to: BUNDLED) extensions or specified

  597.      * on the class path

  598.      * (and therefore can be loaded using the class loader returned by

  599.      * a call to <code>ClassLoader.getSystemClassLoader</code>, whose

  600.      * delegation parent is the extension class loader for installed

  601.      * extensions).

  602.      */

  603.     private static void loadAssistiveTechnologies() {

  604. 

  605. 	// Get accessibility properties 

  606.         final String sep = File.separator;

  607.         final Properties properties = new Properties();

  608. 

  609. 

  610. 	String atNames = (String)java.security.AccessController.doPrivileged(

  611. 	    new java.security.PrivilegedAction() {

  612. 	    public Object run() {

  613. 

  614. 		// Try loading the per-user accessibility properties file.

  615. 		try {

  616. 		    File propsFile = new File(

  617. 		      System.getProperty("user.home") +

  618. 		      sep + ".accessibility.properties");

  619. 		    FileInputStream in =

  620. 			new FileInputStream(propsFile);

  621. 

  622.                     // Inputstream has been buffered in Properties class

  623. 		    properties.load(in);

  624. 		    in.close();

  625. 		} catch (Exception e) {

  626. 		    // Per-user accessibility properties file does not exist

  627. 		}

  628. 

  629. 		// Try loading the system-wide accessibility properties

  630. 		// file only if a per-user accessibility properties

  631. 		// file does not exist or is empty.

  632. 		if (properties.size() == 0) {

  633. 		    try {

  634. 			File propsFile = new File(

  635. 			    System.getProperty("java.home") + sep + "lib" +

  636. 			    sep + "accessibility.properties");

  637. 			FileInputStream in =

  638. 			    new FileInputStream(propsFile);

  639. 			

  640. 			// Inputstream has been buffered in Properties class

  641. 			properties.load(in);

  642. 			in.close();

  643. 		    } catch (Exception e) {

  644. 			// System-wide accessibility properties file does 

  645. 			// not exist;

  646. 		    }

  647. 		}

  648. 		

  649. 		// Get whether a screen magnifier is present.  First check

  650. 		// the system property and then check the properties file.

  651. 		String magPresent = System.getProperty("javax.accessibility.screen_magnifier_present");

  652. 		if (magPresent == null) {

  653. 		    magPresent = properties.getProperty("screen_magnifier_present", null);

  654. 		    if (magPresent != null) {

  655. 			System.setProperty("javax.accessibility.screen_magnifier_present", magPresent);

  656. 		    }

  657. 		}

  658. 

  659. 		// Get the names of any assistive technolgies to load.  First 

  660. 		// check the system property and then check the properties 

  661. 		// file.

  662. 		String classNames = System.getProperty("javax.accessibility.assistive_technologies");

  663. 		if (classNames == null) {

  664. 		    classNames = properties.getProperty("assistive_technologies", null);

  665. 		    if (classNames != null) {

  666. 			System.setProperty("javax.accessibility.assistive_technologies", classNames);

  667. 		    }

  668. 		}

  669. 		return classNames;

  670. 	    }

  671. 	});

  672. 

  673. 

  674. 	// Load any assistive technologies

  675.         if (atNames != null) {

  676. 	    ClassLoader cl = ClassLoader.getSystemClassLoader();

  677.             StringTokenizer parser = new StringTokenizer(atNames," ,");

  678. 	    String atName;

  679.             while (parser.hasMoreTokens()) {

  680. 		atName = parser.nextToken();

  681.                 try {

  682. 		    Class clazz;

  683. 		    if (cl != null) {

  684. 			clazz = cl.loadClass(atName);

  685. 		    } else {

  686. 			clazz = Class.forName(atName);

  687. 		    }

  688. 		    clazz.newInstance();

  689.                 } catch (ClassNotFoundException e) {

  690.                     throw new AWTError("Assistive Technology not found: "

  691. 			    + atName);

  692.                 } catch (InstantiationException e) {

  693.                     throw new AWTError("Could not instantiate Assistive"

  694. 			    + " Technology: " + atName);

  695.                 } catch (IllegalAccessException e) {

  696.                     throw new AWTError("Could not access Assistive"

  697. 			    + " Technology: " + atName);

  698.                 } catch (Exception e) {

  699.                     throw new AWTError("Error trying to install Assistive"

  700. 			    + " Technology: " + atName + " " + e);

  701.                 }

  702.             }

  703.         }

  704.     }

  705. 

  706.     /**

  707.      * Gets the default toolkit.

  708.      * <p>

  709.      * If there is a system property named <code>"awt.toolkit"</code>,

  710.      * that property is treated as the name of a class that is a subclass

  711.      * of <code>Toolkit</code>.

  712.      * <p>

  713.      * If the system property does not exist, then the default toolkit

  714.      * used is the class named <code>"sun.awt.motif.MToolkit"</code>,

  715.      * which is a motif implementation of the Abstract Window Toolkit.

  716.      * <p>

  717.      * Also loads additional classes into the VM, using the property

  718.      * 'assistive_technologies' specified in the Sun reference

  719.      * implementation by a line in the 'accessibility.properties'

  720.      * file.  The form is "assistive_technologies=..." where

  721.      * the "..." is a comma-separated list of assistive technology

  722.      * classes to load.  Each class is loaded in the order given

  723.      * and a single instance of each is created using

  724.      * Class.forName(class).newInstance().  This is done just after

  725.      * the AWT toolkit is created.  All errors are handled via an

  726.      * AWTError exception.

  727.      * @return    the default toolkit.

  728.      * @exception  AWTError  if a toolkit could not be found, or

  729.      *                 if one could not be accessed or instantiated.

  730.      */

  731.     public static synchronized Toolkit getDefaultToolkit() {

  732. 	if (toolkit == null) {

  733. 	    try {

  734. 		// We disable the JIT during toolkit initialization.  This

  735. 		// tends to touch lots of classes that aren't needed again

  736. 		// later and therefore JITing is counter-productiive.

  737. 		java.lang.Compiler.disable();

  738. 

  739. 	        java.security.AccessController.doPrivileged(

  740. 			new java.security.PrivilegedAction() {

  741. 		    public Object run() {

  742. 		        String nm = null;

  743. 			Class cls = null;

  744. 		        try {

  745. 			    nm = System.getProperty("awt.toolkit",

  746. 						"sun.awt.motif.MToolkit");

  747. 			    try {

  748. 			    	cls = Class.forName(nm);

  749. 		            } catch (ClassNotFoundException e) {

  750. 			    	ClassLoader cl = ClassLoader.getSystemClassLoader();

  751.                                 if (cl != null) {

  752. 			    	    try {

  753.                                         cls = cl.loadClass(nm);

  754. 		            	    } catch (ClassNotFoundException ee) {

  755. 			    		throw new AWTError("Toolkit not found: " + nm);

  756. 				    }

  757.                                 }

  758. 	                    }

  759.                             if (cls != null) {

  760. 				toolkit = (Toolkit)cls.newInstance();

  761.                                 if (GraphicsEnvironment.isHeadless()) {

  762.                                     toolkit = new HeadlessToolkit(toolkit);

  763.                                 }

  764. 			    }

  765. 		        } catch (InstantiationException e) {

  766. 			    throw new AWTError("Could not instantiate Toolkit: " +

  767. 					   nm);

  768. 		        } catch (IllegalAccessException e) {

  769. 			    throw new AWTError("Could not access Toolkit: " + nm);

  770. 		        }

  771. 		        return null;

  772. 		    }

  773. 	        });

  774. 	        loadAssistiveTechnologies();

  775. 

  776. 	    } finally {

  777. 		// Make sure to always re-enable the JIT.

  778. 		java.lang.Compiler.enable();

  779. 	    }

  780. 	}

  781. 	return toolkit;

  782.     }

  783. 

  784.     /**

  785.      * Returns an image which gets pixel data from the specified file,

  786.      * whose format can be either GIF, JPEG or PNG.

  787.      * The underlying toolkit attempts to resolve multiple requests

  788.      * with the same filename to the same returned Image.

  789.      * Since the mechanism required to facilitate this sharing of

  790.      * Image objects may continue to hold onto images that are no

  791.      * longer of use for an indefinite period of time, developers

  792.      * are encouraged to implement their own caching of images by

  793.      * using the createImage variant wherever available.

  794.      * @param     filename   the name of a file containing pixel data

  795.      *                         in a recognized file format.

  796.      * @return    an image which gets its pixel data from

  797.      *                         the specified file.

  798.      * @see #createImage(java.lang.String)

  799.      */

  800.     public abstract Image getImage(String filename);

  801. 

  802.     /**

  803.      * Returns an image which gets pixel data from the specified URL.

  804.      * The pixel data referenced by the specified URL must be in one

  805.      * of the following formats: GIF, JPEG or PNG.

  806.      * The underlying toolkit attempts to resolve multiple requests

  807.      * with the same URL to the same returned Image.

  808.      * Since the mechanism required to facilitate this sharing of

  809.      * Image objects may continue to hold onto images that are no

  810.      * longer of use for an indefinite period of time, developers

  811.      * are encouraged to implement their own caching of images by

  812.      * using the createImage variant wherever available.

  813.      * @param     url   the URL to use in fetching the pixel data.

  814.      * @return    an image which gets its pixel data from

  815.      *                         the specified URL.

  816.      * @see #createImage(java.net.URL)

  817.      */

  818.     public abstract Image getImage(URL url);

  819. 

  820.     /**

  821.      * Returns an image which gets pixel data from the specified file.

  822.      * The returned Image is a new object which will not be shared

  823.      * with any other caller of this method or its getImage variant.

  824.      * @param     filename   the name of a file containing pixel data

  825.      *                         in a recognized file format.

  826.      * @return    an image which gets its pixel data from

  827.      *                         the specified file.

  828.      * @see #getImage(java.lang.String)

  829.      */

  830.     public abstract Image createImage(String filename);

  831. 

  832.     /**

  833.      * Returns an image which gets pixel data from the specified URL.

  834.      * The returned Image is a new object which will not be shared

  835.      * with any other caller of this method or its getImage variant.

  836.      * @param     url   the URL to use in fetching the pixel data.

  837.      * @return    an image which gets its pixel data from

  838.      *                         the specified URL.

  839.      * @see #getImage(java.net.URL)

  840.      */

  841.     public abstract Image createImage(URL url);

  842. 

  843.     /**

  844.      * Prepares an image for rendering.

  845.      * <p>

  846.      * If the values of the width and height arguments are both

  847.      * <code>-1</code>, this method prepares the image for rendering

  848.      * on the default screen; otherwise, this method prepares an image

  849.      * for rendering on the default screen at the specified width and height.

  850.      * <p>

  851.      * The image data is downloaded asynchronously in another thread,

  852.      * and an appropriately scaled screen representation of the image is

  853.      * generated.

  854.      * <p>

  855.      * This method is called by components <code>prepareImage</code>

  856.      * methods.

  857.      * <p>

  858.      * Information on the flags returned by this method can be found

  859.      * with the definition of the <code>ImageObserver</code> interface.

  860. 

  861.      * @param     image      the image for which to prepare a

  862.      *                           screen representation.

  863.      * @param     width      the width of the desired screen

  864.      *                           representation, or <code>-1</code>.

  865.      * @param     height     the height of the desired screen

  866.      *                           representation, or <code>-1</code>.

  867.      * @param     observer   the <code>ImageObserver</code>

  868.      *                           object to be notified as the

  869.      *                           image is being prepared.

  870.      * @return    <code>true</code> if the image has already been

  871.      *                 fully prepared; <code>false</code> otherwise.

  872.      * @see       java.awt.Component#prepareImage(java.awt.Image,

  873.      *                 java.awt.image.ImageObserver)

  874.      * @see       java.awt.Component#prepareImage(java.awt.Image,

  875.      *                 int, int, java.awt.image.ImageObserver)

  876.      * @see       java.awt.image.ImageObserver

  877.      */

  878.     public abstract boolean prepareImage(Image image, int width, int height,

  879. 					 ImageObserver observer);

  880. 

  881.     /**

  882.      * Indicates the construction status of a specified image that is

  883.      * being prepared for display.

  884.      * <p>

  885.      * If the values of the width and height arguments are both

  886.      * <code>-1</code>, this method returns the construction status of

  887.      * a screen representation of the specified image in this toolkit.

  888.      * Otherwise, this method returns the construction status of a

  889.      * scaled representation of the image at the specified width

  890.      * and height.

  891.      * <p>

  892.      * This method does not cause the image to begin loading.

  893.      * An application must call <code>prepareImage</code> to force

  894.      * the loading of an image.

  895.      * <p>

  896.      * This method is called by the component's <code>checkImage</code>

  897.      * methods.

  898.      * <p>

  899.      * Information on the flags returned by this method can be found

  900.      * with the definition of the <code>ImageObserver</code> interface.

  901.      * @param     image   the image whose status is being checked.

  902.      * @param     width   the width of the scaled version whose status is

  903.      *                 being checked, or <code>-1</code>.

  904.      * @param     height  the height of the scaled version whose status

  905.      *                 is being checked, or <code>-1</code>.

  906.      * @param     observer   the <code>ImageObserver</code> object to be

  907.      *                 notified as the image is being prepared.

  908.      * @return    the bitwise inclusive <strong>OR</strong> of the

  909.      *                 <code>ImageObserver</code> flags for the

  910.      *                 image data that is currently available.

  911.      * @see       java.awt.Toolkit#prepareImage(java.awt.Image,

  912.      *                 int, int, java.awt.image.ImageObserver)

  913.      * @see       java.awt.Component#checkImage(java.awt.Image,

  914.      *                 java.awt.image.ImageObserver)

  915.      * @see       java.awt.Component#checkImage(java.awt.Image,

  916.      *                 int, int, java.awt.image.ImageObserver)

  917.      * @see       java.awt.image.ImageObserver

  918.      */

  919.     public abstract int checkImage(Image image, int width, int height,

  920. 				   ImageObserver observer);

  921. 

  922.     /**

  923.      * Creates an image with the specified image producer.

  924.      * @param     producer the image producer to be used.

  925.      * @return    an image with the specified image producer.

  926.      * @see       java.awt.Image

  927.      * @see       java.awt.image.ImageProducer

  928.      * @see       java.awt.Component#createImage(java.awt.image.ImageProducer)

  929.      */

  930.     public abstract Image createImage(ImageProducer producer);

  931. 

  932.     /**

  933.      * Creates an image which decodes the image stored in the specified

  934.      * byte array.

  935.      * <p>

  936.      * The data must be in some image format, such as GIF or JPEG,

  937.      * that is supported by this toolkit.

  938.      * @param     imagedata   an array of bytes, representing

  939.      *                         image data in a supported image format.

  940.      * @return    an image.

  941.      * @since     JDK1.1

  942.      */

  943.     public Image createImage(byte[] imagedata) {

  944. 	return createImage(imagedata, 0, imagedata.length);

  945.     }

  946. 

  947.     /**

  948.      * Creates an image which decodes the image stored in the specified

  949.      * byte array, and at the specified offset and length.

  950.      * The data must be in some image format, such as GIF or JPEG,

  951.      * that is supported by this toolkit.

  952.      * @param     imagedata   an array of bytes, representing

  953.      *                         image data in a supported image format.

  954.      * @param     imageoffset  the offset of the beginning

  955.      *                         of the data in the array.

  956.      * @param     imagelength  the length of the data in the array.

  957.      * @return    an image.

  958.      * @since     JDK1.1

  959.      */

  960.     public abstract Image createImage(byte[] imagedata,

  961. 				      int imageoffset,

  962. 				      int imagelength);

  963. 

  964.     /**

  965.      * Gets a <code>PrintJob</code> object which is the result of initiating

  966.      * a print operation on the toolkit's platform.

  967.      * <p>

  968.      * Each actual implementation of this method should first check if there 

  969.      * is a security manager installed. If there is, the method should call

  970.      * the security manager's <code>checkPrintJobAccess</code> method to

  971.      * ensure initiation of a print operation is allowed. If the default

  972.      * implementation of <code>checkPrintJobAccess</code> is used (that is,

  973.      * that method is not overriden), then this results in a call to the

  974.      * security manager's <code>checkPermission</code> method with a <code>

  975.      * RuntimePermission("queuePrintJob")</code> permission.

  976.      *

  977.      * @param	frame the parent of the print dialog. May not be null.

  978.      * @param	jobtitle the title of the PrintJob. A null title is equivalent

  979.      *		to "".

  980.      * @param	props a Properties object containing zero or more properties.

  981.      *		Properties are not standardized and are not consistent across

  982.      *		implementations. Because of this, PrintJobs which require job

  983.      *		and page control should use the version of this function which

  984.      *		takes JobAttributes and PageAttributes objects. This object

  985.      *		may be updated to reflect the user's job choices on exit. May

  986.      *		be null.

  987.      *

  988.      * @return	a <code>PrintJob</code> object, or <code>null</code> if the

  989.      *		user cancelled the print job.

  990.      * @throws	NullPointerException if frame is null.  This exception is

  991.      *          always thrown when GraphicsEnvironment.isHeadless() returns

  992.      *          true.

  993.      * @throws	SecurityException if this thread is not allowed to initiate a

  994.      *		print job request

  995.      * @see     java.awt.GraphicsEnvironment#isHeadless

  996.      * @see	java.awt.PrintJob

  997.      * @see	java.lang.RuntimePermission

  998.      * @since	JDK1.1

  999.      */

  1000.     public abstract PrintJob getPrintJob(Frame frame, String jobtitle,

  1001. 					 Properties props);

  1002. 

  1003.     /**

  1004.      * Gets a <code>PrintJob</code> object which is the result of initiating

  1005.      * a print operation on the toolkit's platform.

  1006.      * <p>

  1007.      * Each actual implementation of this method should first check if there 

  1008.      * is a security manager installed. If there is, the method should call

  1009.      * the security manager's <code>checkPrintJobAccess</code> method to

  1010.      * ensure initiation of a print operation is allowed. If the default

  1011.      * implementation of <code>checkPrintJobAccess</code> is used (that is,

  1012.      * that method is not overriden), then this results in a call to the

  1013.      * security manager's <code>checkPermission</code> method with a <code>

  1014.      * RuntimePermission("queuePrintJob")</code> permission.

  1015.      *

  1016.      * @param	frame the parent of the print dialog. May be null if and only

  1017.      *		if jobAttributes is not null and jobAttributes.getDialog()

  1018.      *		returns	JobAttributes.DialogType.NONE or

  1019.      *		JobAttributes.DialogType.COMMON.

  1020.      * @param	jobtitle the title of the PrintJob. A null title is equivalent

  1021.      *		to "".

  1022.      * @param	jobAttributes a set of job attributes which will control the

  1023.      *		PrintJob. The attributes will be updated to reflect the user's

  1024.      *		choices as outlined in the JobAttributes documentation. May be

  1025.      *		null.

  1026.      * @param	pageAttributes a set of page attributes which will control the

  1027.      *		PrintJob. The attributes will be applied to every page in the

  1028.      *		job. The attributes will be updated to reflect the user's

  1029.      *		choices as outlined in the PageAttributes documentation. May be

  1030.      *		null.

  1031.      *

  1032.      * @return	a <code>PrintJob</code> object, or <code>null</code> if the

  1033.      *		user cancelled the print job.

  1034.      * @throws	NullPointerException if frame is null and either jobAttributes

  1035.      *		is null or jobAttributes.getDialog() returns

  1036.      *		JobAttributes.DialogType.NATIVE.

  1037.      * @throws	IllegalArgumentException if pageAttributes specifies differing

  1038.      *		cross feed and feed resolutions.  This exception is always

  1039.      *          thrown when GraphicsEnvironment.isHeadless() returns true.

  1040.      * @throws	SecurityException if this thread is not allowed to initiate a

  1041.      *		print job request, or if jobAttributes specifies print to file,

  1042.      *		and this thread is not allowed to access the file system

  1043.      * @see	java.awt.PrintJob

  1044.      * @see     java.awt.GraphicsEnvironment#isHeadless

  1045.      * @see	java.lang.RuntimePermission

  1046.      * @see	java.awt.JobAttributes

  1047.      * @see	java.awt.PageAttributes

  1048.      * @since	1.3

  1049.      */

  1050.     public PrintJob getPrintJob(Frame frame, String jobtitle,

  1051. 				JobAttributes jobAttributes,

  1052. 				PageAttributes pageAttributes) {

  1053.         // Override to add printing support with new job/page control classes

  1054. 

  1055.         if (GraphicsEnvironment.isHeadless()) {

  1056.             throw new IllegalArgumentException();

  1057.         }

  1058. 

  1059. 	if (this != Toolkit.getDefaultToolkit()) {

  1060. 	    return Toolkit.getDefaultToolkit().getPrintJob(frame, jobtitle,

  1061. 							   jobAttributes,

  1062. 							   pageAttributes);

  1063. 	} else {

  1064. 	    return getPrintJob(frame, jobtitle, null);

  1065. 	}

  1066.     }

  1067. 

  1068.     /**

  1069.      * Emits an audio beep.

  1070.      * @since     JDK1.1

  1071.      */

  1072.     public abstract void beep();

  1073. 

  1074.     /**

  1075.      * Gets the singleton instance of the system Clipboard which interfaces

  1076.      * with clipboard facilities provided by the native platform. This 

  1077.      * clipboard enables data transfer between Java programs and native

  1078.      * applications which use native clipboard facilities.

  1079.      * <p>

  1080.      * In addition to any and all formats specified in the flavormap.properties

  1081.      * file, or other file specified by the <code>AWT.DnD.flavorMapFileURL

  1082.      * </code> Toolkit property, text returned by the system Clipboard's <code>

  1083.      * getTransferData()</code> method is available in the following flavors:

  1084.      * <ul>

  1085.      * <li>DataFlavor.stringFlavor</li>

  1086.      * <li>DataFlavor.plainTextFlavor (<b>deprecated</b>)</li>

  1087.      * </ul>

  1088.      * As with <code>java.awt.datatransfer.StringSelection</code>, if the

  1089.      * requested flavor is <code>DataFlavor.plainTextFlavor</code>, or an

  1090.      * equivalent flavor, a Reader is returned. <b>Note:</b> The behavior of

  1091.      * the system Clipboard's <code>getTransferData()</code> method for <code>

  1092.      * DataFlavor.plainTextFlavor</code>, and equivalent DataFlavors, is

  1093.      * inconsistent with the definition of <code>DataFlavor.plainTextFlavor

  1094.      * </code>. Because of this, support for <code>

  1095.      * DataFlavor.plainTextFlavor</code>, and equivalent flavors, is

  1096.      * <b>deprecated</b>.

  1097.      * <p>

  1098.      * Each actual implementation of this method should first check if there

  1099.      * is a security manager installed. If there is, the method should call

  1100.      * the security manager's <code>checkSystemClipboardAccess</code> method

  1101.      * to ensure it's ok to to access the system clipboard. If the default

  1102.      * implementation of <code>checkSystemClipboardAccess</code> is used (that

  1103.      * is, that method is not overriden), then this results in a call to the

  1104.      * security manager's <code>checkPermission</code> method with an <code>

  1105.      * AWTPermission("accessClipboard")</code> permission.

  1106.      * 

  1107.      * @return    the system Clipboard

  1108.      * @exception HeadlessException if GraphicsEnvironment.isHeadless()

  1109.      * returns true

  1110.      * @see       java.awt.GraphicsEnvironment#isHeadless

  1111.      * @see       java.awt.datatransfer.Clipboard

  1112.      * @see       java.awt.datatransfer.StringSelection

  1113.      * @see       java.awt.datatransfer.DataFlavor#stringFlavor

  1114.      * @see       java.awt.datatransfer.DataFlavor#plainTextFlavor

  1115.      * @see       java.io.Reader

  1116.      * @see       java.awt.AWTPermission

  1117.      * @since     JDK1.1

  1118.      */

  1119.     public abstract Clipboard getSystemClipboard()

  1120.         throws HeadlessException;

  1121. 

  1122.     /**

  1123.      * Gets the singleton instance of the system selection as a

  1124.      * <code>Clipboard</code> object. This allows an application to read and

  1125.      * modify the current, system-wide selection.

  1126.      * <p>

  1127.      * An application is responsible for updating the system selection whenever

  1128.      * the user selects text, using either the mouse or the keyboard.

  1129.      * Typically, this is implemented by installing a

  1130.      * <code>FocusListener</code> on all <code>Component</code>s which support

  1131.      * text selection, and, between <code>FOCUS_GAINED</code> and

  1132.      * <code>FOCUS_LOST</code> events delivered to that <code>Component</code>,

  1133.      * updating the system selection <code>Clipboard</code> when the selection

  1134.      * changes inside the <code>Component</code>. Properly updating the system

  1135.      * selection ensures that a Java application will interact correctly with

  1136.      * native applications and other Java applications running simultaneously

  1137.      * on the system. Note that <code>java.awt.TextComponent</code> and

  1138.      * <code>javax.swing.text.JTextComponent</code> already adhere to this

  1139.      * policy. When using these classes, and their subclasses, developers need

  1140.      * not write any additional code.

  1141.      * <p>

  1142.      * Some platforms do not support a system selection <code>Clipboard</code>.

  1143.      * On those platforms, this method will return <code>null</code>. In such a

  1144.      * case, an application is absolved from its responsibility to update the

  1145.      * system selection <code>Clipboard</code> as described above.