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.

The interface for objects which have an adjustable numeric value
contained within a bounded range of values.

 Fs = f(Ad)
 Fd = f(As)
 Ar = As*Fs  Ad*Fd
 Cr = Cs*Fs  Cd*Fd

 As = Asr * Aac

 Cs = Csr * Asr * Aac     (if source is not premultiplied)
 Cs = Csr * Aac           (if source is premultiplied)

 Ad = Adr

 Cd = Cdr * Ad    (if destination is not premultiplied)
 Cd = Cdr         (if destination is premultiplied)

 Adf = Ar
 Cdf = Cr                 (if dest is premultiplied)
 Cdf = Cr / Ar            (if dest is not premultiplied)

The AlphaComposite class implements basic alpha
compositing rules for combining source and destination colors
to achieve blending and transparency effects with graphics and
images.
The specific rules implemented by this class are the basic set
of 12 rules described in
T. Porter and T. Duff, "Compositing Digital Images", SIGGRAPH 84,
253-259.
The rest of this documentation assumes some familiarity with the
definitions and concepts outlined in that paper.


This class extends the standard equations defined by Porter and
Duff to include one additional factor.
An instance of the AlphaComposite class can contain
an alpha value that is used to modify the opacity or coverage of
every source pixel before it is used in the blending equations.


It is important to note that the equations defined by the Porter
and Duff paper are all defined to operate on color components
that are premultiplied by their corresponding alpha components.
Since the ColorModel and Raster classes
allow the storage of pixel data in either premultiplied or
non-premultiplied form, all input data must be normalized into
premultiplied form before applying the equations and all results
might need to be adjusted back to the form required by the destination
before the pixel values are stored.


Also note that this class defines only the equations
for combining color and alpha values in a purely mathematical
sense. The accurate application of its equations depends
on the way the data is retrieved from its sources and stored
in its destinations.
See Implementation Caveats
for further information.


The following factors are used in the description of the blending
equation in the Porter and Duff paper:



Factor  Definition
Asthe alpha component of the source pixel
Csa color component of the source pixel in premultiplied form
Adthe alpha component of the destination pixel
Cda color component of the destination pixel in premultiplied form
Fsthe fraction of the source pixel that contributes to the output
Fdthe fraction of the destination pixel that contributes
to the output
Arthe alpha component of the result
Cra color component of the result in premultiplied form




Using these factors, Porter and Duff define 12 ways of choosing
the blending factors Fs and Fd to
produce each of 12 desirable visual effects.
The equations for determining Fs and Fd
are given in the descriptions of the 12 static fields
that specify visual effects.
For example,
the description for
SRC_OVER
specifies that Fs = 1 and Fd = (1-As).
Once a set of equations for determining the blending factors is
known they can then be applied to each pixel to produce a result
using the following set of equations:



     Fs = f(Ad)
     Fd = f(As)
     Ar = As*Fs  Ad*Fd
     Cr = Cs*Fs  Cd*Fd


The following factors will be used to discuss our extensions to
the blending equation in the Porter and Duff paper:



Factor  Definition
Csr one of the raw color components of the source pixel
Cdr one of the raw color components of the destination pixel
Aac  the "extra" alpha component from the AlphaComposite instance
Asr the raw alpha component of the source pixel
Adrthe raw alpha component of the destination pixel
Adf the final alpha component stored in the destination
Cdf the final raw color component stored in the destination



Preparing Inputs


The AlphaComposite class defines an additional alpha
value that is applied to the source alpha.
This value is applied as if an implicit SRC_IN rule were first
applied to the source pixel against a pixel with the indicated
alpha by multiplying both the raw source alpha and the raw
source colors by the alpha in the AlphaComposite.
This leads to the following equation for producing the alpha
used in the Porter and Duff blending equation:



     As = Asr * Aac

All of the raw source color components need to be multiplied
by the alpha in the AlphaComposite instance.
Additionally, if the source was not in premultiplied form
then the color components also need to be multiplied by the
source alpha.
Thus, the equation for producing the source color components
for the Porter and Duff equation depends on whether the source
pixels are premultiplied or not:



     Cs = Csr * Asr * Aac     (if source is not premultiplied)
     Cs = Csr * Aac           (if source is premultiplied)

No adjustment needs to be made to the destination alpha:



     Ad = Adr


The destination color components need to be adjusted only if
they are not in premultiplied form:



     Cd = Cdr * Ad    (if destination is not premultiplied)
     Cd = Cdr         (if destination is premultiplied)

Applying the Blending Equation


The adjusted As, Ad,
Cs, and Cd are used in the standard
Porter and Duff equations to calculate the blending factors
Fs and Fd and then the resulting
premultiplied components Ar and Cr.

Preparing Results


The results only need to be adjusted if they are to be stored
back into a destination buffer that holds data that is not
premultiplied, using the following equations:



     Adf = Ar
     Cdf = Cr                 (if dest is premultiplied)
     Cdf = Cr / Ar            (if dest is not premultiplied)

Note that since the division is undefined if the resulting alpha
is zero, the division in that case is omitted to avoid the "divide
by zero" and the color components are left as
all zeros.

Performance Considerations


For performance reasons, it is preferable that
Raster objects passed to the compose
method of a CompositeContext object created by the
AlphaComposite class have premultiplied data.
If either the source Raster
or the destination Raster
is not premultiplied, however,
appropriate conversions are performed before and after the compositing
operation.

Implementation Caveats



Many sources, such as some of the opaque image types listed
in the BufferedImage class, do not store alpha values
for their pixels.  Such sources supply an alpha of 1.0 for
all of their pixels.


Many destinations also have no place to store the alpha values
that result from the blending calculations performed by this class.
Such destinations thus implicitly discard the resulting
alpha values that this class produces.
It is recommended that such destinations should treat their stored
color values as non-premultiplied and divide the resulting color
values by the resulting alpha value before storing the color
values and discarding the alpha value.


The accuracy of the results depends on the manner in which pixels
are stored in the destination.
An image format that provides at least 8 bits of storage per color
and alpha component is at least adequate for use as a destination
for a sequence of a few to a dozen compositing operations.
An image format with fewer than 8 bits of storage per component
is of limited use for just one or two compositing operations
before the rounding errors dominate the results.
An image format
that does not separately store
color components is not a
good candidate for any type of translucent blending.
For example, BufferedImage.TYPE_BYTE_INDEXED
should not be used as a destination for a blending operation
because every operation
can introduce large errors, due to
the need to choose a pixel from a limited palette to match the
results of the blending equations.


Nearly all formats store pixels as discrete integers rather than
the floating point values used in the reference equations above.
The implementation can either scale the integer pixel
values into floating point values in the range 0.0 to 1.0 or
use slightly modified versions of the equations
that operate entirely in the integer domain and yet produce
analogous results to the reference equations.


Typically the integer values are related to the floating point
values in such a way that the integer 0 is equated
to the floating point value 0.0 and the integer
2^n-1 (where n is the number of bits
in the representation) is equated to 1.0.
For 8-bit representations, this means that 0x00
represents 0.0 and 0xff represents
1.0.


The internal implementation can approximate some of the equations
and it can also eliminate some steps to avoid unnecessary operations.
For example, consider a discrete integer image with non-premultiplied
alpha values that uses 8 bits per component for storage.
The stored values for a
nearly transparent darkened red might be:



   (A, R, G, B) = (0x01, 0xb0, 0x00, 0x00)


If integer math were being used and this value were being
composited in
SRC
mode with no extra alpha, then the math would
indicate that the results were (in integer format):



   (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)


Note that the intermediate values, which are always in premultiplied
form, would only allow the integer red component to be either 0x00
or 0x01.  When we try to store this result back into a destination
that is not premultiplied, dividing out the alpha will give us
very few choices for the non-premultiplied red value.
In this case an implementation that performs the math in integer
space without shortcuts is likely to end up with the final pixel
values of:



   (A, R, G, B) = (0x01, 0xff, 0x00, 0x00)


(Note that 0x01 divided by 0x01 gives you 1.0, which is equivalent
to the value 0xff in an 8-bit storage format.)


Alternately, an implementation that uses floating point math
might produce more accurate results and end up returning to the
original pixel value with little, if any, roundoff error.
Or, an implementation using integer math might decide that since
the equations boil down to a virtual NOP on the color values
if performed in a floating point space, it can transfer the
pixel untouched to the destination and avoid all the math entirely.


These implementations all attempt to honor the
same equations, but use different tradeoffs of integer and
floating point math and reduced or full equations.
To account for such differences, it is probably best to
expect only that the premultiplied form of the results to
match between implementations and image formats.  In this
case both answers, expressed in premultiplied form would
equate to:



   (A, R, G, B) = (0x01, 0x01, 0x00, 0x00)


and thus they would all match.


Because of the technique of simplifying the equations for
calculation efficiency, some implementations might perform
differently when encountering result alpha values of 0.0
on a non-premultiplied destination.
Note that the simplification of removing the divide by alpha
in the case of the SRC rule is technically not valid if the
denominator (alpha) is 0.
But, since the results should only be expected to be accurate
when viewed in premultiplied form, a resulting alpha of 0
essentially renders the resulting color components irrelevant
and so exact behavior in this case should not be expected.

Thrown when a serious Abstract Window Toolkit error has occurred.

The root event class for all AWT events.
This class and its subclasses supercede the original
java.awt.Event class.
Subclasses of this root AWTEvent class defined outside of the
java.awt.event package should define event ID values greater than
the value defined by RESERVED_ID_MAX.

The event masks defined in this class are needed by Component subclasses
which are using Component.enableEvents() to select for event types not
selected by registered listeners. If a listener is registered on a
component, the appropriate event mask is already set internally by the
component.

The masks are also used to specify to which types of events an
AWTEventListener should listen. The masks are bitwise-ORed together
and passed to Toolkit.addAWTEventListener.

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
    ActionListener listener = actionListener;
    if (listener != null) {
        listener.actionPerformed(new ActionEvent());
    }
}

AWTEventMulticaster implements efficient and thread-safe multi-cast
event dispatching for the AWT events defined in the java.awt.event
package.

The following example illustrates how to use this class:



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
        ActionListener listener = actionListener;
        if (listener != null) {
            listener.actionPerformed(new ActionEvent());
        }
    }
}
The important point to note is the first argument to the add and remove methods is the field maintaining the
listeners. In addition you must assign the result of the add
and remove methods to the field maintaining the listeners.

AWTEventMulticaster is implemented as a pair of EventListeners that are set at construction time. AWTEventMulticaster is immutable. The add and remove methods do not alter AWTEventMulticaster in
anyway. If necessary, a new AWTEventMulticaster is
created. In this way it is safe to add and remove listeners during
the process of an event dispatching.  However, event listeners
added during the process of an event dispatch operation are not
notified of the event currently being dispatched.

All of the add methods allow null arguments. If the
first argument is null, the second argument is returned. If
the first argument is not null and the second argument is
null, the first argument is returned. If both arguments are
non-null, a new AWTEventMulticaster is created using
the two arguments and returned.

For the remove methods that take two arguments, the following is
returned:

  null, if the first argument is null, or
      the arguments are equal, by way of ==.
  the first argument, if the first argument is not an instance of
      AWTEventMulticaster.
  result of invoking remove(EventListener) on the
      first argument, supplying the second argument to the
      remove(EventListener) method.

Swing makes use of
EventListenerList for
similar logic. Refer to it for details.

Signals that an Abstract Window Toolkit exception has occurred.

An AWTKeyStroke represents a key action on the
keyboard, or equivalent input device. AWTKeyStrokes
can correspond to only a press or release of a
particular key, just as KEY_PRESSED and
KEY_RELEASED KeyEvents do;
alternately, they can correspond to typing a specific Java character, just
as KEY_TYPED KeyEvents do.
In all cases, AWTKeyStrokes can specify modifiers
(alt, shift, control, meta, altGraph, or a combination thereof) which must be present
during the action for an exact match.

AWTKeyStrokes are immutable, and are intended
to be unique. Client code should never create an
AWTKeyStroke on its own, but should instead use
a variant of getAWTKeyStroke. Client use of these factory
methods allows the AWTKeyStroke implementation
to cache and share instances efficiently.

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.



  accessSystemTray
  Access to the AWT SystemTray instance
  This would allow malicious code to add tray icons to the system tray.
First, such an icon may look like the icon of some known application
(such as a firewall or anti-virus) and order a user to do something unsafe
(with help of balloon messages). Second, the system tray may be glutted with
tray icons so that no one could add a tray icon anymore.



  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. Depending on
the implementation, the security warning may not be shown for the windows
used to enter the full-screen exclusive mode (assuming that the fullScreenExclusive permission has been granted to this application). Note
that this behavior does not mean that the showWindowWithoutWarningBanner permission will be automatically granted to
the application which has the fullScreenExclusive permission:
non-full-screen windows will continue to be shown with the security
warning.



  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.



  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.



  replaceKeyboardFocusManager
  Sets the KeyboardFocusManager for
      a particular thread.
  When SecurityManager is installed, the invoking
      thread must be granted this permission in order to replace
      the current KeyboardFocusManager.  If permission
      is not granted, a SecurityException will be thrown.



  setAppletStub
  Setting the stub which implements Applet container services
  Malicious code could set an applet's stub and result in unexpected
behavior or denial of service to an applet.



  setWindowAlwaysOnTop
  Setting always-on-top property of the window: Window.setAlwaysOnTop(boolean)
  The malicious window might make itself look and behave like a real full desktop, so that
information entered by the unsuspecting user is captured and subsequently misused



  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.



  toolkitModality
  Creating TOOLKIT_MODAL dialogs
      and setting the TOOLKIT_EXCLUDE window property.
  When a toolkit-modal dialog is shown from an applet, it blocks all other
applets in the browser. When launching applications from Java Web Start,
its windows (such as the security dialog) may also be blocked by toolkit-modal
dialogs, shown from these applications.



  watchMousePointer
  Getting the information about the mouse pointer position at any
time
  Constantly watching the mouse pointer,
an applet can make guesses about what the user is doing, i.e. moving
the mouse to the lower left corner of the screen most likely means that
the user is about to launch an application. If a virtual keypad is used
so that keyboard is emulated using the mouse, an applet may guess what
is being typed.

 // sets the Graphics2D object's Transform attribute
 g2d.scale(10, 10);
 // sets the Graphics2D object's Stroke attribute
 g2d.setStroke(new BasicStroke(1.5f));

The BasicStroke class defines a basic set of rendering
attributes for the outlines of graphics primitives, which are rendered
with a Graphics2D object that has its Stroke attribute set to
this BasicStroke.
The rendering attributes defined by BasicStroke describe
the shape of the mark made by a pen drawn along the outline of a
Shape and the decorations applied at the ends and joins of
path segments of the Shape.
These rendering attributes include:

width
The pen width, measured perpendicularly to the pen trajectory.
end caps
The decoration applied to the ends of unclosed subpaths and
dash segments.  Subpaths that start and end on the same point are
still considered unclosed if they do not have a CLOSE segment.
See SEG_CLOSE
for more information on the CLOSE segment.
The three different decorations are: CAP_BUTT,
CAP_ROUND, and CAP_SQUARE.
line joins
The decoration applied at the intersection of two path segments
and at the intersection of the endpoints of a subpath that is closed
using SEG_CLOSE.
The three different decorations are: JOIN_BEVEL,
JOIN_MITER, and JOIN_ROUND.
miter limit
The limit to trim a line join that has a JOIN_MITER decoration.
A line join is trimmed when the ratio of miter length to stroke
width is greater than the miterlimit value.  The miter length is
the diagonal length of the miter, which is the distance between
the inside corner and the outside corner of the intersection.
The smaller the angle formed by two line segments, the longer
the miter length and the sharper the angle of intersection.  The
default miterlimit value of 10.0f causes all angles less than
11 degrees to be trimmed.  Trimming miters converts
the decoration of the line join to bevel.
dash attributes
The definition of how to make a dash pattern by alternating
between opaque and transparent sections.

All attributes that specify measurements and distances controlling
the shape of the returned outline are measured in the same
coordinate system as the original unstroked Shape
argument.  When a Graphics2D object uses a
Stroke object to redefine a path during the execution
of one of its draw methods, the geometry is supplied
in its original form before the Graphics2D transform
attribute is applied.  Therefore, attributes such as the pen width
are interpreted in the user space coordinate system of the
Graphics2D object and are subject to the scaling and
shearing effects of the user-space-to-device-space transform in that
particular Graphics2D.
For example, the width of a rendered shape's outline is determined
not only by the width attribute of this BasicStroke,
but also by the transform attribute of the
Graphics2D object.  Consider this code:

     // sets the Graphics2D object's Transform attribute
     g2d.scale(10, 10);
     // sets the Graphics2D object's Stroke attribute
     g2d.setStroke(new BasicStroke(1.5f));

Assuming there are no other scaling transforms added to the
Graphics2D object, the resulting line
will be approximately 15 pixels wide.
As the example code demonstrates, a floating-point line
offers better precision, especially when large transforms are
used with a Graphics2D object.
When a line is diagonal, the exact width depends on how the
rendering pipeline chooses which pixels to fill as it traces the
theoretical widened outline.  The choice of which pixels to turn
on is affected by the antialiasing attribute because the
antialiasing rendering pipeline can choose to color
partially-covered pixels.

For more information on the user space coordinate system and the
rendering process, see the Graphics2D class comments.

A border layout lays out a container, arranging and resizing
its components to fit in five regions:
north, south, east, west, and center.
Each region may contain no more than one component, and
is identified by a corresponding constant:
NORTH, SOUTH, EAST,
WEST, and CENTER.  When adding a
component to a container with a border layout, use one of these
five constants, for example:


   Panel p = new Panel();
   p.setLayout(new BorderLayout());
   p.add(new Button("Okay"), BorderLayout.SOUTH);
As a convenience, BorderLayout interprets the
absence of a string specification the same as the constant
CENTER:


   Panel p2 = new Panel();
   p2.setLayout(new BorderLayout());
   p2.add(new TextArea());  // Same as p.add(new TextArea(), BorderLayout.CENTER);

In addition, BorderLayout supports the relative
positioning constants, PAGE_START, PAGE_END,
LINE_START, and LINE_END.
In a container whose ComponentOrientation is set to
ComponentOrientation.LEFT_TO_RIGHT, these constants map to
NORTH, SOUTH, WEST, and
EAST, respectively.

For compatibility with previous releases, BorderLayout
also includes the relative positioning constants BEFORE_FIRST_LINE,
AFTER_LAST_LINE, BEFORE_LINE_BEGINS and
AFTER_LINE_ENDS.  These are equivalent to
PAGE_START, PAGE_END, LINE_START
and LINE_END respectively.  For
consistency with the relative positioning constants used by other
components, the latter constants are preferred.

Mixing both absolute and relative positioning constants can lead to
unpredictable results.  If
you use both types, the relative constants will take precedence.
For example, if you add components using both the NORTH
and PAGE_START constants in a container whose
orientation is LEFT_TO_RIGHT, only the
PAGE_START will be layed out.

NOTE: Currently (in the Java 2 platform v1.2),
BorderLayout does not support vertical
orientations.  The isVertical setting on the container's
ComponentOrientation is not respected.

The components are laid out according to their
preferred sizes and the constraints of the container's size.
The NORTH and SOUTH components may
be stretched horizontally; the EAST and
WEST components may be stretched vertically;
the CENTER component may stretch both horizontally
and vertically to fill any space left over.

Here is an example of five buttons in an applet laid out using
the BorderLayout layout manager:



The code for this applet is as follows:



import java.awt.*;
import java.applet.Applet;

public class buttonDir extends Applet {
  public void init() {
    setLayout(new BorderLayout());
    add(new Button("North"), BorderLayout.NORTH);
    add(new Button("South"), BorderLayout.SOUTH);
    add(new Button("East"), BorderLayout.EAST);
    add(new Button("West"), BorderLayout.WEST);
    add(new Button("Center"), BorderLayout.CENTER);
  }
}

Capabilities and properties of buffers.

A type-safe enumeration of the possible back buffer contents after
page-flipping

This class creates a labeled button. The application can cause
some action to happen when the button is pushed. This image
depicts three views of a "Quit" button as it appears
under the Solaris operating system:



The first view shows the button as it appears normally.
The second view shows the button
when it has input focus. Its outline is darkened to let the
user know that it is an active object. The third view shows the
button when the user clicks the mouse over the button, and thus
requests that an action be performed.

The gesture of clicking on a button with the mouse
is associated with one instance of ActionEvent,
which is sent out when the mouse is both pressed and released
over the button. If an application is interested in knowing
when the button has been pressed but not released, as a separate
gesture, it can specialize processMouseEvent,
or it can register itself as a listener for mouse events by
calling addMouseListener. Both of these methods are
defined by Component, the abstract superclass of
all components.

When a button is pressed and released, AWT sends an instance
of ActionEvent to the button, by calling
processEvent on the button. The button's
processEvent method receives all events
for the button; it passes an action event along by
calling its own processActionEvent method.
The latter method passes the action event on to any action
listeners that have registered an interest in action
events generated by this button.

If an application wants to perform some action based on
a button being pressed and released, it should implement
ActionListener and register the new listener
to receive events from this button, by calling the button's
addActionListener method. The application can
make use of the button's action command as a messaging protocol.

A Canvas component represents a blank rectangular
area of the screen onto which the application can draw or from
which the application can trap input events from the user.

An application must subclass the Canvas class in
order to get useful functionality such as creating a custom
component. The paint method must be overridden
in order to perform custom graphics on the canvas.

A CardLayout object is a layout manager for a
container. It treats each component in the container as a card.
Only one card is visible at a time, and the container acts as
a stack of cards. The first component added to a
CardLayout object is the visible component when the
container is first displayed.

The ordering of cards is determined by the container's own internal
ordering of its component objects. CardLayout
defines a set of methods that allow an application to flip
through these cards sequentially, or to show a specified card.
The addLayoutComponent(java.awt.Component, java.lang.Object)
method can be used to associate a string identifier with a given card
for fast random access.

A check box is a graphical component that can be in either an
"on" (true) or "off" (false) state.
Clicking on a check box changes its state from
"on" to "off," or from "off" to "on."

The following code example creates a set of check boxes in
a grid layout:



setLayout(new GridLayout(3, 1));
add(new Checkbox("one", null, true));
add(new Checkbox("two"));
add(new Checkbox("three"));

This image depicts the check boxes and grid layout
created by this code example:



The button labeled one is in the "on" state, and the
other two are in the "off" state. In this example, which uses the
GridLayout class, the states of the three check
boxes are set independently.

Alternatively, several check boxes can be grouped together under
the control of a single object, using the
CheckboxGroup class.
In a check box group, at most one button can be in the "on"
state at any given time. Clicking on a check box to turn it on
forces any other check box in the same group that is on
into the "off" state.

The CheckboxGroup class is used to group together
a set of Checkbox buttons.

Exactly one check box button in a CheckboxGroup can
be in the "on" state at any given time. Pushing any
button sets its state to "on" and forces any other button that
is in the "on" state into the "off" state.

The following code example produces a new check box group,
with three check boxes:



setLayout(new GridLayout(3, 1));
CheckboxGroup cbg = new CheckboxGroup();
add(new Checkbox("one", cbg, true));
add(new Checkbox("two", cbg, false));
add(new Checkbox("three", cbg, false));

This image depicts the check box group created by this example:

This class represents a check box that can be included in a menu.
Selecting the check box in the menu changes its state from
"on" to "off" or from "off" to "on."

The following picture depicts a menu which contains an instance
of CheckBoxMenuItem:



The item labeled Check shows a check box menu item
in its "off" state.

When a check box menu item is selected, AWT sends an item event to
the item. Since the event is an instance of ItemEvent,
the processEvent method examines the event and passes
it along to processItemEvent. The latter method redirects
the event to any ItemListener objects that have
registered an interest in item events generated by this menu item.

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.

The Color class is used to encapsulate colors in the default
sRGB color space or colors in arbitrary color spaces identified by a
ColorSpace.  Every color has an implicit alpha value of 1.0 or
an explicit one provided in the constructor.  The alpha value
defines the transparency of a color and can be represented by
a float value in the range 0.0 - 1.0 or 0 - 255.
An alpha value of 1.0 or 255 means that the color is completely
opaque and an alpha value of 0 or 0.0 means that the color is
completely transparent.
When constructing a Color with an explicit alpha or
getting the color/alpha components of a Color, the color
components are never premultiplied by the alpha component.

The default color space for the Java 2D(tm) API is sRGB, a proposed
standard RGB color space.  For further information on sRGB,
see
http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html
.

This exception is thrown if the native CMM returns an error.

 CIEXYZ
 viewing illuminance: 200 lux
 viewing white point: CIE D50
 media white point: "that of a perfectly reflecting diffuser" -- D50
 media black point: 0 lux or 0 Reflectance
 flare: 1 percent
 surround: 20percent of the media white point
 media description: reflection print (i.e., RLAB, Hunt viewing media)
 note: For developers creating an ICC profile for this conversion
       space, the following is applicable.  Use a simple Von Kries
       white point adaptation folded into the 3X3 matrix parameters
       and fold the flare and surround effects into the three
       one-dimensional lookup tables (assuming one uses the minimal
       model for monitors).

This abstract class is used to serve as a color space tag to identify the
specific color space of a Color object or, via a ColorModel object,
of an Image, a BufferedImage, or a GraphicsDevice.  It contains
methods that transform colors in a specific color space to/from sRGB
and to/from a well-defined CIEXYZ color space.

For purposes of the methods in this class, colors are represented as
arrays of color components represented as floats in a normalized range
defined by each ColorSpace.  For many ColorSpaces (e.g. sRGB), this
range is 0.0 to 1.0.  However, some ColorSpaces have components whose
values have a different range.  Methods are provided to inquire per
component minimum and maximum normalized values.

Several variables are defined for purposes of referring to color
space types (e.g. TYPE_RGB, TYPE_XYZ, etc.) and to refer to specific
color spaces (e.g. CS_sRGB and CS_CIEXYZ).
sRGB is a proposed standard RGB color space.  For more information,
see
http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html
.

The purpose of the methods to transform to/from the well-defined
CIEXYZ color space is to support conversions between any two color
spaces at a reasonably high degree of accuracy.  It is expected that
particular implementations of subclasses of ColorSpace (e.g.
ICC_ColorSpace) will support high performance conversion based on
underlying platform color management systems.

The CS_CIEXYZ space used by the toCIEXYZ/fromCIEXYZ methods can be
described as follows:


     CIEXYZ
     viewing illuminance: 200 lux
     viewing white point: CIE D50
     media white point: "that of a perfectly reflecting diffuser" -- D50
     media black point: 0 lux or 0 Reflectance
     flare: 1 percent
     surround: 20percent of the media white point
     media description: reflection print (i.e., RLAB, Hunt viewing media)
     note: For developers creating an ICC profile for this conversion
           space, the following is applicable.  Use a simple Von Kries
           white point adaptation folded into the 3X3 matrix parameters
           and fold the flare and surround effects into the three
           one-dimensional lookup tables (assuming one uses the minimal
           model for monitors).

The ICC_ColorSpace class is an implementation of the abstract
ColorSpace class.  This representation of
device independent and device dependent color spaces is based on the
International Color Consortium Specification ICC.1:2001-12, File Format for
Color Profiles (see http://www.color.org).

Typically, a Color or ColorModel would be associated with an ICC
Profile which is either an input, display, or output profile (see
the ICC specification).  There are other types of ICC Profiles, e.g.
abstract profiles, device link profiles, and named color profiles,
which do not contain information appropriate for representing the color
space of a color, image, or device (see ICC_Profile).
Attempting to create an ICC_ColorSpace object from an inappropriate ICC
Profile is an error.

ICC Profiles represent transformations from the color space of
the profile (e.g. a monitor) to a Profile Connection Space (PCS).
Profiles of interest for tagging images or colors have a
PCS which is one of the device independent
spaces (one CIEXYZ space and two CIELab spaces) defined in the
ICC Profile Format Specification.  Most profiles of interest
either have invertible transformations or explicitly specify
transformations going both directions.  Should an ICC_ColorSpace
object be used in a way requiring a conversion from PCS to
the profile's native space and there is inadequate data to
correctly perform the conversion, the ICC_ColorSpace object will
produce output in the specified type of color space (e.g. TYPE_RGB,
TYPE_CMYK, etc.), but the specific color values of the output data
will be undefined.

The details of this class are not important for simple applets,
which draw in a default color space or manipulate and display
imported images with a known color space.  At most, such applets
would need to get one of the default color spaces via
ColorSpace.getInstance().

A representation of color profile data for device independent and
device dependent color spaces based on the International Color
Consortium Specification ICC.1:2001-12, File Format for Color Profiles,
(see  http://www.color.org).

An ICC_ColorSpace object can be constructed from an appropriate
ICC_Profile.
Typically, an ICC_ColorSpace would be associated with an ICC
Profile which is either an input, display, or output profile (see
the ICC specification).  There are also device link, abstract,
color space conversion, and named color profiles.  These are less
useful for tagging a color or image, but are useful for other
purposes (in particular device link profiles can provide improved
performance for converting from one device's color space to
another's).

ICC Profiles represent transformations from the color space of
the profile (e.g. a monitor) to a Profile Connection Space (PCS).
Profiles of interest for tagging images or colors have a PCS
which is one of the two specific device independent
spaces (one CIEXYZ space and one CIELab space) defined in the
ICC Profile Format Specification.  Most profiles of interest
either have invertible transformations or explicitly specify
transformations going both directions.

           PCSY = grayTRC[deviceGray]

A subclass of the ICC_Profile class which represents profiles
which meet the following criteria: the color space type of the
profile is TYPE_GRAY and the profile includes the grayTRCTag and
mediaWhitePointTag tags.  Examples of this kind of profile are
monochrome input profiles, monochrome display profiles, and
monochrome output profiles.  The getInstance methods in the
ICC_Profile class will
return an ICC_ProfileGray object when the above conditions are
met.  The advantage of this class is that it provides a lookup
table that Java or native methods may be able to use directly to
optimize color conversion in some cases.

To transform from a GRAY device profile color space to the CIEXYZ Profile
Connection Space, the device gray component is transformed by
a lookup through the tone reproduction curve (TRC).  The result is
treated as the achromatic component of the PCS.


               PCSY = grayTRC[deviceGray]
The inverse transform is done by converting the PCS Y components to
device Gray via the inverse of the grayTRC.

            linearR = redTRC[deviceR]

            linearG = greenTRC[deviceG]

            linearB = blueTRC[deviceB]

The ICC_ProfileRGB class is a subclass of the ICC_Profile class
that represents profiles which meet the following criteria:

The profile's color space type is RGB.
The profile includes the redColorantTag,
greenColorantTag, blueColorantTag,
redTRCTag, greenTRCTag,
blueTRCTag, and mediaWhitePointTag tags.

The ICC_Profile getInstance method will
return an ICC_ProfileRGB object when these conditions are met.
Three-component, matrix-based input profiles and RGB display profiles are
examples of this type of profile.

This profile class provides color transform matrices and lookup tables
that Java or native methods can use directly to
optimize color conversion in some cases.

To transform from a device profile color space to the CIEXYZ Profile
Connection Space, each device color component is first linearized by
a lookup through the corresponding tone reproduction curve (TRC).
The resulting linear RGB components are converted to the CIEXYZ PCS
using a a 3x3 matrix constructed from the RGB colorants.


                linearR = redTRC[deviceR]

                linearG = greenTRC[deviceG]

                linearB = blueTRC[deviceB]

  _      _       _                                             _   _         _
 [  PCSX  ]     [  redColorantX  greenColorantX  blueColorantX  ] [  linearR  ]
 [        ]     [                                               ] [           ]
 [  PCSY  ]  =  [  redColorantY  greenColorantY  blueColorantY  ] [  linearG  ]
 [        ]     [                                               ] [           ]
 [_ PCSZ _]     [_ redColorantZ  greenColorantZ  blueColorantZ _] [_ linearB _]
The inverse transform is performed by converting PCS XYZ components to linear
RGB components through the inverse of the above 3x3 matrix, and then converting
linear RGB to device RGB through inverses of the TRCs.

This exception is thrown when an error occurs in accessing or
processing an ICC_Profile object.

   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");
   }

    static class MyActionListener implements ActionListener
    {
        public void actionPerformed(ActionEvent e)
        {
            System.out.println("Hello There");
        }
    }

    MyApp()
    {
        aButton.addActionListener(new MyActionListener());
    }

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 window. On the contrary, a heavyweight
component is associated with a native window. The isLightweight()
method may be used to distinguish between the two kinds of the components.

Lightweight and heavyweight components may be mixed in a single component
hierarchy. However, for correct operating of such a mixed hierarchy of
components, the whole hierarchy must be valid. When the hierarchy gets
invalidated, like after changing the bounds of components, or
adding/removing components to/from containers, the whole hierarchy must be
validated afterwards by means of the Container.validate() method
invoked on the top-most invalid container of the hierarchy.

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 implements java.io.Serializable
   {
        BigObjectThatShouldNotBeSerializedWithAButton bigOne;
        Button aButton = new Button();

        static 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.

For details on the focus subsystem, see

How to Use the Focus Subsystem,
a section in The Java Tutorial, and the
Focus Specification
for more information.

The ComponentOrientation class encapsulates the language-sensitive
orientation that is to be used to order the elements of a component
or of text. It is used to reflect the differences in this ordering
between Western alphabets, Middle Eastern (such as Hebrew), and Far
Eastern (such as Japanese).

Fundamentally, this governs items (such as characters) which are laid out
in lines, with the lines then laid out in a block. This also applies
to items in a widget: for example, in a check box where the box is
positioned relative to the text.

There are four different orientations used in modern languages
as in the following table.


LT          RT          TL          TR
A B C       C B A       A D G       G D A
D E F       F E D       B E H       H E B
G H I       I H G       C F I       I F C
(In the header, the two-letter abbreviation represents the item direction
in the first letter, and the line direction in the second. For example,
LT means "items left-to-right, lines top-to-bottom",
TL means "items top-to-bottom, lines left-to-right", and so on.)

The orientations are:

LT - Western Europe (optional for Japanese, Chinese, Korean)
RT - Middle East (Arabic, Hebrew)
TR - Japanese, Chinese, Korean
TL - Mongolian

Components whose view and controller code depends on orientation
should use the isLeftToRight() and
isHorizontal() methods to
determine their behavior. They should not include switch-like
code that keys off of the constants, such as:


if (orientation == LEFT_TO_RIGHT) {
  ...
} else if (orientation == RIGHT_TO_LEFT) {
  ...
} else {
  // Oops
}
This is unsafe, since more constants may be added in the future and
since it is not guaranteed that orientation objects will be unique.

The Composite interface, along with
CompositeContext, defines the methods to compose a draw
primitive with the underlying graphics area.
After the Composite is set in the
Graphics2D context, it combines a shape, text, or an image
being rendered with the colors that have already been rendered
according to pre-defined rules. The classes
implementing this interface provide the rules and a method to create
the context for a particular operation.
CompositeContext is an environment used by the
compositing operation, which is created by the Graphics2D
prior to the start of the operation.  CompositeContext
contains private information and resources needed for a compositing
operation.  When the CompositeContext is no longer needed,
the Graphics2D object disposes of it in order to reclaim
resources allocated for the operation.

Instances of classes implementing Composite must be
immutable because the Graphics2D does not clone
these objects when they are set as an attribute with the
setComposite method or when the Graphics2D
object is cloned.  This is to avoid undefined rendering behavior of
Graphics2D, resulting from the modification of
the Composite object after it has been set in the
Graphics2D context.

Since this interface must expose the contents of pixels on the
target device or image to potentially arbitrary code, the use of
custom objects which implement this interface when rendering directly
to a screen device is governed by the readDisplayPixels
AWTPermission.  The permission check will occur when such
a custom object is passed to the setComposite method
of a Graphics2D retrieved from a Component.

The CompositeContext interface defines the encapsulated
and optimized environment for a compositing operation.
CompositeContext objects maintain state for
compositing operations.  In a multi-threaded environment, several
contexts can exist simultaneously for a single Composite
object.

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).

Note: For details on the focus subsystem, see

How to Use the Focus Subsystem,
a section in The Java Tutorial, and the
Focus Specification
for more information.

A FocusTraversalPolicy that determines traversal order based on the order
of child Components in a Container. From a particular focus cycle root, the
policy makes a pre-order traversal of the Component hierarchy, and traverses
a Container's children according to the ordering of the array returned by
Container.getComponents(). Portions of the hierarchy that are
not visible and displayable will not be searched.

By default, ContainerOrderFocusTraversalPolicy implicitly transfers focus
down-cycle. That is, during normal forward focus traversal, the Component
traversed after a focus cycle root will be the focus-cycle-root's default
Component to focus. This behavior can be disabled using the
setImplicitDownCycleTraversal method.

By default, methods of this class will return a Component only if it is
visible, displayable, enabled, and focusable. Subclasses can modify this
behavior by overriding the accept method.

This policy takes into account focus traversal
policy providers.  When searching for first/last/next/previous Component,
if a focus traversal policy provider is encountered, its focus traversal
policy is used to perform the search operation.

A class to encapsulate the bitmap representation of the mouse cursor.

A class that implements a mechanism to transfer data using
cut/copy/paste operations.

FlavorListeners may be registered on an instance of the
Clipboard class to be notified about changes to the set of
DataFlavors available on this clipboard (see
addFlavorListener(java.awt.datatransfer.FlavorListener)).

Defines the interface for classes that will provide data to
a clipboard. An instance of this interface becomes the owner
of the contents of a clipboard (clipboard owner) if it is
passed as an argument to
Clipboard.setContents(java.awt.datatransfer.Transferable, java.awt.datatransfer.ClipboardOwner) method of
the clipboard and this method returns successfully.
The instance remains the clipboard owner until another application
or another object within this application asserts ownership
of this clipboard.

A DataFlavor provides meta information about data. DataFlavor
is typically used to access data on the clipboard, or during
a drag and drop operation.

An instance of DataFlavor encapsulates a content type as
defined in RFC 2045
and RFC 2046.
A content type is typically referred to as a MIME type.

A content type consists of a media type (referred
to as the primary type), a subtype, and optional parameters. See
RFC 2045
for details on the syntax of a MIME type.

The JRE data transfer implementation interprets the parameter "class"
of a MIME type as a representation class.
The representation class reflects the class of the object being
transferred. In other words, the representation class is the type of
object returned by Transferable.getTransferData(java.awt.datatransfer.DataFlavor).
For example, the MIME type of imageFlavor is
"image/x-java-image;class=java.awt.Image",
the primary type is image, the subtype is
x-java-image, and the representation class is
java.awt.Image. When getTransferData is invoked
with a DataFlavor of imageFlavor, an instance of
java.awt.Image is returned.
It's important to note that DataFlavor does no error checking
against the representation class. It is up to consumers of
DataFlavor, such as Transferable, to honor the representation
class.

Note, if you do not specify a representation class when
creating a DataFlavor, the default
representation class is used. See appropriate documentation for
DataFlavor's constructors.

Also, DataFlavor instances with the "text" primary
MIME type may have a "charset" parameter. Refer to
RFC 2046 and
selectBestTextFlavor(java.awt.datatransfer.DataFlavor[]) for details on "text" MIME types
and the "charset" parameter.

Equality of DataFlavors is determined by the primary type,
subtype, and representation class. Refer to equals(DataFlavor) for
details. When determining equality, any optional parameters are ignored.
For example, the following produces two DataFlavors that
are considered identical:


  DataFlavor flavor1 = new DataFlavor(Object.class, "X-test/test; class=<java.lang.Object>; foo=bar");
  DataFlavor flavor2 = new DataFlavor(Object.class, "X-test/test; class=<java.lang.Object>; x=y");
  // The following returns true.
  flavor1.equals(flavor2);
As mentioned, flavor1 and flavor2 are considered identical.
As such, asking a Transferable for either DataFlavor returns
the same results.

For more information on the using data transfer with Swing see
the
How to Use Drag and Drop and Data Transfer,
section in Java Tutorial.

FlavorEvent is used to notify interested parties
that available DataFlavors have changed in the
Clipboard (the event source).

Defines an object which listens for FlavorEvents.

A two-way Map between "natives" (Strings), which correspond to platform-
specific data formats, and "flavors" (DataFlavors), which correspond to
platform-independent MIME types. FlavorMaps need not be symmetric, but
typically are.

A FlavorMap which relaxes the traditional 1-to-1 restriction of a Map. A
flavor is permitted to map to any number of natives, and likewise a native
is permitted to map to any number of flavors. FlavorTables need not be
symmetric, but typically are.

A class to encapsulate MimeType parsing related exceptions

A Transferable which implements the capability required
to transfer a String.

This Transferable properly supports
DataFlavor.stringFlavor
and all equivalent flavors. Support for
DataFlavor.plainTextFlavor
and all equivalent flavors is deprecated. No other
DataFlavors are supported.

The SystemFlavorMap is a configurable map between "natives" (Strings), which
correspond to platform-specific data formats, and "flavors" (DataFlavors),
which correspond to platform-independent MIME types. This mapping is used
by the data transfer subsystem to transfer data between Java and native
applications, and between Java applications in separate VMs.

Defines the interface for classes that can be used to provide data
for a transfer operation.

For information on using data transfer with Swing, see

How to Use Drag and Drop and Data Transfer,
a section in The Java Tutorial, for more information.

Signals that the requested data is not supported in this flavor.

A FocusTraversalPolicy that determines traversal order based on the order
of child Components in a Container. From a particular focus cycle root, the
policy makes a pre-order traversal of the Component hierarchy, and traverses
a Container's children according to the ordering of the array returned by
Container.getComponents(). Portions of the hierarchy that are
not visible and displayable will not be searched.

If client code has explicitly set the focusability of a Component by either
overriding Component.isFocusTraversable() or
Component.isFocusable(), or by calling
Component.setFocusable(), then a DefaultFocusTraversalPolicy
behaves exactly like a ContainerOrderFocusTraversalPolicy. If, however, the
Component is relying on default focusability, then a
DefaultFocusTraversalPolicy will reject all Components with non-focusable
peers. This is the default FocusTraversalPolicy for all AWT Containers.

The focusability of a peer is implementation-dependent. Sun recommends that
all implementations for a particular native platform construct peers with
the same focusability. The recommendations for Windows and Unix are that
Canvases, Labels, Panels, Scrollbars, ScrollPanes, Windows, and lightweight
Components have non-focusable peers, and all other Components have focusable
peers. These recommendations are used in the Sun AWT implementations. Note
that the focusability of a Component's peer is different from, and does not
impact, the focusability of the Component itself.

Please see

How to Use the Focus Subsystem,
a section in The Java Tutorial, and the
Focus Specification
for more information.

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.

Please see

How to Use the Focus Subsystem,
a section in The Java Tutorial, and the
Focus Specification
for more information.

The Desktop class allows a Java application to launch
associated applications registered on the native desktop to handle
a URI or a file.

 Supported operations include:

  launching the user-default browser to show a specified
      URI;
  launching the user-default mail client with an optional
      mailto URI;
  launching a registered application to open, edit or print a
      specified file.


 This class provides methods corresponding to these
operations. The methods look for the associated application
registered on the current platform, and launch it to handle a URI
or file. If there is no associated application or the associated
application fails to be launched, an exception is thrown.

 An application is registered to a URI or file type; for
example, the "sxi" file extension is typically registered
to StarOffice.  The mechanism of registering, accessing, and
launching the associated application is platform-dependent.

 Each operation is an action type represented by the Desktop.Action class.

 Note: when some action is invoked and the associated
application is executed, it will be executed on the same system as
the one on which the Java application was launched.

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 may have another window 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 Frame for
more information.

A dialog can be either modeless (the default) or modal.  A modal
dialog is one which blocks input to some other top-level windows
in the application, except for any windows created with the dialog
as their owner. See AWT Modality
specification for details.

Dialogs are capable of generating the following
WindowEvents:
WindowOpened, WindowClosing,
WindowClosed, WindowActivated,
WindowDeactivated, WindowGainedFocus,
WindowLostFocus.

The Dimension class encapsulates the width and
height of a component (in integer precision) in a single object.
The class is
associated with certain properties of components. Several methods
defined by the Component class and the
LayoutManager interface return a
Dimension object.

Normally the values of width
and height are non-negative integers.
The constructors that allow you to create a dimension do
not prevent you from setting a negative value for these properties.
If the value of width or height is
negative, the behavior of some methods defined by other objects is
undefined.

The DisplayMode class encapsulates the bit depth, height,
width, and refresh rate of a GraphicsDevice. The ability to
change graphics device's display mode is platform- and
configuration-dependent and may not always be available
(see GraphicsDevice.isDisplayChangeSupported()).

For more information on full-screen exclusive mode API, see the

Full-Screen Exclusive Mode API Tutorial.

During DnD operations it is possible that a user may wish to drop the
subject of the operation on a region of a scrollable GUI control that is
not currently visible to the user.

In such situations it is desirable that the GUI control detect this
and institute a scroll operation in order to make obscured region(s)
visible to the user. This feature is known as autoscrolling.

If a GUI control is both an active DropTarget
and is also scrollable, it
can receive notifications of autoscrolling gestures by the user from
the DnD system by implementing this interface.

An autoscrolling gesture is initiated by the user by keeping the drag
cursor motionless with a border region of the Component,
referred to as
the "autoscrolling region", for a predefined period of time, this will
result in repeated scroll requests to the Component
until the drag Cursor resumes its motion.

This class contains constant values representing
the type of action(s) to be performed by a Drag and Drop operation.

A DragGestureEvent is passed
to DragGestureListener's
dragGestureRecognized() method
when a particular DragGestureRecognizer detects that a
platform dependent drag initiating gesture has occurred
on the Component that it is tracking.

The action field of any DragGestureEvent instance should take one of the following
values:

 DnDConstants.ACTION_COPY
 DnDConstants.ACTION_MOVE
 DnDConstants.ACTION_LINK

Assigning the value different from listed above will cause an unspecified behavior.

The listener interface for receiving drag gesture events.
This interface is intended for a drag gesture recognition
implementation. See a specification for DragGestureRecognizer
for details on how to register the listener interface.
Upon recognition of a drag gesture the DragGestureRecognizer calls this interface's
dragGestureRecognized()
method and passes a DragGestureEvent.

The DragGestureRecognizer is an
abstract base class for the specification
of a platform-dependent listener that can be associated with a particular
Component in order to
identify platform-dependent drag initiating gestures.

The appropriate DragGestureRecognizer
subclass instance is obtained from the
DragSource associated with
a particular Component, or from the Toolkit object via its
createDragGestureRecognizer()
method.

Once the DragGestureRecognizer
is associated with a particular Component
it will register the appropriate listener interfaces on that
Component
in order to track the input events delivered to the Component.

Once the DragGestureRecognizer identifies a sequence of events
on the Component as a drag initiating gesture, it will notify
its unicast DragGestureListener by
invoking its
gestureRecognized()
method.

When a concrete DragGestureRecognizer
instance detects a drag initiating
gesture on the Component it is associated with,
it fires a DragGestureEvent to
the DragGestureListener registered on
its unicast event source for DragGestureListener
events. This DragGestureListener is responsible
for causing the associated
DragSource to start the Drag and Drop operation (if
appropriate).

The DragSource is the entity responsible
for the initiation of the Drag
and Drop operation, and may be used in a number of scenarios:

1 default instance per JVM for the lifetime of that JVM.
1 instance per class of potential Drag Initiator object (e.g
TextField). [implementation dependent]
1 per instance of a particular
Component, or application specific
object associated with a Component
instance in the GUI. [implementation dependent]
Some other arbitrary association. [implementation dependent]


Once the DragSource is
obtained, a DragGestureRecognizer should
also be obtained to associate the DragSource
with a particular
Component.

The initial interpretation of the user's gesture,
and the subsequent starting of the drag operation
are the responsibility of the implementing
Component, which is usually
implemented by a DragGestureRecognizer.

When a drag gesture occurs, the
DragSource's
startDrag() method shall be
invoked in order to cause processing
of the user's navigational
gestures and delivery of Drag and Drop
protocol notifications. A
DragSource shall only
permit a single Drag and Drop operation to be
current at any one time, and shall
reject any further startDrag() requests
by throwing an IllegalDnDOperationException
until such time as the extant operation is complete.

The startDrag() method invokes the
createDragSourceContext() method to
instantiate an appropriate
DragSourceContext
and associate the DragSourceContextPeer
with that.

If the Drag and Drop System is
unable to initiate a drag operation for
some reason, the startDrag() method throws
a java.awt.dnd.InvalidDnDOperationException
to signal such a condition. Typically this
exception is thrown when the underlying platform
system is either not in a state to
initiate a drag, or the parameters specified are invalid.

Note that during the drag, the
set of operations exposed by the source
at the start of the drag operation may not change
until the operation is complete.
The operation(s) are constant for the
duration of the operation with respect to the
DragSource.

An abstract adapter class for receiving drag source events. The methods in
this class are empty. This class exists only as a convenience for creating
listener objects.

Extend this class to create a DragSourceEvent listener
and override the methods for the events of interest. (If you implement the
DragSourceListener interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with
a DragSource. When the drag enters, moves over, or exits
a drop site, when the drop action changes, and when the drag ends, the
relevant method in the listener object is invoked, and the
DragSourceEvent is passed to it.

The drop site is associated with the previous dragEnter()
invocation if the latest invocation of dragEnter() on this
adapter corresponds to that drop site and is not followed by a
dragExit() invocation on this adapter.

The DragSourceContext class is responsible for managing the
initiator side of the Drag and Drop protocol. In particular, it is responsible
for managing drag event notifications to the
java.awt.dnd.DragSourceListeners
and java.awt.dnd.DragSourceMotionListeners, and providing the
Transferable representing the source data for the drag operation.

Note that the DragSourceContext itself
implements the DragSourceListener and
DragSourceMotionListener interfaces.
This is to allow the platform peer
(the DragSourceContextPeer instance)
created by the DragSource to notify
the DragSourceContext of
state changes in the ongoing operation. This allows the
DragSourceContext object to interpose
itself between the platform and the
listeners provided by the initiator of the drag operation.


By default, DragSourceContext sets the cursor as appropriate
for the current state of the drag and drop operation. For example, if
the user has chosen the move action,
and the pointer is over a target that accepts
the move action, the default move cursor is shown. When
the pointer is over an area that does not accept the transfer,
the default "no drop" cursor is shown.

This default handling mechanism is disabled when a custom cursor is set
by the setCursor(java.awt.Cursor) method. When the default handling is disabled,
it becomes the responsibility
of the developer to keep the cursor up to date, by listening
to the DragSource events and calling the setCursor() method.
Alternatively, you can provide custom cursor behavior by providing
custom implementations of the DragSource
and the DragSourceContext classes.

The DragSourceDragEvent is
delivered from the DragSourceContextPeer,
via the DragSourceContext, to the DragSourceListener
registered with that DragSourceContext and with its associated
DragSource.

The DragSourceDragEvent reports the target drop action
and the user drop action that reflect the current state of
the drag operation.

Target drop action is one of DnDConstants that represents
the drop action selected by the current drop target if this drop action is
supported by the drag source or DnDConstants.ACTION_NONE if this
drop action is not supported by the drag source.

User drop action depends on the drop actions supported by the drag
source and the drop action selected by the user. The user can select a drop
action by pressing modifier keys during the drag operation:


  Ctrl  Shift -> ACTION_LINK
  Ctrl         -> ACTION_COPY
  Shift        -> ACTION_MOVE
If the user selects a drop action, the user drop action is one of
DnDConstants that represents the selected drop action if this
drop action is supported by the drag source or
DnDConstants.ACTION_NONE if this drop action is not supported
by the drag source.

If the user doesn't select a drop action, the set of
DnDConstants that represents the set of drop actions supported
by the drag source is searched for DnDConstants.ACTION_MOVE,
then for DnDConstants.ACTION_COPY, then for
DnDConstants.ACTION_LINK and the user drop action is the
first constant found. If no constant is found the user drop action
is DnDConstants.ACTION_NONE.

The DragSourceDropEvent is delivered
from the DragSourceContextPeer,
via the DragSourceContext, to the dragDropEnd
method of DragSourceListeners registered with that
DragSourceContext and with its associated
DragSource.
It contains sufficient information for the
originator of the operation
to provide appropriate feedback to the end user
when the operation completes.

This class is the base class for
DragSourceDragEvent and
DragSourceDropEvent.

DragSourceEvents are generated whenever the drag enters, moves
over, or exits a drop site, when the drop action changes, and when the drag
ends. The location for the generated DragSourceEvent specifies
the mouse cursor location in screen coordinates at the moment this event
occurred.

In a multi-screen environment without a virtual device, the cursor location is
specified in the coordinate system of the initiator
GraphicsConfiguration. The initiator
GraphicsConfiguration is the GraphicsConfiguration
of the Component on which the drag gesture for the current drag
operation was recognized. If the cursor location is outside the bounds of
the initiator GraphicsConfiguration, the reported coordinates are
clipped to fit within the bounds of that GraphicsConfiguration.

In a multi-screen environment with a virtual device, the location is specified
in the corresponding virtual coordinate system. If the cursor location is
outside the bounds of the virtual device the reported coordinates are
clipped to fit within the bounds of the virtual device.

The DragSourceListener defines the
event interface for originators of
Drag and Drop operations to track the state of the user's gesture, and to
provide appropriate "drag over"
feedback to the user throughout the
Drag and Drop operation.

The drop site is associated with the previous dragEnter()
invocation if the latest invocation of dragEnter() on this
listener:

corresponds to that drop site and
 is not followed by a dragExit() invocation on this listener.

A listener interface for receiving mouse motion events during a drag
operation.

The class that is interested in processing mouse motion events during
a drag operation either implements this interface or extends the abstract
DragSourceAdapter class (overriding only the methods of
interest).

Create a listener object using that class and then register it with
a DragSource. Whenever the mouse moves during a drag
operation initiated with this DragSource, that object's
dragMouseMoved method is invoked, and the
DragSourceDragEvent is passed to it.

The DropTarget is associated
with a Component when that Component
wishes
to accept drops during Drag and Drop operations.

 Each
DropTarget is associated with a FlavorMap.
The default FlavorMap hereafter designates the
FlavorMap returned by SystemFlavorMap.getDefaultFlavorMap().

this protected nested class implements autoscrolling

An abstract adapter class for receiving drop target events. The methods in
this class are empty. This class exists only as a convenience for creating
listener objects.

Extend this class to create a DropTargetEvent listener
and override the methods for the events of interest. (If you implement the
DropTargetListener interface, you have to define all of
the methods in it. This abstract class defines a null implementation for
every method except drop(DropTargetDropEvent), so you only have
to define methods for events you care about.) You must provide an
implementation for at least drop(DropTargetDropEvent). This
method cannot have a null implementation because its specification requires
that you either accept or reject the drop, and, if accepted, indicate
whether the drop was successful.

Create a listener object using the extended class and then register it with
a DropTarget. When the drag enters, moves over, or exits
the operable part of the drop site for that DropTarget, when
the drop action changes, and when the drop occurs, the relevant method in
the listener object is invoked, and the DropTargetEvent is
passed to it.

The operable part of the drop site for the DropTarget is
the part of the associated Component's geometry that is not
obscured by an overlapping top-level window or by another
Component higher in the Z-order that has an associated active
DropTarget.

During the drag, the data associated with the current drag operation can be
retrieved by calling getTransferable() on
DropTargetDragEvent instances passed to the listener's
methods.

Note that getTransferable() on the
DropTargetDragEvent instance should only be called within the
respective listener's method and all the necessary data should be retrieved
from the returned Transferable before that method returns.

A DropTargetContext is created
whenever the logical cursor associated
with a Drag and Drop operation coincides with the visible geometry of
a Component associated with a DropTarget.
The DropTargetContext provides
the mechanism for a potential receiver
of a drop operation to both provide the end user with the appropriate
drag under feedback, but also to effect the subsequent data transfer
if appropriate.

The DropTargetDragEvent is delivered to a
DropTargetListener via its
dragEnter() and dragOver() methods.

The DropTargetDragEvent reports the source drop actions
and the user drop action that reflect the current state of
the drag operation.

Source drop actions is a bitwise mask of DnDConstants
that represents the set of drop actions supported by the drag source for
this drag operation.

User drop action depends on the drop actions supported by the drag
source and the drop action selected by the user. The user can select a drop
action by pressing modifier keys during the drag operation:


  Ctrl  Shift -> ACTION_LINK
  Ctrl         -> ACTION_COPY
  Shift        -> ACTION_MOVE
If the user selects a drop action, the user drop action is one of
DnDConstants that represents the selected drop action if this
drop action is supported by the drag source or
DnDConstants.ACTION_NONE if this drop action is not supported
by the drag source.

If the user doesn't select a drop action, the set of
DnDConstants that represents the set of drop actions supported
by the drag source is searched for DnDConstants.ACTION_MOVE,
then for DnDConstants.ACTION_COPY, then for
DnDConstants.ACTION_LINK and the user drop action is the
first constant found. If no constant is found the user drop action
is DnDConstants.ACTION_NONE.

The DropTargetDropEvent is delivered
via the DropTargetListener drop() method.

The DropTargetDropEvent reports the source drop actions
and the user drop action that reflect the current state of the
drag-and-drop operation.

Source drop actions is a bitwise mask of DnDConstants
that represents the set of drop actions supported by the drag source for
this drag-and-drop operation.

User drop action depends on the drop actions supported by the drag
source and the drop action selected by the user. The user can select a drop
action by pressing modifier keys during the drag operation:


  Ctrl  Shift -> ACTION_LINK
  Ctrl         -> ACTION_COPY
  Shift        -> ACTION_MOVE
If the user selects a drop action, the user drop action is one of
DnDConstants that represents the selected drop action if this
drop action is supported by the drag source or
DnDConstants.ACTION_NONE if this drop action is not supported
by the drag source.

If the user doesn't select a drop action, the set of
DnDConstants that represents the set of drop actions supported
by the drag source is searched for DnDConstants.ACTION_MOVE,
then for DnDConstants.ACTION_COPY, then for
DnDConstants.ACTION_LINK and the user drop action is the
first constant found. If no constant is found the user drop action
is DnDConstants.ACTION_NONE.

The DropTargetEvent is the base
class for both the DropTargetDragEvent
and the DropTargetDropEvent.
It encapsulates the current state of the Drag and
Drop operations, in particular the current
DropTargetContext.

The DropTargetListener interface
is the callback interface used by the
DropTarget class to provide
notification of DnD operations that involve
the subject DropTarget. Methods of
this interface may be implemented to provide
"drag under" visual feedback to the user throughout
the Drag and Drop operation.

Create a listener object by implementing the interface and then register it
with a DropTarget. When the drag enters, moves over, or exits
the operable part of the drop site for that DropTarget, when
the drop action changes, and when the drop occurs, the relevant method in
the listener object is invoked, and the DropTargetEvent is
passed to it.

The operable part of the drop site for the DropTarget is
the part of the associated Component's geometry that is not
obscured by an overlapping top-level window or by another
Component higher in the Z-order that has an associated active
DropTarget.

During the drag, the data associated with the current drag operation can be
retrieved by calling getTransferable() on
DropTargetDragEvent instances passed to the listener's
methods.

Note that getTransferable() on the
DropTargetDragEvent instance should only be called within the
respective listener's method and all the necessary data should be retrieved
from the returned Transferable before that method returns.

This exception is thrown by various methods in the java.awt.dnd package.
It is usually thrown to indicate that the target in question is unable
to undertake the requested operation that the present time, since the
underlying DnD system is not in the appropriate state.

This abstract subclass of DragGestureRecognizer
defines a DragGestureRecognizer
for mouse-based gestures.

Each platform implements its own concrete subclass of this class,
available via the Toolkit.createDragGestureRecognizer() method,
to encapsulate
the recognition of the platform dependent mouse gesture(s) that initiate
a Drag and Drop operation.

Mouse drag gesture recognizers should honor the
drag gesture motion threshold, available through
DragSource.getDragThreshold().
A drag gesture should be recognized only when the distance
in either the horizontal or vertical direction between
the location of the latest mouse dragged event and the
location of the corresponding mouse button pressed event
is greater than the drag gesture motion threshold.

Drag gesture recognizers created with
DragSource.createDefaultDragGestureRecognizer(java.awt.Component, int, java.awt.dnd.DragGestureListener)
follow this convention.

NOTE: The Event class is obsolete and is
available only for backwards compatibility.  It has been replaced
by the AWTEvent class and its subclasses.

Event is a platform-independent class that
encapsulates events from the platform's Graphical User
Interface in the Java 1.0 event model. In Java 1.1
and later versions, the Event class is maintained
only for backwards compatibility. The information in this
class description is provided to assist programmers in
converting Java 1.0 programs to the new event model.

In the Java 1.0 event model, an event contains an
id field
that indicates what type of event it is and which other
Event variables are relevant for the event.

For keyboard events, key
contains a value indicating which key was activated, and
modifiers contains the
modifiers for that event.  For the KEY_PRESS and KEY_RELEASE
event ids, the value of key is the unicode
character code for the key. For KEY_ACTION and
KEY_ACTION_RELEASE, the value of key is
one of the defined action-key identifiers in the
Event class (PGUP,
PGDN, F1, F2, etc).

A semantic event which indicates that a component-defined action occurred.
This high-level event is generated by a component (such as a
Button) when
the component-specific action occurs (such as being pressed).
The event is passed to every ActionListener object
that registered to receive such events using the component's
addActionListener method.

Note: To invoke an ActionEvent on a
Button using the keyboard, use the Space bar.

The object that implements the ActionListener interface
gets this ActionEvent when the event occurs. The listener
is therefore spared the details of processing individual mouse movements
and mouse clicks, and can instead process a "meaningful" (semantic)
event like "button pressed".

An unspecified behavior will be caused if the id parameter
of any particular ActionEvent instance is not
in the range from ACTION_FIRST to ACTION_LAST.

The listener interface for receiving action events.
The class that is interested in processing an action event
implements this interface, and the object created with that
class is registered with a component, using the component's
addActionListener method. When the action event
occurs, that object's actionPerformed method is
invoked.

                 UNIT_INCREMENT
                 UNIT_DECREMENT
                 BLOCK_INCREMENT
                 BLOCK_DECREMENT
                 TRACK

The adjustment event emitted by Adjustable objects like
Scrollbar and ScrollPane.
When the user changes the value of the scrolling component,
it receives an instance of AdjustmentEvent.

An unspecified behavior will be caused if the id parameter
of any particular AdjustmentEvent instance is not
in the range from ADJUSTMENT_FIRST to ADJUSTMENT_LAST.

The type of any AdjustmentEvent instance takes one of the following
values:

                     UNIT_INCREMENT
                     UNIT_DECREMENT
                     BLOCK_INCREMENT
                     BLOCK_DECREMENT
                     TRACK

Assigning the value different from listed above will cause an unspecified behavior.

The listener interface for receiving adjustment events.

The listener interface for receiving notification of events
dispatched to objects that are instances of Component or
MenuComponent or their subclasses.  Unlike the other EventListeners
in this package, AWTEventListeners passively observe events
being dispatched in the AWT, system-wide.  Most applications
should never use this class; applications which might use
AWTEventListeners include event recorders for automated testing,
and facilities such as the Java Accessibility package.

The class that is interested in monitoring AWT events
implements this interface, and the object created with that
class is registered with the Toolkit, using the Toolkit's
addAWTEventListener method.  When an event is
dispatched anywhere in the AWT, that object's
eventDispatched method is invoked.

A class which extends the EventListenerProxy
specifically for adding an AWTEventListener
for a specific event mask.
Instances of this class can be added as AWTEventListeners
to a Toolkit object.

The getAWTEventListeners method of Toolkit
can return a mixture of AWTEventListener
and AWTEventListenerProxy objects.

An abstract adapter class for receiving component events.
The methods in this class are empty. This class exists as
convenience for creating listener objects.

Extend this class to create a ComponentEvent listener
and override the methods for the events of interest. (If you implement the
ComponentListener interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you can only have to define methods for events you care about.)

Create a listener object using your class and then register it with a
component using the component's addComponentListener
method. When the component's size, location, or visibility
changes, the relevant method in the listener object is invoked,
and the ComponentEvent is passed to it.

A low-level event which indicates that a component moved, changed
size, or changed visibility (also, the root class for the other
component-level events).

Component events are provided for notification purposes ONLY;
The AWT will automatically handle component moves and resizes
internally so that GUI layout works properly regardless of
whether a program is receiving these events or not.

In addition to serving as the base class for other component-related
events (InputEvent, FocusEvent, WindowEvent, ContainerEvent),
this class defines the events that indicate changes in
a component's size, position, or visibility.

This low-level event is generated by a component object (such as a
List) when the component is moved, resized, rendered invisible, or made
visible again. The event is passed to every ComponentListener
or ComponentAdapter object which registered to receive such
events using the component's addComponentListener method.
(ComponentAdapter objects implement the
ComponentListener interface.) Each such listener object
gets this ComponentEvent when the event occurs.

An unspecified behavior will be caused if the id parameter
of any particular ComponentEvent instance is not
in the range from COMPONENT_FIRST to COMPONENT_LAST.

The listener interface for receiving component events.
The class that is interested in processing a component event
either implements this interface (and all the methods it
contains) or extends the abstract ComponentAdapter class
(overriding only the methods of interest).
The listener object created from that class is then registered with a
component using the component's addComponentListener
method. When the component's size, location, or visibility
changes, the relevant method in the listener object is invoked,
and the ComponentEvent is passed to it.

Component events are provided for notification purposes ONLY;
The AWT will automatically handle component moves and resizes
internally so that GUI layout works properly regardless of
whether a program registers a ComponentListener or not.

An abstract adapter class for receiving container events.
The methods in this class are empty. This class exists as
convenience for creating listener objects.

Extend this class to create a ContainerEvent listener
and override the methods for the events of interest. (If you implement the
ContainerListener interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you can only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with
a component using the component's addContainerListener
method. When the container's contents change because a component has
been added or removed, the relevant method in the listener object is invoked,
and the ContainerEvent is passed to it.

A low-level event which indicates that a container's contents
changed because a component was added or removed.

Container events are provided for notification purposes ONLY;
The AWT will automatically handle changes to the containers
contents internally so that the program works properly regardless of
whether the program is receiving these events or not.

This low-level event is generated by a container object (such as a
Panel) when a component is added to it or removed from it.
The event is passed to every ContainerListener
or ContainerAdapter object which registered to receive such
events using the component's addContainerListener method.
(ContainerAdapter objects implement the
ContainerListener interface.) Each such listener object
gets this ContainerEvent when the event occurs.

An unspecified behavior will be caused if the id parameter
of any particular ContainerEvent instance is not
in the range from CONTAINER_FIRST to CONTAINER_LAST.

The listener interface for receiving container events.
The class that is interested in processing a container event
either implements this interface (and all the methods it
contains) or extends the abstract ContainerAdapter class
(overriding only the methods of interest).
The listener object created from that class is then registered with a
component using the component's addContainerListener
method. When the container's contents change because a component
has been added or removed, the relevant method in the listener object
is invoked, and the ContainerEvent is passed to it.

Container events are provided for notification purposes ONLY;
The AWT will automatically handle add and remove operations
internally so the program works properly regardless of
whether the program registers a ContainerListener or not.

An abstract adapter class for receiving keyboard focus events.
The methods in this class are empty. This class exists as
convenience for creating listener objects.

Extend this class to create a FocusEvent listener
and override the methods for the events of interest. (If you implement the
FocusListener interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you can only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with
a component using the component's addFocusListener
method. When the component gains or loses the keyboard focus,
the relevant method in the listener object is invoked,
and the FocusEvent is passed to it.

A low-level event which indicates that a Component has gained or lost the
input focus. This low-level event is generated by a Component (such as a
TextField). The event is passed to every FocusListener or
FocusAdapter object which registered to receive such events
using the Component's addFocusListener method. (
FocusAdapter objects implement the FocusListener
interface.) Each such listener object gets this FocusEvent when
the event occurs.

There are two levels of focus events: permanent and temporary. Permanent
focus change events occur when focus is directly moved from one Component to
another, such as through a call to requestFocus() or as the user uses the
TAB key to traverse Components. Temporary focus change events occur when
focus is temporarily lost for a Component as the indirect result of another
operation, such as Window deactivation or a Scrollbar drag. In this case,
the original focus state will automatically be restored once that operation
is finished, or, for the case of Window deactivation, when the Window is
reactivated. Both permanent and temporary focus events are delivered using
the FOCUS_GAINED and FOCUS_LOST event ids; the level may be distinguished in
the event using the isTemporary() method.

An unspecified behavior will be caused if the id parameter
of any particular FocusEvent instance is not
in the range from FOCUS_FIRST to FOCUS_LAST.

The listener interface for receiving keyboard focus events on
a component.
The class that is interested in processing a focus event
either implements this interface (and all the methods it
contains) or extends the abstract FocusAdapter class
(overriding only the methods of interest).
The listener object created from that class is then registered with a
component using the component's addFocusListener
method. When the component gains or loses the keyboard focus,
the relevant method in the listener object
is invoked, and the FocusEvent is passed to it.

An abstract adapter class for receiving ancestor moved and resized events.
The methods in this class are empty. This class exists as a
convenience for creating listener objects.

Extend this class and override the method for the event of interest. (If
you implement the HierarchyBoundsListener interface, you have
to define both methods in it. This abstract class defines null methods for
them both, so you only have to define the method for the event you care
about.)

Create a listener object using your class and then register it with a
Component using the Component's addHierarchyBoundsListener
method. When the hierarchy to which the Component belongs changes by
resize or movement of an ancestor, the relevant method in the listener
object is invoked, and the HierarchyEvent is passed to it.

The listener interface for receiving ancestor moved and resized events.
The class that is interested in processing these events either implements
this interface (and all the methods it contains) or extends the abstract
HierarchyBoundsAdapter class (overriding only the method of
interest).
The listener object created from that class is then registered with a
Component using the Component's addHierarchyBoundsListener
method. When the hierarchy to which the Component belongs changes by
the resizing or movement of an ancestor, the relevant method in the listener
object is invoked, and the HierarchyEvent is passed to it.

Hierarchy events are provided for notification purposes ONLY;
The AWT will automatically handle changes to the hierarchy internally so
that GUI layout works properly regardless of whether a
program registers an HierarchyBoundsListener or not.

 addition of an ancestor
 removal of an ancestor
 hierarchy made displayable
 hierarchy made undisplayable
 hierarchy shown on the screen (both visible and displayable)
 hierarchy hidden on the screen (either invisible or undisplayable)

 an ancestor was resized
 an ancestor was moved

An event which indicates a change to the Component
hierarchy to which Component belongs.

Hierarchy Change Events (HierarchyListener)

     addition of an ancestor
     removal of an ancestor
     hierarchy made displayable
     hierarchy made undisplayable
     hierarchy shown on the screen (both visible and displayable)
     hierarchy hidden on the screen (either invisible or undisplayable)

Ancestor Reshape Events (HierarchyBoundsListener)

     an ancestor was resized
     an ancestor was moved



Hierarchy events are provided for notification purposes ONLY.
The AWT will automatically handle changes to the hierarchy internally so
that GUI layout and displayability works properly regardless of whether a
program is receiving these events or not.

This event is generated by a Container object (such as a Panel) when the
Container is added, removed, moved, or resized, and passed down the
hierarchy. It is also generated by a Component object when that object's
addNotify, removeNotify, show, or
hide method is called. The ANCESTOR_MOVED and
ANCESTOR_RESIZED
events are dispatched to every HierarchyBoundsListener or
HierarchyBoundsAdapter object which registered to receive
such events using the Component's addHierarchyBoundsListener
method. (HierarchyBoundsAdapter objects implement the
HierarchyBoundsListener interface.) The HIERARCHY_CHANGED events are
dispatched to every HierarchyListener object which registered
to receive such events using the Component's addHierarchyListener
 method. Each such listener object gets this HierarchyEvent
 when the event occurs.

An unspecified behavior will be caused if the id parameter
of any particular HierarchyEvent instance is not
in the range from HIERARCHY_FIRST to HIERARCHY_LAST.

The changeFlags parameter of any HierarchyEvent instance takes one of the following
values:

 HierarchyEvent.PARENT_CHANGED
 HierarchyEvent.DISPLAYABILITY_CHANGED
 HierarchyEvent.SHOWING_CHANGED

Assigning the value different from listed above will cause unspecified behavior.

The listener interface for receiving hierarchy changed events.
The class that is interested in processing a hierarchy changed event
should implement this interface.
The listener object created from that class is then registered with a
Component using the Component's addHierarchyListener
method. When the hierarchy to which the Component belongs changes, the
hierarchyChanged method in the listener object is invoked,
and the HierarchyEvent is passed to it.

Hierarchy events are provided for notification purposes ONLY;
The AWT will automatically handle changes to the hierarchy internally so
that GUI layout, displayability, and visibility work properly regardless
of whether a program registers a HierarchyListener or not.

The root event class for all component-level input events.

Input events are delivered to listeners before they are
processed normally by the source where they originated.
This allows listeners and component subclasses to "consume"
the event so that the source will not process them in their
default manner.  For example, consuming mousePressed events
on a Button component will prevent the Button from being
activated.

Input method events contain information about text that is being
composed using an input method. Whenever the text changes, the
input method sends an event. If the text component that's currently
using the input method is an active client, the event is dispatched
to that component. Otherwise, it is dispatched to a separate
composition window.


The text included with the input method event consists of two parts:
committed text and composed text. Either part may be empty. The two
parts together replace any uncommitted composed text sent in previous events,
or the currently selected committed text.
Committed text should be integrated into the text component's persistent
data, it will not be sent again. Composed text may be sent repeatedly,
with changes to reflect the user's editing operations. Committed text
always precedes composed text.

The listener interface for receiving input method events. A text editing
component has to install an input method event listener in order to work
with input methods.


The text editing component also has to provide an instance of InputMethodRequests.

An event which executes the run() method on a Runnable
 when dispatched by the AWT event dispatcher thread. This class can
be used as a reference implementation of ActiveEvent rather
than declaring a new class and defining dispatch().

Instances of this class are placed on the EventQueue by calls
to invokeLater and invokeAndWait. Client code
can use this fact to write replacement functions for invokeLater
 and invokeAndWait without writing special-case code
in any AWTEventListener objects.

An unspecified behavior will be caused if the id parameter
of any particular InvocationEvent instance is not
in the range from INVOCATION_FIRST to INVOCATION_LAST.

                 ItemEvent.SELECTED
                 ItemEvent.DESELECTED

A semantic event which indicates that an item was selected or deselected.
This high-level event is generated by an ItemSelectable object (such as a
List) when an item is selected or deselected by the user.
The event is passed to every ItemListener object which
registered to receive such events using the component's
addItemListener method.

The object that implements the ItemListener interface gets
this ItemEvent when the event occurs. The listener is
spared the details of processing individual mouse movements and mouse
clicks, and can instead process a "meaningful" (semantic) event like
"item selected" or "item deselected".

An unspecified behavior will be caused if the id parameter
of any particular ItemEvent instance is not
in the range from ITEM_FIRST to ITEM_LAST.

The stateChange of any ItemEvent instance takes one of the following
values:

                     ItemEvent.SELECTED
                     ItemEvent.DESELECTED

Assigning the value different from listed above will cause an unspecified behavior.

The listener interface for receiving item events.
The class that is interested in processing an item event
implements this interface. The object created with that
class is then registered with a component using the
component's addItemListener method. When an
item-selection event occurs, the listener object's
itemStateChanged method is invoked.

An abstract adapter class for receiving keyboard events.
The methods in this class are empty. This class exists as
convenience for creating listener objects.

Extend this class to create a KeyEvent listener
and override the methods for the events of interest. (If you implement the
KeyListener interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you can only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with
a component using the component's addKeyListener
method. When a key is pressed, released, or typed,
the relevant method in the listener object is invoked,
and the KeyEvent is passed to it.

KEY_PRESSED
KEY_TYPED (is only generated if a valid Unicode character could be generated.)
KEY_RELEASED

An event which indicates that a keystroke occurred in a component.

This low-level event is generated by a component object (such as a text
field) when a key is pressed, released, or typed.
The event is passed to every KeyListener
or KeyAdapter object which registered to receive such
events using the component's addKeyListener method.
(KeyAdapter objects implement the
KeyListener interface.)  Each such listener object
gets this KeyEvent when the event occurs.

"Key typed" events are higher-level and generally do not depend on
the platform or keyboard layout.  They are generated when a Unicode character
is entered, and are the preferred way to find out about character input.
In the simplest case, a key typed event is produced by a single key press
(e.g., 'a').  Often, however, characters are produced by series of key
presses (e.g., 'shift'  'a'), and the mapping from key pressed events to
key typed events may be many-to-one or many-to-many.  Key releases are not
usually necessary to generate a key typed event, but there are some cases
where the key typed event is not generated until a key is released (e.g.,
entering ASCII sequences via the Alt-Numpad method in Windows).
No key typed events are generated for keys that don't generate Unicode
characters (e.g., action keys, modifier keys, etc.).

The getKeyChar method always returns a valid Unicode character or
CHAR_UNDEFINED.  Character input is reported by KEY_TYPED events:
KEY_PRESSED and KEY_RELEASED events are not necessarily associated
with character input.  Therefore, the result of the getKeyChar method
is guaranteed to be meaningful only for KEY_TYPED events.

For key pressed and key released events, the getKeyCode method returns
the event's keyCode.  For key typed events, the getKeyCode method
always returns VK_UNDEFINED. The getExtendedKeyCode method
may also be used with many international keyboard layouts.


"Key pressed" and "key released" events are lower-level and depend
on the platform and keyboard layout. They are generated whenever a key is
pressed or released, and are the only way to find out about keys that don't
generate character input (e.g., action keys, modifier keys, etc.). The key
being pressed or released is indicated by the getKeyCode and getExtendedKeyCode
methods, which return a virtual key code.


Virtual key codes are used to report which keyboard key has
been pressed, rather than a character generated by the combination
of one or more keystrokes (such as "A", which comes from shift and "a").


For example, pressing the Shift key will cause a KEY_PRESSED event
with a VK_SHIFT keyCode, while pressing the 'a' key will result in
a VK_A keyCode.  After the 'a' key is released, a KEY_RELEASED event
will be fired with VK_A. Separately, a KEY_TYPED event with a keyChar
value of 'A' is generated.


Pressing and releasing a key on the keyboard results in the generating
the following key events (in order):


    KEY_PRESSED
    KEY_TYPED (is only generated if a valid Unicode character could be generated.)
    KEY_RELEASED

But in some cases (e.g. auto-repeat or input method is activated) the order
could be different (and platform dependent).


Notes:

Key combinations which do not result in Unicode characters, such as action
keys like F1 and the HELP key, do not generate KEY_TYPED events.
Not all keyboards or systems are capable of generating all
virtual key codes.  No attempt is made in Java to generate these keys
artificially.
Virtual key codes do not identify a physical key: they depend on the
platform and keyboard layout. For example, the key that generates VK_Q
when using a U.S. keyboard layout will generate VK_A when using a French
keyboard layout.
The key that generates VK_Q when using a U.S. keyboard layout also
generates a unique code for Russian or Hebrew layout. There is no a
VK_ constant for these and many other codes in various layouts. These codes
may be obtained by using getExtendedKeyCode and are used whenever
a VK_ constant is used.
Not all characters have a keycode associated with them.  For example,
there is no keycode for the question mark because there is no keyboard
for which it appears on the primary layer.
In order to support the platform-independent handling of action keys,
the Java platform uses a few additional virtual key constants for functions
that would otherwise have to be recognized by interpreting virtual key codes
and modifiers. For example, for Japanese Windows keyboards, VK_ALL_CANDIDATES
is returned instead of VK_CONVERT with the ALT modifier.
As specified in Focus Specification
key events are dispatched to the focus owner by default.



WARNING: Aside from those keys that are defined by the Java language
(VK_ENTER, VK_BACK_SPACE, and VK_TAB), do not rely on the values of the VK_
constants.  Sun reserves the right to change these values as needed
to accommodate a wider range of keyboards in the future.

An unspecified behavior will be caused if the id parameter
of any particular KeyEvent instance is not
in the range from KEY_FIRST to KEY_LAST.

The listener interface for receiving keyboard events (keystrokes).
The class that is interested in processing a keyboard event
either implements this interface (and all the methods it
contains) or extends the abstract KeyAdapter class
(overriding only the methods of interest).

The listener object created from that class is then registered with a
component using the component's addKeyListener
method. A keyboard event is generated when a key is pressed, released,
or typed. The relevant method in the listener
object is then invoked, and the KeyEvent is passed to it.

An abstract adapter class for receiving mouse events.
The methods in this class are empty. This class exists as
convenience for creating listener objects.

Mouse events let you track when a mouse is pressed, released, clicked,
moved, dragged, when it enters a component, when it exits and
when a mouse wheel is moved.

Extend this class to create a MouseEvent
(including drag and motion events) or/and MouseWheelEvent
listener and override the methods for the events of interest. (If you implement the
MouseListener,
MouseMotionListener
interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you can only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with
a component using the component's addMouseListener
addMouseMotionListener, addMouseWheelListener
methods.
The relevant method in the listener object is invoked  and the MouseEvent
or MouseWheelEvent  is passed to it in following cases:

when a mouse button is pressed, released, or clicked (pressed and  released)
when the mouse cursor enters or exits the component
when the mouse wheel rotated, or mouse moved or dragged

a mouse button is pressed
a mouse button is released
a mouse button is clicked (pressed and released)
the mouse cursor enters the unobscured part of component's geometry
the mouse cursor exits the unobscured part of component's geometry

the mouse is moved
the mouse is dragged

An event which indicates that a mouse action occurred in a component.
A mouse action is considered to occur in a particular component if and only
if the mouse cursor is over the unobscured part of the component's bounds
when the action happens.
For lightweight components, such as Swing's components, mouse events
are only dispatched to the component if the mouse event type has been
enabled on the component. A mouse event type is enabled by adding the
appropriate mouse-based EventListener to the component
(MouseListener or MouseMotionListener), or by invoking
Component.enableEvents(long) with the appropriate mask parameter
(AWTEvent.MOUSE_EVENT_MASK or AWTEvent.MOUSE_MOTION_EVENT_MASK).
If the mouse event type has not been enabled on the component, the
corresponding mouse events are dispatched to the first ancestor that
has enabled the mouse event type.

For example, if a MouseListener has been added to a component, or
enableEvents(AWTEvent.MOUSE_EVENT_MASK) has been invoked, then all
the events defined by MouseListener are dispatched to the component.
On the other hand, if a MouseMotionListener has not been added and
enableEvents has not been invoked with
AWTEvent.MOUSE_MOTION_EVENT_MASK, then mouse motion events are not
dispatched to the component. Instead the mouse motion events are
dispatched to the first ancestors that has enabled mouse motion
events.

This low-level event is generated by a component object for:

Mouse Events

    a mouse button is pressed
    a mouse button is released
    a mouse button is clicked (pressed and released)
    the mouse cursor enters the unobscured part of component's geometry
    the mouse cursor exits the unobscured part of component's geometry

 Mouse Motion Events

    the mouse is moved
    the mouse is dragged



A MouseEvent object is passed to every
MouseListener
or MouseAdapter object which is registered to receive
the "interesting" mouse events using the component's
addMouseListener method.
(MouseAdapter objects implement the
MouseListener interface.) Each such listener object
gets a MouseEvent containing the mouse event.

A MouseEvent object is also passed to every
MouseMotionListener or
MouseMotionAdapter object which is registered to receive
mouse motion events using the component's
addMouseMotionListener
method. (MouseMotionAdapter objects implement the
MouseMotionListener interface.) Each such listener object
gets a MouseEvent containing the mouse motion event.

When a mouse button is clicked, events are generated and sent to the
registered MouseListeners.
The state of modal keys can be retrieved using InputEvent.getModifiers()
and InputEvent.getModifiersEx().
The button mask returned by InputEvent.getModifiers() reflects
only the button that changed state, not the current state of all buttons.
(Note: Due to overlap in the values of ALT_MASK/BUTTON2_MASK and
META_MASK/BUTTON3_MASK, this is not always true for mouse events involving
modifier keys).
To get the state of all buttons and modifier keys, use
InputEvent.getModifiersEx().
The button which has changed state is returned by getButton()

For example, if the first mouse button is pressed, events are sent in the
following order:


   id              modifiers    button
   MOUSE_PRESSED:  BUTTON1_MASK BUTTON1
   MOUSE_RELEASED: BUTTON1_MASK BUTTON1
   MOUSE_CLICKED:  BUTTON1_MASK BUTTON1
When multiple mouse buttons are pressed, each press, release, and click
results in a separate event.

For example, if the user presses button 1 followed by
button 2, and then releases them in the same order,
the following sequence of events is generated:


   id              modifiers    button
   MOUSE_PRESSED:  BUTTON1_MASK BUTTON1
   MOUSE_PRESSED:  BUTTON2_MASK BUTTON2
   MOUSE_RELEASED: BUTTON1_MASK BUTTON1
   MOUSE_CLICKED:  BUTTON1_MASK BUTTON1
   MOUSE_RELEASED: BUTTON2_MASK BUTTON2
   MOUSE_CLICKED:  BUTTON2_MASK BUTTON2
If button 2 is released first, the
MOUSE_RELEASED/MOUSE_CLICKED pair
for BUTTON2_MASK arrives first,
followed by the pair for BUTTON1_MASK.

Some extra mouse buttons are added to extend the standard set of buttons
represented by the following constants:BUTTON1, BUTTON2, and BUTTON3.
Extra buttons have no assigned BUTTONx
constants as well as their button masks have no assigned BUTTONx_DOWN_MASK
constants. Nevertheless, ordinal numbers starting from 4 may be
used as button numbers (button ids). Values obtained by the
getMaskForButton(button) method may be used
as button masks.

MOUSE_DRAGGED events are delivered to the Component
in which the mouse button was pressed until the mouse button is released
(regardless of whether the mouse position is within the bounds of the
Component).  Due to platform-dependent Drag&Drop implementations,
MOUSE_DRAGGED events may not be delivered during a native
Drag&Drop operation.

In a multi-screen environment mouse drag events are delivered to the
Component even if the mouse position is outside the bounds of the
GraphicsConfiguration associated with that
Component. However, the reported position for mouse drag events
in this case may differ from the actual mouse position:

In a multi-screen environment without a virtual device:

The reported coordinates for mouse drag events are clipped to fit within the
bounds of the GraphicsConfiguration associated with
the Component.
In a multi-screen environment with a virtual device:

The reported coordinates for mouse drag events are clipped to fit within the
bounds of the virtual device associated with the Component.


An unspecified behavior will be caused if the id parameter
of any particular MouseEvent instance is not
in the range from MOUSE_FIRST to MOUSE_LAST-1
(MOUSE_WHEEL is not acceptable).

The listener interface for receiving "interesting" mouse events
(press, release, click, enter, and exit) on a component.
(To track mouse moves and mouse drags, use the
MouseMotionListener.)

The class that is interested in processing a mouse event
either implements this interface (and all the methods it
contains) or extends the abstract MouseAdapter class
(overriding only the methods of interest).

The listener object created from that class is then registered with a
component using the component's addMouseListener
method. A mouse event is generated when the mouse is pressed, released
clicked (pressed and released). A mouse event is also generated when
the mouse cursor enters or leaves a component. When a mouse event
occurs, the relevant method in the listener object is invoked, and
the MouseEvent is passed to it.

An abstract adapter class for receiving mouse motion events.
The methods in this class are empty. This class exists as
convenience for creating listener objects.

Mouse motion events occur when a mouse is moved or dragged.
(Many such events will be generated in a normal program.
To track clicks and other mouse events, use the MouseAdapter.)

Extend this class to create a MouseEvent listener
and override the methods for the events of interest. (If you implement the
MouseMotionListener interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you can only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with
a component using the component's addMouseMotionListener
method. When the mouse is moved or dragged, the relevant method in the
listener object is invoked and the MouseEvent is passed to it.

The listener interface for receiving mouse motion events on a component.
(For clicks and other mouse events, use the MouseListener.)

The class that is interested in processing a mouse motion event
either implements this interface (and all the methods it
contains) or extends the abstract MouseMotionAdapter class
(overriding only the methods of interest).

The listener object created from that class is then registered with a
component using the component's addMouseMotionListener
method. A mouse motion event is generated when the mouse is moved
or dragged. (Many such events will be generated). When a mouse motion event
occurs, the relevant method in the listener object is invoked, and
the MouseEvent is passed to it.

An event which indicates that the mouse wheel was rotated in a component.

A wheel mouse is a mouse which has a wheel in place of the middle button.
This wheel can be rotated towards or away from the user.  Mouse wheels are
most often used for scrolling, though other uses are possible.

A MouseWheelEvent object is passed to every MouseWheelListener
object which registered to receive the "interesting" mouse events using the
component's addMouseWheelListener method.  Each such listener
object gets a MouseEvent containing the mouse event.

Due to the mouse wheel's special relationship to scrolling Components,
MouseWheelEvents are delivered somewhat differently than other MouseEvents.
This is because while other MouseEvents usually affect a change on
the Component directly under the mouse
cursor (for instance, when clicking a button), MouseWheelEvents often have
an effect away from the mouse cursor (moving the wheel while
over a Component inside a ScrollPane should scroll one of the
Scrollbars on the ScrollPane).

MouseWheelEvents start delivery from the Component underneath the
mouse cursor.  If MouseWheelEvents are not enabled on the
Component, the event is delivered to the first ancestor
Container with MouseWheelEvents enabled.  This will usually be
a ScrollPane with wheel scrolling enabled.  The source
Component and x,y coordinates will be relative to the event's
final destination (the ScrollPane).  This allows a complex
GUI to be installed without modification into a ScrollPane, and
for all MouseWheelEvents to be delivered to the ScrollPane for
scrolling.

Some AWT Components are implemented using native widgets which
display their own scrollbars and handle their own scrolling.
The particular Components for which this is true will vary from
platform to platform.  When the mouse wheel is
moved over one of these Components, the event is delivered straight to
the native widget, and not propagated to ancestors.

Platforms offer customization of the amount of scrolling that
should take place when the mouse wheel is moved.  The two most
common settings are to scroll a certain number of "units"
(commonly lines of text in a text-based component) or an entire "block"
(similar to page-up/page-down).  The MouseWheelEvent offers
methods for conforming to the underlying platform settings.  These
platform settings can be changed at any time by the user.  MouseWheelEvents
reflect the most recent settings.

The MouseWheelEvent class includes methods for
getting the number of "clicks" by which the mouse wheel is rotated.
The getWheelRotation() method returns the integer number
of "clicks" corresponding to the number of notches by which the wheel was
rotated. In addition to this method, the MouseWheelEvent
class provides the getPreciseWheelRotation() method which returns
a double number of "clicks" in case a partial rotation occurred.
The getPreciseWheelRotation() method is useful if a mouse supports
a high-resolution wheel, such as a freely rotating wheel with no
notches. Applications can benefit by using this method to process
mouse wheel events more precisely, and thus, making visual perception
smoother.

The listener interface for receiving mouse wheel events on a component.
(For clicks and other mouse events, use the MouseListener.
For mouse movement and drags, use the MouseMotionListener.)

The class that is interested in processing a mouse wheel event
implements this interface (and all the methods it contains).

The listener object created from that class is then registered with a
component using the component's addMouseWheelListener
method. A mouse wheel event is generated when the mouse wheel is rotated.
When a mouse wheel event occurs, that object's mouseWheelMoved
method is invoked.

For information on how mouse wheel events are dispatched, see
the class description for MouseWheelEvent.

The component-level paint event.
This event is a special type which is used to ensure that
paint/update method calls are serialized along with the other
events delivered from the event queue.  This event is not
designed to be used with the Event Listener model; programs
should continue to override paint/update methods in order
render themselves properly.

An unspecified behavior will be caused if the id parameter
of any particular PaintEvent instance is not
in the range from PAINT_FIRST to PAINT_LAST.

A semantic event which indicates that an object's text changed.
This high-level event is generated by an object (such as a TextComponent)
when its text changes. The event is passed to
every TextListener object which registered to receive such
events using the component's addTextListener method.

The object that implements the TextListener interface gets
this TextEvent when the event occurs. The listener is
spared the details of processing individual mouse movements and key strokes
Instead, it can process a "meaningful" (semantic) event like "text changed".

An unspecified behavior will be caused if the id parameter
of any particular TextEvent instance is not
in the range from TEXT_FIRST to TEXT_LAST.

The listener interface for receiving text events.

The class that is interested in processing a text event
implements this interface. The object created with that
class is then registered with a component using the
component's addTextListener method. When the
component's text changes, the listener object's
textValueChanged method is invoked.

An abstract adapter class for receiving window events.
The methods in this class are empty. This class exists as
convenience for creating listener objects.

Extend this class to create a WindowEvent listener
and override the methods for the events of interest. (If you implement the
WindowListener interface, you have to define all of
the methods in it. This abstract class defines null methods for them
all, so you can only have to define methods for events you care about.)

Create a listener object using the extended class and then register it with
a Window using the window's addWindowListener
method. When the window's status changes by virtue of being opened,
closed, activated or deactivated, iconified or deiconified,
the relevant method in the listener
object is invoked, and the WindowEvent is passed to it.

A low-level event that indicates that a window has changed its status. This
low-level event is generated by a Window object when it is opened, closed,
activated, deactivated, iconified, or deiconified, or when focus is
transfered into or out of the Window.

The event is passed to every WindowListener
or WindowAdapter object which registered to receive such
events using the window's addWindowListener method.
(WindowAdapter objects implement the
WindowListener interface.) Each such listener object
gets this WindowEvent when the event occurs.

An unspecified behavior will be caused if the id parameter
of any particular WindowEvent instance is not
in the range from WINDOW_FIRST to WINDOW_LAST.

The listener interface for receiving WindowEvents, including
WINDOW_GAINED_FOCUS and WINDOW_LOST_FOCUS events.
The class that is interested in processing a WindowEvent
either implements this interface (and
all the methods it contains) or extends the abstract
WindowAdapter class (overriding only the methods of interest).
The listener object created from that class is then registered with a
Window
using the Window's addWindowFocusListener method.
When the Window's
status changes by virtue of it being opened, closed, activated, deactivated,
iconified, or deiconified, or by focus being transfered into or out of the
Window, the relevant method in the listener object is invoked,
and the WindowEvent is passed to it.

The listener interface for receiving window events.
The class that is interested in processing a window event
either implements this interface (and all the methods it
contains) or extends the abstract WindowAdapter class
(overriding only the methods of interest).
The listener object created from that class is then registered with a
Window using the window's addWindowListener
method. When the window's status changes by virtue of being opened,
closed, activated or deactivated, iconified or deiconified,
the relevant method in the listener object is invoked, and the
WindowEvent is passed to it.

The listener interface for receiving window state events.

The class that is interested in processing a window state event
either implements this interface (and all the methods it contains)
or extends the abstract WindowAdapter class
(overriding only the methods of interest).

The listener object created from that class is then registered with
a window using the Window's
addWindowStateListener method.  When the window's
state changes by virtue of being iconified, maximized etc., the
windowStateChanged method in the listener object is
invoked, and the WindowEvent is passed to it.

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.

For information on the threading issues of the event dispatch
machinery, see AWT Threading Issues.

The FileDialog class displays a dialog window
from which the user can select a file.

Since it is a modal dialog, when the application calls
its show method to display the dialog,
it blocks the rest of the application until the user has
chosen a file.

A flow layout arranges components in a directional flow, much
like lines of text in a paragraph. The flow direction is
determined by the container's componentOrientation
property and may be one of two values:

ComponentOrientation.LEFT_TO_RIGHT
ComponentOrientation.RIGHT_TO_LEFT

Flow layouts are typically used
to arrange buttons in a panel. It arranges buttons
horizontally until no more buttons fit on the same line.
The line alignment is determined by the align
property. The possible values are:

LEFT
RIGHT
CENTER
LEADING
TRAILING


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.

A FocusTraversalPolicy defines the order in which Components with a
particular focus cycle root are traversed. Instances can apply the policy to
arbitrary focus cycle roots, allowing themselves to be shared across
Containers. They do not need to be reinitialized when the focus cycle roots
of a Component hierarchy change.

The core responsibility of a FocusTraversalPolicy is to provide algorithms
determining the next and previous Components to focus when traversing
forward or backward in a UI. Each FocusTraversalPolicy must also provide
algorithms for determining the first, last, and default Components in a
traversal cycle. First and last Components are used when normal forward and
backward traversal, respectively, wraps. The default Component is the first
to receive focus when traversing down into a new focus traversal cycle.
A FocusTraversalPolicy can optionally provide an algorithm for determining
a Window's initial Component. The initial Component is the first to receive
focus when a Window is first made visible.

FocusTraversalPolicy takes into account focus traversal
policy providers.  When searching for first/last/next/previous Component,
if a focus traversal policy provider is encountered, its focus traversal
policy is used to perform the search operation.

Please see

How to Use the Focus Subsystem,
a section in The Java Tutorial, and the
Focus Specification
for more information.

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 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 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.

Font and TextAttribute

Font supports most
TextAttributes.  This makes some operations, such as
rendering underlined text, convenient since it is not
necessary to explicitly construct a TextLayout object.
Attributes can be set on a Font by constructing or deriving it
using a Map of TextAttribute values.

The values of some TextAttributes are not
serializable, and therefore attempting to serialize an instance of
Font that has such values will not serialize them.
This means a Font deserialized from such a stream will not compare
equal to the original Font that contained the non-serializable
attributes.  This should very rarely pose a problem
since these attributes are typically used only in special
circumstances and are unlikely to be serialized.


FOREGROUND and BACKGROUND use
Paint values. The subclass Color is
serializable, while GradientPaint and
TexturePaint are not.
CHAR_REPLACEMENT uses
GraphicAttribute values.  The subclasses
ShapeGraphicAttribute and
ImageGraphicAttribute are not serializable.
INPUT_METHOD_HIGHLIGHT uses
InputMethodHighlight values, which are
not serializable.  See InputMethodHighlight.


Clients who create custom subclasses of Paint and
GraphicAttribute can make them serializable and
avoid this problem.  Clients who use input method highlights can
convert these to the platform-specific attributes for that
highlight on the current platform and set them on the Font as
a workaround.

The Map-based constructor and
deriveFont APIs ignore the FONT attribute, and it is
not retained by the Font; the static getFont(java.util.Map<? extends java.text.AttributedCharacterIterator.Attribute, ?>) method should
be used if the FONT attribute might be present.  See TextAttribute.FONT for more information.

Several attributes will cause additional rendering overhead
and potentially invoke layout.  If a Font has such
attributes, the hasLayoutAttributes() method
will return true.

Note: Font rotations can cause text baselines to be rotated.  In
order to account for this (rare) possibility, font APIs are
specified to return metrics and take parameters 'in
baseline-relative coordinates'.  This maps the 'x' coordinate to
the advance along the baseline, (positive x is forward along the
baseline), and the 'y' coordinate to a distance along the
perpendicular to the baseline at 'x' (positive y is 90 degrees
clockwise from the baseline vector).  APIs for which this is
especially important are called out as having 'baseline-relative
coordinates.'

The FontRenderContext class is a container for the
information needed to correctly measure text.  The measurement of text
can vary because of rules that map outlines to pixels, and rendering
hints provided by an application.

One such piece of information is a transform that scales
typographical points to pixels. (A point is defined to be exactly 1/72
of an inch, which is slightly different than
the traditional mechanical measurement of a point.)  A character that
is rendered at 12pt on a 600dpi device might have a different size
than the same character rendered at 12pt on a 72dpi device because of
such factors as rounding to pixel boundaries and hints that the font
designer may have specified.

Anti-aliasing and Fractional-metrics specified by an application can also
affect the size of a character because of rounding to pixel
boundaries.

Typically, instances of FontRenderContext are
obtained from a Graphics2D object.  A
FontRenderContext which is directly constructed will
most likely not represent any actual graphics device, and may lead
to unexpected or incorrect results.

The GlyphJustificationInfo class represents information
about the justification properties of a glyph.  A glyph is the visual
representation of one or more characters.  Many different glyphs can
be used to represent a single character or combination of characters.
The four justification properties represented by
GlyphJustificationInfo are weight, priority, absorb and
limit.

Weight is the overall 'weight' of the glyph in the line.  Generally it is
proportional to the size of the font.  Glyphs with larger weight are
allocated a correspondingly larger amount of the change in space.

Priority determines the justification phase in which this glyph is used.
All glyphs of the same priority are examined before glyphs of the next
priority.  If all the change in space can be allocated to these glyphs
without exceeding their limits, then glyphs of the next priority are not
examined. There are four priorities, kashida, whitespace, interchar,
and none.  KASHIDA is the first priority examined. NONE is the last
priority examined.

Absorb determines whether a glyph absorbs all change in space.  Within a
given priority, some glyphs may absorb all the change in space.  If any of
these glyphs are present, no glyphs of later priority are examined.

Limit determines the maximum or minimum amount by which the glyph can
change. Left and right sides of the glyph can have different limits.

Each GlyphJustificationInfo represents two sets of
metrics, which are growing and shrinking.  Growing
metrics are used when the glyphs on a line are to be
spread apart to fit a larger width.  Shrinking metrics are used when
the glyphs are to be moved together to fit a smaller width.

The GlyphMetrics class represents information for a
single glyph.   A glyph is the visual representation of one or more
characters.  Many different glyphs can be used to represent a single
character or combination of characters.  GlyphMetrics
instances are produced by Font and are applicable
to a specific glyph in a particular Font.

Glyphs are either STANDARD, LIGATURE, COMBINING, or COMPONENT.

STANDARD glyphs are commonly used to represent single characters.
LIGATURE glyphs are used to represent sequences of characters.
COMPONENT glyphs in a GlyphVector do not correspond to a
particular character in a text model. Instead, COMPONENT glyphs are
added for typographical reasons, such as Arabic justification.
COMBINING glyphs embellish STANDARD or LIGATURE glyphs, such
as accent marks.  Carets do not appear before COMBINING glyphs.


Other metrics available through GlyphMetrics are the
components of the advance, the visual bounds, and the left and right
side bearings.

Glyphs for a rotated font, or obtained from a GlyphVector
which has applied a rotation to the glyph, can have advances that
contain both X and Y components.  Usually the advance only has one
component.

The advance of a glyph is the distance from the glyph's origin to the
origin of the next glyph along the baseline, which is either vertical
or horizontal.  Note that, in a GlyphVector,
the distance from a glyph to its following glyph might not be the
glyph's advance, because of kerning or other positioning adjustments.

The bounds is the smallest rectangle that completely contains the
outline of the glyph.  The bounds rectangle is relative to the
glyph's origin.  The left-side bearing is the distance from the glyph
origin to the left of its bounds rectangle. If the left-side bearing is
negative, part of the glyph is drawn to the left of its origin.  The
right-side bearing is the distance from the right side of the bounds
rectangle to the next glyph origin (the origin plus the advance).  If
negative, part of the glyph is drawn to the right of the next glyph's
origin.  Note that the bounds does not necessarily enclose all the pixels
affected when rendering the glyph, because of rasterization and pixel
adjustment effects.

Although instances of GlyphMetrics can be directly
constructed, they are almost always obtained from a
GlyphVector.  Once constructed, GlyphMetrics
objects are immutable.

Example:
Querying a Font for glyph information


Font font = ...;
int glyphIndex = ...;
GlyphMetrics metrics = GlyphVector.getGlyphMetrics(glyphIndex);
int isStandard = metrics.isStandard();
float glyphAdvance = metrics.getAdvance();

A GlyphVector object is a collection of glyphs
containing geometric information for the placement of each glyph
in a transformed coordinate space which corresponds to the
device on which the GlyphVector is ultimately
displayed.

The GlyphVector does not attempt any interpretation of
the sequence of glyphs it contains.  Relationships between adjacent
glyphs in sequence are solely used to determine the placement of
the glyphs in the visual coordinate space.

Instances of GlyphVector are created by a Font.

In a text processing application that can cache intermediate
representations of text, creation and subsequent caching of a
GlyphVector for use during rendering is the fastest
method to present the visual representation of characters to a user.

A GlyphVector is associated with exactly one
Font, and can provide data useful only in relation to
this Font.  In addition, metrics obtained from a
GlyphVector are not generally geometrically scaleable
since the pixelization and spacing are dependent on grid-fitting
algorithms within a Font.  To facilitate accurate
measurement of a GlyphVector and its component
glyphs, you must specify a scaling transform, anti-alias mode, and
fractional metrics mode when creating the GlyphVector.
These characteristics can be derived from the destination device.

For each glyph in the GlyphVector, you can obtain:

the position of the glyph
the transform associated with the glyph
the metrics of the glyph in the context of the
  GlyphVector.  The metrics of the glyph may be
  different under different transforms, application specified
  rendering hints, and the specific instance of the glyph within
  the GlyphVector.


Altering the data used to create the GlyphVector does not
alter the state of the GlyphVector.

Methods are provided to adjust the positions of the glyphs
within the GlyphVector.  These methods are most
appropriate for applications that are performing justification
operations for the presentation of the glyphs.

Methods are provided to transform individual glyphs within the
GlyphVector.  These methods are primarily useful for
special effects.

Methods are provided to return both the visual, logical, and pixel bounds
of the entire GlyphVector or of individual glyphs within
the GlyphVector.

Methods are provided to return a Shape for the
GlyphVector, and for individual glyphs within the
GlyphVector.

This class is used with the CHAR_REPLACEMENT attribute.

The GraphicAttribute class represents a graphic embedded
in text. Clients subclass this class to implement their own char
replacement graphics.  Clients wishing to embed shapes and images in
text need not subclass this class.  Instead, clients can use the
ShapeGraphicAttribute and ImageGraphicAttribute
classes.

Subclasses must ensure that their objects are immutable once they
are constructed.  Mutating a GraphicAttribute that
is used in a TextLayout results in undefined behavior from the
TextLayout.

The ImageGraphicAttribute class is an implementation of
GraphicAttribute which draws images in
a TextLayout.

LayoutPath provides a mapping between locations relative to the
baseline and points in user space.  Locations consist of an advance
along the baseline, and an offset perpendicular to the baseline at
the advance.  Positive values along the perpendicular are in the
direction that is 90 degrees clockwise from the baseline vector.
Locations are represented as a Point2D, where x is the advance and
y is the offset.

Point2D pen = new Point2D(10, 20);
Graphics2D g2d = (Graphics2D)graphics;
FontRenderContext frc = g2d.getFontRenderContext();

// let styledText be an AttributedCharacterIterator containing at least
// one character

LineBreakMeasurer measurer = new LineBreakMeasurer(styledText, frc);
float wrappingWidth = getSize().width - 15;

while (measurer.getPosition() < fStyledText.length()) {

    TextLayout layout = measurer.nextLayout(wrappingWidth);

    pen.y = (layout.getAscent());
    float dx = layout.isLeftToRight() ?
        0 : (wrappingWidth - layout.getAdvance());

    layout.draw(graphics, pen.x  dx, pen.y);
    pen.y = layout.getDescent()  layout.getLeading();
}

float leftMargin = 10, rightMargin = 310;
float[] tabStops = { 100, 250 };

// assume styledText is an AttributedCharacterIterator, and the number
// of tabs in styledText is tabCount

int[] tabLocations = new int[tabCount+1];

int i = 0;
for (char c = styledText.first(); c != styledText.DONE; c = styledText.next()) {
    if (c == '\t') {
        tabLocations[i++] = styledText.getIndex();
    }
}
tabLocations[tabCount] = styledText.getEndIndex() - 1;

// Now tabLocations has an entry for every tab's offset in
// the text.  For convenience, the last entry is tabLocations
// is the offset of the last character in the text.

LineBreakMeasurer measurer = new LineBreakMeasurer(styledText);
int currentTab = 0;
float verticalPos = 20;

while (measurer.getPosition() < styledText.getEndIndex()) {

    // Lay out and draw each line.  All segments on a line
    // must be computed before any drawing can occur, since
    // we must know the largest ascent on the line.
    // TextLayouts are computed and stored in a Vector;
    // their horizontal positions are stored in a parallel
    // Vector.

    // lineContainsText is true after first segment is drawn
    boolean lineContainsText = false;
    boolean lineComplete = false;
    float maxAscent = 0, maxDescent = 0;
    float horizontalPos = leftMargin;
    Vector layouts = new Vector(1);
    Vector penPositions = new Vector(1);

    while (!lineComplete) {
        float wrappingWidth = rightMargin - horizontalPos;
        TextLayout layout =
                measurer.nextLayout(wrappingWidth,
                                    tabLocations[currentTab]+1,
                                    lineContainsText);

        // layout can be null if lineContainsText is true
        if (layout != null) {
            layouts.addElement(layout);
            penPositions.addElement(new Float(horizontalPos));
            horizontalPos = layout.getAdvance();
            maxAscent = Math.max(maxAscent, layout.getAscent());
            maxDescent = Math.max(maxDescent,
                layout.getDescent()  layout.getLeading());
        } else {
            lineComplete = true;
        }

        lineContainsText = true;

        if (measurer.getPosition() == tabLocations[currentTab]+1) {
            currentTab++;
        }

        if (measurer.getPosition() == styledText.getEndIndex())
            lineComplete = true;
        else if (horizontalPos >= tabStops[tabStops.length-1])
            lineComplete = true;

        if (!lineComplete) {
            // move to next tab stop
            int j;
            for (j=0; horizontalPos >= tabStops[j]; j++) {}
            horizontalPos = tabStops[j];
        }
    }

    verticalPos = maxAscent;

    Enumeration layoutEnum = layouts.elements();
    Enumeration positionEnum = penPositions.elements();

    // now iterate through layouts and draw them
    while (layoutEnum.hasMoreElements()) {
        TextLayout nextLayout = (TextLayout) layoutEnum.nextElement();
        Float nextPosition = (Float) positionEnum.nextElement();
        nextLayout.draw(graphics, nextPosition.floatValue(), verticalPos);
    }

    verticalPos = maxDescent;
}

The LineBreakMeasurer class allows styled text to be
broken into lines (or segments) that fit within a particular visual
advance.  This is useful for clients who wish to display a paragraph of
text that fits within a specific width, called the wrapping
width.

LineBreakMeasurer is constructed with an iterator over
styled text.  The iterator's range should be a single paragraph in the
text.
LineBreakMeasurer maintains a position in the text for the
start of the next text segment.  Initially, this position is the
start of text.  Paragraphs are assigned an overall direction (either
left-to-right or right-to-left) according to the bidirectional
formatting rules.  All segments obtained from a paragraph have the
same direction as the paragraph.

Segments of text are obtained by calling the method
nextLayout, which returns a TextLayout
representing the text that fits within the wrapping width.
The nextLayout method moves the current position
to the end of the layout returned from nextLayout.

LineBreakMeasurer implements the most commonly used
line-breaking policy: Every word that fits within the wrapping
width is placed on the line. If the first word does not fit, then all
of the characters that fit within the wrapping width are placed on the
line.  At least one character is placed on each line.

The TextLayout instances returned by
LineBreakMeasurer treat tabs like 0-width spaces.  Clients
who wish to obtain tab-delimited segments for positioning should use
the overload of nextLayout which takes a limiting offset
in the text.
The limiting offset should be the first character after the tab.
The TextLayout objects returned from this method end
at the limit provided (or before, if the text between the current
position and the limit won't fit entirely within the  wrapping
width).

Clients who are laying out tab-delimited text need a slightly
different line-breaking policy after the first segment has been
placed on a line.  Instead of fitting partial words in the
remaining space, they should place words which don't fit in the
remaining space entirely on the next line.  This change of policy
can be requested in the overload of nextLayout which
takes a boolean parameter.  If this parameter is
true, nextLayout returns
null if the first word won't fit in
the given space.  See the tab sample below.

In general, if the text used to construct the
LineBreakMeasurer changes, a new
LineBreakMeasurer must be constructed to reflect
the change.  (The old LineBreakMeasurer continues to
function properly, but it won't be aware of the text change.)
Nevertheless, if the text change is the insertion or deletion of a
single character, an existing LineBreakMeasurer can be
'updated' by calling insertChar or
deleteChar. Updating an existing
LineBreakMeasurer is much faster than creating a new one.
Clients who modify text based on user typing should take advantage
of these methods.

Examples:
Rendering a paragraph in a component



public void paint(Graphics graphics) {

    Point2D pen = new Point2D(10, 20);
    Graphics2D g2d = (Graphics2D)graphics;
    FontRenderContext frc = g2d.getFontRenderContext();

    // let styledText be an AttributedCharacterIterator containing at least
    // one character

    LineBreakMeasurer measurer = new LineBreakMeasurer(styledText, frc);
    float wrappingWidth = getSize().width - 15;

    while (measurer.getPosition() < fStyledText.length()) {

        TextLayout layout = measurer.nextLayout(wrappingWidth);

        pen.y = (layout.getAscent());
        float dx = layout.isLeftToRight() ?
            0 : (wrappingWidth - layout.getAdvance());

        layout.draw(graphics, pen.x  dx, pen.y);
        pen.y = layout.getDescent()  layout.getLeading();
    }
}


Rendering text with tabs.  For simplicity, the overall text
direction is assumed to be left-to-right



public void paint(Graphics graphics) {

    float leftMargin = 10, rightMargin = 310;
    float[] tabStops = { 100, 250 };

    // assume styledText is an AttributedCharacterIterator, and the number
    // of tabs in styledText is tabCount

    int[] tabLocations = new int[tabCount+1];

    int i = 0;
    for (char c = styledText.first(); c != styledText.DONE; c = styledText.next()) {
        if (c == '\t') {
            tabLocations[i++] = styledText.getIndex();
        }
    }
    tabLocations[tabCount] = styledText.getEndIndex() - 1;

    // Now tabLocations has an entry for every tab's offset in
    // the text.  For convenience, the last entry is tabLocations
    // is the offset of the last character in the text.

    LineBreakMeasurer measurer = new LineBreakMeasurer(styledText);
    int currentTab = 0;
    float verticalPos = 20;

    while (measurer.getPosition() < styledText.getEndIndex()) {

        // Lay out and draw each line.  All segments on a line
        // must be computed before any drawing can occur, since
        // we must know the largest ascent on the line.
        // TextLayouts are computed and stored in a Vector;
        // their horizontal positions are stored in a parallel
        // Vector.

        // lineContainsText is true after first segment is drawn
        boolean lineContainsText = false;
        boolean lineComplete = false;
        float maxAscent = 0, maxDescent = 0;
        float horizontalPos = leftMargin;
        Vector layouts = new Vector(1);
        Vector penPositions = new Vector(1);

        while (!lineComplete) {
            float wrappingWidth = rightMargin - horizontalPos;
            TextLayout layout =
                    measurer.nextLayout(wrappingWidth,
                                        tabLocations[currentTab]+1,
                                        lineContainsText);

            // layout can be null if lineContainsText is true
            if (layout != null) {
                layouts.addElement(layout);
                penPositions.addElement(new Float(horizontalPos));
                horizontalPos = layout.getAdvance();
                maxAscent = Math.max(maxAscent, layout.getAscent());
                maxDescent = Math.max(maxDescent,
                    layout.getDescent()  layout.getLeading());
            } else {
                lineComplete = true;
            }

            lineContainsText = true;

            if (measurer.getPosition() == tabLocations[currentTab]+1) {
                currentTab++;
            }

            if (measurer.getPosition() == styledText.getEndIndex())
                lineComplete = true;
            else if (horizontalPos >= tabStops[tabStops.length-1])
                lineComplete = true;

            if (!lineComplete) {
                // move to next tab stop
                int j;
                for (j=0; horizontalPos >= tabStops[j]; j++) {}
                horizontalPos = tabStops[j];
            }
        }

        verticalPos = maxAscent;

        Enumeration layoutEnum = layouts.elements();
        Enumeration positionEnum = penPositions.elements();

        // now iterate through layouts and draw them
        while (layoutEnum.hasMoreElements()) {
            TextLayout nextLayout = (TextLayout) layoutEnum.nextElement();
            Float nextPosition = (Float) positionEnum.nextElement();
            nextLayout.draw(graphics, nextPosition.floatValue(), verticalPos);
        }

        verticalPos = maxDescent;
    }
}

The LineMetrics class allows access to the
metrics needed to layout characters along a line
and to layout of a set of lines.  A LineMetrics
object encapsulates the measurement information associated
with a run of text.

Fonts can have different metrics for different ranges of
characters.  The getLineMetrics methods of
Font take some text as an argument
and return a LineMetrics object describing the
metrics of the initial number of characters in that text, as
returned by getNumChars().

The MultipleMaster interface represents Type 1
Multiple Master fonts.
A particular Font object can implement this interface.

  Unicode Range
  NumericShaper Constants
  Precedence


  Arabic
  NumericShaper.ARABIC
      NumericShaper.EASTERN_ARABIC
  NumericShaper.EASTERN_ARABIC


  NumericShaper.Range.ARABIC
      NumericShaper.Range.EASTERN_ARABIC
  NumericShaper.Range.EASTERN_ARABIC


  Tai Tham
  NumericShaper.Range.TAI_THAM_HORA
      NumericShaper.Range.TAI_THAM_THAM
  NumericShaper.Range.TAI_THAM_THAM

The NumericShaper class is used to convert Latin-1 (European)
digits to other Unicode decimal digits.  Users of this class will
primarily be people who wish to present data using
national digit shapes, but find it more convenient to represent the
data internally using Latin-1 (European) digits.  This does not
interpret the deprecated numeric shape selector character (U+206E).

Instances of NumericShaper are typically applied
as attributes to text with the
NUMERIC_SHAPING attribute
of the TextAttribute class.
For example, this code snippet causes a TextLayout to
shape European digits to Arabic in an Arabic context:


Map map = new HashMap();
map.put(TextAttribute.NUMERIC_SHAPING,
    NumericShaper.getContextualShaper(NumericShaper.ARABIC));
FontRenderContext frc = ...;
TextLayout layout = new TextLayout(text, map, frc);
layout.draw(g2d, x, y);

It is also possible to perform numeric shaping explicitly using instances
of NumericShaper, as this code snippet demonstrates:


char[] text = ...;
// shape all EUROPEAN digits (except zero) to ARABIC digits
NumericShaper shaper = NumericShaper.getShaper(NumericShaper.ARABIC);
shaper.shape(text, start, count);

// shape European digits to ARABIC digits if preceding text is Arabic, or
// shape European digits to TAMIL digits if preceding text is Tamil, or
// leave European digits alone if there is no preceding text, or
// preceding text is neither Arabic nor Tamil
NumericShaper shaper =
    NumericShaper.getContextualShaper(NumericShaper.ARABIC |
                                        NumericShaper.TAMIL,
                                      NumericShaper.EUROPEAN);
shaper.shape(text, start, count);

Bit mask- and enum-based Unicode ranges

This class supports two different programming interfaces to
represent Unicode ranges for script-specific digits: bit
mask-based ones, such as NumericShaper.ARABIC, and
enum-based ones, such as NumericShaper.Range.ARABIC.
Multiple ranges can be specified by ORing bit mask-based constants,
such as:


NumericShaper.ARABIC | NumericShaper.TAMIL
or creating a Set with the NumericShaper.Range
constants, such as:


EnumSet.of(NumericShaper.Scirpt.ARABIC, NumericShaper.Range.TAMIL)
The enum-based ranges are a super set of the bit mask-based ones.

If the two interfaces are mixed (including serialization),
Unicode range values are mapped to their counterparts where such
mapping is possible, such as NumericShaper.Range.ARABIC
from/to NumericShaper.ARABIC.  If any unmappable range
values are specified, such as NumericShaper.Range.BALINESE,
those ranges are ignored.

Decimal Digits Precedence

A Unicode range may have more than one set of decimal digits. If
multiple decimal digits sets are specified for the same Unicode
range, one of the sets will take precedence as follows.



      Unicode Range
      NumericShaper Constants
      Precedence


      Arabic
      NumericShaper.ARABIC
          NumericShaper.EASTERN_ARABIC
      NumericShaper.EASTERN_ARABIC


      NumericShaper.Range.ARABIC
          NumericShaper.Range.EASTERN_ARABIC
      NumericShaper.Range.EASTERN_ARABIC


      Tai Tham
      NumericShaper.Range.TAI_THAM_HORA
          NumericShaper.Range.TAI_THAM_THAM
      NumericShaper.Range.TAI_THAM_THAM

The OpenType interface represents OpenType and
TrueType fonts.  This interface makes it possible to obtain
sfnt tables from the font.  A particular
Font object can implement this interface.

For more information on TrueType and OpenType fonts, see the
OpenType specification.
( http://www.microsoft.com/typography/otspec/ ).

The ShapeGraphicAttribute class is an implementation of
GraphicAttribute that draws shapes in a TextLayout.

The TextAttribute class defines attribute keys and
attribute values used for text rendering.

TextAttribute instances are used as attribute keys to
identify attributes in
Font,
TextLayout,
AttributedCharacterIterator,
and other classes handling text attributes. Other constants defined
in this class can be used as attribute values.

For each text attribute, the documentation provides:

  the type of its value,
  the relevant predefined constants, if any
  the default effect if the attribute is absent
  the valid values if there are limitations
  a description of the effect.


Values

  The values of attributes must always be immutable.
  Where value limitations are given, any value outside of that
  set is reserved for future use; the value will be treated as
  the default.
  The value null is treated the same as the
  default value and results in the default behavior.
  If the value is not of the proper type, the attribute
  will be ignored.
  The identity of the value does not matter, only the actual
  value.  For example, TextAttribute.WEIGHT_BOLD and
  new Float(2.0)
  indicate the same WEIGHT.
  Attribute values of type Number (used for
  WEIGHT, WIDTH, POSTURE,
  SIZE, JUSTIFICATION, and
  TRACKING) can vary along their natural range and are
  not restricted to the predefined constants.
  Number.floatValue() is used to get the actual value
  from the Number.
  The values for WEIGHT, WIDTH, and
  POSTURE are interpolated by the system, which
  can select the 'nearest available' font or use other techniques to
  approximate the user's request.



Summary of attributes



Key
Value Type
Principal Constants
Default Value


FAMILY
String
See Font DIALOG,
DIALOG_INPUT, SERIF,
SANS_SERIF, and MONOSPACED.

"Default" (use platform default)


WEIGHT
Number
WEIGHT_REGULAR, WEIGHT_BOLD
WEIGHT_REGULAR


WIDTH
Number
WIDTH_CONDENSED, WIDTH_REGULAR,WIDTH_EXTENDED
WIDTH_REGULAR


POSTURE
Number
POSTURE_REGULAR, POSTURE_OBLIQUE
POSTURE_REGULAR


SIZE
Number
none
12.0


TRANSFORM
TransformAttribute
See TransformAttribute IDENTITY
TransformAttribute.IDENTITY


SUPERSCRIPT
Integer
SUPERSCRIPT_SUPER, SUPERSCRIPT_SUB
0 (use the standard glyphs and metrics)


FONT
Font
none
null (do not override font resolution)


CHAR_REPLACEMENT
GraphicAttribute
none
null (draw text using font glyphs)


FOREGROUND
Paint
none
null (use current graphics paint)


BACKGROUND
Paint
none
null (do not render background)


UNDERLINE
Integer
UNDERLINE_ON
-1 (do not render underline)


STRIKETHROUGH
Boolean
STRIKETHROUGH_ON
false (do not render strikethrough)


RUN_DIRECTION
Boolean
RUN_DIRECTION_LTRRUN_DIRECTION_RTL
null (use Bidi standard default)


BIDI_EMBEDDING
Integer
none
0 (use base line direction)


JUSTIFICATION
Number
JUSTIFICATION_FULL
JUSTIFICATION_FULL


INPUT_METHOD_HIGHLIGHT
InputMethodHighlight,Annotation
(see class)
null (do not apply input highlighting)


INPUT_METHOD_UNDERLINE
Integer
UNDERLINE_LOW_ONE_PIXEL,UNDERLINE_LOW_TWO_PIXEL
-1 (do not render underline)


SWAP_COLORS
Boolean
SWAP_COLORS_ON
false (do not swap colors)


NUMERIC_SHAPING
NumericShaper
none
null (do not shape digits)


KERNING
Integer
KERNING_ON
0 (do not request kerning)


LIGATURES
Integer
LIGATURES_ON
0 (do not form optional ligatures)


TRACKING
Number
TRACKING_LOOSE, TRACKING_TIGHT
0 (do not add tracking)

The TextHitInfo class represents a character position in a
text model, and a bias, or "side," of the character.  Biases are
either leading (the left edge, for a left-to-right character)
or trailing (the right edge, for a left-to-right character).
Instances of TextHitInfo are used to specify caret and
insertion positions within text.

For example, consider the text "abc".  TextHitInfo.trailing(1)
corresponds to the right side of the 'b' in the text.

TextHitInfo is used primarily by TextLayout and
clients of TextLayout.  Clients of TextLayout
query TextHitInfo instances for an insertion offset, where
new text is inserted into the text model.  The insertion offset is equal
to the character position in the TextHitInfo if the bias
is leading, and one character after if the bias is trailing.  The
insertion offset for TextHitInfo.trailing(1) is 2.

Sometimes it is convenient to construct a TextHitInfo with
the same insertion offset as an existing one, but on the opposite
character.  The getOtherHit method constructs a new
TextHitInfo with the same insertion offset as an existing
one, with a hit on the character on the other side of the insertion offset.
Calling getOtherHit on trailing(1) would return leading(2).
In general, getOtherHit for trailing(n) returns
leading(n+1) and getOtherHit for leading(n)
returns trailing(n-1).

Example:
Converting a graphical point to an insertion point within a text
model


TextLayout layout = ...;
Point2D.Float hitPoint = ...;
TextHitInfo hitInfo = layout.hitTestChar(hitPoint.x, hitPoint.y);
int insPoint = hitInfo.getInsertionIndex();
// insPoint is relative to layout;  may need to adjust for use
// in a text model

TextLayout is an immutable graphical representation of styled
character data.

It provides the following capabilities:

implicit bidirectional analysis and reordering,
cursor positioning and movement, including split cursors for
mixed directional text,
highlighting, including both logical and visual highlighting
for mixed directional text,
multiple baselines (roman, hanging, and centered),
hit testing,
justification,
default font substitution,
metric information such as ascent, descent, and advance, and
rendering


A TextLayout object can be rendered using
its draw method.

TextLayout can be constructed either directly or through
the use of a LineBreakMeasurer.  When constructed directly, the
source text represents a single paragraph.  LineBreakMeasurer
allows styled text to be broken into lines that fit within a particular
width.  See the LineBreakMeasurer documentation for more
information.

TextLayout construction logically proceeds as follows:

paragraph attributes are extracted and examined,
text is analyzed for bidirectional reordering, and reordering
information is computed if needed,
text is segmented into style runs
fonts are chosen for style runs, first by using a font if the
attribute TextAttribute.FONT is present, otherwise by computing
a default font using the attributes that have been defined
if text is on multiple baselines, the runs or subruns are further
broken into subruns sharing a common baseline,
glyphvectors are generated for each run using the chosen font,
final bidirectional reordering is performed on the glyphvectors


All graphical information returned from a TextLayout
object's methods is relative to the origin of the
TextLayout, which is the intersection of the
TextLayout object's baseline with its left edge.  Also,
coordinates passed into a TextLayout object's methods
are assumed to be relative to the TextLayout object's
origin.  Clients usually need to translate between a
TextLayout object's coordinate system and the coordinate
system in another object (such as a
Graphics object).

TextLayout objects are constructed from styled text,
but they do not retain a reference to their source text.  Thus,
changes in the text previously used to generate a TextLayout
do not affect the TextLayout.

Three methods on a TextLayout object
(getNextRightHit, getNextLeftHit, and
hitTestChar) return instances of TextHitInfo.
The offsets contained in these TextHitInfo objects
are relative to the start of the TextLayout, not
to the text used to create the TextLayout.  Similarly,
TextLayout methods that accept TextHitInfo
instances as parameters expect the TextHitInfo object's
offsets to be relative to the TextLayout, not to any
underlying text storage model.

Examples:
Constructing and drawing a TextLayout and its bounding
rectangle:


  Graphics2D g = ...;
  Point2D loc = ...;
  Font font = Font.getFont("Helvetica-bold-italic");
  FontRenderContext frc = g.getFontRenderContext();
  TextLayout layout = new TextLayout("This is a string", font, frc);
  layout.draw(g, (float)loc.getX(), (float)loc.getY());

  Rectangle2D bounds = layout.getBounds();
  bounds.setRect(bounds.getX()+loc.getX(),
                 bounds.getY()+loc.getY(),
                 bounds.getWidth(),
                 bounds.getHeight());
  g.draw(bounds);


Hit-testing a TextLayout (determining which character is at
a particular graphical location):


  Point2D click = ...;
  TextHitInfo hit = layout.hitTestChar(
                        (float) (click.getX() - loc.getX()),
                        (float) (click.getY() - loc.getY()));


Responding to a right-arrow key press:


  int insertionIndex = ...;
  TextHitInfo next = layout.getNextRightHit(insertionIndex);
  if (next != null) {
      // translate graphics to origin of layout on screen
      g.translate(loc.getX(), loc.getY());
      Shape[] carets = layout.getCaretShapes(next.getInsertionIndex());
      g.draw(carets[0]);
      if (carets[1] != null) {
          g.draw(carets[1]);
      }
  }

Drawing a selection range corresponding to a substring in the source text.
The selected area may not be visually contiguous:


  // selStart, selLimit should be relative to the layout,
  // not to the source text

  int selStart = ..., selLimit = ...;
  Color selectionColor = ...;
  Shape selection = layout.getLogicalHighlightShape(selStart, selLimit);
  // selection may consist of disjoint areas
  // graphics is assumed to be tranlated to origin of layout
  g.setColor(selectionColor);
  g.fill(selection);

Drawing a visually contiguous selection range.  The selection range may
correspond to more than one substring in the source text.  The ranges of
the corresponding source text substrings can be obtained with
getLogicalRangesForVisualSelection():


  TextHitInfo selStart = ..., selLimit = ...;
  Shape selection = layout.getVisualHighlightShape(selStart, selLimit);
  g.setColor(selectionColor);
  g.fill(selection);
  int[] ranges = getLogicalRangesForVisualSelection(selStart, selLimit);
  // ranges[0], ranges[1] is the first selection range,
  // ranges[2], ranges[3] is the second selection range, etc.

Note: Font rotations can cause text baselines to be rotated, and
multiple runs with different rotations can cause the baseline to
bend or zig-zag.  In order to account for this (rare) possibility,
some APIs are specified to return metrics and take parameters 'in
baseline-relative coordinates' (e.g. ascent, advance), and others
are in 'in standard coordinates' (e.g. getBounds).  Values in
baseline-relative coordinates map the 'x' coordinate to the
distance along the baseline, (positive x is forward along the
baseline), and the 'y' coordinate to a distance along the
perpendicular to the baseline at 'x' (positive y is 90 degrees
clockwise from the baseline vector).  Values in standard
coordinates are measured along the x and y axes, with 0,0 at the
origin of the TextLayout.  Documentation for each relevant API
indicates what values are in what coordinate system.  In general,
measurement-related APIs are in baseline-relative coordinates,
while display-related APIs are in standard coordinates.

Defines a policy for determining the strong caret location.
This class contains one method, getStrongCaret, which
is used to specify the policy that determines the strong caret in
dual-caret text.  The strong caret is used to move the caret to the
left or right. Instances of this class can be passed to
getCaretShapes, getNextLeftHit and
getNextRightHit to customize strong caret
selection.

To specify alternate caret policies, subclass CaretPolicy
and override getStrongCaret.  getStrongCaret
should inspect the two TextHitInfo arguments and choose
one of them as the strong caret.

Most clients do not need to use this class.

The TextMeasurer class provides the primitive operations
needed for line break: measuring up to a given advance, determining the
advance of a range of characters, and generating a
TextLayout for a range of characters. It also provides
methods for incremental editing of paragraphs.

A TextMeasurer object is constructed with an
AttributedCharacterIterator
representing a single paragraph of text.  The value returned by the
getBeginIndex
method of AttributedCharacterIterator
defines the absolute index of the first character.  The value
returned by the
getEndIndex
method of AttributedCharacterIterator defines the index
past the last character.  These values define the range of indexes to
use in calls to the TextMeasurer.  For example, calls to
get the advance of a range of text or the line break of a range of text
must use indexes between the beginning and end index values.  Calls to
insertChar
and
deleteChar
reset the TextMeasurer to use the beginning index and end
index of the AttributedCharacterIterator passed in those calls.

Most clients will use the more convenient LineBreakMeasurer,
which implements the standard line break policy (placing as many words
as will fit on each line).

The TransformAttribute class provides an immutable
wrapper for a transform so that it is safe to use as an attribute.

Thrown by method createFont in the Font class to indicate
that the specified font is bad.

The FontMetrics class defines a font metrics object, which
encapsulates information about the rendering of a particular font on a
particular screen.

Note to subclassers: Since many of these methods form closed,
mutually recursive loops, you must take care that you implement
at least one of the methods in each such loop to prevent
infinite recursion when your subclass is used.
In particular, the following is the minimal suggested set of methods
to override in order to ensure correctness and prevent infinite
recursion (though other subsets are equally feasible):

getAscent()
getLeading()
getMaxAdvance()
charWidth(char)
charsWidth(char[], int, int)



Note that the implementations of these methods are
inefficient, so they are usually overridden with more efficient
toolkit-specific implementations.

When an application asks to place a character at the position
(x, y), the character is placed so that its
reference point (shown as the dot in the accompanying image) is
put at that position. The reference point specifies a horizontal
line called the baseline of the character. In normal
printing, the baselines of characters should align.

In addition, every character in a font has an ascent, a
descent, and an advance width. The ascent is the
amount by which the character ascends above the baseline. The
descent is the amount by which the character descends below the
baseline. The advance width indicates the position at which AWT
should place the next character.

An array of characters or a string can also have an ascent, a
descent, and an advance width. The ascent of the array is the
maximum ascent of any character in the array. The descent is the
maximum descent of any character in the array. The advance width
is the sum of the advance widths of each of the characters in the
character array.  The advance of a String is the
distance along the baseline of the String.  This
distance is the width that should be used for centering or
right-aligning the String.
Note that the advance of a String is not necessarily
the sum of the advances of its characters measured in isolation
because the width of a character can vary depending on its context.
For example, in Arabic text, the shape of a character can change
in order to connect to other characters.  Also, in some scripts,
certain character sequences can be represented by a single shape,
called a ligature.  Measuring characters individually does
not account for these transformations.
Font metrics are baseline-relative, meaning that they are
generally independent of the rotation applied to the font (modulo
possible grid hinting effects).  See Font.

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

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
Frame(String title, 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:
    If the program doesn't
    explicitly hide or dispose the window while processing
    this event, the window close operation is canceled.
WINDOW_CLOSED
WINDOW_ICONIFIED
WINDOW_DEICONIFIED
WINDOW_ACTIVATED
WINDOW_DEACTIVATED
WINDOW_GAINED_FOCUS
WINDOW_LOST_FOCUS
WINDOW_STATE_CHANGED

 [ x']   [  m00  m01  m02  ] [ x ]   [ m00x  m01y  m02 ]
 [ y'] = [  m10  m11  m12  ] [ y ] = [ m10x  m11y  m12 ]
 [ 1 ]   [   0    0    1   ] [ 1 ]   [         1         ]

The AffineTransform class represents a 2D affine transform
that performs a linear mapping from 2D coordinates to other 2D
coordinates that preserves the "straightness" and
"parallelness" of lines.  Affine transformations can be constructed
using sequences of translations, scales, flips, rotations, and shears.

Such a coordinate transformation can be represented by a 3 row by
3 column matrix with an implied last row of [ 0 0 1 ].  This matrix
transforms source coordinates (x,y) into
destination coordinates (x',y') by considering
them to be a column vector and multiplying the coordinate vector
by the matrix according to the following process:


     [ x']   [  m00  m01  m02  ] [ x ]   [ m00x  m01y  m02 ]
     [ y'] = [  m10  m11  m12  ] [ y ] = [ m10x  m11y  m12 ]
     [ 1 ]   [   0    0    1   ] [ 1 ]   [         1         ]
Handling 90-Degree Rotations

In some variations of the rotate methods in the
AffineTransform class, a double-precision argument
specifies the angle of rotation in radians.
These methods have special handling for rotations of approximately
90 degrees (including multiples such as 180, 270, and 360 degrees),
so that the common case of quadrant rotation is handled more
efficiently.
This special handling can cause angles very close to multiples of
90 degrees to be treated as if they were exact multiples of
90 degrees.
For small multiples of 90 degrees the range of angles treated
as a quadrant rotation is approximately 0.00000121 degrees wide.
This section explains why such special care is needed and how
it is implemented.

Since 90 degrees is represented as PI/2 in radians,
and since PI is a transcendental (and therefore irrational) number,
it is not possible to exactly represent a multiple of 90 degrees as
an exact double precision value measured in radians.
As a result it is theoretically impossible to describe quadrant
rotations (90, 180, 270 or 360 degrees) using these values.
Double precision floating point values can get very close to
non-zero multiples of PI/2 but never close enough
for the sine or cosine to be exactly 0.0, 1.0 or -1.0.
The implementations of Math.sin() and
Math.cos() correspondingly never return 0.0
for any case other than Math.sin(0.0).
These same implementations do, however, return exactly 1.0 and
-1.0 for some range of numbers around each multiple of 90
degrees since the correct answer is so close to 1.0 or -1.0 that
the double precision significand cannot represent the difference
as accurately as it can for numbers that are near 0.0.

The net result of these issues is that if the
Math.sin() and Math.cos() methods
are used to directly generate the values for the matrix modifications
during these radian-based rotation operations then the resulting
transform is never strictly classifiable as a quadrant rotation
even for a simple case like rotate(Math.PI/2.0),
due to minor variations in the matrix caused by the non-0.0 values
obtained for the sine and cosine.
If these transforms are not classified as quadrant rotations then
subsequent code which attempts to optimize further operations based
upon the type of the transform will be relegated to its most general
implementation.

Because quadrant rotations are fairly common,
this class should handle these cases reasonably quickly, both in
applying the rotations to the transform and in applying the resulting
transform to the coordinates.
To facilitate this optimal handling, the methods which take an angle
of rotation measured in radians attempt to detect angles that are
intended to be quadrant rotations and treat them as such.
These methods therefore treat an angle theta as a quadrant
rotation if either Math.sin(theta) or
Math.cos(theta) returns exactly 1.0 or -1.0.
As a rule of thumb, this property holds true for a range of
approximately 0.0000000211 radians (or 0.00000121 degrees) around
small multiples of Math.PI/2.0.

Arc2D is the abstract superclass for all objects that
store a 2D arc defined by a framing rectangle,
start angle, angular extent (length of the arc), and a closure type
(OPEN, CHORD, or PIE).


The arc is a partial section of a full ellipse which
inscribes the framing rectangle of its parent RectangularShape.


The angles are specified relative to the non-square
framing rectangle such that 45 degrees always falls on the line from
the center of the ellipse to the upper right corner of the framing
rectangle.
As a result, if the framing rectangle is noticeably longer along one
axis than the other, the angles to the start and end of the arc segment
will be skewed farther along the longer axis of the frame.


The actual storage representation of the coordinates is left to
the subclass.

This class defines an arc specified in double precision.

This class defines an arc specified in float precision.

An Area object stores and manipulates a
resolution-independent description of an enclosed area of
2-dimensional space.
Area objects can be transformed and can perform
various Constructive Area Geometry (CAG) operations when combined
with other Area objects.
The CAG operations include area
addition, subtraction,
intersection, and exclusive or.
See the linked method documentation for examples of the various
operations.

The Area class implements the Shape
interface and provides full support for all of its hit-testing
and path iteration facilities, but an Area is more
specific than a generalized path in a number of ways:

Only closed paths and sub-paths are stored.
    Area objects constructed from unclosed paths
    are implicitly closed during construction as if those paths
    had been filled by the Graphics2D.fill method.
The interiors of the individual stored sub-paths are all
    non-empty and non-overlapping.  Paths are decomposed during
    construction into separate component non-overlapping parts,
    empty pieces of the path are discarded, and then these
    non-empty and non-overlapping properties are maintained
    through all subsequent CAG operations.  Outlines of different
    component sub-paths may touch each other, as long as they
    do not cross so that their enclosed areas overlap.
The geometry of the path describing the outline of the
    Area resembles the path from which it was
    constructed only in that it describes the same enclosed
    2-dimensional area, but may use entirely different types
    and ordering of the path segments to do so.

Interesting issues which are not always obvious when using
the Area include:

Creating an Area from an unclosed (open)
    Shape results in a closed outline in the
    Area object.
Creating an Area from a Shape
    which encloses no area (even when "closed") produces an
    empty Area.  A common example of this issue
    is that producing an Area from a line will
    be empty since the line encloses no area.  An empty
    Area will iterate no geometry in its
    PathIterator objects.
A self-intersecting Shape may be split into
    two (or more) sub-paths each enclosing one of the
    non-intersecting portions of the original path.
An Area may take more path segments to
    describe the same geometry even when the original
    outline is simple and obvious.  The analysis that the
    Area class must perform on the path may
    not reflect the same concepts of "simple and obvious"
    as a human being perceives.

The CubicCurve2D class defines a cubic parametric curve
segment in (x,y) coordinate space.

This class is only the abstract superclass for all objects which
store a 2D cubic curve segment.
The actual storage representation of the coordinates is left to
the subclass.

A cubic parametric curve segment specified with
double coordinates.

A cubic parametric curve segment specified with
float coordinates.

The Dimension2D class is to encapsulate a width
and a height dimension.

This class is only the abstract superclass for all objects that
store a 2D dimension.
The actual storage representation of the sizes is left to
the subclass.

The Ellipse2D class describes an ellipse that is defined
by a framing rectangle.

This class is only the abstract superclass for all objects which
store a 2D ellipse.
The actual storage representation of the coordinates is left to
the subclass.

The Double class defines an ellipse specified
in double precision.

The Float class defines an ellipse specified
in float precision.

The FlatteningPathIterator class returns a flattened view of
another PathIterator object.  Other Shape
classes can use this class to provide flattening behavior for their paths
without having to perform the interpolation calculations themselves.

The GeneralPath class represents a geometric path
constructed from straight lines, and quadratic and cubic
(Bézier) curves.  It can contain multiple subpaths.

GeneralPath is a legacy final class which exactly
implements the behavior of its superclass Path2D.Float.
Together with Path2D.Double, the Path2D classes
provide full implementations of a general geometric path that
support all of the functionality of the Shape and
PathIterator interfaces with the ability to explicitly
select different levels of internal coordinate precision.

Use Path2D.Float (or this legacy GeneralPath
subclass) when dealing with data that can be represented
and used with floating point precision.  Use Path2D.Double
for data that requires the accuracy or range of double precision.

The IllegalPathStateException represents an
exception that is thrown if an operation is performed on a path
that is in an illegal state with respect to the particular
operation being performed, such as appending a path segment
to a GeneralPath without an initial moveto.

This Line2D represents a line segment in (x,y)
coordinate space.  This class, like all of the Java 2D API, uses a
default coordinate system called user space in which the y-axis
values increase downward and x-axis values increase to the right.  For
more information on the user space coordinate system, see the

Coordinate Systems section of the Java 2D Programmer's Guide.

This class is only the abstract superclass for all objects that
store a 2D line segment.
The actual storage representation of the coordinates is left to
the subclass.

A line segment specified with double coordinates.

A line segment specified with float coordinates.

The NoninvertibleTransformException class represents
an exception that is thrown if an operation is performed requiring
the inverse of an AffineTransform object but the
AffineTransform is in a non-invertible state.

The Path2D class provides a simple, yet flexible
shape which represents an arbitrary geometric path.
It can fully represent any path which can be iterated by the
PathIterator interface including all of its segment
types and winding rules and it implements all of the
basic hit testing methods of the Shape interface.

Use Path2D.Float when dealing with data that can be represented
and used with floating point precision.  Use Path2D.Double
for data that requires the accuracy or range of double precision.

Path2D provides exactly those facilities required for
basic construction and management of a geometric path and
implementation of the above interfaces with little added
interpretation.
If it is useful to manipulate the interiors of closed
geometric shapes beyond simple hit testing then the
Area class provides additional capabilities
specifically targeted at closed figures.
While both classes nominally implement the Shape
interface, they differ in purpose and together they provide
two useful views of a geometric shape where Path2D
deals primarily with a trajectory formed by path segments
and Area deals more with interpretation and manipulation
of enclosed regions of 2D geometric space.

The PathIterator interface has more detailed descriptions
of the types of segments that make up a path and the winding rules
that control how to determine which regions are inside or outside
the path.

The Double class defines a geometric path with
coordinates stored in double precision floating point.

The Float class defines a geometric path with
coordinates stored in single precision floating point.

The PathIterator interface provides the mechanism
for objects that implement the Shape
interface to return the geometry of their boundary by allowing
a caller to retrieve the path of that boundary a segment at a
time.  This interface allows these objects to retrieve the path of
their boundary a segment at a time by using 1st through 3rd order
Bézier curves, which are lines and quadratic or cubic
Bézier splines.

Multiple subpaths can be expressed by using a "MOVETO" segment to
create a discontinuity in the geometry to move from the end of
one subpath to the beginning of the next.

Each subpath can be closed manually by ending the last segment in
the subpath on the same coordinate as the beginning "MOVETO" segment
for that subpath or by using a "CLOSE" segment to append a line
segment from the last point back to the first.
Be aware that manually closing an outline as opposed to using a
"CLOSE" segment to close the path might result in different line
style decorations being used at the end points of the subpath.
For example, the BasicStroke object
uses a line "JOIN" decoration to connect the first and last points
if a "CLOSE" segment is encountered, whereas simply ending the path
on the same coordinate as the beginning coordinate results in line
"CAP" decorations being used at the ends.

The Point2D class defines a point representing a location
in (x,y) coordinate space.

This class is only the abstract superclass for all objects that
store a 2D coordinate.
The actual storage representation of the coordinates is left to
the subclass.

The Double class defines a point specified in
double precision.

The Float class defines a point specified in float
precision.

The QuadCurve2D class defines a quadratic parametric curve
segment in (x,y) coordinate space.

This class is only the abstract superclass for all objects that
store a 2D quadratic curve segment.
The actual storage representation of the coordinates is left to
the subclass.

A quadratic parametric curve segment specified with
double coordinates.

A quadratic parametric curve segment specified with
float coordinates.

The Rectangle2D class describes a rectangle
defined by a location (x,y) and dimension
(w x h).

This class is only the abstract superclass for all objects that
store a 2D rectangle.
The actual storage representation of the coordinates is left to
the subclass.

The Double class defines a rectangle specified in
double coordinates.

The Float class defines a rectangle specified in float
coordinates.

RectangularShape is the base class for a number of
Shape objects whose geometry is defined by a rectangular frame.
This class does not directly specify any specific geometry by
itself, but merely provides manipulation methods inherited by
a whole category of Shape objects.
The manipulation methods provided by this class can be used to
query and modify the rectangular frame, which provides a reference
for the subclasses to define their geometry.

The RoundRectangle2D class defines a rectangle with
rounded corners defined by a location (x,y), a
dimension (w x h), and the width and height of an arc
with which to round the corners.

This class is the abstract superclass for all objects that
store a 2D rounded rectangle.
The actual storage representation of the coordinates is left to
the subclass.

The Double class defines a rectangle with rounded
corners all specified in double coordinates.