The JComponent Class

With the exception of top-level containers, all Swing components whose names begin with " J " descend from the JComponent ^[9] class. For example, JPanel , JScrollPane , JButton , and JTable all inherit from JComponent . However, JFrame and JDialog don't because they implement top-level containers.

^[9] JComponent API documentation: http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JComponent.html.

The JComponent class extends the Container ^[10] class, which itself extends Component . ^[11] The Component class includes everything from layout hints to painting and event support. The Container class supports adding components to the container and laying them out. This section's API tables summarize the most often used methods of Component and Container , as well as of JComponent .

^[10] Container API documentation: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/Container.html.

^[11] Component API documentation: http://java.sun.com/j2se/1.4.2/docs/api/java/awt/Component.html.

JComponent Features

The JComponent class gives its descendants many features:

• Tool tips

• Borders

• Application-wide pluggable look and feel

• Custom properties

• Support for layout

• Support for accessibility

• Support for drag and drop

• Double buffering

• Key bindings

Tool Tips

By specifying a string with the setToolTipText method, you can provide help to users of a component. When the cursor pauses over the component, the specified string is displayed in a small window that appears near the component. See How to Use Tool Tips (page 403) in Chapter 7.

Borders

The setBorder method allows you to specify the border that a component displays around its edges. To paint the inside of a component, override the paintComponent method. See How to Use Borders (page 535) in Chapter 9 and Performing Custom Painting (page 129) in Chapter 6 for details.

Application-Wide Pluggable Look and Feel

Behind the scenes, each JComponent object has a corresponding ComponentUI object that performs all the drawing, event handling, size determination, and so on, for that JComponent . Exactly which ComponentUI object is used depends on the current look and feel, which you can set using the UIManager.setLookAndFeel method. See How to Set the Look and Feel (page 628) in Chapter 9.

Custom Properties

You can associate one or more properties ( name /object pairs) with any JComponent . For example, a layout manager might use properties to associate a constraints object with each JComponent it manages . You put and get properties using the putClientProperty and getClientProperty methods. For general information about properties, see How to Write a Property-Change Listener (page 704) in Chapter 10.

Support for Layout

Although the Component class provides layout hint methods such as getPreferredSize and getAlignmentX , it doesn't provide any way to set these layout hints, short of creating a subclass and overriding the methods. To give you another way to set layout hints, the JComponent class adds setter methods ” setPreferredSize , setMinimumSize , setMaximumSize , setAlignmentX , and setAlignmentY . See Chapter 4, Laying Out Components within a Container (page 87), for more information.

Support for Accessibility

The JComponent class provides API and basic functionality to help assistive technologies, such as screen readers, get information from Swing components. See How to Support Assistive Technologies (page 519) in Chapter 9.

Support for Drag and Drop

The JComponent class provides API to set a component's transfer handler, which is the basis for Swing's drag-and-drop support. See How to Use Drag and Drop and Data Transfer (page 545) in Chapter 9.

Double Buffering

Double buffering smooths onscreen painting. See Chapter 6, Performing Custom Painting (page 129).

Key Bindings

This feature makes components react when the user presses a key on the keyboard. For example, in many look and feels, when a button has the focus, pressing the Space key is equivalent to a mouse click on the button. The look and feel automatically sets up the bindings between pressing and releasing the Space key and the resulting effects on the button. See How to Use Key Bindings (page 623) in Chapter 9 for more information.

The JComponent API

The JComponent class provides many new methods and inherits many methods from Component and Container . Tables 1 through 8 summarize the methods we use the most. You can find the Component , Container , and JComponent API documentation online at:

http://java.sun.com/j2se/1.4.2/docs/api/java/awt/Component.html

http://java.sun.com/j2se/1.4.2/docs/api/java/awt/Container.html

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JComponent.html

Table 1. Customizing Component Appearance

Method	Purpose
void setBorder(Border) Border getBorder() ( in JComponent)	Set or get the border of the component. See How to Use Borders (page 535) in Chapter 9 for details.
void setForeground(Color) void setBackground(Color) ( in Component)	Set the foreground or background color for the component. The foreground is generally the color used to draw the text. The background is the color of the background areas of the component, assuming that the component is opaque .
Color getForeground() Color getBackground() ( in Component)	Get the foreground or background color for the component.
void setOpaque(boolean) ( in JComponent) boolean isOpaque() ( in Component)	Set or get whether the component is opaque. An opaque component fills its background with its background color.
void setFont(Font) Font getFont() ( in Component)	Set or get the component's font. If a font hasn't been set for the component, the font of its parent is returned.
FontMetrics getFontMetrics(Font) ( in Component)	Get the font metrics for the specified font.

Table 2. Setting and Getting Component State

Method	Purpose
void setToolTipText(String) ( in JComponent)	Set the text to display in a tool tip. See How to Use Tool Tips (page 434) in Chapter 7 for more information.
void setName(String) String getName() ( in Component)	Set or get the name of the component. This can be useful when you need to associate text with a component that doesn't display text.
boolean isShowing() ( in Component)	Determine whether the component is showing onscreen. This means that the component must be visible and must be in a container that's visible and showing.
void setEnabled(boolean) boolean isEnabled() ( in Component)	Set or get whether the component is enabled. An enabled component can respond to user input and generate events.
void setVisible(boolean) boolean isVisible() ( in Component)	Set or get whether the component is visible. Components are initially visible, with the exception of top-level components and internal frames .

Table 3. Handling Events See Writing Event Listeners (page 107).

Method	Purpose
void addMouseListener(MouseListener) void removeMouseListener(MouseListener) ( in Component)	Add or remove a mouse listener to or from the compon-ent. Mouse listeners are notified when the user uses the mouse to interact with the listened-to component.
void addMouseMotionListener( MouseMotionListener) void removeMouseMotionListener( MouseMotionListener) ( in Component)	Add or remove a mouse motion listener to or from the component. Mouse motion listeners are notified when the user moves the mouse within the listened-to component's bounds.
void addKeyListener(KeyListener) void removeKeyListener(KeyListener) ( in Component)	Add or remove a key listener to or from the component. Key listeners are notified when the user types at the keyboard and the listened-to component has the keyboard focus.
void addComponentListener( ComponentListener) void removeComponentListener( ComponentListener) ( in Component)	Add or remove a component listener to or from the component. Component listeners are notified when the listened-to component is hidden, shown, moved, or resized.
void setTransferHandler( TransferHandler) TransferHandler getTransferHandler() ( in Component)	Set or remove the transferHandler property. The TransferHandler supports exchanging data via cut, copy, or paste to/from a clipboard as well as drag and drop. See How to Use Drag and Drop and Data Transfer (page 545) in Chapter 9 for more details. Introduced in 1.4.
boolean contains(int, int) boolean contains(Point) ( in Component)	Determine whether the specified point is within the component. The argument should be specified in terms of the component's coordinate system. The two int arguments specify x and y coordinates, respectively.
Component getComponentAt(int, int) boolean getComponentAt(Point) ( in Component)	Return the component that contains the specified x, y position. The topmost child component is returned in the case where components overlap. This is determined by finding the component closest to the index 0 that claims to contain the given point via Component.contains() .

Table 4. Painting Components See Performing Custom Painting (page 129).

Method	Purpose
void repaint() void repaint(int, int, int, int) ( in Component)	Request that all or part of the component be repainted. The four int arguments specify the bounds ( x, y , width, height, in that order) of the rectangle to be painted .
void repaint(Rectangle) ( in JComponent)	Request that the specified area within the component be repainted.
void revalidate() ( in JComponent)	Request that the component and its affected containers be laid out again. Generally you shouldn't have to invoke this method unless you explicitly change a component's size/alignment hints after it's visible or change a containment hierarchy after it's visible. You might need to invoke repaint after revalidate .
void paintComponent(Graphics) ( in JComponent)	Paint the component. Override this method to implement painting for custom components.

Table 5. Dealing with the Containment Hierarchy See Top-Level Containers and Containment Hierarchies (page 48).

Method	Purpose
Component add(Component) Component add(Component, int) void add(Component, Object) ( in Component)	Add the specified component to this container. The one-argument version of this method adds the component to the end of the container. When present, the int argument indicates the new component's position within the container. When present, the Object argument provides layout constraints to the current layout manager.
void remove(int) void remove(Component) void removeAll() ( in Component)	Removes one of or all of the components from this container. When present, the int argument indicates the position within the container of the component to remove.
JRootPane getRootPane() ( in JComponent)	Get the root pane that contains the component.
Container getTopLevelAncestor() ( in JComponent)	Get the topmost container for the component ” Window , Applet , or null if the component hasn't been added to any container.
Container getParent() ( in Component)	Get the component's immediate container.
int getComponentCount() ( in JComponent)	Get the number of components in this container.
Component getComponent(int) Component[] getComponents() ( in Component)	Get one or all of the components in this container. The int argument indicates the position of the component to get.

Table 6. Laying out Components See Doing without a Layout Manager (Absolute Positioning) (page 100).

Method	Purpose
void setPreferredSize(Dimension) void setMaximumSize(Dimension) void setMinimumSize(Dimension) ( in JComponent)	Set the component's preferred, maximum, or minimum size, measured in pixels. The preferred size indicates the best size for the component. The component should be no larger than its maximum size and no smaller than its minimum size. These are hints only and might be ignored by certain layout managers.
Dimension getPreferredSize() Dimension getMaximumSize() Dimension getMinimumSize() ( in Component)	Get the preferred, maximum, or minimum size of the component, measured in pixels. For non- JComponent subclasses, which don't have the corresponding setter methods, you can set a component's preferred, maximum, or minimum size by creating a subclass and overriding these methods.
void setAlignmentX(float) void setAlignmentY(float) ( in JComponent)	Set the alignment along the x or y axis. These values indicate how the component should be aligned relative to other components. The value should be a number between 0 and 1, where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, and 0.5 is centered, and so on. Be aware that these are hints only and might be ignored by certain layout managers.
float getAlignmentX() float getAlignmentY() ( in Component)	Get the alignment of the component along the x or y axis. For non- JComponent subclasses, which don't have the corresponding setter methods, you can set a component's alignment by creating a subclass and overriding these methods.
void setLayout(LayoutManager) LayoutManager getLayout() ( in Component)	Set or get the component's layout manager. The layout manager is responsible for sizing and positioning the components within a container.
void applyComponentOrientation( ComponentOrientation) ( in Component)	Set the ComponentOrientation property of this container and all the components within it. Introduced in 1.4.

Table 7. Getting Size and Position Information

Method	Purpose
int getWidth() int getHeight() ( in JComponent)	Get the current width or height of the component, measured in pixels.
Dimension getSize() Dimension getSize(Dimension) ( in Component)	Get the component's current size, measured in pixels. When using the one-argument version of this method, the caller is responsible for creating the Dimension instance in which the result is returned.
int getX() int getY() ( in Component)	Get the current x or y coordinate of the component's origin relative to the parent's upper left corner, measured in pixels.
Rectangle getBounds() Rectangle getBounds(Rectangle) ( in Component)	Get the bounds of the component, measured in pixels. The bounds specify the component's width, height, and origin relative to its parent. When using the one-argument version of this method, the caller is responsible for creating the Rectangle instance in which the result is returned.
Point getLocation() Point getLocation(Point) Point getLocationOnScreen() ( in Component)	Get the current location of the component relative to the parent's upper left corner, measured in pixels. When using the one-argument version of the getLocation method, the caller is responsible for creating the Point instance in which the result is returned. The getLocationOnScreen method returns the position relative to the upper left corner of the screen.
Insets getInsets() ( in Component)	Get the size of the component's border.

Table 8. Specifying Absolute Size and Position

Method	Purpose
void setLocation(int, int) void setLocation(Point) ( in Component)	Set the location of the component, in pixels, relative to the parent's upper left corner. The two int arguments specify x and y , in that order. Use these methods to position a component when you aren't using a layout manager.
void setSize(int, int) void setSize(Dimension) ( in Component)	Set the size of the component, measured in pixels. The two int arguments specify width and height, in that order. Use these methods to size a component when you aren't using a layout manager.
void setBounds(int, int, int, int) void setBounds(Rectangle) ( in Component)	Set the size and location relative to the parent's upper left corner, in pixels. The four int arguments specify x, y , width, and height, in that order. Use these methods to position and size a component when you aren't using a layout manager.