Chapter 3. Swing Component Basics
3.3 The JComponent Class
3.3.4 Fields and Methods 1 Protected Fields
protected AccessibleContext accessibleContext
Holds the AccessibleContext for the component.
protected EventListenerList listenerList
The event listener list for the component. See Chapter 27 for more information on the
EventListenerList class.
protected ComponentUI ui
The UI delegate for the component.
3.3.4.2 Constructor
public JComponent()
Initializes a simple JComponent and sets the layout manager to null.
3.3.4.3 Graphics
protected Graphics getComponentGraphics(Graphics g)
Accepts a graphics context and modifies its foreground color and font to match the current defaults. If the debug graphics option has been activated, the method returns a special graphics object that the programmer can configure for debugging component drawing with the color and font modifications.
Equivalent to paint(g). This is significantly different from the update() method of Component, which first cleared the component's background. In Swing, clearing the
component is handled by ComponentUI, based on whether the component is opaque.
public boolean contains(int x, int y)
Returns true if the coordinates passed in are inside the bounding box of the component, false otherwise. The method always asks the UI delegate first, giving it an opportunity to
define the bounding box as it sees fit. If the UI delegate does not exist for this component, or cannot define the bounding box, the standard component contains() method is invoked.
publicInsets getInsets (Insets insets)
Copies the JComponent's insets into the given Insets object, and returns a reference to this
object.
public void paint(Graphics g)
The primary method that the AWT subsystem calls upon for components to draw
themselves if they are not obscured. This method delegates most of its work to the protected methods paintComponent(), paintBorder(), and paintChildren(), which it calls in that
order. Because this method performs its own internal calculations, it is generally not a good idea to override it in a subclass; if you want to redefine how a component draws itself, override paintComponent() instead.
public void reshape(int x, int y, int w, int h)
Resets the bounds property of the component.
protected void paintComponent(Graphics g)
Draws the component using the graphics context provided. Unless overridden, it simply turns around and calls the paint() method of the delegate. If there is no delegate, the
method does nothing.
protected void paintChildren(Graphics g)
Cycles through each of the component's children, invoking the paint() method on each
one.
protected void paintBorder(Graphics g)
Paints the border (or borders) outlined in by the border property of JComponent. Note that
if a border is defined, JComponent ignores its own insets and uses the border instead.
public void repaint(long tm, int x, int y, int width, int height)
public void repaint(Rectangle r)
These methods place a request to repaint the specified region on the repaint manager's update queue. The initial variable tm of the first repaint() method is no longer used and
component layers, it is widely preferred that you call these methods, instead of directly invoking paint().
public void paintImmediately(int x, int y, int w, int h)
public void paintImmediately(Rectangle r)
These methods force an immediate repaint of the specified region in the component. This method is invoked by the repaint manager when it is time for the component to draw itself; the programmer should not call this method. This method may move to
java.awt.Component in the future.
public void revalidate()
Adds the current component to the repaint manager's revalidation queue, which is located on the system event queue.
public void computeVisibleRect(Rectangle visibleRect)
Calculates a Rectangle that represents the intersection of the component's own visible
rectangle and each of its ancestors. The result is placed in the visibleRect property and is
used to determine how much of a component is drawn to the screen.
3.3.4.4 Focus
public void requestFocus()
Shifts the focus to this component if the requestFocusEnabled property is true.
public boolean requestDefaultFocus()
Shifts the focus to a default component, typically the first focus-traversable component in the current container. If the method is unable to find such a component, it returns false.
public void grabFocus()
Used by focus managers to shift the focus to this component, regardless of the state of the
requestFocusEnabled property. Because of this, it is generally better to use requestFocus() instead of this method.
public boolean hasFocus()
Returns true if this component currently has the focus. This method is defined in java.awt.Component in JDK 1.2.
3.3.4.5 Keyboard Actions
public void registerKeyboardAction(ActionListener anAction, String aCommand,KeyStroke aKeyStroke, int aCondition)
public void registerKeyboardAction(ActionListener anAction, KeyStroke aKeyStroke,int aCondition)
These methods register a specific keyboard action with the component. When the keystroke
actionPerformed() method of the object implementing anAction. If the programmer
desires, the action command can be set to aCommand. The conditions involved are listed in
Table 3.7.
public void unregisterKeyboardAction(KeyStroke aKeyStroke)
Unregisters a keyboard action from the component.
public int getConditionForKeyStroke(KeyStroke aKeyStroke)
Returns the conditions defined for the keyboard action triggered by aKeyStroke.
public ActionListener getActionForKeyStroke(KeyStroke aKeyStroke)
Returns the Action that is registered to be triggered by aKeyStroke.
public void resetKeyboardActions()
Clears all keyboard actions for the component.
protected void processComponentKeyEvent(KeyEvent e)
This protected method is called if there are no keyboard actions matching the keystroke directed at the component. The method currently does nothing; you can override it in your own components to perform component-specific keyboard handling.
3.3.4.6 Tooltips
public String getToolTipText(MouseEvent event)
Retrieves the text used for the component's tooltip, given the appropriate mouse event.
JComponent always returns the current toolTipText property. However, you can override
this method in your own component if you want to return different strings based on various mouse events.
public Point getToolTipLocation(MouseEvent event)
Currently returns null. You can override it in your own component to specify the local
component coordinates where its tooltip should be displayed. If the method returns null,
Swing chooses a location for you.
public JToolTip createToolTip()
Returns a new instance of JToolTip by default. If you want to extend the JToolTip class
with a tooltip creation of your own, you can override this method in your components, forcing it to return the new class to the tooltip manager.
3.3.4.7 Client Properties
public final Object getClientProperty(Object key)
Searches the client property list for the Object specified under the appropriate key. It
public final void putClientProperty(Object key, Object value)
Inserts the specified client property value under the appropriate key. If the value passed in is null, the property is cleared from the list.
3.3.4.8 Event Handlers
protected void processFocusEvent(FocusEvent e)
Sets an internal flag that indicates whether the JComponent has gained or lost the focus. You
can override this method in a subclass to determine how your component reacts to
super.processFocusEvent().
protected void processComponentKeyEvent (KeyEvent e)
This method currently does nothing. You can override it if you want to handle KeyEvents in
your component independent of those consumed by the focus handler and key listeners. If you handle any KeyEvent notifications in this method, be sure to consume them.
protected void processKeyEvent(KeyEvent e)
Handles the key events for each component. It first checks with the focus manager to see if it can consume the key event, then checks for any interested listeners, and (if it has not been consumed) invokes the processComponentKeyEvent() above. If the key event still has not
been consumed at this point, it will check to see if there are any keyboard actions registered with the component.
protected void processMouseMotionEvent(MouseEvent e)
Tracks mouse drags in the event that the Swing component supports autoscrolling. You can override this method in a subclass to determine how your component reacts to mouse motion events. If you do so, be sure to call super.processMouseMotionEvent().
3.3.4.9 Miscellaneous
protected void setUI(ComponentUI u)
Installs u as the UI delegate for the component, effectively changing the component's look-
and-feel. This change doesn't appear onscreen until updateUI() is called.
public void updateUI()
Called by the current UIManager to notify the component that the look-and-feel for the
component has changed, and the UI delegate should repaint itself.
public void addNotify()
Called by Swing to notify the component that it has gained a parent. The method fires a notification to all AncestorListeners, passing in a reference to the new parent component.
The parent component (and its ancestors) inherit each of the appropriate keyboard actions and AWT event masks, as appropriate. addNotify() also fires a property change event
public void removeNotify()
Called by Swing to notify the component that it has lost a parent. The method fires a notification to all AncestorListeners, informing them that the parent component is no
longer an ancestor. removeNotify() also fires a property change event indicating that the
"ancestor"property has changed.
public void scrollRectToVisible(Rectangle aRect)
Calls similar methods up the component hierarchy. You can override this method at any level if you want to explicitly handle scrolling updates.
public static boolean isLightweightComponent(Component c)
A convenience method that returns a boolean indicating whether the component passed is a
lightweight component. If it is, the method returns true. Otherwise, it returns false. This
method may move to java.awt.Component in the future.