|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectbb.gui.ScreenShot
public final class ScreenShot
Class which supports taking screen shots of the entire desktop, AWT Components, or Swing JComponents.
This functionality is implemented in a series of take
methods, each of which returns a BufferedImage.
This class also offers convenience write
methods for storing BufferedImages to files.
The images taken by this class should be the precise images seen on the screen. However, the images written to files may deviate from the originals. One obvious cause is limitations of the chosen file format (especially with lossy formats like jpeg). A subtle issue can occur, however, even when using lossless formats like png: if the file is subsequently opened by another application, that application may rescale the image, which can often cause visible artifacts.
To see this last problem on Windows XP,
call take()
which returns an image of the entire desktop and write it to a file,
and then open the file with XP's default graphics file viewer ("Windows Picture And Fax Viewer").
This program shrinks the desktop image in order to fit it inside the program's window,
and rescaling artifacts are readily seen, especially if the desktop image has any kind of text in it.
If "Windows Picture And Fax Viewer" instead cropped the image or had a scroll pane, then this should not happen.
Acknowledgement: this class was inspired by the program ScreenImage. Differences from the above program:
BufferedImage.TYPE_INT_ARGB
instead of BufferedImage.TYPE_INT_RGB
in order to preserve alphadefault image file format
is PNG instead of JPEGtake
methods simply take snapshots and never have the side effect of writing image filestake
which can get a snapshot of a region of a Component
Like typical Java GUI code, this class is not multithread safe:
it expects to only be called by EventQueue
's dispatch thread
.
This threading limitation is checked in every public method.
Nested Class Summary | |
---|---|
static class |
ScreenShot.UnitTest
See the Overview page of the project's javadocs for a general description of this unit test class. |
Field Summary | |
---|---|
static String |
formatNameDefault
Default value for the graphics file format that will be written by this class. |
private static int |
imageType
Defines the image type for the BufferedImages that will create when taking snapshots. |
Constructor Summary | |
---|---|
private |
ScreenShot()
This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class. |
Method Summary | |
---|---|
private static String |
getGraphicsFormat(File file)
Returns the name of the graphics format stored in file. |
static BufferedImage |
take()
Takes a screen shot of the entire desktop. |
static BufferedImage |
take(Component component)
Takes a screen shot of that part of the desktop whose area is where component lies. |
static BufferedImage |
take(Component component,
Rectangle region)
Takes a screen shot of that part of the desktop whose area is the region relative to where component lies. |
static BufferedImage |
take(JComponent jcomponent)
Takes a screen shot of just jcomponent (no other gui elements will be present in the result). |
static BufferedImage |
take(JComponent jcomponent,
Rectangle region)
Takes a screen shot of just the specified region of jcomponent (no other gui elements will be present in the result). |
static BufferedImage |
take(Rectangle region)
Takes a screen shot of the specified region of the desktop. |
static void |
write(BufferedImage image,
File file)
Calls . |
static void |
write(BufferedImage image,
String filePath)
Calls . |
static void |
write(BufferedImage image,
String formatName,
File file)
Writes image to file in the format specified by formatName. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
private static final int imageType
BufferedImage.TYPE_INT_ARGB
, which was chosen because
public static final String formatNameDefault
Constructor Detail |
---|
private ScreenShot()
Method Detail |
---|
public static BufferedImage take() throws AWTException, SecurityException, IllegalStateException
Any thread may call this method.
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
AWTException
- if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
SecurityException
- if createRobot permission is not grantedpublic static BufferedImage take(Rectangle region) throws IllegalArgumentException, IllegalStateException, AWTException, SecurityException
Any thread may call this method.
region
- the Rectangle within the screen that will be captured
IllegalArgumentException
- if region == null; region's width and height are not greater than zero
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
AWTException
- if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
SecurityException
- if createRobot permission is not grantedpublic static BufferedImage take(Component component) throws IllegalArgumentException, IllegalStateException, AWTException, SecurityException
Only EventQueue
's dispatch thread
may call this method.
component
- AWT Component to take a screen shot of
IllegalArgumentException
- if component == null; component's width and height are not greater than zero
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
AWTException
- if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
SecurityException
- if createRobot permission is not grantedpublic static BufferedImage take(Component component, Rectangle region) throws IllegalArgumentException, IllegalStateException, AWTException, SecurityException
Only EventQueue
's dispatch thread
may call this method.
component
- AWT Component to take a screen shot ofregion
- the Rectangle relative to component that will be captured
IllegalArgumentException
- if component == null; component's width and height are not greater than zero; region == null
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
AWTException
- if the platform configuration does not allow low-level input control. This exception is always thrown when GraphicsEnvironment.isHeadless() returns true
SecurityException
- if createRobot permission is not grantedpublic static BufferedImage take(JComponent jcomponent) throws IllegalArgumentException, IllegalStateException
Only EventQueue
's dispatch thread
may call this method.
jcomponent
- Swing JComponent to take a screen shot of
IllegalArgumentException
- if jcomponent == null
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
public static BufferedImage take(JComponent jcomponent, Rectangle region) throws IllegalArgumentException, IllegalStateException
Only EventQueue
's dispatch thread
may call this method.
jcomponent
- Swing JComponent to take a screen shot ofregion
- the Rectangle relative to jcomponent that will be captured
IllegalArgumentException
- if jcomponent == null; region == null
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
public static void write(BufferedImage image, String filePath) throws IllegalArgumentException, IllegalStateException, IOException
write
(image, new File(filePath))
.
image
- the BufferedImage to be writtenfilePath
- path of the File that will write image to
IllegalArgumentException
- if image == null; filePath is blank
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
IOException
- if an I/O problem occurspublic static void write(BufferedImage image, File file) throws IllegalArgumentException, IllegalStateException, IOException
write
(image, getGraphicsFormat
(file), file)
.
image
- the BufferedImage to be writtenfile
- the File that will write image to
IllegalArgumentException
- if image or file is null
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
IOException
- if an I/O problem occurspublic static void write(BufferedImage image, String formatName, File file) throws IllegalArgumentException, IllegalStateException, IOException
Warning: a side effect of this method is that it will create any needed parent directories of file if they are not already existing.
image
- the BufferedImage to be writtenformatName
- the graphics file format (e.g. "pnj", "jpeg", etc);
must be in the same set of values supported by the formatName arg of ImageIO.write(RenderedImage, String, File)
file
- the File that will write image to
IllegalArgumentException
- if image == null; type is blank; file == null
IllegalStateException
- if calling thread is not EventQueue
's dispatch thread
IOException
- if an I/O problem occursprivate static String getGraphicsFormat(File file) throws IllegalArgumentException
This is assumed to be file's extension, if it exists.
Otherwise, if file has no extension, then formatNameDefault
is returned.
Any thread may call this method.
file
- the File whose graphics format needs to be determined
IllegalArgumentException
- if file == null
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |