Chapter 2. (Introduction) Swing Mechanics. Easy for reading, Click here!

Subpages: 1. JComponent properties, size, and positioning 
2.  Event handling and dispatching 
3. Multithreading
4. Timers
5. AppContext service
6. Inside Timers & the TimerQueue
7. JavaBeans architecture
8. Fonts, Colors, Graphics and text
9. Using the Graphics clipping area
10. Graphics debugging
11. Painting and validation
12. Focus Management
13. Keyboard input, KeyStrokes, and Actions
14. SwingUtilities

2.14  SwingUtilities

class javax.swing.SwingUtilities

In section 2.3 we discussed two methods in the SwingUtilities class used for executing code in the event-dispatching thread. These are just 2 of the 36 generic utility methods defined SwingUtilities, which break down logically into seven groups: computational methods, conversion methods, accessibility methods, retrieval methods, multithreading/event-related methods, mouse button methods, and layout/rendering/UI methods. Each of these methods is static, and they are described very briefly in this section (for a more thorough understanding see the SwingUtilities.java source code).

2.14.1 Computational methods

Rectangle[] computeDifference(Rectangle rectA, Rectangle rectB): returns those rectangular regions representing the portion of rectA that do not intersect with rectB.

Rectangle computeIntersection(int x, int y, int width, int height, Rectangle dest): returns the intersection of two rectangular areas. The first region is defined by the int parameters and the second by the Rectangle parameter. The Rectangle parameter is altered and returned as the result of the computation so that a new Rectangle does not have to be instantiated.

Rectangle computeUnion(int x, inty, int width, int height, Rectangle dest): returns the union of two rectangular areas. The first region is defined by the int parameters and the second by the Rectangle parameter. The Rectangle parameter is altered and returned as the result of the computation so that a new Rectangle does not have to be instantiated.

isRectangleContainingRectangle(Rectangle a, Rectangle b): returns true if Rectangle b is completely contained in Rectangle a.

computeStringWidth(FontMetrics fm, String str): returns the width of the given String according to the given FontMetrics object (see 2.8.3).

2.14.2  Conversion methods

MouseEvent convertMouseEvent(Component source, MouseEvent sourceEvent, Component destination): returns a new MouseEvent with destination as its source and x,y-coordinates converted to the corrdinate system of destination (both assuming destination is not null). If destination is null the coordinates are converted to the coordinate system of source, and source is set as the source of the event. If both are null the MouseEvent returned is identical to the event passed in.

Point convertPoint(Component source, Point aPoint, Component destination): returns a Point representing aPoint converted to coordinate system of the destination component as if it were originating in the source component. If either component is null the coordinate system of the other is used, and if both are null the Point returned is identical to the Point passed in.

Point convertPoint(Component source, int x, int y, Component destination): this method acts identically to the above convertPoint() method except that it takes int parameters representing the Point to convert rather than a Point instance.

Rectangle convertRectangle(Component source, Rectangle aRectangle, Component destination): returns a Rectangle converted from then source component's coordinate system to the destination component's coordinate system. This method behaves similarly to convertPoint().

void convertPointFromScreen(Point p, Component c): converts a given Point in screen coordinates to the coordinate system of the given Component.

void convertPointToScreen(Point p, Component c): converts a given Point in the given Component's coordinate system to the coordinate system of the screen.

2.14.3  Accessibility methods

Accessible getAccessibleAt(Component c, Point p): returns the Accessible component at the given Point in the coordinate system of the given Component (null will be returned if none is found). Note that an Accessible component is one that implements the javax.accessibility.Accessible interface.

Accessible getAccessibleChild(Component c, int i): returns the ith Accessible child of the given Component.

int getAccessibleChildrenCount(Component c): returns the number of Accessible children contained in the given Component.

int getAccessibleIndexInParent(Component c): returns the index of the given Component in its parent disregarding all contained components that do not implement the Accessible interface. -1 will be returned if the parent is null or does not implement Accessible, or the given Component does not implement Accessible.

AccessibleStateSet getAccessibleStateSet(Component c): returns the set of AccessibleStates that are active for the given Component.

2.14.4  Retrieval methods

Component findFocusOwner(Component c): returns the component contained within the given Component (or the given Component itself) that has the current focus. If there is no such component null is returned.

Container getAncestorNamed(String name, Component comp): returns the closest ancestor of the given Component with the given name. Otherwise null is returned. (Note that each Component has a name property which can assigned and retrieved using setName() and getName() methods respectively.)

Container getAncestorOfClass(Class c, Component comp): returns the closest ancestor of the given Component that is an instance of c. Otherwise null is returned.

Component getDeepestComponentAt(Component parent, int x, int y): returns the most 'contained' child of the given Component containing the point (x,y) in terms of the coordinate system of the given Component. If the given Component is not a Container this method simply returns it immediately.

Rectangle getLocalBounds(Component c): returns a Rectagle representing the bounds of a given Component in terms of its own coordinate system (thus it always starts at 0,0).

Component getRoot(Component c): returns the first ancestor of c that is a Window. Otherwise this method returns the last ancestor that is an Applet.

JRootPane getRootPane(Component c): returns the first JRootPane parent of c, or c itself if it is a JRootPane.

Window windowForComponent(Component c): return the first ancestor of c that is a Window. Otherwise this method returns null.

boolean isDescendingFrom(Component allegedDescendent, Component allegedAncestor): returns true if allegedDescendent is contained in allegedAncestor.

2.14.5  Multithreading/event-related methods

See section 2.3 for more about these methods.

void invokeAndWait(Runnable obj): sends the given Runnable to the event-dispatching queue and blocks on the current thread.

void invokeLater(Runnable obj): sends the given Runnable to the event-dispatching queue and continues.

boolean isEventDispatchThread(): returns true if the current thread is the event-dispatching thread.

2.14.6  Mouse button methods

boolean isLeftMouseButton(MouseEvent): returns true if the given MouseEvent corresponds to left mouse button activation.

boolean isMiddleMouseButton(MouseEvent): returns true if the given MouseEvent corresponds to middle mouse button activation.

boolean isRightMouseButton(MouseEvent): returns true if the given MouseEvent corresponds to right mouse button activation.

2.14.7  Layout/rendering/UI methods

String layoutCompoundLabel(FontMetrics fm, String text, icon icon, int verticalAlignment, int horizontalAlignment, int verticalTextPosition, int horizontalTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int textIconGap): this method is normally used by JLabel's UI delegate to lay out text and/or an icon using the given FontMetrics object, alignment settings and text positions within the viewR Rectangle. If it is determined that the label text will not fit within this Rectangle, an elipsis ("...") is used in place of the text that will not fit. The textR and iconR Rectangles are modified to reflect the new layout, and the String that results from this layout is returned.

String layoutCompoundLabel(JComponent c, FontMetrics fm, String text, icon icon, int verticalAlignment, int horizontalAlignment, int verticalTextPosition, int horizontalTextPosition, Rectangle viewR, Rectangle iconR, Rectangle textR, int textIconGap): this method is identical to the above method, but takes target component to check whether or not text orientation should play a role (see the "Component Orientation in Swing: How JFC Components support BIDI text" article at the Swing Connection for more about orientation: http://java.sun.com/products/jfc/tsc/tech_topics/bidi/bidi.html).

void paintComponent(Graphics g, Component c, Container p, int x, int y, int w, int h): paints the given Component in the given graphical context, using the rectangle defined by the four int parameters as the clipping area. The given Container is used to act as the Component's parent so that any validation and repaint requests that occur on that component do not propogate up the ancestry tree of the component owning the given graphial context. This is the same methodology used by component renderers of JList, JTree, and JTable to properly exhibit "rubber stamp" behavior. This behavior is accomplished through the use of a CellRendererPane (see chapter 17 for more about this class and why it is used to wrap renderers).

void paintComponent(Graphics g, Component c, Container p, Rectangle r): functions identical to the above method, but takes a Rectangle parameter rather than four ints.

void updateComponentTreeUI(Component c): notifies all components contained in c, and c itself, to update their UI delegate to match the current UIManager and UIDefaults settings (see chapter 21).