javax.swing
Class SwingUtilities

java.lang.Object
  javax.swing.SwingUtilities

All Implemented Interfaces:

SwingConstants

public class SwingUtilities

extends java.lang.Object

implements SwingConstants

A collection of utility methods for Swing.

Field Summary

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Method Summary

static Rectangle	calculateInnerArea(JComponent c, Rectangle r) Stores the position and size of the inner painting area of the specified component in r and returns r.
static Rectangle[]	computeDifference(Rectangle rectA, Rectangle rectB) Convenience returning an array of rect representing the regions within rectA that do not overlap with rectB.
static Rectangle	computeIntersection(int x, int y, int width, int height, Rectangle dest) Convenience to calculate the intersection of two rectangles without allocating a new rectangle.
static int	computeStringWidth(java.awt.FontMetrics fm, java.lang.String str) Compute the width of the string using a font with the specified "metrics" (sizes).
static Rectangle	computeUnion(int x, int y, int width, int height, Rectangle dest) Convenience method that calculates the union of two rectangles without allocating a new rectangle.
static java.awt.event.MouseEvent	convertMouseEvent(java.awt.Component source, java.awt.event.MouseEvent sourceEvent, java.awt.Component destination) Returns a MouseEvent similar to sourceEvent except that its x and y members have been converted to destination's coordinate system.
static Point	convertPoint(java.awt.Component source, int x, int y, java.awt.Component destination) Convert the point (x,y) in source coordinate system to destination coordinate system.
static Point	convertPoint(java.awt.Component source, Point aPoint, java.awt.Component destination) Convert a aPoint in source coordinate system to destination coordinate system.
static void	convertPointFromScreen(Point p, java.awt.Component c) Convert a point from a screen coordinates to a component's coordinate system
static void	convertPointToScreen(Point p, java.awt.Component c) Convert a point from a component's coordinate system to screen coordinates.
static Rectangle	convertRectangle(java.awt.Component source, Rectangle aRectangle, java.awt.Component destination) Convert the rectangle aRectangle in source coordinate system to destination coordinate system.
static java.awt.Container	getAncestorNamed(java.lang.String name, java.awt.Component comp) Convenience method for searching above comp in the component hierarchy and returns the first object of name it finds.
static java.awt.Container	getAncestorOfClass(java.lang.Class c, java.awt.Component comp) Convenience method for searching above comp in the component hierarchy and returns the first object of class c it finds.
static java.awt.Component	getDeepestComponentAt(java.awt.Component parent, int x, int y) Returns the deepest visible descendent Component of parent that contains the location x, y.
static Rectangle	getLocalBounds(java.awt.Component aComponent) Return the rectangle (0,0,bounds.width,bounds.height) for the component aComponent
static JRootPane	getRootPane(java.awt.Component c) If c is a JRootPane descendant return its JRootPane ancestor.
static java.awt.Window	getWindowAncestor(java.awt.Component c)
static void	invokeAndWait(java.lang.Runnable doRun) Causes doRun.run() to be executed synchronously on the AWT event dispatching thread.
static void	invokeLater(java.lang.Runnable doRun) Causes doRun.run() to be executed asynchronously on the AWT event dispatching thread.
static boolean	isDescendingFrom(java.awt.Component a, java.awt.Component b) Return true if a component a descends from a component b
static boolean	isEventDispatchThread() Returns true if the current thread is an AWT event dispatching thread.
static boolean	isLeftMouseButton(java.awt.event.MouseEvent anEvent) Returns true if the mouse event specifies the left mouse button.
static boolean	isMiddleMouseButton(java.awt.event.MouseEvent anEvent) Returns true if the mouse event specifies the middle mouse button.
static boolean	isRectangleContainingRectangle(Rectangle a, Rectangle b) Return true if a contains b
static boolean	isRightMouseButton(java.awt.event.MouseEvent anEvent) Returns true if the mouse event specifies the right mouse button.
static java.lang.String	layoutCompoundLabel(java.awt.FontMetrics fm, java.lang.String text, Icon icon, int verticalAlignment, int horizontalAlignment, int verticalTextPosition, int horizontalTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int textIconGap) Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string.
static boolean	notifyAction(Action action, KeyStroke ks, java.awt.event.KeyEvent event, java.lang.Object sender, int modifiers) Invokes actionPerformed on action if action is enabled (and non null).
static boolean	processKeyBindings(java.awt.event.KeyEvent event) Process the key bindings for the Component associated with event.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isRectangleContainingRectangle

public static final boolean isRectangleContainingRectangle(Rectangle a,
                                                           Rectangle b)

Return true if a contains b

getLocalBounds

public static Rectangle getLocalBounds(java.awt.Component aComponent)

Return the rectangle (0,0,bounds.width,bounds.height) for the component aComponent

getWindowAncestor

public static java.awt.Window getWindowAncestor(java.awt.Component c)

Returns:

the first Window ancestor of c, or null if component is not contained inside a window

convertPoint

public static Point convertPoint(java.awt.Component source,
                                 Point aPoint,
                                 java.awt.Component destination)

Convert a aPoint in source coordinate system to destination coordinate system. If source>is null,aPoint is assumed to be in destination's root component coordinate system. If destinationis null, aPoint will be converted to source's root component coordinate system. If both source and destination are null, return aPoint without any conversion.

convertPoint

public static Point convertPoint(java.awt.Component source,
                                 int x,
                                 int y,
                                 java.awt.Component destination)

Convert the point (x,y) in source coordinate system to destination coordinate system. If source>is null,(x,y) is assumed to be in destination's root component coordinate system. If destinationis null, (x,y) will be converted to source's root component coordinate system. If both source and destination are null, return (x,y) without any conversion.

convertRectangle

public static Rectangle convertRectangle(java.awt.Component source,
                                         Rectangle aRectangle,
                                         java.awt.Component destination)

Convert the rectangle aRectangle in source coordinate system to destination coordinate system. If source>is null,aRectangle is assumed to be in destination's root component coordinate system. If destinationis null, aRectangle will be converted to source's root component coordinate system. If both source and destination are null, return aRectangle without any conversion.

getAncestorOfClass

public static java.awt.Container getAncestorOfClass(java.lang.Class c,
                                                    java.awt.Component comp)

Convenience method for searching above comp in the component hierarchy and returns the first object of class c it finds. Can return null, if a class c cannot be found.

getAncestorNamed

public static java.awt.Container getAncestorNamed(java.lang.String name,
                                                  java.awt.Component comp)

Convenience method for searching above comp in the component hierarchy and returns the first object of name it finds. Can return null, if name cannot be found.

getDeepestComponentAt

public static java.awt.Component getDeepestComponentAt(java.awt.Component parent,
                                                       int x,
                                                       int y)

Returns the deepest visible descendent Component of parent that contains the location x, y. If parent does not contain the specified location, then null is returned. If parent is not a container, or none of parent's visible descendents contain the specified location, parent is returned.

Parameters:

parent - the root component to begin the search

x - the x target location

y - the y target location

convertMouseEvent

public static java.awt.event.MouseEvent convertMouseEvent(java.awt.Component source,
                                                          java.awt.event.MouseEvent sourceEvent,
                                                          java.awt.Component destination)

Returns a MouseEvent similar to sourceEvent except that its x and y members have been converted to destination's coordinate system. If source is null, sourceEvent x and y members are assumed to be into destination's root component coordinate system. If destination is null, the returned MouseEvent will be in source's coordinate system. sourceEvent will not be changed. A new event is returned. the source field of the returned event will be set to destination if destination is non null use the translateMouseEvent() method to translate a mouse event from one component to another without changing the source.

convertPointToScreen

public static void convertPointToScreen(Point p,
                                        java.awt.Component c)

Convert a point from a component's coordinate system to screen coordinates.

Parameters:

p - a Point object (converted to the new coordinate system)

c - a Component object

convertPointFromScreen

public static void convertPointFromScreen(Point p,
                                          java.awt.Component c)

Convert a point from a screen coordinates to a component's coordinate system

Parameters:

p - a Point object (converted to the new coordinate system)

c - a Component object

isDescendingFrom

public static boolean isDescendingFrom(java.awt.Component a,
                                       java.awt.Component b)

Return true if a component a descends from a component b

computeIntersection

public static Rectangle computeIntersection(int x,
                                            int y,
                                            int width,
                                            int height,
                                            Rectangle dest)

Convenience to calculate the intersection of two rectangles without allocating a new rectangle. If the two rectangles don't intersect, then the returned rectangle begins at (0,0) and has zero width and height.

Parameters:

x - the X coordinate of the first rectangle's top-left point

y - the Y coordinate of the first rectangle's top-left point

width - the width of the first rectangle

height - the height of the first rectangle

dest - the second rectangle

Returns:

dest, modified to specify the intersection

computeUnion

public static Rectangle computeUnion(int x,
                                     int y,
                                     int width,
                                     int height,
                                     Rectangle dest)

Convenience method that calculates the union of two rectangles without allocating a new rectangle.

Parameters:

x - the x-coordinate of the first rectangle

y - the y-coordinate of the first rectangle

width - the width of the first rectangle

height - the height of the first rectangle

dest - the coordinates of the second rectangle; the union of the two rectangles is returned in this rectangle

Returns:

the dest Rectangle

computeDifference

public static Rectangle[] computeDifference(Rectangle rectA,
                                            Rectangle rectB)

Convenience returning an array of rect representing the regions within rectA that do not overlap with rectB. If the two Rects do not overlap, returns an empty array

isLeftMouseButton

public static boolean isLeftMouseButton(java.awt.event.MouseEvent anEvent)

Returns true if the mouse event specifies the left mouse button.

Parameters:

anEvent - a MouseEvent object

Returns:

true if the left mouse button was active

isMiddleMouseButton

public static boolean isMiddleMouseButton(java.awt.event.MouseEvent anEvent)

Returns true if the mouse event specifies the middle mouse button.

Parameters:

anEvent - a MouseEvent object

Returns:

true if the middle mouse button was active

isRightMouseButton

public static boolean isRightMouseButton(java.awt.event.MouseEvent anEvent)

Returns true if the mouse event specifies the right mouse button.

Parameters:

anEvent - a MouseEvent object

Returns:

true if the right mouse button was active

computeStringWidth

public static int computeStringWidth(java.awt.FontMetrics fm,
                                     java.lang.String str)

Compute the width of the string using a font with the specified "metrics" (sizes).

Parameters:

fm - a FontMetrics object to compute with

str - the String to compute

Returns:

an int containing the string width

layoutCompoundLabel

public static java.lang.String layoutCompoundLabel(java.awt.FontMetrics fm,
                                                   java.lang.String text,
                                                   Icon icon,
                                                   int verticalAlignment,
                                                   int horizontalAlignment,
                                                   int verticalTextPosition,
                                                   int horizontalTextPosition,
                                                   Rectangle viewR,
                                                   Rectangle iconR,
                                                   Rectangle textR,
                                                   int textIconGap)

Compute and return the location of the icons origin, the location of origin of the text baseline, and a possibly clipped version of the compound labels string. Locations are computed relative to the viewR rectangle. This method does not know how to handle LEADING/TRAILING values in horizontalTextPosition (they will default to RIGHT) and in horizontalAlignment (they will default to CENTER).

invokeLater

public static void invokeLater(java.lang.Runnable doRun)

Causes doRun.run() to be executed asynchronously on the AWT event dispatching thread. This will happen after all pending AWT events have been processed. This method should be used when an application thread needs to update the GUI. In the following example the invokeLater call queues the Runnable object doHelloWorld on the event dispatching thread and then prints a message.

 Runnable doHelloWorld = new Runnable() {
     public void run() {
         System.out.println("Hello World on " + Thread.currentThread());
     }
 };

 SwingUtilities.invokeLater(doHelloWorld);
 System.out.println("This might well be displayed before the other message.");
 

If invokeLater is called from the event dispatching thread -- for example, from a JButton's ActionListener -- the doRun.run() will still be deferred until all pending events have been processed. Note that if the doRun.run() throws an uncaught exception the event dispatching thread will unwind (not the current thread).

Additional documentation and examples for this method can be found in How to Use Threads, in The Java Tutorial.

As of 1.3 this method is just a cover for java.awt.EventQueue.invokeLater().

See Also:

invokeAndWait(java.lang.Runnable)

invokeAndWait

public static void invokeAndWait(java.lang.Runnable doRun)
                          throws java.lang.InterruptedException,
                                 java.lang.reflect.InvocationTargetException

Causes doRun.run() to be executed synchronously on the AWT event dispatching thread. This call will block until all pending AWT events have been processed and (then) doRun.run() returns. This method should be used when an application thread needs to update the GUI. It should not be called from the EventDispatchThread. Here's an example that creates a new application thread that uses invokeAndWait() to print a string from the event dispatching thread and then, when that's finished, print a string from the application thread.

 final Runnable doHelloWorld = new Runnable() {
     public void run() {
         System.out.println("Hello World on " + Thread.currentThread());
     }
 };

 Thread appThread = new Thread() {
     public void run() {
         try {
             SwingUtilities.invokeAndWait(doHelloWorld);
         }
         catch (Exception e) {
             e.printStackTrace();
         }
         System.out.println("Finished on " + Thread.currentThread());
     }
 };
 appThread.start();
 

Note that if the Runnable.run() method throws an uncaught exception (on the event dispatching thread) it's caught and rethrown, as an InvocationTargetException, on the callers thread.

Additional documentation and examples for this method can be found in How to Use Threads, in The Java Tutorial.

As of 1.3 this method is just a cover for java.awt.EventQueue.invokeAndWait().

Throws:

java.lang.InterruptedException - if we're interrupted while waiting for the event dispatching thread to finish excecuting doRun.run()

java.lang.reflect.InvocationTargetException - if doRun.run() throws

See Also:

invokeLater(java.lang.Runnable)

isEventDispatchThread

public static boolean isEventDispatchThread()

Returns true if the current thread is an AWT event dispatching thread.

As of 1.3 this method is just a cover for java.awt.EventQueue.isDispatchThread().

Returns:

true if the current thread is an AWT event dispatching thread

getRootPane

public static JRootPane getRootPane(java.awt.Component c)

If c is a JRootPane descendant return its JRootPane ancestor. If c is a RootPaneContainer then return its JRootPane.

Returns:

the JRootPane for Component c or null.

processKeyBindings

public static boolean processKeyBindings(java.awt.event.KeyEvent event)

Process the key bindings for the Component associated with event. This method is only useful if event.getComponent() does not descend from JComponent, or your are not invoking super.processKeyEvent from within your JComponent subclass. JComponent automatically processes bindings from within its processKeyEvent method, hence you rarely need to directly invoke this method.

Parameters:

event - KeyEvent used to identify which bindings to process, as well as which Component has focus.

Returns:

true if a binding has found and processed

Since:

1.4

notifyAction

public static boolean notifyAction(Action action,
                                   KeyStroke ks,
                                   java.awt.event.KeyEvent event,
                                   java.lang.Object sender,
                                   int modifiers)

Invokes actionPerformed on action if action is enabled (and non null). The command for the ActionEvent is determined by:

1. If the action was registered via registerKeyboardAction, then the command string passed in (null will be used if null was passed in).
2. Action value with name Action.ACTION_COMMAND_KEY, unless null.
3. String value of the KeyEvent, unless getKeyChar returns KeyEvent.CHAR_UNDEFINED..

This will return true if action is non-null and actionPerformed is invoked on it.

Since:

1.3

calculateInnerArea

public static Rectangle calculateInnerArea(JComponent c,
                                           Rectangle r)

Stores the position and size of the inner painting area of the specified component in r and returns r. The position and size specify the bounds of the component, adjusted so as not to include the border area (the insets). This method is useful for classes that implement painting code.

Parameters:

c - the JComponent in question; if null, this method returns null

r - the Rectangle instance to be modified; may be null

Returns:

null if the Component is null; otherwise, returns the passed-in rectangle (if non-null) or a new rectangle specifying position and size information

Since:

1.4