java.awt Documentation Differences

This file contains all the changes in documentation in the package java.awt as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

A class which implements efficient and thread-safe multi-cast event dispatching for the AWT events defined in the java.awt.event package. This class will manage an immutable structure consisting of a chain of event listeners and will dispatch events to those listeners. Because the structure is immutable it is safe to use this API to add/remove listeners during the process of an event dispatch operation. An example of how this class could be used to implement a new component which fires "action" events:

 public myComponent extends Component { ActionListener actionListener = null; public synchronized void addActionListener(ActionListener l) { actionListener = AWTEventMulticaster.add(actionListener l); } public synchronized void removeActionListener(ActionListener l) { actionListener = AWTEventMulticaster.remove(actionListener l); } public void processEvent(AWTEvent e) { // when event occurs which causes "action" semantic if (actionListener = null) { actionListener.actionPerformed(new ActionEvent()); } } 

@author John Rose @author Amy Fowler @version 1.31 1232 01/0317/0102 @since 1.1

This class is for AWT permissions. An AWTPermission contains a target name but no actions list; you either have the named permission or you don't.

The target name is the name of the AWT permission (see below). The naming convention follows the hierarchical property naming convention. Also an asterisk could be used to represent all AWT permissions.

The following table lists all the possible AWTPermission target names and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

Permission Target Name	What the Permission Allows	Risks of Allowing this Permission
accessClipboard	Posting and retrieval of information to and from the AWT clipboard	This would allow malfeasant code to share potentially sensitive or confidential information.
accessEventQueue	Access to the AWT event queue	After retrieving the AWT event queue malicious code may peek at and even remove existing events from its event queue as well as post bogus events which may purposefully cause the application or applet to misbehave in an insecure manner.
listenToAllAWTEvents	Listen to all AWT events system-wide	After adding an AWT event listener malicious code may scan all AWT events dispatched in the system allowing it to read all user input (such as passwords). Each AWT event listener is called from within the context of that event queue's EventDispatchThread so if the accessEventQueue permission is also enabled malicious code could modify the contents of AWT event queues system-wide causing the application or applet to misbehave in an insecure manner.
showWindowWithoutWarningBanner	Display of a window without also displaying a banner warning that the window was created by an applet	Without this warning an applet may pop up windows without the user knowing that they belong to an applet. Since users may make security-sensitive decisions based on whether or not the window belongs to an applet (entering a username and password into a dialog box for example) disabling this warning banner may allow applets to trick the user into entering such information.
readDisplayPixels	Readback of pixels from the display screen	Interfaces such as the java.awt.Composite interface or the java.awt.Robot class allow arbitrary code to examine pixels on the display enable malicious code to snoop on the activities of the user.
createRobot	Create java.awt.Robot objects	The java.awt.Robot object allows code to generate native-level mouse and keyboard events as well as read the screen. It could allow malicious code to control the system run other programs read the display and deny mouse and keyboard access to the user.
fullScreenExclusive	Enter full-screen exclusive mode	Entering full-screen exclusive mode allows direct access to low-level graphics card memory. This could be used to spoof the system since the program is in direct control of rendering.

@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.21 1222 02/03/01/02 @author Marianne Mueller @author Roland Schemers

Creates a new AWTPermission object with the specified name. The name is the symbolic name of the AWTPermission and the actions string is currently unused and should be null. This constructor exists for use by the Policy object to instantiate new permission objects. @param name the name of the AWTPermission @param actions should be null

An interface for events that know how to dispatch themselves. By implementing this interface an event can be placed upon the event queue and its dispatch() method will be called when the event is dispatched using the EventDispatchThread.

This is a very useful mechanism for avoiding deadlocks. If a thread is executing in a critical section (i.e. it has entered one or more monitors) calling other synchronized code may cause deadlocks. To avoid the potential deadlocks an ActiveEvent can be created to run the second section of code at later time. If there is contention on the monitor the second thread will simply block until the first thread has finished its work and exited its monitors.

For security reasons it is often desirable to use an ActiveEvent to avoid calling untrusted code from a critical thread. For instance peer implementations can use this facility to avoid making calls into user code from a system thread. Doing so avoids potential deadlocks and denial-of-service attacks. @author Timothy Prinzing @version 1.1011 12/03/0112/02 @since 1.2

Dispatch the event to it'sits target listeners of the events source or do whatever it is this event is supposed to do.

Tests ifDetermines whether the specified Objectobject is equal to this AlphaComposite.

The result is true if and only if the argument is not null and is an AlphaComposite object that has the same compositing rule and alpha value as this object. @param obj the Object to test for equality @return true if obj equals this AlphaComposite; false otherwise.

Returns the alpha value of this AlphaComposite. If this AlphaComposite does not have an alpha value 1.0 is returned. @return the alpha value of this AlphaComposite.

Creates an AlphaComposite object with the specified rule and the constant alpha to multiply with the alpha of the source. The source is multiplied with the specified alpha before being composited with the destination. @param rule the compositing rule @param alpha the constant alpha to be multiplied with the alpha of the source. alpha must be a floating point number in the inclusive range [0.0  1.0]. @throws IllegalArgumentException if alpha is less than 0.0 or greater than 1.0 or if rule is not one of the following: #CLEAR #SRC #DST #SRC_OVER #DST_OVER #SRC_IN #DST_IN #SRC_OUT #DST_OUT #SRC_ATOP #DST_ATOP or #XOR

Capabilities and properties of buffers. @see java.awt.image.BufferStrategy#getCapabilities() @see GraphicsConfiguration#getCapabilitiesgetBufferCapabilities @author Michael Martak @since 1.4

@return the resulting contents of the back buffer after page-flipping. This value is null when the isPageFlipping returns false implying blitting. It can be one of FlipContents.UNDEFINED (the assumed default) FlipContents.BACKGROUND FlipContents.PRIOR or FlipContents.COPIED. @see #isPageFlipping @see FlipContents#UNDEFINED @see FlipContents#BACKGROUND @see FlipContents#PRIOR @see FlipContents#COPIED

@return whether or not the buffer strategy uses page flipping; a set of buffers that uses page flipping can swap the contents internally between the front buffer and one or more back buffers by switching the video pointer (or by copying memory internally). A non-flipping set of buffers uses blitting to copy the contents from one buffer to another; when this is the case getFlipContents returns null

The Choice class presents a pop-up menu of choices. The current choice is displayed as the title of the menu.

The following code example produces a pop-up menu:

---

 Choice ColorChooser = new Choice(); ColorChooser.add("Green"); ColorChooser.add("Red"); ColorChooser.add("Blue"); 

---

After this choice menu has been added to a panel it appears as follows in its normal state:

In the picture "Green" is the current choice. Pushing the mouse button down on the object causes a menu to appear with the current choice highlighted.

Some native platforms do not support arbitrary resizing of Choice components and the behavior of setSize()/getSize() is bound by such limitations. Native GUI Choice components' size are often bound by such attributes as font size and length of items contained within the Choice.

@version 1.7879 12/03/0120/02 @author Sami Shaio @author Arthur van Hoff @since JDK1.0

Returns the index of the currently selected item. If nothing is selected returns -1. @return the index of the currently selected item or -1 if nothing is currently selected @see #getSelectedItem

Determines whether another object is equal to this Color.

The result is true if and only if the argument is not null and is a Color object that has the same red green blue and bluealpha values as this object. @param obj the object to test for equality with this Color @return true if the objects are the same; false otherwise. @since JDK1.0

A component is an object having a graphical representation that can be displayed on the screen and that can interact with the user. Examples of components are the buttons checkboxes and scrollbars of a typical graphical user interface.

The Component class is the abstract superclass of the nonmenu-related Abstract Window Toolkit components. Class Component can also be extended directly to create a lightweight component. A lightweight component is a component that is not associated with a native opaque window.

Serialization

It is important to note that only AWT listeners which conform to the Serializable protocol will be saved when the object is stored. If an AWT object has listeners that aren't marked serializable they will be dropped at writeObject time. Developers will need as always to consider the implications of making an object serializable. One situation to watch out for is this:

 import java.awt.*; import java.awt.event.*; import java.io.Serializable; class MyApp implements ActionListener Serializable { BigObjectThatShouldNotBeSerializedWithAButton bigOne; Button aButton = new Button(); MyApp() { // Oops now aButton has a listener with a reference // to bigOne aButton.addActionListener(this); } public void actionPerformed(ActionEvent e) { System.out.println("Hello There"); } } 

In this example serializing aButton by itself will cause MyApp and everything it refers to to be serialized as well. The problem is that the listener is serializable by coincidence not by design. To separate the decisions about MyApp and the ActionListener being serializable one can use a nested class as in the following example:

 import java.awt.*; import java.awt.event.*; import java.io.Serializable; class MyApp java.io.Serializable { BigObjectThatShouldNotBeSerializedWithAButton bigOne; Button aButton = new Button(); class MyActionListener implements ActionListener { public void actionPerformed(ActionEvent e) { System.out.println("Hello There"); } } MyApp() { aButton.addActionListener(new MyActionListener()); } } 

Note: For more information on the paint mechanisms utilitized by AWT and Swing including information on how to write the most efficient painting code see Painting in AWT and Swing. @version 1.330 12347 05/03/0102 @author Arthur van Hoff @author Sami Shaio

Adds the specified mouse motion listener to receive mouse motion events from this component. If listener l is null no exception is thrown and no action is performed. @param l the mouse motion listener @see java.awt.event.MouseMotionEventMouseEvent @see java.awt.event.MouseMotionListener @see #removeMouseMotionListener @see #getMouseMotionListeners @since JDK1.1

Adds a PropertyChangeListener to the listener list for a specific property. The specified property may be user-defined or one of the following:

• this Component's font ("font")
• this Component's background color ("background")
• this Component's foreground color ("foreground")
• this Component's focusability ("focusable")
• this Component's focus traversal keys enabled state ("focusTraversalKeysEnabled")
• this Component's Set of FORWARD_TRAVERSAL_KEYS ("forwardFocusTraversalKeys")
• this Component's Set of BACKWARD_TRAVERSAL_KEYS ("backwardFocusTraversalKeys")
• this Component's Set of UP_CYCLE_TRAVERSAL_KEYS ("upCycleFocusTraversalKeys")

Note that if this Component is inheriting a bound property then no event will be fired in response to a change in the inherited property.

If listener is null no exception is thrown and no action is performed. @param propertyName one of the property names listed above @param listener the PropertyChangeListener to be added @see #removePropertyChangeListener(java.lang.String java.beans.PropertyChangeListener) @see #getPropertyChangeListeners(java.lang.String) @see #addPropertyChangeListener(java.lang.String java.beans.PropertyChangeListener)

Returns an array of all the listeners which have been associated with the named property. @return all of the PropertyChangeListeners associated with the named property or an empty array if no listeners have been added @see #addPropertyChangeListener(java.lang.String java.beans.PropertyChangeListener) @see #removePropertyChangeListener(java.lang.String java.beans.PropertyChangeListener) @see #getPropertyChangeListeners @since 1.4

Repaints the component when the image has changed. This imageUpdate method of an ImageObserver is called when more information about an image which had been previously requested using an asynchronous routine such as the drawImage method of Graphics becomes available. See the definition of imageUpdate for more information on this method and its arguments.

The imageUpdate method of Component incrementally draws an image on the component as more of the bits of the image are available.

If the system property awt.image.incrementalDrawincrementaldraw is missing or has the value true the image is incrementally drawn. If the system property has any other value then the image is not drawn until it has been completely loaded.

Also if incremental drawing is in effect the value of the system property awt.image.redrawrate is interpreted as an integer to give the maximum redraw rate in milliseconds. If the system property is missing or cannot be interpreted as an integer the redraw rate is once every 100ms.

The interpretation of the x y width and height arguments depends on the value of the infoflags argument. @param img the image being observed @param infoflags see imageUpdate for more information @param x the x coordinate @param y the y coordinate @param w the width @param h the height @return false if the infoflags indicate that the image is completely loaded; true otherwise. @see java.awt.image.ImageObserver @see Graphics#drawImage(Image int int Color java.awt.image.ImageObserver) @see Graphics#drawImage(Image int int java.awt.image.ImageObserver) @see Graphics#drawImage(Image int int int int Color java.awt.image.ImageObserver) @see Graphics#drawImage(Image int int int int java.awt.image.ImageObserver) @see java.awt.image.ImageObserver#imageUpdate(java.awt.Image int int int int int) @since JDK1.0

Paints this component.

This method is called when the contents of the component should be painted; in response tosuch as when the component is first being shown or damageis damaged and in need needingof repair. The clip rectangle in the Graphics parameter will beis set to the area which needs to be painted. Subclasses of Component that override this method need not call super.paint(g).

For performance reasons ComponentsComponents with zero width or height aren't considered to need painting when they are first shown and also aren't considered to need repair.

Note: For more information on the paint mechanisms utilitized by AWT and Swing including information on how to write the most efficient painting code see Painting in AWT and Swing. @param g the graphics context to use for painting @see #update @since JDK1.0

Processes mouse motion events occurring on this component by dispatching them to any registered MouseMotionListener objects.

This method is not called unless mouse motion events are enabled for this component. Mouse motion events are enabled when one of the following occurs:

• A MouseMotionListener object is registered via addMouseMotionListener.
• Mouse motion events are enabled via enableEvents.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the mouse motion event @see java.awt.event.MouseMotionEventMouseEvent @see java.awt.event.MouseMotionListener @see #addMouseMotionListener @see #enableEvents @since JDK1.1

Removes the specified mouse motion listener so that it no longer receives mouse motion events from this component. This method performs no function nor does it throw an exception if the listener specified by the argument was not previously added to this component. If listener l is null no exception is thrown and no action is performed. @param l the mouse motion listener @see java.awt.event.MouseMotionEventMouseEvent @see java.awt.event.MouseMotionListener @see #addMouseMotionListener @see #getMouseMotionListeners @since JDK1.1

Removes a PropertyChangeListener from the listener list for a specific property. This method should be used to remove PropertyChangeListeners that were registered for a specific bound property.

If listener is null no exception is thrown and no action is performed. @param propertyName a valid property name @param listener the PropertyChangeListener to be removed @see #addPropertyChangeListener(java.lang.String java.beans.PropertyChangeListener) @see #getPropertyChangeListeners(java.lang.String) @see #removePropertyChangeListener(java.beans.PropertyChangeListener)

Repaints this component.

ThisIf this component is a lightweight component this method causes a call to this component's paint method as soon as possible. Otherwise this method causes a call to this component's update method as soon as possible.

Note: For more information on the paint mechanisms utilitized by AWT and Swing including information on how to write the most efficient painting code see Painting in AWT and Swing. @see #update(Graphics) @since JDK1.0

Repaints the specified rectangle of this component.

ThisIf this component is a lightweight component this method causes a call to this component's paint method as soon as possible. Otherwise this method causes a call to this component's update method as soon as possible.

Note: For more information on the paint mechanisms utilitized by AWT and Swing including information on how to write the most efficient painting code see Painting in AWT and Swing. @param x the x coordinate @param y the y coordinate @param width the width @param height the height @see #update(Graphics) @since JDK1.0

Repaints the component. This willIf this resultcomponent is a lightweight component this results in a call to updatepaint within tm milliseconds.

Note: For more information on the paint mechanisms utilitized by AWT and Swing including information on how to write the most efficient painting code see Painting in AWT and Swing. @param tm maximum time in milliseconds before update @see #paint @see #update(Graphics) @since JDK1.0

Repaints the specified rectangle of this component within tm milliseconds.

ThisIf this component is a lightweight component this method causes a call to this component's paint method. Otherwise this method causes a call to this component's update method.

Note: For more information on the paint mechanisms utilitized by AWT and Swing including information on how to write the most efficient painting code see Painting in AWT and Swing. @param tm maximum time in milliseconds before update @param x the x coordinate @param y the y coordinate @param width the width @param height the height @see #update(Graphics) @since JDK1.0

Sets whether or not paint messages received from the operating system should be ignored. This does not affect paint events generated in software by the AWT unless they are an immediate response to an OS-level paint message.

This is useful for example if running under full-screen mode and better performance is desired or if page-flipping is used as the buffer strategy. @since 1.4 @see #getIgnoreRepaint @see Canvas#createBufferStrategy @see Window#createBufferStrategy @see java.awt.image.BufferStrategy @see GraphicsDevice#setFullScreenWindow

Transfers the focus up one focus traversal cycle. Typically the focus owner is set to this Component's focus cycle root and the current focus cycle root is set to the new focus owner's focus cycle root. If however this Component's focus cycle root is a Window then the focus owner is set to the focus cycle root's default Component to focus and the current focus cycle root is unchanged. @see #requestFocus() @see Container#isFocusCycleRoot() @see Container#setFocusCycleRoot(boolean) @since 1.4

Updates this component.

TheIf this component is not a lightweight component the AWT calls the update method in response to a call to repaint. The appearance of the component on the screen has not changed since the last call to update or paint. You can assume that the background is not cleared.

The updatemethod of Component calls this component's paint method to redraw this component. This method is commonly overridden by subclasses which need to do additional work in response to a call to repaint. Subclasses of Component that override this method should either call super.update(g) or call paint directly.

The origin of the graphics context its (0  0) coordinate point is the top-left corner of this component. The clipping region of the graphics context is the bounding rectangle of this component.

Note: For more information on the paint mechanisms utilitized by AWT and Swing including information on how to write the most efficient painting code see Painting in AWT and Swing. @param g the specified context to use for updating @see #paint @see #repaint() @since JDK1.0

A generic Abstract Window Toolkit(AWT) container object is a component that can contain other AWT components.

Components added to a container are tracked in a list. The order of the list will define the components' front-to-back stacking order within the container. If no index is specified when adding a component to a container it will be added to the end of the list (and hence to the bottom of the stacking order). @version 1.223 03229 04/02/02 @author Arthur van Hoff @author Sami Shaio @see #add(java.awt.Component int) @see #getComponent(int) @see LayoutManager @since JDK1.0

Appends the specified component to the end of this container. This is a convenience method for #addImpl

Note: If a component has been added to a container that has been displayed validate must be called on that container to display the new component. If multiple components are being added you can improve efficiency by calling validate only once after all the components have been added. @param comp the component to be added @see #addImpl @see #validate @see #revalidate @return the component argument

Adds the specified component to the end of this container. Also notifies the layout manager to add the component to this container's layout using the specified constraints object. This is a convenience method for #addImpl

Note: If a component has been added to a container that has been displayed validate must be called on that container to display the new component. If multiple components are being added you can improve efficiency by calling validate only once after all the components have been added. @param comp the component to be added @param constraints an object expressing layout contraints for this component @see #addImpl @see #validate @see #revalidate @see LayoutManager @since JDK1.1

Adds the specified component to this container with the specified constraints at the specified index. Also notifies the layout manager to add the component to the this container's layout using the specified constraints object. This is a convenience method for #addImpl

Note: If a component has been added to a container that has been displayed validate must be called on that container to display the new component. If multiple components are being added you can improve efficiency by calling validate only once after all the components have been added. @param comp the component to be added @param constraints an object expressing layout contraints for this @param index the position in the container's list at which to insert the component.; -1 means insert at the end. component @see #addImpl @see #validate @see #revalidate @see #remove @see LayoutManager

Adds the specified component to this container at the given position. This is a convenience method for #addImpl

Note: If a component has been added to a container that has been displayed validate must be called on that container to display the new component. If multiple components are being added you can improve efficiency by calling validate only once after all the components have been added. @param comp the component to be added @param index the position at which to insert the component or -1 to append the component to the end @return the component comp @see #addImpl @see #remove @see #validate @see #revalidate

Adds the specified component to this container. This is a convenience method for #addImpl

This method is obsolete as of 1.1. Please use the method add(Component Object) instead. @see add(Component Object)

Makes this Container displayable by connecting it to a native screen resource. Making a container displayable will cause anyall of its children to be made displayable. This method is called internally by the toolkit and should not be called directly by programs. @see Component#isDisplayable @see #removeNotify

Makes this Container undisplayable by removing its connection to its native screen resource. MakeMaking a container undisplayable will cause anyall of its children to be made undisplayable. This method is called by the toolkit internally and should not be called directly by programs. @see Component#isDisplayable @see #addNotify

Validates this container and all of its subcomponents.

AWTThe uses validate method is used to cause a container to lay out its subcomponents again. after the components it contains haveIt should be invoked when this beencontainer's subcomponents are modified (added to or modifiedremoved from the container or layout-related information changed) after the container has been displayed. @see #validateadd(java.awt.Component) @see Component#invalidate @see #revalidate

The default KeyboardFocusManager for AWT applications. Focus traversal is done in response to a Component's focus traversal keys and using a Container's FocusTraversalPolicy. @author David Mendenhall @version 1.12 0314 04/0211/02 @see FocusTraversalPolicy @see Component#setFocusTraversalKeys @see Component#getFocusTraversalKeys @since 1.4

A Dialog is a top-level window with a title and a border that is typically used to take some form of input from the user. The size of the dialog includes any area designated for the border. The dimensions of the border area can be obtained using the getInsets method however since these dimensions are platform-dependent a valid insets value cannot be obtained until the dialog is made displayable by either calling pack or show. Since the border area is included in the overall size of the dialog the border effectively obscures a portion of the dialog constraining the area available for rendering and/or displaying subcomponents to the rectangle which has an upper-left corner location of (insets.left insets.top) and has a size of width - (insets.left + insets.right) by height - (insets.top + insets.bottom).

The default layout for a dialog is BorderLayout.

A dialog may have its native decorations (i.e. Frame & Titlebar) turned off with setUndecorated. This can only be done while the dialog is not displayable

A dialog must have either a frame or another dialog defined as its owner when it's constructed. When the owner window of a visible dialog is minimized the dialog will automatically be hidden from the user. When the owner window is subsequently restored the dialog is made visible to the user again.

In a multi-screen environment you can create a Dialog on a different screen device than its owner. See java.awt.Frame for more information.

A dialog can be either modeless (the default) or modal. A modal dialog is one which blocks input to all other toplevel windows in the application except for any windows created with the dialog as their owner.

Dialogs are capable of generating the following WindowEvents: WindowOpened WindowClosing WindowClosed WindowActivated WindowDeactivated WindowGainedFocus WindowLostFocus. @see WindowEvent @see Window#addWindowListener @version 1.83 1284 05/0329/0102 @author Sami Shaio @author Arthur van Hoff @since JDK1.0

EventQueue is a platform-independent class that queues events both from the underlying peer classes and from trusted application classes.

It encapsulates asynchronous event dispatch machinery which extracts events from the queue and dispatches them by calling dispatchEvent(AWTEvent) method on this EventQueue with the event to be dispatched as an argument. The particular behavior of this machinery is implementation-dependent. The only requirements are that events which were actually enqueued to this queue (note that events being posted to the EventQueue can be coalesced) are dispatched:

Sequentially.

That is it is not permitted that several events from this queue are dispatched simultaneously.

In the same order as they are enqueued.

That is if AWTEvent A is enqueued to the EventQueue before AWTEvent B then event B will not be dispatched before event A.

Some browsers partition applets in different code bases into separate contexts and establish walls between these contexts. In such a scenario there will be one EventQueue per context. Other browsers place all applets into the same context implying that there will be only a single global EventQueue for all applets. This behavior is implementation-dependent. Consult your browser's documentation for more information. @author Thomas Ball @author Fred Ecks @author David Mendenhall @version 1.82 1284 04/0317/0102 @since 1.1

Dispatches an event. The manner in which the event is dispatched depends upon the type of the event and the type of the event's source object:

Event Type	Source Type	Dispatched To
ActiveEvent	Any	event.dispatch()
Other	Component	source.dispatchEvent(AWTEvent)
Other	MenuComponent	source.dispatchEvent(AWTEvent)
Other	Other	No action (ignored)

@param theEvent an instance of java.awt.AWTEvent or a subclass of it @throws NullPointerException if event is null

Posts a 1.1-style event to the EventQueue. If there is an existing event on the queue with the same ID and event source the source Component's coalesceEvents method will be called. @param theEvent an instance of java.awt.AWTEvent or a subclass of it @throws NullPointerException if theEvent is null

Replaces the existing EventQueue with the specified one. Any pending events are transferred to the new EventQueue for processing by it. @param newEventQueue an EventQueue (or subclass thereof) instance to be use @see java.awt.EventQueue#pop @throws NullPointerException if newEventQueue is null

A flow layout arranges components in a left-to-right flow much like lines of text in a paragraph. Flow layouts are typically used to arrange buttons in a panel. It will arrange buttons left to right until no more buttons fit on the same line. Each line is centered.

For example the following picture shows an applet using the flow layout manager (its default layout manager) to position three buttons:

Here is the code for this applet:

---

 import java.awt.*; import java.applet.Applet; public class myButtons extends Applet { Button button1 button2 button3; public void init() { button1 = new Button("Ok"); button2 = new Button("Open"); button3 = new Button("Close"); add(button1); add(button2); add(button3); } } 

---

A flow layout lets each component assume its natural (preferred) size. @version 1.43 1244 04/0317/0102 @author Arthur van Hoff @author Sami Shaio @since JDK1.0

Lays out the container. This method lets each component take its preferred size by reshaping the components in the target container in order to satisfy the constraintsalignment of this FlowLayout object. @param target the specified component being laid out @see Container @see java.awt.Container#doLayout

The Font class represents fonts which are used to render text in a visible way. A font provides the information needed to map sequences of characters to sequences of glyphs and to render sequences of glyphs on Graphics and Component objects.

Characters and Glyphs

A character is a symbol that represents an item such as a letter a digit or punctuation in an abstract way. For example 'g' LATIN SMALL LETTER G is a character.

A glyph is a shape used to render a character or a sequence of characters. In simple writing systems such as Latin typically one glyph represents one character. In general however characters and glyphs do not have one-to-one correspondence. For example the character 'á' LATIN SMALL LETTER A WITH ACUTE can be represented by two glyphs: one for 'a' and one for '´'. On the other hand the two-character string "fi" can be represented by a single glyph an "fi" ligature. In complex writing systems such as Arabic or the South and South-East Asian writing systems the relationship between characters and glyphs can be more complicated and involve context-dependent selection of glyphs as well as glyph reordering. A font encapsulates the collection of glyphs needed to render a selected set of characters as well as the tables needed to map sequences of characters to corresponding sequences of glyphs.

Physical and Logical Fonts

The Java 2 platform distinguishes between two kinds of fonts: physical fonts and logical fonts.

Physical fonts are the actual font libraries containing glyph data and tables to map from character sequences to glyph sequences using a font technology such as TrueType or PostScript Type 1. All implementations of the Java 2 platform must support TrueType fonts; support for other font technologies is implementation dependent. Physical fonts may use names such as Helvetica Palatino HonMincho or any number of other font names. Typically each physical font supports only a limited set of writing systems for example only Latin characters or only Japanese and Basic Latin. The set of available physical fonts varies between configurations. Applications that require specific fonts can bundle them and instantiate them using the createFont method.

Logical fonts are the five font families defined by the Java platform which must be supported by any Java runtime environment: Serif SansSerif Monospaced Dialog and DialogInput. These logical fonts are not actual font libraries. Instead the logical font names are mapped to physical fonts by the Java runtime environment. The mapping is implementation and usually locale dependent so the look and the metrics provided by them vary. Typically each logical font name maps to several physical fonts in order to cover a large range of characters.

Peered AWT components such as Label and TextField can only use logical fonts.

For a discussion of the relative advantages and disadvantages of using physical or logical fonts see the Internationalization FAQ document.

Font Faces and Names

A Font can have many faces such as heavy medium oblique gothic and regular. All of these faces have similar typographic design.

There are three different names that you can get from a Font object. The logical font name is simply the name that was used to construct the font. The font face name or just font name for short is the name of a particular font face like Helvetica Bold. The family name is the name of the font family that determines the typographic design across several faces like Helvetica.

The Font class represents an instance of a font face from a collection of font faces that are present in the system resources of the host system. As examples Arial Bold and Courier Bold Italic are font faces. There can be several Font objects associated with a font face each differing in size style transform and font features. The getAllFonts method of the GraphicsEnvironment class returns an array of all font faces available in the system. These font faces are returned as Font objects with a size of 1 identity transform and default font features. These base fonts can then be used to derive new Font objects with varying sizes styles transforms and font features via the deriveFont methods in this class. @version 1.171 12177 04/0327/0102

Compares this Font object to the specified Object. @param obj the Object to compare. @return true if the objects are the same or if the argument is a Font object describing the same font as this object; false otherwise. @since JDK1.0

A Frame is a top-level window with a title and a border.

The size of the frame includes any area designated for the border. The dimensions of the border area may be obtained using the getInsets method however since these dimensions are platform-dependent a valid insets value cannot be obtained until the frame is made displayable by either calling pack or show. Since the border area is included in the overall size of the frame the border effectively obscures a portion of the frame constraining the area available for rendering and/or displaying subcomponents to the rectangle which has an upper-left corner location of (insets.left insets.top) and has a size of width - (insets.left + insets.right) by height - (insets.top + insets.bottom).

The default layout for a frame is BorderLayout.

A frame may have its native decorations (i.e. Frame and Titlebar) turned off with setUndecorated. This can only be done while the frame is not displayable

In a multi-screen environment you can create a Frame on a different screen device by constructing the Frame with #Frame(GraphicsConfiguration) or titl GraphicsConfiguration)}. The GraphicsConfiguration object is one of the GraphicsConfiguration objects of the target screen device.

In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices the bounds of all configurations are relative to the virtual-coordinate system. The origin of the virtual-coordinate system is at the upper left-hand corner of the primary physical screen. Depending on the location of the primary screen in the virtual device negative coordinates are possible as shown in the following figure.

In such an environment when calling setLocation you must pass a virtual coordinate to this method. Similarly calling getLocationOnScreen on a Frame returns virtual device coordinates. Call the getBounds method of a GraphicsConfiguration to find its origin in the virtual coordinate system.

The following code sets the location of the Frame at (10 10) relative to the origin of the physical screen of the corresponding GraphicsConfiguration. If the bounds of the GraphicsConfiguration is not taken into account the Frame location would be set at (10 10) relative to the virtual-coordinate system and would appear on the primary physical screen which might be different from the physical screen of the specified GraphicsConfiguration.

 Frame f = new Frame(GraphicsConfiguration gc); Rectangle bounds = gc.getBounds(); f.setLocation(10 + bounds.x 10 + bounds.y); 

Frames are capable of generating the following types of WindowEvents:

• WINDOW_OPENED
• WINDOW_CLOSING
• WINDOW_CLOSED
• WINDOW_ICONIFIED
• WINDOW_DEICONIFIED
• WINDOW_ACTIVATED
• WINDOW_DEACTIVATED
• WINDOW_GAINED_FOCUS
• WINDOW_LOST_FOCUS
• WINDOW_STATE_CHANGED

@version 1.131 12134 04/0311/0102 @author Sami Shaio @see WindowEvent @see Window#addWindowListener @since JDK1.0

Gets the image to be displayed in the minimized icon for this frame. @return the icon image for this frame or null if this frame doesn't have an icon image. @see #setIconImage(IconImage)

Gets maximized bounds for this frame. @return maximized bounds for this frame. May be null. Some fields may becontain Integer.MAX_VALUE to indicate that system supplied values for this field must be used. @return maximized bounds for this frame; may be null @see #setMaximizedBounds(Rectangle) @since 1.4

SetSets the maximized bounds for this frame.

When a frame is in maximized state the system supplies some defaultdefaults bounds for the maximized state. Using thisThis method allows some or all of those system supplied values mayto be overridenoverridden.

If bounds is null accept bounds supplied by the system. If it's not non-null you can override some of the system supplied values while accepting others by setting those fields you want to accept from system to Integer.MAX_VALUE.

On some systems only the size portion of the bounds is taken into account. @param bounds bounds for the maximized state. @see getMaximizedBounds @since 1.4

Disables or enables decorations for this frame. This method can only be called while the frame is not displayable. @param undecorated true if no frame decorations are to be enabled; false if frame decorations are to be enabled. @throws IllegalComponentStateException if the frame is displayable. @see #isUndecorated @see Component#isDisplayable @see javax.swing.JFrame#setDefaultLookAndFeelDecorated(boolean) @since 1.4

The GraphicsConfiguration class describes the characteristics of a graphics destination such as a printer or monitor. There can be many GraphicsConfiguration objects associated with a single graphics device representing different drawing modes or capabilities. The corresponding native structure will vary from platform to platform. For example on X11 windowing systems each visual is a different GraphicsConfiguration. On win32Microsoft Windows GraphicsConfigurations represent PixelFormats available in the current resolution and color depth.

In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices the bounds of the GraphicsConfiguration objects are relative to the virtual coordinate system. When setting the location of a component use getBounds to get the bounds of the desired GraphicsConfiguration and offset the location with the coordinates of the GraphicsConfiguration as the following code sample illustrates:

 Frame f = new Frame(GraphicsConfiguration gc); // where gc is a GraphicsConfiguration Rectangle bounds = gc.getBounds(); f.setLocation(10 + bounds.x 10 + bounds.y); 

To determine if your environment is a virtual device environment call getBounds on all of the GraphicsConfiguration objects in your system. If any of the origins of the returned bounds areis not (0  0) your environment is a virtual device environment.

You can also use getBounds to determine the bounds of the virtual device. CallTo do this first call getBounds on all of the GraphicsConfiguration objects in your system. Then calculate the union of all of the bounds returned from the calls to getBounds. The union is the bounds of the virtual device. The following code sample calculates the bounds of the virtual device.

 Rectangle virtualBounds = new Rectangle(); GraphicsEnvironment ge = GraphicsEnvironment. getLocalGraphicsEnvironment(); GraphicsDevice[] gs = ge.getScreenDevices(); for (int j = 0; j  @see Window @see Frame @see GraphicsEnvironment @see GraphicsDevice

The GraphicsDevice class describes the graphics devices that might be available in a particular graphics environment. These include screen and printer devices. Note that there can be many screens and many printers in an instance of GraphicsEnvironment Each graphics device has one or more GraphicsConfiguration objects associated with it. These objects specify the different configurations in which the GraphicsDevice can be used.

In a multi-screen environment the GraphicsConfiguration objects can be used to render components on multiple screens. The following code sample demonstrates how to create a JFrame object for each GraphicsConfiguration on each screen device in the GraphicsEnvironment:

 GraphicsEnvironment ge = GraphicsEnvironment. getLocalGraphicsEnvironment(); GraphicsDevice[] gs = ge.getScreenDevices(); for (int j = 0; j  @see GraphicsEnvironment @see GraphicsConfiguration @version 1.25 1226 08/0316/0102

The GraphicsEnvironment class describes the collection of GraphicsDevice objects and java.awt.Font objects available to a Java(tm) application on a particular platform. The resources in this GraphicsEnvironment might be local or on a remote machine. GraphicsDevice objects can be screens printers or image buffers and are the destination of Graphics2D drawing methods. Each GraphicsDevice has a number of GraphicsConfiguration objects associated with it. These objects specify the different configurations in which the GraphicsDevice can be used. @see GraphicsDevice @see GraphicsConfiguration @version 1.51 1253 04/0327/0102

Returns a Graphics2D object for rendering into the specified BufferedImage @param img the specified BufferedImage @return a Graphics2D to be used for rendering into the specified BufferedImage.

Returns an array containing a one-point size instance of all fonts available in this GraphicsEnvironment. Typical usage would be to allow a user to select a particular font. Then the application can size the font and set various font attributes by calling the deriveFont method on the choosen instance.

This method provides for the application the most precise control over which Font instance is used to render text. If a font in this GraphicsEnvironment has multiple programmable variations only one instance of that Font is returned in the array and other variations must be derived by the application.

If a font in this environment has multiple programmable variations such as Multiple-Master fonts only one instance of that font is returned in the Font array. The other variations must be derived by the application. @return an array of Font objects. @see #getAvailableFontFamilyNames @see java.awt.Font @see java.awt.Font#deriveFont @see java.awt.Font#getFontName @since 1.2

Returns the Point where Windows should be centered. It is recommended that centered Windows be checked to ensure they fit within the available display area using getMaximumWindowBounds(). @return the point where Windows should be centered. @exception HeadlessException if isHeadless() returns true @see #getMaximumWindowBounds @since 1.4

Returns the default screen GraphicsDevice. @return the GraphicsDevice that represents the default screen device. @exception HeadlessException if isHeadless() returns true @see isHeadless

Returns the local GraphicsEnvironment. @return thisthe local GraphicsEnvironment.

Returns the maximum bounds for centered Windows. These bounds account for objects in the native windowing system such as task bars and menu bars. The returned bounds will reside on a single display with one exception: on multi-screen systems where Windows should be centered across all displays this method returns the bounds of the entire display area.

To get the usable bounds of a single display use GraphicsConfiguration.getBounds() and Toolkit.getScreenInsets(). @return the maximum bounds for centered Windows. @exception HeadlessException if isHeadless() returns true @see #getCenterPoint @see GraphicsConfiguration#getBounds @see Toolkit#getScreenInsets @since 1.4

Returns an array of all of the screen GraphicsDevice objects. @return an array containing all the GraphicsDevice objects that represent screen devices. @exception HeadlessException if isHeadless() returns true @see isHeadless

Tests whether or not a display keyboard and mouse can be supported in this environment. If this method returns true a HeadlessException is thrown from areas of the Toolkit and GraphicsEnvironment that are dependent on a display keyboard or mouse. @return true if this environment cannot support a display keyboard and mouse; false otherwise. @see java.awt.HeadlessException @since 1.4

Returns whether or not a display keyboard and mouse can be supported in this graphics environment. If this returns true HeadlessException will be thrown from areas of the graphics environment that are dependent on a display keyboard or mouse. @return true if a display keyboard and mouse can be supported in this environment; false otherwise. @see java.awt.HeadlessException @see #isHeadless @since 1.4

This method is obsolete and supplied for backwards compatability only; new code should call adjustForGravity() instead. @see adjustForGravity

This method is obsolete and supplied for backwards compatability only; new code should call arrangeGrid() instead. @see arrangeGrid

This method is obsolete and supplied for backwards compatability only; new code should call getLayoutInfo() instead. @see getLayoutInfo

This method is obsolete and supplied for backwards compatability only; new code should call getMinSize() instead. @see getMinSize

Adjusts the x y width and height fields to the correct values depending on the constraint geometry and pads. @param constraints the constraints to be applied @param r the Rectangle to be adjusted @since 1.4

LayLays out the grid. @param parent the layout container @since 1.4

Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin 1 is aligned the furthest away from the origin 0.5 is centered etc.

@return the value 0.5f to indicate centered

Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin 1 is aligned the furthest away from the origin 0.5 is centered etc.

@return the value 0.5f to indicate centered

FillFills in an instance of the above structureGridBagLayoutInfo for the current set of managed children. This requires three passes through the set of children: 1)

1. Figure out the dimensions of the layout grid 2).
2. Determine which cells the components occupy 3).
3. Distribute the weights and min sizes amoung the rows/columns.

This also caches the minsizes for all the children when they are first encountered (so subsequent loops don't need to ask again). @param parent the layout container @param sizeflag either PREFERREDSIZE or MINSIZE @return the GridBagLayoutInfo for the set of children @since 1.4

FigureFigures out the minimum size of the master based on the information from getLayoutInfo(). @param parent the layout container @param info the layout info for this parent @return a Dimension object containing the minimum size @since 1.4

Lays out the specified container using this grid bag layout. This method reshapes components in the specified container in order to satisfy the contraints of this GridBagLayout object.

Most applications do not call this method directly. @param parent the container in which to do the layout. @see java.awt.Container @see java.awt.Container#doLayout

Retrieves the constraints for the specified component. The return value is not a copy but is the actual GridBagConstraints object used by the layout mechanism. @param comp the component to be queried @return the contraints for the specified componen.component

Returns the maximum dimensions for this layout given the components in the specified target container. @param target the componentcontainer which needs to be laid out @see Container @see #minimumLayoutSize(Container) @see #preferredLayoutSize(Container) @return the maximum dimensions for this layout

Determines the minimum size of the targetparent container using this grid bag layout.

Most applications do not call this method directly. @param targetparent the container in which to do the layout. @see java.awt.Container#doLayout @return the minimum size of the parent container

Determines the preferred size of the targetparent container using this grid bag layout.

Most applications do not call this method directly. @param targetparent the container in which to do the layout. @see java.awt.Container#getPreferredSize @return the preferred size of the parent container

This hashtable maintains the association between a component and its gridbag constraints. The Keys in comptable are the components and the values are the instances of GridBagConstraints. @serial @see java.awt.GridBagConstraints

The GridLayout class is a layout manager that lays out a container's components in a rectangular grid. The container is divided into equal-sized rectangles and one component is placed in each rectangle. For example the following is an applet that lays out six buttons into three rows and two columns:

---

 import java.awt.*; import java.applet.Applet; public class ButtonGrid extends Applet { public void init() { setLayout(new GridLayout(3 2)); add(new Button("1")); add(new Button("2")); add(new Button("3")); add(new Button("4")); add(new Button("5")); add(new Button("6")); } } 

---

If the container's ComponentOrientation property is horizontal and left-to-right the above example produces the output shown in Figure 1. If the container's ComponentOrientation property is horizontal and right-to-left the example produces the output shown in Figure 2.

Figure 1: Horizontal Left-to-Right	Figure 2: Horizontal Right-to-Left

When both the number of rows and the number of columns have been set to non-zero values either by a constructor or by the setRows and setColumns methods the number of columns specified is ignored. Instead the number of columns is determined from the specified number or rows and the total number of components in the layout. So for example if three rows and two columns have been specified and nine components are added to the layout they will be displayed as three rows of three columns. Specifying the number of columns affects the layout only when the number of rows is set to zero. @version 1.3132 12/03/0111/02 @author Arthur van Hoff @since JDK1.0

Determines the minimum size of the container argument using this grid layout.

The minimum width of a grid layout is the largest minimum width of any of the widthscomponents in the container times the number of columns plus the horizontal padding times the number of columns plus one plus the left and right insets of the target container.

The minimum height of a grid layout is the largest minimum height of any of the heightscomponents in the container times the number of rows plus the vertical padding times the number of rows plus one plus the top and bottom insets of the target container. @param target the container in which to do the layout @return the minimum dimensions needed to lay out the subcomponents of the specified container @see java.awt.GridLayout#preferredLayoutSize @see java.awt.Container#doLayout

Determines the preferred size of the container argument using this grid layout.

The preferred width of a grid layout is the largest preferred width of any of the widthscomponents in the container times the number of columns plus the horizontal padding times the number of columns plus one plus the left and right insets of the target container.

The preferred height of a grid layout is the largest preferred height of any of the heightscomponents in the container times the number of rows plus the vertical padding times the number of rows plus one plus the top and bottom insets of the target container. @param target the container in which to do the layout @return the preferred dimensions to lay out the subcomponents of the specified container @see java.awt.GridLayout#minimumLayoutSize @see java.awt.Container#getPreferredSize()

A set of attributes which control a print job.

Instances of this class control the number of copies default selection destination print dialog file and printer names page ranges multiple document handling (including collation) and multi-page imposition (such as duplex) of every print job which uses the instance. Attribute names are compliant with the Internet Printing Protocol (IPP) 1.1 where possible. Attribute values are partially compliant where possible.

To use a method which takes an inner class type pass a reference to one of the constant fields of the inner class. Client code cannot create new instances of the inner class types because none of those classes has a public constructor. For example to set the print dialog type to the cross-platform pure Java print dialog use the following code:

 import java.awt.JobAttributes; public class PureJavaPrintDialogExample { public void setPureJavaPrintDialog(JobAttributes jobAttributes) { jobAttributes.setDialog(JobAttributes.DialogType.COMMON); } } 

Every IPP attribute which supports an attributeName-default value has a corresponding setattributeNameToDefault method. Default value fields are not provided. @version 1.67 12/03/0119/02 @author David Mendenhall

A type-safe enumeration of possible multiple documentcopy handling states. TheseIt states are in partial compliance with IPPis used to control how the sheets 1.1of multiple copies of a single document are collated.

The MultipleDocumentHandlingType instance to use for specifying that the job should be divided into separate collated documentscopies.

The MultipleDocumentHandlingType instance to use for specifying that the job should be divided into separate uncollated documentscopies.

Specifies the handling of multiple documentscopies including collation for jobs using these attributes. This attribute is updated to the value chosen by the user. @return MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_COLLATED_COPIES or MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES.

Specifies the handling of multiple documentscopies including collation for jobs using these attributes. Not specifying this attribute is equivalent to specifying MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES. @param multipleDocumentHandling MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_COLLATED_COPIES or MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES. @throws IllegalArgumentException if multipleDocumentHandling is null.

Sets the handling of multiple documentscopies including collation for jobs using these attributes to the default. The default handling is MultipleDocumentHandlingType.SEPARATE_DOCUMENTS_UNCOLLATED_COPIES.

The KeyboardFocusManager is responsible for managing the active and focused Windows and the current focus owner. The focus owner is defined as the Component in an application that will typically receive all KeyEvents generated by the user. The focused Window is the Window that is or contains the focus owner. Only a Frame or a Dialog can be the active Window. The native windowing system may denote the active Window or its children with special decorations such as a highlighted title bar. The active Window is always either the focused Window or the first Frame or Dialog that is an owner of the focused Window.

The KeyboardFocusManager is both a centralized location for client code to query for the focus owner and initiate focus changes and an event dispatcher for all FocusEvents WindowEvents related to focus and KeyEvents.

Some browsers partition applets in different code bases into separate contexts and establish walls between these contexts. In such a scenario there will be one KeyboardFocusManager per context. Other browsers place all applets into the same context implying that there will be only a single global KeyboardFocusManager for all applets. This behavior is implementation-dependent. Consult your browser's documentation for more information. No matter how many contexts there may be however there can never be more than one focus owner focused Window or active Window per ClassLoader. @author David Mendenhall @version 1.2529 03/0221/02 @see Window @see Frame @see Dialog @see java.awt.event.FocusEvent @see java.awt.event.WindowEvent @see java.awt.event.KeyEvent @since 1.4

Adds a PropertyChangeListener to the listener list for a specific property. The specified property may be user-defined or one of the following:

• the focus owner ("focusOwner")
• the permanent focus owner ("permanentFocusOwner")
• the focused Window ("focusedWindow")
• the active Window ("activeWindow")
• the default focus traversal policy ("defaultFocusTraversalPolicy")
• the Set of default FORWARD_TRAVERSAL_KEYS ("forwardDefaultFocusTraversalKeys")
• the Set of default BACKWARD_TRAVERSAL_KEYS ("backwardDefaultFocusTraversalKeys")
• the Set of default UP_CYCLE_TRAVERSAL_KEYS ("upCycleDefaultFocusTraversalKeys")
• the Set of default DOWN_CYCLE_TRAVERSAL_KEYS ("downCycleDefaultFocusTraversalKeys")
• the current focus cycle root ("currentFocusCycleRoot")

If listener is null no exception is thrown and no action is performed. @param propertyName one of the property names listed above @param listener the PropertyChangeListener to be added @see #addPropertyChangeListener(java.beans.PropertyChangeListener) @see #removePropertyChangeListener(java.lang.String java.beans.PropertyChangeListener) @see #getPropertyChangeListeners(java.lang.String)

Returns an array of all the PropertyChangeListeners associated with the named property. @return all of the PropertyChangeListeners associated with the named property or an empty array if no such listeners have been added. @see #addPropertyChangeListener(java.lang.String java.beans.PropertyChangeListener) @see #removePropertyChangeListener(java.lang.String java.beans.PropertyChangeListener) @since 1.4

Returns an array of all the VetoableChangeListeners associated with the named property. @return all of the VetoableChangeListeners associated with the named property or an empty array if no such listeners have been added. @see #addVetoableChangeListener(java.lang.String java.beans.VetoableChangeListener) @see #removeVetoableChangeListener(java.lang.String java.beans.VetoableChangeListener) @see #getVetoableChangeListeners @since 1.4

Removes a PropertyChangeListener from the listener list for a specific property. This method should be used to remove PropertyChangeListeners that were registered for a specific bound property.

If listener is null no exception is thrown and no action is performed. @param propertyName a valid property name @param listener the PropertyChangeListener to be removed @see #addPropertyChangeListener(java.lang.String java.beans.PropertyChangeListener) @see #getPropertyChangeListeners(java.lang.String) @see #removePropertyChangeListener(java.beans.PropertyChangeListener)

The List component presents the user with a scrolling list of text items. The list can be set up so that the user can choose either one item or multiple items.

For example the code . . .

---

 List lst = new List(4 false); lst.add("Mercury"); lst.add("Venus"); lst.add("Earth"); lst.add("JavaSoft"); lst.add("Mars"); lst.add("Jupiter"); lst.add("Saturn"); lst.add("Uranus"); lst.add("Neptune"); lst.add("Pluto"); cnt.add(lst); 

---

where cnt is a container produces the following scrolling list:

Clicking on an item that isn't selected selects it. Clicking on an item that is already selected deselects it. In the preceding example only one item from the scrolling list can be selected at a time since the second argument when creating the new scrolling list is false. Selecting an item causes any other selected item to be automatically deselected.

Note that the list in the example shown was created with four visible rows. Once the list has been created the number of visible rows cannot be changed. A default List is created with four rows so that lst = new List() is equivalent to list = new List(4 false).

Beginning with Java 1.1 the Abstract Window Toolkit sends the List object all mouse keyboard and focus events that occur over it. (The old AWT event model is being maintained only for backwards compatibility and its use is discouraged.)

When an item is selected or deselected by the user AWT sends an instance of ItemEvent to the list. When the user double-clicks on an item in a scrolling list AWT sends an instance of ActionEvent to the list following the item event. AWT also generates an action event when the user presses the return key while an item in the list is selected.

If an application wants to perform some action based on an item in this list being selected or activated by the user it should implement ItemListener or ActionListener as appropriate and register the new listener to receive events from this list.

For multiple-selection scrolling lists it is considered a better user interface to use an external gesture (such as clicking on a button) to trigger the action. @version 1.9192 12/03/0127/02 @author Sami Shaio @see java.awt.event.ItemEvent @see java.awt.event.ItemListener @see java.awt.event.ActionEvent @see java.awt.event.ActionListener @since JDK1.0

A Menu object is a pull-down menu component that is deployed from a menu bar.

A menu can optionally be a tear-off menu. A tear-off menu can be opened and dragged away from its parent menu bar or menu. It remains on the screen after the mouse button has been released. The mechanism for tearing off a menu is platform dependent since the look and feel of the tear-off menu is determined by its peer. On platforms that do not support tear-off menus the tear-off property is ignored.

Each item in a menu must belong to the MenuItem class. It can be an instance of MenuItem a submenu (an instance of Menu) or a check box (an instance of CheckboxMenuItem). @version 1.68 1269 02/0304/0102 @author Sami Shaio @see java.awt.MenuItem @see java.awt.CheckboxMenuItem @since JDK1.0

The abstract class MenuComponent is the superclass of all menu-related components. In this respect the class MenuComponent is analogous to the abstract superclass Component for AWT components.

Menu components receive and process AWT events just as components do through the method processEvent. @version 1.6567 12/03/0121/02 @author Arthur van Hoff @since JDK1.0

Inner class of MenuComponent used to provide default support for accessibility. This class is not meant to be used directly by application developers but is instead meant only to be subclassed by menu component developers.

The class used to obtain the accessible role for this object.

A point representing a location in (x y) coordinate space specified in integer precision. @version 1.3435 12/03/0120/02 @author Sami Shaio @since JDK1.0

Sets the location of this point to the specified floatdouble coordinates. The floatdouble values will be rounded to integer values. Any number smaller than Integer.MIN_VALUE will be reset to MIN_VALUE and any number larger than Integer.MAX_VALUE will be reset to MAX_VALUE. @param x the x coordinate of the new location @param y the y coordinate of the new location @see #getLocation

Tests if the interior of this Polygon entirely contains the specified Rectangle2D. @param r the specified Rectangle2D @return true if this Polygon entirely contains the specified Rectangle2D; false otherwise. @see #contains(double double double double)

This class is used to generate native system input events for the purposes of test automation self-running demos and other applications where control of the mouse and keyboard is needed. The primary purpose of Robot is to facilitate automated testing of Java platform implementations.

Using the class to generate input events differs from posting events to the AWT event queue or AWT components in that the events are generated in the platform's native input queue. For example Robot.mouseMove will actually move the mouse cursor instead of just generating mouse move events.

Note that some platforms require special privileges or extensions to access low-level input control. If the current platform configuration does not allow input control an AWTException will be thrown when trying to construct Robot objects. For example X-Window systems will throw the exception if the XTEST 2.2 standard extension is not supported (or not enabled) by the X server.

Applications that use Robot for purposes other than self-testing should handle these error conditions gracefully. @version 1.2021 12/03/0115/02 @author Robi Khan @since 1.3

Sleeps for the specified time. To catch any InterruptedExceptions that occur Thread.sleep() may be used instead. @param ms time to sleep in milliseconds @throws IllegalArgumentException if ms is not between 0 and 60 000 milliseconds inclusive @see java.lang.Thread#sleep()

The Scrollbar class embodies a scroll bar a familiar user-interface object. A scroll bar provides a convenient means for allowing a user to select from a range of values. The following three vertical scroll bars could be used as slider controls to pick the red green and blue components of a color:

Each scroll bar in this example could be created with code similar to the following:

---

 redSlider=new Scrollbar(Scrollbar.VERTICAL 0 1 0 255); add(redSlider); 

---

Alternatively a scroll bar can represent a range of values. For example if a scroll bar is used for scrolling through text the width of the "bubble" or "thumb" can represent the amount of text that is visible. Here is an example of a scroll bar that represents a range:

The value range represented by the bubble is the visible range of the scroll bar. The horizontal scroll bar in this example could be created with code like the following:

---

 ranger = new Scrollbar(Scrollbar.HORIZONTAL 0 60 0 300); add(ranger); 

---

Note that the actual maximum value of the scroll bar is the maximum minus the visible. In the previous example because the maximum is 300 and the visible is 60 the actual maximum value is 240. The range of the scrollbar track is 0 - 300. The left side of the bubble indicates the value of the scroll bar.

Normally the user changes the value of the scroll bar by making a gesture with the mouse. For example the user can drag the scroll bar's bubble up and down or click in the scroll bar's unit increment or block increment areas. Keyboard gestures can also be mapped to the scroll bar. By convention the Page Up and Page Down keys are equivalent to clicking in the scroll bar's block increment and block decrement areas.

When the user changes the value of the scroll bar the scroll bar receives an instance of AdjustmentEvent. The scroll bar processes this event passing it along to any registered listeners.

Any object that wishes to be notified of changes to the scroll bar's value should implement AdjustmentListener an interface defined in the package java.awt.event. Listeners can be added and removed dynamically by calling the methods addAdjustmentListener and removeAdjustmentListener.

The AdjustmentEvent class defines five types of adjustment event listed here:

• AdjustmentEvent.TRACK is sent out when the user drags the scroll bar's bubble.
• AdjustmentEvent.UNIT_INCREMENT is sent out when the user clicks in the left arrow of a horizontal scroll bar or the top arrow of a vertical scroll bar or makes the equivalent gesture from the keyboard.
• AdjustmentEvent.UNIT_DECREMENT is sent out when the user clicks in the right arrow of a horizontal scroll bar or the bottom arrow of a vertical scroll bar or makes the equivalent gesture from the keyboard.
• AdjustmentEvent.BLOCK_INCREMENT is sent out when the user clicks in the track to the left of the bubble on a horizontal scroll bar or above the bubble on a vertical scroll bar. By convention the Page Up key is equivalent if the user is using a keyboard that defines a Page Up key.
• AdjustmentEvent.BLOCK_DECREMENT is sent out when the user clicks in the track to the right of the bubble on a horizontal scroll bar or below the bubble on a vertical scroll bar. By convention the Page Down key is equivalent if the user is using a keyboard that defines a Page Down key.

The JDK 1.0 event system is supported for backwards compatibility but its use with newer versions of the platform is discouraged. The five types of adjustment event introduced with JDK 1.1 correspond to the five event types that are associated with scroll bars in previous platform versions. The following list gives the adjustment event type and the corresponding JDK 1.0 event type it replaces.

• AdjustmentEvent.TRACK replaces Event.SCROLL_ABSOLUTE
• AdjustmentEvent.UNIT_INCREMENT replaces Event.SCROLL_LINE_UP
• AdjustmentEvent.UNIT_DECREMENT replaces Event.SCROLL_LINE_DOWN
• AdjustmentEvent.BLOCK_INCREMENT replaces Event.SCROLL_PAGE_UP
• AdjustmentEvent.BLOCK_DECREMENT replaces Event.SCROLL_PAGE_DOWN

@version 1.9394 12/03/0111/02 @author Sami Shaio @see java.awt.event.AdjustmentEvent @see java.awt.event.AdjustmentListener @since JDK1.0

Sets the minimum value of this scroll bar.

When setMinimum is called the limiting argument takes precedence over the existing scrollbar value.

Normally a program should change a scroll bar's minimum value only by calling setValues. The setValues method simultaneously and synchronously sets the minimum maximum visible amount and value properties of a scroll bar so that they are mutually consistent.

Note that setting the minimum value to Integer.MIN_VALUE will result in the new minimum value to be set to Integer.MIN_VALUE - 1. @param newMinimum the new minimum value for this scroll bar @see java.awt.Scrollbar#setValues @see java.awt.Scrollbar#setMaximum @since JDK1.1

This class is the abstract superclass of all actual implementations of the Abstract Window Toolkit. Subclasses of Toolkit are used to bind the various components to particular native toolkit implementations.

Most applications should not call any of the methods in this class directly. The methods defined by Toolkit are the "glue" that joins the platform-independent classes in the java.awt package with their counterparts in java.awt.peer. Some methods defined by Toolkit query the native operating system directly. @version 1.181 12184 04/0302/0102 @author Sami Shaio @author Arthur van Hoff @author Fred Ecks @since JDK1.0

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 image the image to display when the cursor is active. @param hotSpot the X and Y of the large cursor's hot spot. The; the hotSpot values must be less than the Dimension returned by 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. @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true @see java.awt.GraphicsEnvironment#isHeadless @since 1.2

Gets the size of the screen. On systems with multiple displays the primary display is used. Multi-screen aware display dimensions are available from GraphicsConfiguration and 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.GraphicsEnvironmentGraphicsDevice#getDisplayMode @see java.awt.GraphicsEnvironment#isHeadless

A Window object is a top-level window with no borders and no menubar. The default layout for a window is BorderLayout.

A window must have either a frame dialog or another window defined as its owner when it's constructed.

In a multi-screen environment you can create a Window on a different screen device by constructing the Window with GraphicsConfiguration) The GraphicsConfiguration object is one of the GraphicsConfiguration objects of the target screen device.

In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices the bounds of all configurations are relative to the virtual device coordinate system. The origin of the virtual-coordinate system is at the upper left-hand corner of the primary physical screen. Depending on the location of the primary screen in the virtual device negative coordinates are possible as shown in the following figure.

In such an environment when calling setLocation you must pass a virtual coordinate to this method. Similarly calling getLocationOnScreen on a Window returns virtual device coordinates. Call the getBounds method of a GraphicsConfiguration to find its origin in the virtual coordinate system.

The following code sets the location of a Window at (10 10) relative to the origin of the physical screen of the corresponding GraphicsConfiguration. If the bounds of the GraphicsConfiguration is not taken into account the Window location would be set at (10 10) relative to the virtual-coordinate system and would appear on the primary physical screen which might be different from the physical screen of the specified GraphicsConfiguration.

 Window w = new Window(Window owner GraphicsConfiguration gc); Rectangle bounds = gc.getBounds(); w.setLocation(10 + bounds.x 10 + bounds.y); 

Windows are capable of generating the following WindowEvents: WindowOpened WindowClosed WindowGainedFocus WindowLostFocus. @version 1.171 04175 03/0925/02 @author Sami Shaio @author Arthur van Hoff @see WindowEvent @see #addWindowListener @see java.awt.BorderLayout @since JDK1.0

Gets a focus traversal key for this Window. (See setFocusTraversalKeysetFocusTraversalKeys for a full description of each key.)

If the traversal key has not been explicitly set for this Window then this Window's parent's traversal key is returned. If the traversal key has not been explicitly set for any of this Window's ancestors then the current KeyboardFocusManager's default traversal key is returned. @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYKEYS KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYKEYS KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYKEYS or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYKEYS @return the AWTKeyStroke for the specified key @see Container#setFocusTraversalKeysetFocusTraversalKeys @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYKEYS @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYKEYS @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYKEYS @see KeyboardFocusManager#DOWN_CYCLE_TRAVERSAL_KEYKEYS @throws IllegalArgumentException if id is not one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYKEYS KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYKEYS KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYKEYS or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYKEYS @since 1.4

Returns the owner of this window. @since 1.2