Chapter 9. The java.awt Package

ActiveEvent	Java 1.2
java.awt

This interface is implemented by events that know how to dispatch themselves. When the event dispatch system encounters an ActiveEvent on the event queue, it simply invokes the dispatch() method of the event, instead of attempting to dispatch the event on its own. This interface is implemented by java.awt.event.InvocationEvent, which is used by the invokeLater() and invokeAndWait() methods of EventQueue.

Implementations: java.awt.event.InvocationEvent

Adjustable	Java 1.1
java.awt	PJ1.1

This interface defines the methods that should be implemented by an object that maintains a user-adjustable numeric value. The adjustable value has specified minimum and maximum values, and it may be incremented or decremented either a unit at a time or a block at a time. An Adjustable object generates an AdjustmentEvent when it is adjusted and maintains a list of AdjustmentListener objects interested in being notified when such an event occurs.

This interface abstracts the essential functionality of the Scrollbar and javax.swing.JScrollBar components.

Implementations: Scrollbar, javax.swing.JScrollBar

Passed To: java.awt.event.AdjustmentEvent.AdjustmentEvent(), java.awt.peer.ScrollPanePeer.{setUnitIncrement(), setValue()}

Returned By: ScrollPane.{getHAdjustable(), getVAdjustable()}, java.awt.event.AdjustmentEvent.getAdjustable()

AlphaComposite	Java 1.2
java.awt

This implementation of the Composite interface blends colors according to their levels of alpha transparency. AlphaComposite does not have a public constructor, but you can obtain a shared immutable instance by calling the static getInstance() method, specifying the desired compositing rule (one of the eight integer constants defined by the class), and specifying an alpha value. Alternatively, if you use an alpha value of 1.0, you can simply use one of the eight predefined AlphaComposite constants. Once you have obtained an AlphaComposite object, you use it by passing it to the setComposite() method of a Graphics2D object.

The most common way to use an AlphaComposite object is to specify the SRC_OVER compositing rule and an alpha value greater than 0 but less than 1. This causes the source colors you draw to be given the specified level of alpha transparency, so that they are blended with whatever colors already exist on the screen, making the destination colors appear to show through the translucent source colors. This technique allows you to achieve transparency effects using opaque colors when you are drawing onto a drawing surface, like a screen, that does not have an alpha channel.

The other compositing rules of AlphaComposite are best understood when both the source (your drawing) and the destination (the drawing surface) have alpha channels. For example, you can create translucent Color objects with the four-argument version of the Color() constructor, and you can create an off-screen image with an alpha channel by passing the constant TYPE_INT_ARGB to the java.awt.image.BufferedImage() constructor. (Once your compositing operation has been performed in an off-screen image with an alpha channel, you can view the results by copying the contents of the image to the screen, of course.) When your source and destination have alpha channels built in, you do not usually specify an alpha value for the AlphaComposite itself. If you do, however, the transparency values of the source colors are multiplied by this alpha value.

AlphaComposite supports the following compositing rules:

SRC

Replace the colors of the destination with the colors of the source, ignoring the destination colors and the transparency of the source.

SRC_OVER

Combine the source and destination colors combined based on the transparency of the source, so that the source appears to be drawn over the destination.

DST_OVER

Combine the source and destination colors based on the transparency of the destination, so that the source appears to be drawn underneath the destination.

SRC_IN

Draw the colors of the source using the transparency values of the destination, completely ignoring the colors of the destination.

SRC_OUT

Draw the colors of the source using the inverse transparency values of the destination.

DST_IN

Modify the colors of the destination using the alpha values of the source and ignoring the colors of the source.

DST_OUT

Modify the colors of the destination using the inverted alpha values of the source and ignoring the colors of the source.

CLEAR

Ignore the color and transparency of both the destination and the source. This clears the destination by making it a fully transparent black.

Hierarchy: Object-->AlphaComposite(Composite)

Returned By: AlphaComposite.getInstance()

Type Of: AlphaComposite.{Clear, DstIn, DstOut, DstOver, Src, SrcIn, SrcOut, SrcOver}

AWTError	Java 1.0
java.awt	serializable error PJ1.1

Signals that an error has occurred in the java.awt package.

Hierarchy: Object-->Throwable(Serializable)-->Error-->AWTError

AWTEvent	Java 1.1
java.awt	serializable event PJ1.1

This abstract class serves as the root event type for all AWT events in Java 1.1 and supersedes the Event class that was used in Java 1.0.

Each AWTEvent has a source object, as all EventObject objects do. You can query the source of an event with the inherited getSource() method. The AWTEvent class adds an event type, or ID, for every AWT event. Use getID() to query the type of an event. Subclasses of AWTEvent define various constants for this type field.

The various _MASK constants are used by applets and custom components that call the enableEvents() method of Component to receive various event types without having to register EventListener objects.

Hierarchy: Object-->java.util.EventObject(Serializable)-->AWTEvent

Subclasses: java.awt.event.ActionEvent, java.awt.event.AdjustmentEvent, java.awt.event.ComponentEvent, java.awt.event.InputMethodEvent, java.awt.event.InvocationEvent, java.awt.event.ItemEvent, java.awt.event.TextEvent, javax.swing.event.AncestorEvent, javax.swing.event.InternalFrameEvent

Passed To: Too many methods to list.

Returned By: Component.coalesceEvents(), EventQueue.{getNextEvent(), peekEvent()}

AWTEventMulticaster	Java 1.1
java.awt	PJ1.1

AWTEventMulticaster is a convenience class used when writing a custom AWT component. It provides an easy way to maintain a list of AWT EventListener objects and notify the listeners on that list when an event occurs.

AWTEventMulticaster implements each of the event listener interfaces defined in the java.awt.event package, which means that an AWTEventMulticaster object can serve as any desired type of event listener. (It also means that the class defines quite a few methods.) AWTEventMulticaster implements what amounts to a linked list of EventListener objects. When you invoke one of the EventListener methods of an AWTEventMulticaster, it invokes the same method on all of the EventListener objects in the linked list.

Rather than instantiate an AWTEventMulticaster object directly, you use the static add() and remove() methods of the class to add and remove EventListener objects from the linked list. Calling add() or remove() returns an AWTEventMulticaster with the appropriate EventListener object registered or deregistered. Using an AWTEventMulticaster is somewhat non-intuitive, so here is some example code that shows its use:

public class MyList extends Component {   // a class that sends ItemEvents
  // The head of a linked list of AWTEventMulticaster objects
  protected ItemListener listener = null;
  public void addItemListener(ItemListener l) {      // add a listener
    listener = AWTEventMulticaster.add(listener, l);
  }
  public void removeItemListener(ItemListener l) {   // remove a listener
    listener = AWTEventMulticaster.remove(listener, l);
  }
  protected void fireItemEvent(ItemEvent e) {        // notify all listeners
    if (listener != null) listener.itemStateChanged(e);
  }
  // The rest of the class goes here
}

Hierarchy: Object-->AWTEventMulticaster(java.awt.event.ActionListener(java.util.EventListener),java.awt.event.AdjustmentListener(java.util.EventListener),java.awt.event.ComponentListener(java.util.EventListener),java.awt.event.ContainerListener(java.util.EventListener),java.awt.event.FocusListener(java.util.EventListener),java.awt.event.InputMethodListener(java.util.EventListener),java.awt.event.ItemListener(java.util.EventListener),java.awt.event.KeyListener(java.util.EventListener),java.awt.event.MouseListener(java.util.EventListener),java.awt.event.MouseMotionListener(java.util.EventListener),java.awt.event.TextListener(java.util.EventListener),java.awt.event.WindowListener(java.util.EventListener))

AWTException	Java 1.0
java.awt	serializable checked PJ1.1

Signals that an exception has occurred in the java.awt package.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->AWTException

Thrown By: Cursor.getSystemCustomCursor()

AWTPermission	Java 1.2
java.awt	serializable permission

This class encapsulates permissions for performing various AWT-related operations; applications do not typically use it. The name, or target, of a permission should be one of the following values: "accessClipboard", "accessEventQueue", "listenToAllAWTEvents", or "showWindowWithoutWarningBanner". Alternatively, a name of "*" implies all of these values. AWTPermission does not use actions, so the actions argument to the constructor should be null.

Hierarchy: Object-->java.security.Permission(java.security.Guard,Serializable)-->java.security.BasicPermission(Serializable)-->AWTPermission

BasicStroke	Java 1.2
java.awt

This class defines properties that control how lines are drawn. By default, lines are one-pixel wide and solid. To change these attributes, pass a BasicStroke (or another implementation of Stroke) to the setStroke() method of a Graphics2D object. BasicStroke supports the following line attribute properties:

lineWidth

The thickness of the line.

endCap

The end cap style of the line. CAP_BUTT specifies that a line ends exactly at its end points, without caps. CAP_SQUARE causes a line to end with square caps that extend beyond the end points by a distance equal to one-half of the line width. CAP_ROUND specifies that a line ends with round caps with a radius of one-half of the line width.

lineJoin

The join style when two line segments meet at the vertex of a shape. JOIN_MITER specifies that the outside edges of the two line segments are extended as far as necessary until they intersect. JOIN_BEVEL causes the outside corners of the vertex to be joined with a straight line. JOIN_ROUND specifies that the vertex is rounded with a curve that has a radius of half the line width.

miterLimit

The maximum length of the miter used to connect two intersecting line segments. When two lines intersect at an acute angle and the line join style is JOIN_MITER, the length of the miter gets progressively longer as the angle between the lines gets smaller. This property imposes a maximum length on the miter; beyond this length, the miter is squared off.

dashArray

The pattern of dashes and spaces that make up a dashed line. This attribute is an array, where the first element and all the additional odd elements specify the lengths of dashes. The second element and all the additional even elements specify the lengths of the spaces. When the dash pattern is complete, it starts over at the beginning of the array, of course.

dashPhase

The distance into the dash pattern that line drawing begins. Note that this value is not an index into the dash array, but a distance. For example, if you've specified a dash of length 5 followed by a space of length 3 and want to begin your line with the space rather than the dash, you set this property to 5.

See Stroke for a discussion of how line drawing is performed in Java 2D.

Hierarchy: Object-->BasicStroke(Stroke)

BorderLayout	Java 1.0
java.awt	serializable layout manager PJ1.1

A LayoutManager that arranges components that have been added to their Container (using the Container.add() method) with the names "North", "South", "East", "West", and "Center". These named components are arranged along the edges and in the center of the container. The hgap and vgap arguments to the BorderLayout constructor specify the desired horizontal and vertical spacing between adjacent components.

In Java 1.1, five constants were defined to represent these strings. In Java 1.2, an additional four constants have been added to represent the four sides of the container in a way that is independent of writing direction. For example, BEFORE_LINE_BEGINS is the same as WEST in locales where text is drawn from left to right, but is the same as EAST in locales where text is drawn from right to left.

Note that an application should never call the LayoutManager methods of this class directly; the Container for which the BorderLayout is registered does this.

In Java 1.1, five constants were defined to represent these strings. In Java 1.2, an additional four constants have been added to represent the four sides of the container in a way that is independent of writing direction. For example, BEFORE_LINE_BEGINS is the same as WEST in locales where text is drawn from left to right but is the same as EAST in locales where text is drawn right to left.

Hierarchy: Object-->BorderLayout(LayoutManager2(LayoutManager),Serializable)

Button	Java 1.0
java.awt	serializable AWT component PJ1.1

This class represents a GUI push button that displays a specified textual label. Use setActionCommand() to specify an identifying string that is included in the ActionEvent events generated by the button.

Hierarchy: Object-->Component(java.awt.image.ImageObserver,MenuContainer,Serializable)-->Button

Passed To: Toolkit.createButton()

Canvas	Java 1.0
java.awt	serializable AWT component PJ1.1

A Component that does no default drawing or event handling on its own. You can subclass it to display any kind of drawing or image and handle any kind of user input event. Canvas inherits the event-handling methods of its superclass. In Java 1.1, you can also subclass Component directly to create a lightweight component, instead of having to subclass Canvas.

Hierarchy: Object-->Component(java.awt.image.ImageObserver,MenuContainer,Serializable)-->Canvas

Passed To: Toolkit.createCanvas()

CardLayout	Java 1.0
java.awt	serializable layout manager PJ1.1

A LayoutManager that makes each of the components it manages as large as the container and ensures that only one is visible at a time. The standard LayoutManager methods are called by the Container object and should not be called directly by applet or application code. first(), last(), next(), previous(), and show() make a particular Component in the Container visible. The names with which the components are added to the container are used only by the show() method.

Hierarchy: Object-->CardLayout(LayoutManager2(LayoutManager),Serializable)

Checkbox	Java 1.0
java.awt	serializable AWT component PJ1.1

This class represents a GUI checkbox with a textual label. The Checkbox maintains a boolean state--whether it is checked or not. The checkbox may optionally be part of a CheckboxGroup that enforces radio button behavior.

Hierarchy: Object-->Component(java.awt.image.ImageObserver,MenuContainer,Serializable)-->Checkbox(ItemSelectable)

Passed To: CheckboxGroup.{setCurrent(), setSelectedCheckbox()}, Toolkit.createCheckbox()

Returned By: CheckboxGroup.{getCurrent(), getSelectedCheckbox()}

CheckboxGroup	Java 1.0
java.awt	serializable PJ1.1

A CheckboxGroup object enforces mutual exclusion (also known as radio button behavior) among any number of Checkbox buttons. A Checkbox component can specify a CheckboxGroup object when created or with its setCheckboxGroup() method. If a Checkbox within a CheckboxGroup object is selected, the CheckboxGroup ensures that the previously selected Checkbox becomes unselected.

Hierarchy: Object-->CheckboxGroup(Serializable)

Passed To: Checkbox.{Checkbox(), setCheckboxGroup()}, java.awt.peer.CheckboxPeer.setCheckboxGroup()

Returned By: Checkbox.getCheckboxGroup()

CheckboxMenuItem	Java 1.0
java.awt	serializable AWT component PJ1.1(opt)

This class represents a checkbox with a textual label in a GUI menu. It maintains a boolean state--whether it is checked or not. See also MenuItem.

Hierarchy: Object-->MenuComponent(Serializable)-->MenuItem-->CheckboxMenuItem(ItemSelectable)

Passed To: Toolkit.createCheckboxMenuItem()

Choice	Java 1.0
java.awt	serializable AWT component PJ1.1

This class represents an option menu or dropdown list. The addItem() method adds an item with the specified label to a Choice menu. getSelectedIndex() returns the numerical position of the selected item in the menu, while getSelectedItem() returns the label of the selected item.

Hierarchy: Object-->Component(java.awt.image.ImageObserver,MenuContainer,Serializable)-->Choice(ItemSelectable)

Passed To: Toolkit.createChoice()

Color	Java 1.0
java.awt	serializable PJ1.1

This class describes a color in terms of the individual components of that color. These components are either float values that range between 0 and 1 or 8-bit integers that range from 0 to 255. Prior to Java 1.2, only the RGB (red, green, blue) color space was supported. With the advent of Java 2D, the Color class has been extended to support alpha transparency and arbitrary java.awt.color.ColorSpace objects. In addition, the Java 1.2 Color class implements the Paint interface and is used to perform Java 2D drawing and filling operations that use solid colors.

Color objects can be obtained in a number of ways. The Color() constructors allow color components to be directly specified. The class also defines several color constants. The SystemColor subclass defines other useful Color constants that are related to standard colors used on the system desktop. The static methods HSBtoRGB() and RGBtoHSB() convert between the RGB color space and the HSB (hue, saturation, brightness) color space and can be used to create colors specified using the more intuitive HSB color components. brighter() and darker() return variants on the current color and are useful for creating shading effects.

An RGB color can be expressed as a 24-bit number, where the top 8 bits specifies the red component, the middle 8 bits specifies the green component, and the low 8 bits specifies the blue component. Colors are often represented using a string representation of this 24-bit number. It is particularly common to use a hexadecimal representation for a color, since it keeps the red, green, and blue components distinct. For example, the string "0xFF0000" represents a bright red color: the red component has a value of 255, and both the green and blue components are 0. The static decode() method converts color strings encoded in this way to Color objects. Each getColor() method looks up the specified key in the system properties list and then decodes the value and returns the resulting Color or the specified default color, if no color is found in the properties list.

getRGB() returns the red, green, and blue components of a color as a 24-bit number. getRed(), getBlue(), getGreen(), and getAlpha() return the individual components of a color as integers. getComponents() is a generalized method that returns the color and transparency components of a color in a float array, using an optionally specified ColorSpace. getColorComponents() is similar but returns only the color components, not the transparency component. getRGBComponents() returns the color and alpha components as float values using the RGB color space. getRGBColorComponents() does the same but does not return the alpha component. Each of these methods either fills in the elements of a float[] array you provide or allocates one of its own, if you pass null.

Hierarchy: Object-->Color(Paint(Tra