Chapter 28

Package java.awt

CONTENTS

• BorderLayout
• Button
• Canvas
• CardLayout
• Checkbox
• CheckboxGroup
• CheckboxMenuItem
• Choice
• Color
• Component
• Container
• Dialog
• Dimension
• Event
• FileDialog
• FlowLayout
• Font
• FontMetrics
• Frame
• Graphics
• GridBagConstraints
• GridBagLayout
• GridLayout
• Image

The java.awt package contains what is known as the Java Abstract Windowing Toolkit. The classes within this package make up the pre-built graphical user interface components that are available to Java developers through the Java Developer's Kit. Classes defined within this package include such useful components as colors, fonts, and widgets, such as buttons and scrollbars. This package also defines two interfaces, LayoutManager and MenuContainer, as well as the exception AWTException and the error AWTError. The java.awt package also contains two subpackages: java.awt.image and java.awt.peer. This chapter documents all public instance variables and methods of each subpackage, class, interface, exception, and error in the java.awt package. Because the java.awt package is so large, Table 28.1 shows a complete list of its contents, and Figure 28.1 shows the hierarchy of the contents of that package.

Figure 28.1: Contents of package java.awt.

BorderLayout

Object

The class hierarchy for the BorderLayout class derives from the class java.lang.Object. (See Listing 28.1.) A BorderLayout lays out components on a panel by implementing the LayoutManager interface. Components are laid out using members named North, South, East, West, and Center. BorderLayout's overall derivation is shown in Figure 28.1.

Listing 28.1. Public members of java.awt.BorderLayout.

public class BorderLayout implements LayoutManager {
  public BorderLayout()
  public BorderLayout(int hgap, int vgap)
  public void addLayoutComponent(String name, Component comp)
  public void removeLayoutComponent(Component comp)
  public Dimension minimumLayoutSize(Container target)
  public Dimension preferredLayoutSize(Container target)
  public void layoutContainer(Container target)
  public String toString()
}

public BorderLayout()

This BorderLayout constructor constructs a BorderLayout layout manager.

public BorderLayout(int hgap, int vgap)

This BorderLayout constructor constructs a BorderLayout layout manager using the hgap and vgap values to set the horizontal and vertical gap sizes.

hgap is an integer value used to set the horizontal gap size.

public void addLayoutComponent(String name, Component comp)

addLayoutComponent adds a component to the BorderLayout according to that component's name (North, South, East, West, or Center). The component's preferred size is used for all layout types except Center.

name is a string value that must correspond to one of the following names: North, South, East, West, or Center.

public void removeLayoutComponent(Component comp)

removeLayoutComponent removes the specified component from the layout manager.

comp is the component object to be removed.

public Dimension minimumLayoutSize(Container target)

minimumLayoutSize returns the minimum Dimension needed to lay out the components contained in the target parameter. Note that this function only determines the required size based on visible components.

target is a Container class containing components to be laid out. This class could be a Frame, Window, or any other class derived from the Container class.

public Dimension preferredLayoutSize(Container target)

preferredLayoutSize returns the preferred Dimension needed to lay out the components contained in the target parameter. This Dimension is based on the individual component's preferred sizes. Note that this function only determines the required size based on visible components.

target is a Container class containing components to be laid out. This class could be a Frame, Window, or any other class derived from the Container class.

public void layoutContainer(Container target)

layoutContainer lays out the components contained in the target Container parameter. This method reshapes the components in the Container based on the requirements of the BorderLayout itself.

target is a Container class containing components to be laid out. This class could be a Frame, Window, or any other class derived from the Container class.

public String toString()

toString returns a string representation of the BorderLayout class.

A String value containing the BorderLayout class's name plus its hgap and vgap values (see the BorderLayout() constructor).

Button

Component

The class hierarchy for the Button class derives from the class java.awt.Component. (See Listing 28.2.) A Button can be placed on any type of layout because it derives directly from Component. Button's overall derivation is shown in Figure 28.1.

Listing 28.2. Public members of java.awt.Button.

public class Button extends Component {
  public Button()
  public Button(String label)
  public synchronized void addNotify()
  public String getLabel()
  public void setLabel(String label)
}

public Button()

This Button constructor constructs a simple button with no text label.

public Button(String label)

This Button constructor constructs a simple button with a text label.

Label is a String value used to set the button's label.

public synchronized void addNotify()

addNotify sets the peer of the button using the function getToolkit().createButton(). Using peer interfaces allows you to change the user interface of the button without changing its functionality.

addNotify() in class Component.

public String getLabel()

getLabel returns the button's label string.

A String value representing the button's label string.

public void setLabel(String label)

setLabel modifies the button's label string.

label is a String value representing the button's new label string.

Canvas

Component

The class hierarchy for the Canvas class derives from the class java.awt.Component. (See Listing 28.3.) A Canvas is used as a drawing surface for GUI applications. Canvas's overall derivation is shown in Figure 28.1.

Listing 28.3. Public members of java.awt.Canvas.

public class Canvas extends Component {
  public synchronized void addNotify()
  public void paint(Graphics g)
}

public synchronized void addNotify()

addNotify sets the peer of the Canvas using the function getToolkit().createCanvas(). Using peer interfaces allows you to change the user interface of the canvas without changing its functionality.

addNotify() in class Component.

public void paint(Graphics g)

The paint() method paints the Graphics canvas (specified by the g parameter) using the default background color, which is determined by calling getBackground().

paint() in class Component.

CardLayout

Object

LayoutManager

The class hierarchy for the CardLayout class derives from the class java.lang.Object. (See Listing 28.4.) The CardLayout class is a LayoutManager that allows the addition of cards, only one of which can be visible at any given time. The user is allowed to flip through the cards. CardLayout's overall derivation is shown in Figure 28.1.

Listing 28.4. Public members of java.awt.CardLayout.

public class CardLayout implements LayoutManager {
  public CardLayout()
  public CardLayout(int hgap, int vgap)
  public void addLayoutComponent(String name, Component comp)
  public void removeLayoutComponent(Component comp)
  public Dimension preferredLayoutSize(Container target)
  public Dimension minimumLayoutSize(Container target)
  public void layoutContainer(Container parent)
  public void first(Container parent)
  public void next(Container parent)

  public void previous(Container parent)
  public void last(Container parent)
  public void show(Container parent, String name)
  public String toString()
}

public CardLayout()

This CardLayout constructor creates a new CardLayout layout manager.

public CardLayout(int hgap, int vgap)

This CardLayout constructor constructs a CardLayout layout manager using the hgap and vgap values to set the horizontal and vertical gap sizes.

Hgap is an integer value used to set the horizontal gap size.

public void addLayoutComponent(String name, Component comp)

name is a string value that corresponds to the component's name.

public void removeLayoutComponent(Component comp)

removeLayoutComponent removes the specified component from the layout manager.

comp is the component object to be removed.

public Dimension minimumLayoutSize(Container target)

minimumLayoutSize returns the minimum Dimension needed to lay out the components contained in the target parameter. Note that this function only determines the required size based on visible components.

target is a Container class containing components to be laid out. This class could be a Frame, Window, or any other class derived from the Container class.

public Dimension preferredLayoutSize(Container target)

preferredLayoutSize returns the preferred Dimension needed to lay out the components contained in the target parameter. This Dimension is based on the individual component's preferred sizes. Note that this function only determines the required size based on visible components.

target is a Container class containing components to be laid out. This class could be a Frame, Window, or any other class derived from the Container class.

public void layoutContainer(Container parent)

layoutContainer lays out the components contained in the parent Container parameter. This method reshapes the components in the Container based on the requirements of the BorderLayout itself.

parent is a Container class containing components to be laid out. This class could be a Frame, Window, or any other class derived from the Container class.

public void first(Container parent)

The first() method shows the first component in CardLayout (the first card).

parent is the parent Container class containing the components to be flipped through.

public void next(Container parent)

The next() method shows the next component in CardLayout (the next card).

parent is the parent Container class containing the components to be flipped through.

public void previous(Container parent)

The previous() method shows the previous component in CardLayout (the previous card).

parent is the parent Container class containing the components to be flipped through.

public void last(Container parent)

The last() method shows the last component in CardLayout (the last card).

parent is the parent Container class containing the components to be flipped through.

public void show(Container parent, String name)

The show() method flips to the component specified in the name parameter.

parent is the parent Container class containing the components to be flipped through.

public String toString()

toString returns a string representation of the CardLayout class.

A String value containing the CardLayout class's name plus its hgap and vgap values (see the CardLayout() constructor).

Checkbox

Component

The class hierarchy for the Checkbox class derives from the class java.awt.Component. (See Listing 28.5.) A Checkbox is a user interface component that represents a true/false (or on/off) value. Checkbox's overall derivation is shown in Figure 28.1.

Listing 28.5. Public members of java.awt.Checkbox.

public class Checkbox extends Component {
  public Checkbox()
  public Checkbox(String label)
  public Checkbox(String label, CheckboxGroup group, boolean state)
  public synchronized void addNotify()
  public String getLabel()
  public void setLabel(String label)
  public boolean getState()
  public void setState(boolean state)
  public CheckboxGroup getCheckboxGroup()
  public void setCheckboxGroup(CheckboxGroup g)
}

public Checkbox()

This Checkbox constructor constructs the simplest of all checkboxes: one with no label, no group, and a false state value.

public Checkbox(String label)

This Checkbox constructor constructs a checkbox using the label parameter to set the checkbox's label. This checkbox belongs to no group and is set to a false state value.

label is a string value representing the Checkbox's label.

public Checkbox(String label, CheckboxGroup group, boolean state)

This Checkbox constructor constructs a checkbox including the label, group, and initial value.

label is a string value representing the Checkbox's label.

state is the initial state value for this Checkbox.

public synchronized void addNotify()

addNotify sets the peer of the Checkbox using the function getToolkit().createCheckbox(). Using peer interfaces allows you to change the user interface of the Checkbox without changing its functionality.

addNotify() in class Component.

public String getLabel()

getLabel returns the Checkbox's label string.

A String value representing the Checkbox's label string.

public void setLabel(String label)

setLabel modifies the Checkbox's label string.

label is a String value representing the Checkbox's new label string.

public boolean getState()

getState returns the Checkbox's current state value.

A Boolean value representing the Checkbox's current state.

public void setState(boolean state)

setState sets the Checkbox to the value represented by the state parameter.

state is a Boolean value containing the new value of the Checkbox's state.

public CheckboxGroup getCheckboxGroup()

The getCheckboxGroup() method returns the CheckboxGroup that this Checkbox is a member of.

A CheckboxGroup class that this Checkbox is a member of. (For more information on CheckboxGroups, see the documentation for the CheckboxGroup class later in this chapter.)

public void setCheckboxGroup(CheckboxGroup g)

The setCheckboxGroup() method adds this Checkbox to a CheckboxGroup.

g is a CheckboxGroup class that this Checkbox is to be added to. (For more information on CheckboxGroups, see the documentation for the CheckboxGroup class later in this chapter.)

CheckboxGroup

Object

The class hierarchy for the CheckboxGroup class derives from the class java.lang.Object. (See Listing 28.6.) A CheckboxGroup groups a set of Checkbox classes. When Checkboxes are created within a CheckboxGroup, only one Checkbox can be selected at one time. CheckboxGroup's overall derivation is shown in Figure 28.1.

Listing 28.6. Public members of java.awt.CheckboxGroup.

public class CheckboxGroup {
  public CheckboxGroup()
  public Checkbox getCurrent()
  public synchronized void setCurrent(Checkbox box)
  public String toString()
}

public CheckboxGroup()

This CheckboxGroup constructor constructs a CheckboxGroup instance with no checkbox members.

public Checkbox getCurrent()

The getCurrent() method returns the current Checkbox.

A Checkbox object representing the currently selected Checkbox.

public synchronized void setCurrent(Checkbox box)

The setCurrent() method sets the current Checkbox in this CheckboxGroup.

box is the Checkbox object that is to be made current.

public String toString()

toString() returns a string containing CheckboxGroup information.

A String value containing the CheckboxGroup's name as well as the name of the currently selected Checkbox.

CheckboxMenuItem

MenuItem

The class hierarchy for the CheckboxMenuItem class derives from the class java.awt.MenuItem. (See Listing 28.7.) A CheckboxMenuItem is a user interface component that can be added to a menu to represent a Boolean value selection. CheckboxMenuItem's overall derivation is shown in Figure 28.1.

Listing 28.7. Public members of java.awt.CheckboxMenuItem.

public class CheckboxMenuItem extends MenuItem {
  public CheckboxMenuItem(String label)
  public synchronized void addNotify()
  public boolean getState()
  public void setState(boolean t)
  public String paramString()
}

public CheckboxMenuItem(String label)

This CheckboxMenuItem constructor creates a CheckboxMenuItem with a text label containing the string passed in.

label is a string value representing the label of the CheckboxMenuItem to be displayed.

public synchronized void addNotify()

addNotify sets the peer of the CheckboxMenuItem using the function getToolkit(). createCheckboxMenuItem(). Using peer interfaces allows you to change the user interface of the CheckboxMenuItem without changing its functionality.

addNotify() in class Component.

public boolean getState()

getState() returns the state value of the CheckboxMenuItem's checkbox.

A Boolean value representing the CheckboxMenuItem's checkbox state value.

public void setState(boolean t)

setState() sets the CheckboxMenuItem's checkbox state value.

t is a Boolean value representing the CheckboxMenuItem's checkbox state value.

public String paramString()

paramString() returns a string containing CheckboxMenuItem information.

A string value containing the CheckboxMenuItem's label as well as the state value of the CheckboxMenuItem's checkbox.

Choice

Component

The class hierarchy for the Choice class derives from the class java.awt.Component. (See Listing 28.8.) A Choice is a user interface component that displays a pop-up menu. The current selection is displayed as the pop-up menu's title. Choice's overall derivation is shown in Figure 28.1.

Listing 28.8. Public members of java.awt.Choice.

public class Choice extends Component {
  public Choice()
  public synchronized void addNotify()
  public int countItems()
  public String getItem(int index)
  public synchronized void addItem(String item)
  public String getSelectedItem()
  public int getSelectedIndex()
  public synchronized void select(int pos)
  public void select(String str)
}

public Choice()

This Choice constructor creates a default Choice object that contains no information.

public synchronized void addNotify()

addNotify sets the peer of the Choice using the function getToolkit().createChoice(). Using peer interfaces allows you to change the user interface of the Choice without changing its functionality.

addNotify() in class Component.

public int countItems()

countItems() returns the number of items (or choices) that are available in this Choice object. See the addItem() method later in this section for information on Choice items.

An integer value containing the number of items stored in this Choice object.

public String getItem(int index)

The getItem() method returns the choice string at the index represented by the index value passed in.

index is an integer value representing the index of the string item to be returned.

public synchronized void addItem(String item)

addItem() adds a String to a Choice object's internal list. The currently selected item in that list is displayed in the Choice object's pop-up menu.

item is a String object containing a string to be added to the choice list.

public String getSelectedItem()

getSelectedItem() returns the string value of the currently selected item. See the select() method later in this section for information on selecting Choice items.

A String value containing the currently selected item's string.

public int getSelectedIndex()

getSelectedIndex() returns the index of the currently selected item. See the select() method for information on selecting Choice items.

An integer value containing the index of the currently selected item.

public synchronized void select(int pos)

This select() method selects the item at the position represented by the pos parameter.

pos is an integer value representing the position of the item to be selected.

public void select(String str)

This select() method selects the item represented by the str parameter.

str is a String value representing the string value of the choice to be selected.

Color

Object

The class hierarchy for the Color class derives from the class java.awt.Object. (See Listing 28.9.) The Color 1 class is provided to encapsulate RGB (Red-Green-Blue) color values. Color's overall derivation is shown in Figure 28.1.

Listing 28.9. Public members of java.awt.Color.

public final class Color {
  public final static Color white
  public final static Color lightGray
  public final static Color gray
  public final static Color darkGray
  public final static Color black
  public final static Color red
  public final static Color pink
  public final static Color orange
  public final static Color yellow
  public final static Color green
  public final static Color magenta
  public final static Color cyan
  public final static Color blue
  public Color(int r, int g, int b)
  public Color(int rgb)
  public Color(float r, float g, float b)
  public int getRed()
  public int getGreen()
  public int getBlue()
  public int getRGB()
  public Color brighter()
  public Color darker()
  public int hashCode()
  public boolean equals(Object obj)
  public String toString()
  public static Color getColor(String nm)
  public static Color getColor(String nm, Color v)
  public static Color getColor(String nm, int v)
  public static int HSBtoRGB(float hue, float saturation, float brightness)
  public static float[] RGBtoHSB(int r, int g, int b, float[] hsbvals)
  public static Color getHSBColor(float h, float s, float b)
}

public final static Color white

Static value representing the color white.

public final static Color lightGray

Static value representing the color light gray.

public final static Color gray

Static value representing the color gray.

public final static Color darkGray

Static value representing the color dark gray.

public final static Color black

Static value representing the color black.

public final static Color red

Static value representing the color red.

public final static Color pink

Static value representing the color pink.

public final static Color orange

Static value representing the color orange.

public final static Color yellow

Static value representing the color yellow.

public final static Color green

Static value representing the color green.

public final static Color magenta

Static value representing the color magenta.

public final static Color cyan

Static value representing the color cyan.

public final static Color blue

Static value representing the color blue.

public Color(int r, int g, int b)

This Color constructor accepts as arguments individual red, green, and blue color values. These values must be in the range 0-255 and are used to build a 24-bit color value using the following method:

The red value represents bits 16-23.

The green value represents bits 8-15.

The blue value represents bits 0-7.

This Color constructor determines the closest color to the value supported by the current output device.

r is the red color value.

public Color(int rgb)

This Color constructor creates a Color object based on the RGB color value passed in.

rgb is an integer value containing the red, green, and blue color values that are used to create this Color object.

public Color(float r, float g, float b)

This Color constructor creates a Color object based on the color values passed in. This constructor is similar to the Color constructor that accepts integer red, green, and blue inputs except that this Color constructor accepts float values. These values must be in the range 0-1.0 and are used to build a 24-bit color value using the following method:

The red value * 255 represents bits 16-23.

The green value * 255 represents bits 8-15.

The blue value * 255 represents bits 0-7.

This Color constructor determines the closest color to the value supported by the current output device.

r is the red color value.

public int getRed()

The getRed() method returns the red component of this Color.

An integer value representing this Color's red component.

public int getGreen()

The getGreen() method returns the green component of this Color.

An integer value representing this Color's green component.

public int getBlue()

The getBlue() method returns the blue component of this Color.

An integer value representing this Color's blue component.

public int getRGB()

The getRGB() method returns the RGB value of this Color.

An integer value representing this Color's RGB value in the default RGB color model.

public Color brighter()

The brighter() method brightens this Color by modifying the RGB color value. This method increases the individual red, green, and blue color components by a factor of approxi- mately 1.4.

A Color object representing a brighter version of the current color.

public Color darker()

The darker() method darkens this Color by modifying the RGB color value. This method decreases the individual red, green, and blue color components by a factor of approxi- mately 1.4.

A Color object representing a darker version of the current color.

public int hashCode()

hashCode() returns this Color's hash code. This is useful when storing Colors in a hash table.

An integer value representing this Color's hash code.

public boolean equals(Object obj)

The equals() method compares the Object parameter with this Color object. It returns a Boolean value representing the result of this comparison.

obj is an Object object to be compared with this Color.

public String toString()

toString()returns a string representation of the Color class.

A String value containing the Color class's name plus its red, green, and blue values (see the Color() constructors).

public static Color getColor(String nm)

getColor() returns the specified color property based on the name that is passed in.

nm is the name of the color property.

public static Color getColor(String nm, Color v)

getColor() returns the specified Color property of the specified color.

nm is the name of the color property.

public static Color getColor(String nm, int v)

getColor() returns the specified Color property of the color value that is passed in.

nm is the name of the color property.

public static int HSBtoRGB(float hue, float saturation, float brightness)

HSB stands for hue, saturation, and brightness. To convert from an HSB value to an RGB value, simply call this function with the appropriate arguments.

hue is the color's hue component.

public static float[] RGBtoHSB(int r, int g, int b, float[] hsbvals)

HSB stands for hue, saturation, and brightness. To convert from an RGB value to an HSB value, simply call this function with the appropriate arguments.

r is the color's red component.

hsbvals is an array that stores the HSB result values.

public static Color getHSBColor(float h, float s, float b)

The getHSBColor() method returns a Color object representing the RGB value of the input HSB parameters.

h is the color's hue component.

Component

Object

ImageObserver

The class hierarchy for the Component class derives from the class java.lang.Object. (See Listing 28.10.) The Component class represents a generic user interface component. All AWT UI components derive from the Component class. Component's overall derivation is shown in Fig-ure 28.1.

Listing 28.10. Public members of java.awt.Component.

public abstract class Component implements ImageObserver {
  public Container getParent()
  public ComponentPeer getPeer()
  public Toolkit getToolkit()
  public boolean isValid()
  public boolean isVisible()
  public boolean isShowing()
  public boolean isEnabled()
  public Point location()
  public Dimension size()
  public Rectangle bounds()
  public synchronized void enable()
  public void enable(boolean cond)
  public synchronized void disable()
  public synchronized void show()
  public void show(boolean cond)
  public synchronized void hide()
  public Color getForeground()
  public synchronized void setForeground(Color c)
  public Color getBackground()
  public synchronized void setBackground(Color c)
  public Font getFont()
  public synchronized void setFont(Font f)
  public synchronized ColorModel getColorModel()
  public void move(int x, int y)
  public void resize(int width, int height)
  public void resize(Dimension d)
  public synchronized void reshape(int x, int y, int width, int height)
  public Dimension preferredSize()
  public Dimension minimumSize()
  public void layout()
  public void validate()
  public void invalidate()
  public Graphics getGraphics()
  public FontMetrics getFontMetrics(Font font)
  public void paint(Graphics g)
  public void update(Graphics g)
  public void paintAll(Graphics g)
  public void repaint()
  public void repaint(long tm)
  public void repaint(int x, int y, int width, int height)
  public void repaint(long tm, int x, int y, int width, int height)
  public void print(Graphics g)
  public void printAll(Graphics g)
  public boolean imageUpdate(Image img, int flags,
                               int x, int y, int w, int h)
  public Image createImage(ImageProducer producer)
  public Image createImage(int width, int height
  public boolean prepareImage(Image image, ImageObserver observer)
  public boolean prepareImage(Image image, int width, int height,
                                ImageObserver observer)
  public int checkImage(Image image, ImageObserver observer)
  public int checkImage(Image image, int width, int height,
                          ImageObserver observer)
  public synchronized boolean inside(int x, int y)
  public Component locate(int x, int y)
  public void deliverEvent(Event e)
  public boolean postEvent(Event e)
  public boolean handleEvent(Event evt)
  public boolean mouseDown(Event evt, int x, int y)
  public boolean mouseDrag(Event evt, int x, int y)
  public boolean mouseUp(Event evt, int x, int y)
  public boolean mouseMove(Event evt, int x, int y)
  public boolean mouseEnter(Event evt, int x, int y)
  public boolean mouseExit(Event evt, int x, int y)
  public boolean keyDown(Event evt, int key)
  public boolean keyUp(Event evt, int key)
  public boolean action(Event evt, Object what)
  public void addNotify()
  public synchronized void removeNotify()
  public boolean gotFocus(Event evt, Object what)
  public boolean lostFocus(Event evt, Object what)
  public void requestFocus()
  public void nextFocus()
  public String toString()
  public void list()
  public void list(PrintStream out)
  public void list(PrintStream out, int indent)
}

public Container getParent()

getParent() returns this component's parent (a Container class).

public ComponentPeer getPeer()

getPeer() returns this component's peer (a ComponentPeer interface).

A ComponentPeer interface representing the component's peer. For more information on ComponentPeers, see the documentation for the ComponentPeer interface later in this chapter.

public Toolkit getToolkit()

getToolkit() returns the toolkit of this component. The toolkit creates the peer for the component.

A Toolkit class. A toolkit is required to bind the abstract AWT classes to a native toolkit implementation. For more information on the Toolkit class, see the documentation for the Toolkit class later in this chapter.

public boolean isValid()

isValid() determines whether this component is valid. A Component is considered to be invalid when it is first shown on the screen.

A Boolean value representing the valid state of this component.