/* * Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.awt; import java.awt.datatransfer.Clipboard; import java.awt.dnd.DragGestureListener; import java.awt.dnd.DragGestureRecognizer; import java.awt.dnd.DragSource; import java.awt.event.AWTEventListener; import java.awt.event.AWTEventListenerProxy; import java.awt.event.ActionEvent; import java.awt.event.AdjustmentEvent; import java.awt.event.ComponentEvent; import java.awt.event.ContainerEvent; import java.awt.event.FocusEvent; import java.awt.event.HierarchyEvent; import java.awt.event.InputEvent; import java.awt.event.InputMethodEvent; import java.awt.event.InvocationEvent; import java.awt.event.ItemEvent; import java.awt.event.KeyEvent; import java.awt.event.MouseEvent; import java.awt.event.PaintEvent; import java.awt.event.TextEvent; import java.awt.event.WindowEvent; import java.awt.im.InputMethodHighlight; import java.awt.image.ColorModel; import java.awt.image.ImageObserver; import java.awt.image.ImageProducer; import java.beans.PropertyChangeEvent; import java.beans.PropertyChangeListener; import java.beans.PropertyChangeSupport; import java.io.File; import java.io.FileInputStream; import java.net.URL; import java.security.AccessController; import java.security.PrivilegedAction; import java.util.ArrayList; import java.util.Arrays; import java.util.EventListener; import java.util.HashMap; import java.util.Map; import java.util.MissingResourceException; import java.util.Properties; import java.util.ResourceBundle; import java.util.ServiceLoader; import java.util.Set; import java.util.WeakHashMap; import java.util.stream.Collectors; import javax.accessibility.AccessibilityProvider; import sun.awt.AWTAccessor; import sun.awt.AWTPermissions; import sun.awt.AppContext; import sun.awt.HeadlessToolkit; import sun.awt.PeerEvent; import sun.awt.SunToolkit; /** * This class is the abstract superclass of all actual * implementations of the Abstract Window Toolkit. Subclasses of * the {@code Toolkit} class are used to bind the various components * to particular native toolkit implementations. *
* Many GUI events may be delivered to user * asynchronously, if the opposite is not specified explicitly. * As well as * many GUI operations may be performed asynchronously. * This fact means that if the state of a component is set, and then * the state immediately queried, the returned value may not yet * reflect the requested change. This behavior includes, but is not * limited to: *
* Most applications should not call any of the methods in this
* class directly. The methods defined by {@code Toolkit} are
* the "glue" that joins the platform-independent classes in the
* {@code java.awt} package with their counterparts in
* {@code java.awt.peer}. Some methods defined by
* {@code Toolkit} query the native operating system directly.
*
* @author Sami Shaio
* @author Arthur van Hoff
* @author Fred Ecks
* @since 1.0
*/
public abstract class Toolkit {
// The following method is called by the private method
// updateSystemColors
in SystemColor
.
/**
* Fills in the integer array that is supplied as an argument
* with the current system color values.
*
* @param systemColors an integer array.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.1
*/
protected void loadSystemColors(int[] systemColors)
throws HeadlessException {
GraphicsEnvironment.checkHeadless();
}
/**
* Controls whether the layout of Containers is validated dynamically
* during resizing, or statically, after resizing is complete.
* Use {@code isDynamicLayoutActive()} to detect if this feature enabled
* in this program and is supported by this operating system
* and/or window manager.
* Note that this feature is supported not on all platforms, and
* conversely, that this feature cannot be turned off on some platforms.
* On these platforms where dynamic layout during resizing is not supported
* (or is always supported), setting this property has no effect.
* Note that this feature can be set or unset as a property of the
* operating system or window manager on some platforms. On such
* platforms, the dynamic resize property must be set at the operating
* system or window manager level before this method can take effect.
* This method does not change support or settings of the underlying
* operating system or
* window manager. The OS/WM support can be
* queried using getDesktopProperty("awt.dynamicLayoutSupported") method.
*
* @param dynamic If true, Containers should re-layout their
* components as the Container is being resized. If false,
* the layout will be validated after resizing is completed.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see #isDynamicLayoutSet()
* @see #isDynamicLayoutActive()
* @see #getDesktopProperty(String propertyName)
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.4
*/
public void setDynamicLayout(final boolean dynamic)
throws HeadlessException {
GraphicsEnvironment.checkHeadless();
if (this != getDefaultToolkit()) {
getDefaultToolkit().setDynamicLayout(dynamic);
}
}
/**
* Returns whether the layout of Containers is validated dynamically
* during resizing, or statically, after resizing is complete.
* Note: this method returns the value that was set programmatically;
* it does not reflect support at the level of the operating system
* or window manager for dynamic layout on resizing, or the current
* operating system or window manager settings. The OS/WM support can
* be queried using getDesktopProperty("awt.dynamicLayoutSupported").
*
* @return true if validation of Containers is done dynamically,
* false if validation is done after resizing is finished.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see #setDynamicLayout(boolean dynamic)
* @see #isDynamicLayoutActive()
* @see #getDesktopProperty(String propertyName)
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.4
*/
protected boolean isDynamicLayoutSet()
throws HeadlessException {
GraphicsEnvironment.checkHeadless();
if (this != Toolkit.getDefaultToolkit()) {
return Toolkit.getDefaultToolkit().isDynamicLayoutSet();
} else {
return false;
}
}
/**
* Returns whether dynamic layout of Containers on resize is currently
* enabled on the underlying operating system and/or window manager. If the
* platform supports it, {@code setDynamicLayout(boolean)} may be used to
* programmatically enable or disable platform dynamic layout. Regardless of
* whether that toggling is supported, or whether {@code true} or {@code
* false} is specified as an argument, or has never been called at all, this
* method will return the active current platform behavior and which will be
* followed by the JDK in determining layout policy during resizing.
*
* If dynamic layout is currently inactive then Containers re-layout their * components when resizing is completed. As a result the * {@code Component.validate()} method will be invoked only once per resize. * If dynamic layout is currently active then Containers re-layout their * components on every native resize event and the {@code validate()} method * will be invoked each time. The OS/WM support can be queried using the * getDesktopProperty("awt.dynamicLayoutSupported") method. This property * will reflect the platform capability but is not sufficient to tell if it * is presently enabled. * * @return true if dynamic layout of Containers on resize is currently * active, false otherwise. * @throws HeadlessException if the GraphicsEnvironment.isHeadless() method * returns true * @see #setDynamicLayout(boolean dynamic) * @see #isDynamicLayoutSet() * @see #getDesktopProperty(String propertyName) * @see java.awt.GraphicsEnvironment#isHeadless * @since 1.4 */ public boolean isDynamicLayoutActive() throws HeadlessException { GraphicsEnvironment.checkHeadless(); if (this != Toolkit.getDefaultToolkit()) { return Toolkit.getDefaultToolkit().isDynamicLayoutActive(); } else { return false; } } /** * Gets the size of the screen. On systems with multiple displays, the * primary display is used. Multi-screen aware display dimensions are * available from {@code GraphicsConfiguration} and * {@code GraphicsDevice}. * @return the size of this toolkit's screen, in pixels. * @exception HeadlessException if GraphicsEnvironment.isHeadless() * returns true * @see java.awt.GraphicsConfiguration#getBounds * @see java.awt.GraphicsDevice#getDisplayMode * @see java.awt.GraphicsEnvironment#isHeadless */ public abstract Dimension getScreenSize() throws HeadlessException; /** * Returns the screen resolution in dots-per-inch. * @return this toolkit's screen resolution, in dots-per-inch. * @exception HeadlessException if GraphicsEnvironment.isHeadless() * returns true * @see java.awt.GraphicsEnvironment#isHeadless */ public abstract int getScreenResolution() throws HeadlessException; /** * Gets the insets of the screen. * @param gc a {@code GraphicsConfiguration} * @return the insets of this toolkit's screen, in pixels. * @exception HeadlessException if GraphicsEnvironment.isHeadless() * returns true * @see java.awt.GraphicsEnvironment#isHeadless * @since 1.4 */ public Insets getScreenInsets(GraphicsConfiguration gc) throws HeadlessException { GraphicsEnvironment.checkHeadless(); if (this != Toolkit.getDefaultToolkit()) { return Toolkit.getDefaultToolkit().getScreenInsets(gc); } else { return new Insets(0, 0, 0, 0); } } /** * Determines the color model of this toolkit's screen. *
* {@code ColorModel} is an abstract class that * encapsulates the ability to translate between the * pixel values of an image and its red, green, blue, * and alpha components. *
* This toolkit method is called by the * {@code getColorModel} method * of the {@code Component} class. * @return the color model of this toolkit's screen. * @exception HeadlessException if GraphicsEnvironment.isHeadless() * returns true * @see java.awt.GraphicsEnvironment#isHeadless * @see java.awt.image.ColorModel * @see java.awt.Component#getColorModel */ public abstract ColorModel getColorModel() throws HeadlessException; /** * Returns the names of the available fonts in this toolkit.
* For 1.1, the following font names are deprecated (the replacement * name follows): *
* The ZapfDingbats fontname is also deprecated in 1.1 but the characters * are defined in Unicode starting at 0x2700, and as of 1.1 Java supports * those characters. * @return the names of the available fonts in this toolkit. * @deprecated see {@link java.awt.GraphicsEnvironment#getAvailableFontFamilyNames()} * @see java.awt.GraphicsEnvironment#getAvailableFontFamilyNames() */ @Deprecated public abstract String[] getFontList(); /** * Gets the screen device metrics for rendering of the font. * @param font a font * @return the screen metrics of the specified font in this toolkit * @deprecated As of JDK version 1.2, replaced by the {@code Font} * method {@code getLineMetrics}. * @see java.awt.font.LineMetrics * @see java.awt.Font#getLineMetrics * @see java.awt.GraphicsEnvironment#getScreenDevices */ @Deprecated public abstract FontMetrics getFontMetrics(Font font); /** * Synchronizes this toolkit's graphics state. Some window systems * may do buffering of graphics events. *
* This method ensures that the display is up-to-date. It is useful
* for animation.
*/
public abstract void sync();
/**
* The default toolkit.
*/
private static Toolkit toolkit;
/**
* Used internally by the assistive technologies functions; set at
* init time and used at load time
*/
private static String atNames;
/**
* Initializes properties related to assistive technologies.
* These properties are used both in the loadAssistiveProperties()
* function below, as well as other classes in the jdk that depend
* on the properties (such as the use of the screen_magnifier_present
* property in Java2D hardware acceleration initialization). The
* initialization of the properties must be done before the platform-
* specific Toolkit class is instantiated so that all necessary
* properties are set up properly before any classes dependent upon them
* are initialized.
*/
private static void initAssistiveTechnologies() {
// Get accessibility properties
final String sep = File.separator;
final Properties properties = new Properties();
atNames = java.security.AccessController.doPrivileged(
new java.security.PrivilegedAction
* If a system property named {@code "java.awt.headless"} is set
* to {@code true} then the headless implementation
* of {@code Toolkit} is used,
* otherwise the default platform-specific implementation of
* {@code Toolkit} is used.
*
* If this Toolkit is not a headless implementation and if they exist, service
* providers of {@link javax.accessibility.AccessibilityProvider} will be loaded
* if specified by the system property
* {@code javax.accessibility.assistive_technologies}.
*
* An example of setting this property is to invoke Java with
* {@code -Djavax.accessibility.assistive_technologies=MyServiceProvider}.
* In addition to MyServiceProvider other service providers can be specified
* using a comma separated list. Service providers are loaded after the AWT
* toolkit is created.
* If the list of assistive technology providers is the empty string or
* contains only white space characters then the method returns immediately.
* All other errors are handled via an AWTError exception.
*
* The names specified in the assistive_technologies property are used to query
* each service provider implementation. If the requested name matches the
* {@linkplain AccessibilityProvider#getName name} of the service provider, the
* {@link AccessibilityProvider#activate} method will be invoked to activate the
* matching service provider.
*
* @implSpec
* If assistive technology service providers are not specified with a system
* property this implementation will look in a properties file located as follows:
*
* Since the mechanism required to facilitate this sharing of
* {@code Image} objects may continue to hold onto images
* that are no longer in use for an indefinite period of time,
* developers are encouraged to implement their own caching of
* images by using the {@link #createImage(java.lang.String) createImage}
* variant wherever available.
* If the image data contained in the specified file changes,
* the {@code Image} object returned from this method may
* still contain stale information which was loaded from the
* file after a prior call.
* Previously loaded image data can be manually discarded by
* calling the {@link Image#flush flush} method on the
* returned {@code Image}.
*
* This method first checks if there is a security manager installed.
* If so, the method calls the security manager's
* {@code checkRead} method with the file specified to ensure
* that the access to the image is allowed.
* @param filename the name of a file containing pixel data
* in a recognized file format.
* @return an image which gets its pixel data from
* the specified file.
* @throws SecurityException if a security manager exists and its
* checkRead method doesn't allow the operation.
* @see #createImage(java.lang.String)
*/
public abstract Image getImage(String filename);
/**
* Returns an image which gets pixel data from the specified URL.
* The pixel data referenced by the specified URL must be in one
* of the following formats: GIF, JPEG or PNG.
* The underlying toolkit attempts to resolve multiple requests
* with the same URL to the same returned Image.
*
* Since the mechanism required to facilitate this sharing of
* {@code Image} objects may continue to hold onto images
* that are no longer in use for an indefinite period of time,
* developers are encouraged to implement their own caching of
* images by using the {@link #createImage(java.net.URL) createImage}
* variant wherever available.
* If the image data stored at the specified URL changes,
* the {@code Image} object returned from this method may
* still contain stale information which was fetched from the
* URL after a prior call.
* Previously loaded image data can be manually discarded by
* calling the {@link Image#flush flush} method on the
* returned {@code Image}.
*
* This method first checks if there is a security manager installed.
* If so, the method calls the security manager's
* {@code checkPermission} method with the corresponding
* permission to ensure that the access to the image is allowed.
* If the connection to the specified URL requires
* either {@code URLPermission} or {@code SocketPermission},
* then {@code URLPermission} is used for security checks.
* @param url the URL to use in fetching the pixel data.
* @return an image which gets its pixel data from
* the specified URL.
* @throws SecurityException if a security manager exists and its
* checkPermission method doesn't allow
* the operation.
* @see #createImage(java.net.URL)
*/
public abstract Image getImage(URL url);
/**
* Returns an image which gets pixel data from the specified file.
* The returned Image is a new object which will not be shared
* with any other caller of this method or its getImage variant.
*
* This method first checks if there is a security manager installed.
* If so, the method calls the security manager's
* {@code checkRead} method with the specified file to ensure
* that the image creation is allowed.
* @param filename the name of a file containing pixel data
* in a recognized file format.
* @return an image which gets its pixel data from
* the specified file.
* @throws SecurityException if a security manager exists and its
* checkRead method doesn't allow the operation.
* @see #getImage(java.lang.String)
*/
public abstract Image createImage(String filename);
/**
* Returns an image which gets pixel data from the specified URL.
* The returned Image is a new object which will not be shared
* with any other caller of this method or its getImage variant.
*
* This method first checks if there is a security manager installed.
* If so, the method calls the security manager's
* {@code checkPermission} method with the corresponding
* permission to ensure that the image creation is allowed.
* If the connection to the specified URL requires
* either {@code URLPermission} or {@code SocketPermission},
* then {@code URLPermission} is used for security checks.
* @param url the URL to use in fetching the pixel data.
* @return an image which gets its pixel data from
* the specified URL.
* @throws SecurityException if a security manager exists and its
* checkPermission method doesn't allow
* the operation.
* @see #getImage(java.net.URL)
*/
public abstract Image createImage(URL url);
/**
* Prepares an image for rendering.
*
* If the values of the width and height arguments are both
* {@code -1}, this method prepares the image for rendering
* on the default screen; otherwise, this method prepares an image
* for rendering on the default screen at the specified width and height.
*
* The image data is downloaded asynchronously in another thread,
* and an appropriately scaled screen representation of the image is
* generated.
*
* This method is called by components {@code prepareImage}
* methods.
*
* Information on the flags returned by this method can be found
* with the definition of the {@code ImageObserver} interface.
* @param image the image for which to prepare a
* screen representation.
* @param width the width of the desired screen
* representation, or {@code -1}.
* @param height the height of the desired screen
* representation, or {@code -1}.
* @param observer the {@code ImageObserver}
* object to be notified as the
* image is being prepared.
* @return {@code true} if the image has already been
* fully prepared; {@code false} otherwise.
* @see java.awt.Component#prepareImage(java.awt.Image,
* java.awt.image.ImageObserver)
* @see java.awt.Component#prepareImage(java.awt.Image,
* int, int, java.awt.image.ImageObserver)
* @see java.awt.image.ImageObserver
*/
public abstract boolean prepareImage(Image image, int width, int height,
ImageObserver observer);
/**
* Indicates the construction status of a specified image that is
* being prepared for display.
*
* If the values of the width and height arguments are both
* {@code -1}, this method returns the construction status of
* a screen representation of the specified image in this toolkit.
* Otherwise, this method returns the construction status of a
* scaled representation of the image at the specified width
* and height.
*
* This method does not cause the image to begin loading.
* An application must call {@code prepareImage} to force
* the loading of an image.
*
* This method is called by the component's {@code checkImage}
* methods.
*
* Information on the flags returned by this method can be found
* with the definition of the {@code ImageObserver} interface.
* @param image the image whose status is being checked.
* @param width the width of the scaled version whose status is
* being checked, or {@code -1}.
* @param height the height of the scaled version whose status
* is being checked, or {@code -1}.
* @param observer the {@code ImageObserver} object to be
* notified as the image is being prepared.
* @return the bitwise inclusive OR of the
* {@code ImageObserver} flags for the
* image data that is currently available.
* @see java.awt.Toolkit#prepareImage(java.awt.Image,
* int, int, java.awt.image.ImageObserver)
* @see java.awt.Component#checkImage(java.awt.Image,
* java.awt.image.ImageObserver)
* @see java.awt.Component#checkImage(java.awt.Image,
* int, int, java.awt.image.ImageObserver)
* @see java.awt.image.ImageObserver
*/
public abstract int checkImage(Image image, int width, int height,
ImageObserver observer);
/**
* Creates an image with the specified image producer.
* @param producer the image producer to be used.
* @return an image with the specified image producer.
* @see java.awt.Image
* @see java.awt.image.ImageProducer
* @see java.awt.Component#createImage(java.awt.image.ImageProducer)
*/
public abstract Image createImage(ImageProducer producer);
/**
* Creates an image which decodes the image stored in the specified
* byte array.
*
* The data must be in some image format, such as GIF or JPEG,
* that is supported by this toolkit.
* @param imagedata an array of bytes, representing
* image data in a supported image format.
* @return an image.
* @since 1.1
*/
public Image createImage(byte[] imagedata) {
return createImage(imagedata, 0, imagedata.length);
}
/**
* Creates an image which decodes the image stored in the specified
* byte array, and at the specified offset and length.
* The data must be in some image format, such as GIF or JPEG,
* that is supported by this toolkit.
* @param imagedata an array of bytes, representing
* image data in a supported image format.
* @param imageoffset the offset of the beginning
* of the data in the array.
* @param imagelength the length of the data in the array.
* @return an image.
* @since 1.1
*/
public abstract Image createImage(byte[] imagedata,
int imageoffset,
int imagelength);
/**
* Gets a {@code PrintJob} object which is the result of initiating
* a print operation on the toolkit's platform.
*
* Each actual implementation of this method should first check if there
* is a security manager installed. If there is, the method should call
* the security manager's {@code checkPrintJobAccess} method to
* ensure initiation of a print operation is allowed. If the default
* implementation of {@code checkPrintJobAccess} is used (that is,
* that method is not overriden), then this results in a call to the
* security manager's {@code checkPermission} method with a
* {@code RuntimePermission("queuePrintJob")} permission.
*
* @param frame the parent of the print dialog. May not be null.
* @param jobtitle the title of the PrintJob. A null title is equivalent
* to "".
* @param props a Properties object containing zero or more properties.
* Properties are not standardized and are not consistent across
* implementations. Because of this, PrintJobs which require job
* and page control should use the version of this function which
* takes JobAttributes and PageAttributes objects. This object
* may be updated to reflect the user's job choices on exit. May
* be null.
* @return a {@code PrintJob} object, or {@code null} if the
* user cancelled the print job.
* @throws NullPointerException if frame is null
* @throws SecurityException if this thread is not allowed to initiate a
* print job request
* @see java.awt.GraphicsEnvironment#isHeadless
* @see java.awt.PrintJob
* @see java.lang.RuntimePermission
* @since 1.1
*/
public abstract PrintJob getPrintJob(Frame frame, String jobtitle,
Properties props);
/**
* Gets a {@code PrintJob} object which is the result of initiating
* a print operation on the toolkit's platform.
*
* Each actual implementation of this method should first check if there
* is a security manager installed. If there is, the method should call
* the security manager's {@code checkPrintJobAccess} method to
* ensure initiation of a print operation is allowed. If the default
* implementation of {@code checkPrintJobAccess} is used (that is,
* that method is not overriden), then this results in a call to the
* security manager's {@code checkPermission} method with a
* {@code RuntimePermission("queuePrintJob")} permission.
*
* @param frame the parent of the print dialog. May not be null.
* @param jobtitle the title of the PrintJob. A null title is equivalent
* to "".
* @param jobAttributes a set of job attributes which will control the
* PrintJob. The attributes will be updated to reflect the user's
* choices as outlined in the JobAttributes documentation. May be
* null.
* @param pageAttributes a set of page attributes which will control the
* PrintJob. The attributes will be applied to every page in the
* job. The attributes will be updated to reflect the user's
* choices as outlined in the PageAttributes documentation. May be
* null.
* @return a {@code PrintJob} object, or {@code null} if the
* user cancelled the print job.
* @throws NullPointerException if frame is null
* @throws IllegalArgumentException if pageAttributes specifies differing
* cross feed and feed resolutions. Also if this thread has
* access to the file system and jobAttributes specifies
* print to file, and the specified destination file exists but
* is a directory rather than a regular file, does not exist but
* cannot be created, or cannot be opened for any other reason.
* However in the case of print to file, if a dialog is also
* requested to be displayed then the user will be given an
* opportunity to select a file and proceed with printing.
* The dialog will ensure that the selected output file
* is valid before returning from this method.
* @throws SecurityException if this thread is not allowed to initiate a
* print job request, or if jobAttributes specifies print to file,
* and this thread is not allowed to access the file system
* @see java.awt.PrintJob
* @see java.awt.GraphicsEnvironment#isHeadless
* @see java.lang.RuntimePermission
* @see java.awt.JobAttributes
* @see java.awt.PageAttributes
* @since 1.3
*/
public PrintJob getPrintJob(Frame frame, String jobtitle,
JobAttributes jobAttributes,
PageAttributes pageAttributes) {
// Override to add printing support with new job/page control classes
if (this != Toolkit.getDefaultToolkit()) {
return Toolkit.getDefaultToolkit().getPrintJob(frame, jobtitle,
jobAttributes,
pageAttributes);
} else {
return getPrintJob(frame, jobtitle, null);
}
}
/**
* Emits an audio beep depending on native system settings and hardware
* capabilities.
* @since 1.1
*/
public abstract void beep();
/**
* Gets the singleton instance of the system Clipboard which interfaces
* with clipboard facilities provided by the native platform. This
* clipboard enables data transfer between Java programs and native
* applications which use native clipboard facilities.
*
* In addition to any and all default formats text returned by the system
* Clipboard's {@code getTransferData()} method is available in the
* following flavors:
*
* Each actual implementation of this method should first check if there
* is a security manager installed. If there is, the method should call
* the security manager's {@link SecurityManager#checkPermission
* checkPermission} method to check {@code AWTPermission("accessClipboard")}.
*
* @return the system Clipboard
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @see java.awt.datatransfer.Clipboard
* @see java.awt.datatransfer.StringSelection
* @see java.awt.datatransfer.DataFlavor#stringFlavor
* @see java.awt.datatransfer.DataFlavor#plainTextFlavor
* @see java.io.Reader
* @see java.awt.AWTPermission
* @since 1.1
*/
public abstract Clipboard getSystemClipboard()
throws HeadlessException;
/**
* Gets the singleton instance of the system selection as a
* {@code Clipboard} object. This allows an application to read and
* modify the current, system-wide selection.
*
* An application is responsible for updating the system selection whenever
* the user selects text, using either the mouse or the keyboard.
* Typically, this is implemented by installing a
* {@code FocusListener} on all {@code Component}s which support
* text selection, and, between {@code FOCUS_GAINED} and
* {@code FOCUS_LOST} events delivered to that {@code Component},
* updating the system selection {@code Clipboard} when the selection
* changes inside the {@code Component}. Properly updating the system
* selection ensures that a Java application will interact correctly with
* native applications and other Java applications running simultaneously
* on the system. Note that {@code java.awt.TextComponent} and
* {@code javax.swing.text.JTextComponent} already adhere to this
* policy. When using these classes, and their subclasses, developers need
* not write any additional code.
*
* Some platforms do not support a system selection {@code Clipboard}.
* On those platforms, this method will return {@code null}. In such a
* case, an application is absolved from its responsibility to update the
* system selection {@code Clipboard} as described above.
*
* Each actual implementation of this method should first check if there
* is a security manager installed. If there is, the method should call
* the security manager's {@link SecurityManager#checkPermission
* checkPermission} method to check {@code AWTPermission("accessClipboard")}.
*
* @return the system selection as a {@code Clipboard}, or
* {@code null} if the native platform does not support a
* system selection {@code Clipboard}
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
*
* @see java.awt.datatransfer.Clipboard
* @see java.awt.event.FocusListener
* @see java.awt.event.FocusEvent#FOCUS_GAINED
* @see java.awt.event.FocusEvent#FOCUS_LOST
* @see TextComponent
* @see javax.swing.text.JTextComponent
* @see AWTPermission
* @see GraphicsEnvironment#isHeadless
* @since 1.4
*/
public Clipboard getSystemSelection() throws HeadlessException {
GraphicsEnvironment.checkHeadless();
if (this != Toolkit.getDefaultToolkit()) {
return Toolkit.getDefaultToolkit().getSystemSelection();
} else {
GraphicsEnvironment.checkHeadless();
return null;
}
}
/**
* Determines which modifier key is the appropriate accelerator
* key for menu shortcuts.
*
* Menu shortcuts, which are embodied in the
* {@code MenuShortcut} class, are handled by the
* {@code MenuBar} class.
*
* By default, this method returns {@code Event.CTRL_MASK}.
* Toolkit implementations should override this method if the
* Control key isn't the correct key for accelerators.
* @return the modifier mask on the {@code Event} class
* that is used for menu shortcuts on this toolkit.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @see java.awt.MenuBar
* @see java.awt.MenuShortcut
* @deprecated It is recommended that extended modifier keys and
* {@link #getMenuShortcutKeyMaskEx()} be used instead
* @since 1.1
*/
@Deprecated(since = "10")
public int getMenuShortcutKeyMask() throws HeadlessException {
GraphicsEnvironment.checkHeadless();
return Event.CTRL_MASK;
}
/**
* Determines which extended modifier key is the appropriate accelerator
* key for menu shortcuts.
*
* Menu shortcuts, which are embodied in the {@code MenuShortcut} class, are
* handled by the {@code MenuBar} class.
*
* By default, this method returns {@code InputEvent.CTRL_DOWN_MASK}.
* Toolkit implementations should override this method if the
* Control key isn't the correct key for accelerators.
*
* @return the modifier mask on the {@code InputEvent} class that is used
* for menu shortcuts on this toolkit
* @throws HeadlessException if GraphicsEnvironment.isHeadless() returns
* true
* @see java.awt.GraphicsEnvironment#isHeadless
* @see java.awt.MenuBar
* @see java.awt.MenuShortcut
* @since 10
*/
public int getMenuShortcutKeyMaskEx() throws HeadlessException {
GraphicsEnvironment.checkHeadless();
return InputEvent.CTRL_DOWN_MASK;
}
/**
* Returns whether the given locking key on the keyboard is currently in
* its "on" state.
* Valid key codes are
* {@link java.awt.event.KeyEvent#VK_CAPS_LOCK VK_CAPS_LOCK},
* {@link java.awt.event.KeyEvent#VK_NUM_LOCK VK_NUM_LOCK},
* {@link java.awt.event.KeyEvent#VK_SCROLL_LOCK VK_SCROLL_LOCK}, and
* {@link java.awt.event.KeyEvent#VK_KANA_LOCK VK_KANA_LOCK}.
*
* @param keyCode the key code
* @return {@code true} if the given key is currently in its "on" state;
* otherwise {@code false}
* @exception java.lang.IllegalArgumentException if {@code keyCode}
* is not one of the valid key codes
* @exception java.lang.UnsupportedOperationException if the host system doesn't
* allow getting the state of this key programmatically, or if the keyboard
* doesn't have this key
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.3
*/
public boolean getLockingKeyState(int keyCode)
throws UnsupportedOperationException
{
GraphicsEnvironment.checkHeadless();
if (! (keyCode == KeyEvent.VK_CAPS_LOCK || keyCode == KeyEvent.VK_NUM_LOCK ||
keyCode == KeyEvent.VK_SCROLL_LOCK || keyCode == KeyEvent.VK_KANA_LOCK)) {
throw new IllegalArgumentException("invalid key for Toolkit.getLockingKeyState");
}
throw new UnsupportedOperationException("Toolkit.getLockingKeyState");
}
/**
* Sets the state of the given locking key on the keyboard.
* Valid key codes are
* {@link java.awt.event.KeyEvent#VK_CAPS_LOCK VK_CAPS_LOCK},
* {@link java.awt.event.KeyEvent#VK_NUM_LOCK VK_NUM_LOCK},
* {@link java.awt.event.KeyEvent#VK_SCROLL_LOCK VK_SCROLL_LOCK}, and
* {@link java.awt.event.KeyEvent#VK_KANA_LOCK VK_KANA_LOCK}.
*
* Depending on the platform, setting the state of a locking key may
* involve event processing and therefore may not be immediately
* observable through getLockingKeyState.
*
* @param keyCode the key code
* @param on the state of the key
* @exception java.lang.IllegalArgumentException if {@code keyCode}
* is not one of the valid key codes
* @exception java.lang.UnsupportedOperationException if the host system doesn't
* allow setting the state of this key programmatically, or if the keyboard
* doesn't have this key
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.3
*/
public void setLockingKeyState(int keyCode, boolean on)
throws UnsupportedOperationException
{
GraphicsEnvironment.checkHeadless();
if (! (keyCode == KeyEvent.VK_CAPS_LOCK || keyCode == KeyEvent.VK_NUM_LOCK ||
keyCode == KeyEvent.VK_SCROLL_LOCK || keyCode == KeyEvent.VK_KANA_LOCK)) {
throw new IllegalArgumentException("invalid key for Toolkit.setLockingKeyState");
}
throw new UnsupportedOperationException("Toolkit.setLockingKeyState");
}
/**
* Give native peers the ability to query the native container
* given a native component (eg the direct parent may be lightweight).
*
* @param c the component to fetch the container for
* @return the native container object for the component
*/
protected static Container getNativeContainer(Component c) {
return c.getNativeContainer();
}
/**
* Creates a new custom cursor object.
* If the image to display is invalid, the cursor will be hidden (made
* completely transparent), and the hotspot will be set to (0, 0).
*
* Note that multi-frame images are invalid and may cause this
* method to hang.
*
* @param cursor the image to display when the cursor is activated
* @param hotSpot the X and Y of the large cursor's hot spot; the
* hotSpot values must be less than the Dimension returned by
* {@code getBestCursorSize}
* @param name a localized description of the cursor, for Java Accessibility use
* @exception IndexOutOfBoundsException if the hotSpot values are outside
* the bounds of the cursor
* @return the cursor created
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.2
*/
public Cursor createCustomCursor(Image cursor, Point hotSpot, String name)
throws IndexOutOfBoundsException, HeadlessException
{
// Override to implement custom cursor support.
if (this != Toolkit.getDefaultToolkit()) {
return Toolkit.getDefaultToolkit().
createCustomCursor(cursor, hotSpot, name);
} else {
return new Cursor(Cursor.DEFAULT_CURSOR);
}
}
/**
* Returns the supported cursor dimension which is closest to the desired
* sizes. Systems which only support a single cursor size will return that
* size regardless of the desired sizes. Systems which don't support custom
* cursors will return a dimension of 0, 0.
* Note: if an image is used whose dimensions don't match a supported size
* (as returned by this method), the Toolkit implementation will attempt to
* resize the image to a supported size.
* Since converting low-resolution images is difficult,
* no guarantees are made as to the quality of a cursor image which isn't a
* supported size. It is therefore recommended that this method
* be called and an appropriate image used so no image conversion is made.
*
* @param preferredWidth the preferred cursor width the component would like
* to use.
* @param preferredHeight the preferred cursor height the component would like
* to use.
* @return the closest matching supported cursor size, or a dimension of 0,0 if
* the Toolkit implementation doesn't support custom cursors.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.2
*/
public Dimension getBestCursorSize(int preferredWidth,
int preferredHeight) throws HeadlessException {
GraphicsEnvironment.checkHeadless();
// Override to implement custom cursor support.
if (this != Toolkit.getDefaultToolkit()) {
return Toolkit.getDefaultToolkit().
getBestCursorSize(preferredWidth, preferredHeight);
} else {
return new Dimension(0, 0);
}
}
/**
* Returns the maximum number of colors the Toolkit supports in a custom cursor
* palette.
* Note: if an image is used which has more colors in its palette than
* the supported maximum, the Toolkit implementation will attempt to flatten the
* palette to the maximum. Since converting low-resolution images is difficult,
* no guarantees are made as to the quality of a cursor image which has more
* colors than the system supports. It is therefore recommended that this method
* be called and an appropriate image used so no image conversion is made.
*
* @return the maximum number of colors, or zero if custom cursors are not
* supported by this Toolkit implementation.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless
* @since 1.2
*/
public int getMaximumCursorColors() throws HeadlessException {
GraphicsEnvironment.checkHeadless();
// Override to implement custom cursor support.
if (this != Toolkit.getDefaultToolkit()) {
return Toolkit.getDefaultToolkit().getMaximumCursorColors();
} else {
return 0;
}
}
/**
* Returns whether Toolkit supports this state for
* {@code Frame}s. This method tells whether the UI
* concept of, say, maximization or iconification is
* supported. It will always return false for "compound" states
* like {@code Frame.ICONIFIED|Frame.MAXIMIZED_VERT}.
* In other words, the rule of thumb is that only queries with a
* single frame state constant as an argument are meaningful.
* Note that supporting a given concept is a platform-
* dependent feature. Due to native limitations the Toolkit
* object may report a particular state as supported, however at
* the same time the Toolkit object will be unable to apply the
* state to a given frame. This circumstance has two following
* consequences:
* If there is a security manager then its
* {@link SecurityManager#checkPermission checkPermission} method
* is called to check {@code AWTPermission("accessEventQueue")}.
*
* @return the {@code EventQueue} object
* @throws SecurityException
* if a security manager is set and it denies access to
* the {@code EventQueue}
* @see java.awt.AWTPermission
*/
public final EventQueue getSystemEventQueue() {
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkPermission(AWTPermissions.CHECK_AWT_EVENTQUEUE_PERMISSION);
}
return getSystemEventQueueImpl();
}
/**
* Gets the application's or applet's {@code EventQueue}
* instance, without checking access. For security reasons,
* this can only be called from a {@code Toolkit} subclass.
* @return the {@code EventQueue} object
*/
protected abstract EventQueue getSystemEventQueueImpl();
/* Accessor method for use by AWT package routines. */
static EventQueue getEventQueue() {
return getDefaultToolkit().getSystemEventQueueImpl();
}
/**
* Creates a concrete, platform dependent, subclass of the abstract
* DragGestureRecognizer class requested, and associates it with the
* DragSource, Component and DragGestureListener specified.
*
* subclasses should override this to provide their own implementation
*
* @param
* First, if there is a security manager, its {@code checkPermission}
* method is called with an
* {@code AWTPermission("listenToAllAWTEvents")} permission.
* This may result in a SecurityException.
*
* {@code eventMask} is a bitmask of event types to receive.
* It is constructed by bitwise OR-ing together the event masks
* defined in {@code AWTEvent}.
*
* Note: event listener use is not recommended for normal
* application use, but are intended solely to support special
* purpose facilities including support for accessibility,
* event record/playback, and diagnostic tracing.
*
* If listener is null, no exception is thrown and no action is performed.
*
* @param listener the event listener.
* @param eventMask the bitmask of event types to receive
* @throws SecurityException
* if a security manager exists and its
* {@code checkPermission} method doesn't allow the operation.
* @see #removeAWTEventListener
* @see #getAWTEventListeners
* @see SecurityManager#checkPermission
* @see java.awt.AWTEvent
* @see java.awt.AWTPermission
* @see java.awt.event.AWTEventListener
* @see java.awt.event.AWTEventListenerProxy
* @since 1.2
*/
public void addAWTEventListener(AWTEventListener listener, long eventMask) {
AWTEventListener localL = deProxyAWTEventListener(listener);
if (localL == null) {
return;
}
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkPermission(AWTPermissions.ALL_AWT_EVENTS_PERMISSION);
}
synchronized (this) {
SelectiveAWTEventListener selectiveListener =
listener2SelectiveListener.get(localL);
if (selectiveListener == null) {
// Create a new selectiveListener.
selectiveListener = new SelectiveAWTEventListener(localL,
eventMask);
listener2SelectiveListener.put(localL, selectiveListener);
eventListener = ToolkitEventMulticaster.add(eventListener,
selectiveListener);
}
// OR the eventMask into the selectiveListener's event mask.
selectiveListener.orEventMasks(eventMask);
enabledOnToolkitMask |= eventMask;
long mask = eventMask;
for (int i=0; i
* First, if there is a security manager, its {@code checkPermission}
* method is called with an
* {@code AWTPermission("listenToAllAWTEvents")} permission.
* This may result in a SecurityException.
*
* Note: event listener use is not recommended for normal
* application use, but are intended solely to support special
* purpose facilities including support for accessibility,
* event record/playback, and diagnostic tracing.
*
* If listener is null, no exception is thrown and no action is performed.
*
* @param listener the event listener.
* @throws SecurityException
* if a security manager exists and its
* {@code checkPermission} method doesn't allow the operation.
* @see #addAWTEventListener
* @see #getAWTEventListeners
* @see SecurityManager#checkPermission
* @see java.awt.AWTEvent
* @see java.awt.AWTPermission
* @see java.awt.event.AWTEventListener
* @see java.awt.event.AWTEventListenerProxy
* @since 1.2
*/
public void removeAWTEventListener(AWTEventListener listener) {
AWTEventListener localL = deProxyAWTEventListener(listener);
if (listener == null) {
return;
}
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkPermission(AWTPermissions.ALL_AWT_EVENTS_PERMISSION);
}
synchronized (this) {
SelectiveAWTEventListener selectiveListener =
listener2SelectiveListener.get(localL);
if (selectiveListener != null) {
listener2SelectiveListener.remove(localL);
int[] listenerCalls = selectiveListener.getCalls();
for (int i=0; i
*
* Only the first of these files to be located will be consulted. The requested
* service providers are specified by setting the {@code assistive_technologies=}
* property. A single provider or a comma separated list of providers can be
* specified.
*
* @return the default toolkit.
* @exception AWTError if a toolkit could not be found, or
* if one could not be accessed or instantiated.
* @see java.util.ServiceLoader
* @see javax.accessibility.AccessibilityProvider
*/
public static synchronized Toolkit getDefaultToolkit() {
if (toolkit == null) {
java.security.AccessController.doPrivileged(
new java.security.PrivilegedAction
*
* As with {@code java.awt.datatransfer.StringSelection}, if the
* requested flavor is {@code DataFlavor.plainTextFlavor}, or an
* equivalent flavor, a Reader is returned. Note: The behavior of
* the system Clipboard's {@code getTransferData()} method for
* {@code DataFlavor.plainTextFlavor}, and equivalent DataFlavors, is
* inconsistent with the definition of {@code DataFlavor.plainTextFlavor}.
* Because of this, support for
* {@code DataFlavor.plainTextFlavor}, and equivalent flavors, is
* deprecated.
*
*
*
* @param state one of named frame state constants.
* @return {@code true} is this frame state is supported by
* this Toolkit implementation, {@code false} otherwise.
* @exception HeadlessException
* if {@code GraphicsEnvironment.isHeadless()}
* returns {@code true}.
* @see java.awt.Window#addWindowStateListener
* @since 1.4
*/
public boolean isFrameStateSupported(int state)
throws HeadlessException
{
GraphicsEnvironment.checkHeadless();
if (this != Toolkit.getDefaultToolkit()) {
return Toolkit.getDefaultToolkit().
isFrameStateSupported(state);
} else {
return (state == Frame.NORMAL); // others are not guaranteed
}
}
/**
* Support for I18N: any visible strings should be stored in
* sun.awt.resources.awt.properties. The ResourceBundle is stored
* here, so that only one copy is maintained.
*/
private static ResourceBundle resources;
private static ResourceBundle platformResources;
// called by platform toolkit
private static void setPlatformResources(ResourceBundle bundle) {
platformResources = bundle;
}
/**
* Initialize JNI field and method ids
*/
private static native void initIDs();
/**
* WARNING: This is a temporary workaround for a problem in the
* way the AWT loads native libraries. A number of classes in the
* AWT package have a native method, initIDs(), which initializes
* the JNI field and method ids used in the native portion of
* their implementation.
*
* Since the use and storage of these ids is done by the
* implementation libraries, the implementation of these method is
* provided by the particular AWT implementations (for example,
* "Toolkit"s/Peer), such as Motif, Microsoft Windows, or Tiny. The
* problem is that this means that the native libraries must be
* loaded by the java.* classes, which do not necessarily know the
* names of the libraries to load. A better way of doing this
* would be to provide a separate library which defines java.awt.*
* initIDs, and exports the relevant symbols out to the
* implementation libraries.
*
* For now, we know it's done by the implementation, and we assume
* that the name of the library is "awt". -br.
*
* If you change loadLibraries(), please add the change to
* java.awt.image.ColorModel.loadLibraries(). Unfortunately,
* classes can be loaded in java.awt.image that depend on
* libawt and there is no way to call Toolkit.loadLibraries()
* directly. -hung
*/
private static boolean loaded = false;
static void loadLibraries() {
if (!loaded) {
java.security.AccessController.doPrivileged(
new java.security.PrivilegedAction
* To change the returned value it is necessary to set the {@code sun.awt.enableExtraMouseButtons}
* property before the {@code Toolkit} class initialization. This setting could be done on the application
* startup by the following command:
*
* java -Dsun.awt.enableExtraMouseButtons=false Application
*
* Alternatively, the property could be set in the application by using the following code:
*
* System.setProperty("sun.awt.enableExtraMouseButtons", "true");
*
* before the {@code Toolkit} class initialization.
* If not set by the time of the {@code Toolkit} class initialization, this property will be
* initialized with {@code true}.
* Changing this value after the {@code Toolkit} class initialization will have no effect.
*
* @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true
* @return {@code true} if events from extra mouse buttons are allowed to be processed and posted;
* {@code false} otherwise
* @see System#getProperty(String propertyName)
* @see System#setProperty(String propertyName, String value)
* @see java.awt.EventQueue
* @since 1.7
*/
public boolean areExtraMouseButtonsEnabled() throws HeadlessException {
GraphicsEnvironment.checkHeadless();
return Toolkit.getDefaultToolkit().areExtraMouseButtonsEnabled();
}
}