bb.gui
Class SwingUtil

java.lang.Object
  extended by bb.gui.SwingUtil

public final class SwingUtil
extends Object

General static utility methods that are useful for Swing programming.

Like typical Java GUI code, most of this class's methods are not multithread safe: they expect to only be called by EventQueue's dispatch thread. This threading limitation is checked in all public methods unless noted otherwise (e.g. the invokeXXX methods may be safely called by any thread).

Author:
Brent Boyer

Nested Class Summary
static class SwingUtil.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Constructor Summary
private SwingUtil()
          This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.
 
Method Summary
static void centerLineInScrollPane(JTextComponent textComponent)
          Centers the line containing the caret inside a scroll pane.
static Dimension fractionOfScreenSize(double fraction)
          Returns fractionOfScreenSize(fraction, fraction).
static Dimension fractionOfScreenSize(double fractionX, double fractionY)
          First gets the screen's size by calling screenSize.
static void invokeNow(Runnable task)
          Synchronously executes task on EventQueue's dispatch thread (i.e. this method does return until task has finished running).
static void invokeNowIfEdt(Runnable task)
          Ensures that at some point task is executed on EventQueue's dispatch thread.
static void maximizeWindow(Window window)
          Sets the location and size of window so as to maximize its area.
static Dimension screenSize()
          Returns the screen's size.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SwingUtil

private SwingUtil()
This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.

Method Detail

invokeNow

public static void invokeNow(Runnable task)
                      throws IllegalArgumentException,
                             InterruptedException,
                             InvocationTargetException
Synchronously executes task on EventQueue's dispatch thread (i.e. this method does return until task has finished running).

If the calling thread is EventQueue's dispatch thread, then this method directly executes task. Otherwise, task is submitted to EventQueue.invokeAndWait, and this method returns when invokeAndWait returns.

Thus, any thread may call this method (unlike EventQueue.invokeAndWait, which cannot be called by EventQueue's dispatch thread).

Throws:
IllegalArgumentException - if task == null
InterruptedException - if calling thread is interrupted while waiting for the dispatch thread to finish excecuting task.run
InvocationTargetException - if an exception is thrown by task.run

invokeNowIfEdt

public static void invokeNowIfEdt(Runnable task)
                           throws IllegalArgumentException
Ensures that at some point task is executed on EventQueue's dispatch thread.

If the calling thread is EventQueue's dispatch thread, then this method directly executes task. Otherwise, task is submitted to EventQueue.invokeLater, and then this method immediately returns.

So, in general, task is asynchronously executed. However, in the special case that the calling thread is already the dispatch thread, it is synchronously executed.

Any thread may call this method.

Throws:
IllegalArgumentException - if task == null

maximizeWindow

public static void maximizeWindow(Window window)
                           throws IllegalArgumentException,
                                  IllegalStateException,
                                  HeadlessException
Sets the location and size of window so as to maximize its area.

The fundamental upper bound is the size of the screen. On systems with multiple displays, the size of the primary display is used.

A secondary constraint is the presence of permanent desktop items like the Windows Taskbar. This method assumes that you do not want the window to cover these items, so their presence makes the effective screen size smaller.

Throws:
IllegalArgumentException - if window is null
IllegalStateException - if calling thread is not EventQueue's dispatch thread
HeadlessException - if GraphicsEnvironment.isHeadless() returns true

centerLineInScrollPane

public static void centerLineInScrollPane(JTextComponent textComponent)
                                   throws IllegalArgumentException,
                                          IllegalStateException,
                                          BadLocationException
Centers the line containing the caret inside a scroll pane.

Parameters:
textComponent - the JTextComponent whose line is to be centered
Throws:
IllegalArgumentException - if textComponent is null
IllegalStateException - if calling thread is not EventQueue's dispatch thread; textComponent has not been added to a JScrollPane
BadLocationException - if an internal error happens when setting the viewport's position

screenSize

public static Dimension screenSize()
                            throws HeadlessException,
                                   IllegalStateException
Returns the screen's size. On systems with multiple displays, just the primary display is used.

Throws:
IllegalStateException - if calling thread is not EventQueue's dispatch thread
HeadlessException - if GraphicsEnvironment.isHeadless() returns true

fractionOfScreenSize

public static Dimension fractionOfScreenSize(double fraction)
                                      throws IllegalArgumentException,
                                             IllegalStateException,
                                             HeadlessException
Returns fractionOfScreenSize(fraction, fraction).

Throws:
IllegalArgumentException - if fraction is abnormal or negative
IllegalStateException - if calling thread is not EventQueue's dispatch thread
HeadlessException - if GraphicsEnvironment.isHeadless() returns true

fractionOfScreenSize

public static Dimension fractionOfScreenSize(double fractionX,
                                             double fractionY)
                                      throws IllegalArgumentException,
                                             IllegalStateException,
                                             HeadlessException
First gets the screen's size by calling screenSize. Then returns a new Dimension instance whose width is the screen's width multiplied by fractionX and whose height is the screen's height multiplied by fractionY.

Throws:
IllegalArgumentException - if fractionX or fractionY are abnormal or negative
IllegalStateException - if calling thread is not EventQueue's dispatch thread
HeadlessException - if GraphicsEnvironment.isHeadless() returns true