JxCapture Programmer's Guide Version: 1.0 Last Updated: September 19, 2007
Copyright © 2002-2007 TeamDev Ltd. Chapter 1. Introduction
JxCapture is a cross-platform* library that provides a comprehensive
screen capture API for Java applications. The JxCapture distribution contains code samples demonstrating all
the API features and a demo application (JxCapture Demo) allowing you to
easily capture whatever you want on the screen in many different ways,
including: full-screen capture (available on multiple monitors) active window capture object capture of any UI element like window, button, menu,
etc. rectangular region capture inclusion of the mouse pointer to the capture
* The current version of JxCapture is available only for the Windows
platform. Support for more platforms is under way. 1.1. About this GuideThis guide introduces JxCapture, describes its architecture,
concepts and principles, requirements for using the product as well as
provides sufficient information you need to know to start working with
JxCapture. This document covers all platform versions of JxCapture. In cases
where functions treat a particular platform in a specific way, or
specific configuration settings are needed, these are marked
accordingly. 1.2. About JxCaptureAs stated above, JxCapture is a cross-platform library providing a
comprehensive screen capture API for Java applications. You can capture
any graphic element on the screen, whether an entire window or just a
single object on it, and save it as a
java.awt.image.BufferedImage object for further
manipulation in Java code. Chapter 2. Getting Started
2.1. System RequirementsThe following are general requirements for running JxCapture on
the following supported platforms: There are no specific memory or hardware requirements for
developing an application based on JxCapture. 2.1.1. Other PlatformsSupport for other platforms like Linux and Mac OS X is planned
for the future. 2.2. Package ContentsThe JxCapture package consists of the following main files
required for work: All the files need to be placed in appropriate locations. Please
see the section "Configuring JxCapture" for more details about the
product installation instructions. The package may also contain other
files providing some useful information for you, for example the
Readme.txt file. Chapter 3. Configuring JxCapture
JxCapture consists of five main files required for the operation of
the software: two JAR files, native code library, and two license files.
The following sections describe where each file should be located. No
other configuration is required. 3.1. Library JAR FilesThe JxCapture JAR file should be located in the program class
path. Because of the limitations of the Java native library loading
mechanism, it is not recommended to load JxCapture in custom class
loaders, unless you are sure that it will be loaded in only one such
class loader. The library files can also be placed in the boot class path or in
the extension directory of Java runtime, but this is not
required. 3.2. Native Code LibraryThe JNIWrapper native code library is loaded using the standard
Java native code loading mechanism. There are no known problems with
placing the native code library file on a mapped drive or even using it
from the network share using a UNC path.  | Do not rename the library file, or else it will not be
loaded. |
Even though the native code library can be placed
virtually anywhere, its actual location should be determined considering
the fact that Java code must find the library to load. It can be placed
somewhere within the program library search path (value of the
java.library.path system property, which is by
default equal to the value of the system variable PATH on
Windows). Alternatively, you can add a search path to the default library
loader used by JNIWrapper or even write a custom one that searches for
native code in a predefined location. Using a default path may be
preferable for development and library loader as a much better way for
distributing a complete application. Since version 3.0 of JNIWrapper it is possible to keep native
libraries within a JAR file. JNIWrapper will automatically locate and
install a library on demand. You may want to install the native code library into the
directories on the default system path, for example: Note that this requires having appropriate access rights on the
Windows 2000/XP, Linux and Mac OS X systems. Installing the native code
library in this way may be convenient, but it is not a required
procedure. 3.3. License FilesPlacing the license files is very simple: They should be located
in the same folder where the native JNIWrapper library
(jniwrap.dll file) resides.  | Do not rename the license files, or else they will not be
recognized. |
Also, there is one universal way for the redistribution of
the runtime license files. You just need to save these files to your
application's JAR file, to its META-INF subfolder.
For example, if you have some application called
<application_name>.jar, the
jniwrap.lic and jxcapture.lic
files should be located in the following folder: <application_name>.jar
\META-INF
jniwrap.lic
jxcapture.lic You may appear to have several licenses for JxCapture for
different supported platforms. In this case, you must put all the
license key files as described above, but make sure there is no file
name conflict. JxCapture accepts multiple license files named like shown
below: jniwrap.lic jxcapture.lic jniwrap.lic1 jxcapture.lic1 jniwrap.lic2 jxcapture.lic2 ... jniwrap.lic999 jxcapture.lic999
Chapter 4. JxCapture Architecture
The JxCapture library provides the base
CaptureOperation abstract class and its
implementations: ActiveWindowCapture,
DesktopCapture,
ObjectOnScreenCapture,
RegionCapture and other. All capture operations can
be divided into: simple capture operations (such as
DesktopCapture and
ActiveWindowCapture). capture operations involving user interaction, e.g. a drawable
capture operation (such as ObjectOnScreenCapture
and RegionCapture).
The hierarchy of the JxCapture API base classes is given
below. Chapter 5. Using JxCapture in Java Applications
To perform a specific capture operation (for example, a desktop
capture), you just need to create an appropriate
CaptureOperation (for example,
DesktopCapture) instance, register
CaptureListener as a
java.awt.image.BufferedImage object in order to
receive the result of capturing, and call the
CaptureOperation.execute() method to execute the
operation. More information about using various capture operations is given
below. 5.1. Working with Simple Capture OperationsSimple capture operations do not require user interaction and are
intended to capture a specified area on the screen, such as full screen
or active window. The following sample demonstrates how you can capture a full
screen: CaptureOperation captureOperation = new DesktopCapture();
captureOperation.addCaptureListener(new CaptureAdapter() {
public void complete(BufferedImage image) {
// save image to file
}
});
captureOperation.execute(); First off, you should create an appropriate
CaptureOperation instance. To capture a full
screen, you should use a DesktopCapture
implementation. CaptureOperation captureOperation = new DesktopCapture(); To listen the result of capture operation, you can add your
CaptureListener implementation: captureOperation.addCaptureListener(new CaptureAdapter() {
public void complete(BufferedImage image) {
// save image to file
}
}); When the capture operation is completed, the
CaptureListener.complete() event will be fired with
the java.awt.image.BufferedImage parameter
containing the result image. You can use the result image at your
option. For example, you can save it to a specified file or draw over
some UI component. If you need to capture an active window (i.e. the window the user
is currently working with), use the
ActiveWindowCapture implementation. For
example: CaptureOperation captureOperation = new ActiveWindowCapture(); All other steps for this use case are the same as described in the
previous examples. 5.2. Working with Drawable Capture OperationsSometimes you may need to capture a specific region or a UI
element like window, button, menu etc. These operations require user
interaction. For such operations, the JxCapture API provides the base
DrawableCapture abstract class with appropriate
implementations: RegionCapture and
ObjectOnScreenCapture. All drawable capture operations must determine appropriate
"Controller" and "Painter". According to the Model-View-Controller (MVC)
pattern, the "Controller" represents a controller of the operation and
encapsulates all user actions during the capture operation (such as
mouse and keyboard actions). The "Painter" represents a view of the
capture operation and determines behavior during the capture operation
(for example, drawing a selected rectangle). The JxCapture API defines a
specific implementation for each "Controller" and "Painter". For example, if you need to capture a specific rectangular region
on the screen, use the RegionCapture
operation: SelectionPainter painter = new RegionPainter();
SelectionController controller = new RegionController(painter);
CaptureOperation captureOperation = new RegionCapture(controller);
captureOperation.addCaptureListener(new CaptureAdapter() {
public void complete(BufferedImage image) {
// save image to file
}
});
captureOperation.execute(); To create a RegionCapture instance, you need
to specify the controller and painter. As mentioned earlier, the
JxCapture API determines a specific implementation for each drawable
capture operation. For the RegionCapture operation,
there are RegionController and
RegionPainter. If you need to capture a specific UI element like window, button
or menu, use the ObjectOnScreenCapture operation.
For example: SelectionPainter painter = new ObjectOnScreenPainter();
SelectionController controller = new ObjectOnScreenController(painter);
CaptureOperation captureOperation = new ObjectOnScreenCapture(controller);
captureOperation.addCaptureListener(new CaptureAdapter() {
public void complete(BufferedImage image) {
// save image to file
}
});
captureOperation.execute(); 5.2.1. Using Help DialogIn certain cases, you may want to display some help information
during a capture operation (for example, show the current mouse
pointer location, pixel color under the mouse pointer, etc). In this
case, the JxCapture API allows you to specify a Help dialog. To do so, you should define your implementation of the
teamdev.jxcapture.toolkit.DialogComponent
interface. The DialogComponent.createComponent()
method should return a JComponent object that
represents the content of the Help dialog. Then you must register your implementation by using the
DrawableArea.setDialogComponent() method. The following sample demonstrates how you can specify the Help
dialog. SelectionPainter painter = new RegionPainter();
SelectionController controller = new RegionController(painter);
DrawableCapture captureOperation = new RegionCapture(controller);
captureOperation.addCaptureListener(new CaptureAdapter() {
public void cancel() {
System.out.println("Cancel.");
}
public void complete(BufferedImage image) {
try {
ImageIO.write(image, "PNG", new File("C:/region.png"));
} catch (IOException e) {
e.printStackTrace();
}
}
});
DrawableArea drawableArea = captureOperation.getDrawableArea();
// setting the dialog for the capture operation
drawableArea.setDialogComponent(new MyDialogComponent());
// executing the capture operation
captureOperation.execute(); MyDialogComponent represents an
implementation of the DialogComponent interface.
This dialog just displays the "Help Dialog" string. The size of the
Help dialog depends on its content. So, to set the size of the Help
dialog, you must specify the size of its content. /**
* Represents a custom dialog that will be shown during the capture operation.
*/
private static class MyDialogComponent implements DialogComponent {
public MyDialogComponent() {
}
public JComponent createComponent() {
JPanel contentPanel = new JPanel(new BorderLayout());
contentPanel.setSize(200, 100); // sets the size for the Help dialog content panel
contentPanel.add(new JLabel("Help Dialog"), BorderLayout.CENTER);
return contentPanel;
}
public int getInvisibleBorder() {
return 50;
}
public int getLocation() {
return Positions.TOP_LEFT;
}
public Positioner getPositioner() {
return new DiagonalPositioner();
}
} Chapter 6. Using JxCapture in Java Web Start Applications
This section describes the way of deploying your applications that
use JxCapture with the help of Java Web Start (JWS). One of the major requirements for any JWS application is that all
its resources are to be located inside signed JAR files. Although JAR
files can be signed many times, JWS does not accept files with more than
one signature. It is also mandatory that all application JAR files are
signed with the same signature. All JxCapture libraries are supplied already signed, and signing
them with a new signature makes them unacceptable for JWS. Fortunately,
there is a simple solution. The main idea is to use the
<extension> tag in the
.jnlp file and to create two different
.jnlp files for your application. One
.jnlp file should contain your application files and
the other -- JxCapture resources. This technique is demonstrated in the
example below. The first file is the application
.jnlp file (demo.jnlp): <?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0+" codebase="http://www.teamdev.com/" href="demo.jnlp">
<information>
<title>JxCapture Demo Application</title>
<vendor>TeamDev Ltd.</vendor>
<description>JxCapture Demo Application</description>
<description kind="short">The demo of JxCapture library</description>
<offline-allowed/>
</information>
<security>
<all-permissions/>
</security>
<resources>
<j2se version="1.4+" initial-heap-size="256m"/>
<jar href="demo.jar"/><!-- demo.jar is your jar file signed with your own signature-->
<extension name="jnw" href="jnw.jnlp"/>
</resources>
<component-desc/>
<application-desc main-class="teamdev.jxcapture.samples.demo.JxCaptureDemo"/>
</jnlp> The <extension> tag above makes a
reference to the other jnw.jnlp file which is
declared in the following way: <?xml version="1.0" encoding="utf-8"?>
<jnlp spec="1.0+" codebase="http://www.teamdev.com/" href="jnw.jnlp">
<information>
<title>JxCapture resources</title>
<vendor>TeamDev Ltd.</vendor>
<description>JxCapture Application</description>
<description kind="short">JxCapture Application</description>
<offline-allowed/>
</information>
<security>
<all-permissions/>
</security>
<resources os="Windows">
<nativelib href="jniwraplib.jar"/>
</resources>
<resources>
<jar href="jniwrap.jar"/>
<jar href="jxcapture.jar"/>
</resources>
<component-desc/>
</jnlp> The second jnw.jnlp file represents the
JxCapture resource bundle for redistribution as part of another JWS
application. The jniwraplib.jar package should only
include one file: jniwrap.dll. After you've configured the .jnlp files, place
them in your Web site and create a link to your main
.jnlp file that will also download JxCapture
resources by the reference.  | The license files for JxCapture should be placed in the
META-INF folder of your application's JAR
file. |
Chapter 7. Using JxCapture in Applets
To use JxCapture in applets, follow these instructions: Copy jniwrap.dll to the folder of a Web
server computer where the applet resides (it is recommended, but you
can place jniwrap.dll in some other folder on the
Web server). Prepend the following code to the init()
method of the applet: // passes the instance of the current object as a parameter
AppletHelper.getInstance().init(this); This call downloads jniwrap.dll from the
Web server and copies it to the Windows system32
folder in the client's computer. The presence of
jniwrap.dll on the client side is required,
otherwise the applet will not work. If you copied jniwrap.dll to a folder with
no residing applet, you should provide JNIWrapper library's URL, for
example: AppletHelper.getInstance().init("http://applets.com/native/jniwrap.dll"); Prepend the following code to the method to start the applet
method: AppletHelper.getInstance().start(); This call starts a NativeResourceCollector
thread of JNIWrapper. Append the following code to the method to stop the applet
method: AppletHelper.getInstance().stop(); This call stops a NativeResourceCollector
thread of JNIWrapper. The license files (jniwrap.lic and
jxcapture.lic) can be included in any JAR file of
a JWS application, in the META-INF
subfolder. application.jar should be signed and should
reference the JxCapture library(s) in its manifest file by setting the
class path variable. Signing of JxCapture libraries is not necessary
as they are already signed.
The sample build file that prepares an applet library is shown
below: <project name="Applet Sample" default="build" basedir=".">
<property name="certificate" value=".keystore"/>
<property name="jniwrapperLicenseFile" value="jniwrap.lic"/>
<property name="jxcaptureLicenseFile" value="jxcapture.lic"/>
<property name="appletClasses" value="classes"/>
<target name="build">
<jar destfile="sample.jar">
<fileset dir="${appletClasses}" includes="AppletSample.class"/>
<manifest>
<attribute name="Class-Path" value="jniwrap-3.6.jar; jxcapture-1.0.jar"/>
</manifest>
<zipfileset file="${jniwrapperLicenseFile}" prefix="META-INF" />
<zipfileset file="${jxcaptureLicenseFile}" prefix="META-INF" />
</jar>
<signjar jar="sample.jar" alias="your_alias" keystore="${certificate}" storepass="your_storepass" keypass="your_keypass" />
</target>
</project> Below is given the applet usage sample: <html>
<body><h1>Applet Sample</h1>
<p>
<applet docbase="http://your_url" code="AppletSample.class" width="400" height="300" archive="sample.jar"/>
</body>
</html> Chapter 8. Support
If you have any problems or questions regarding JxCapture, please
check the documents listed below: If none of the above resources contain the answer to your questions,
please e-mail us at: jxcapture-support@teamdev.com
If you want to discuss topics related to JxCapture, please visit a
specialized forum on the TeamDev integrated customer support and
troubleshooting center at: http://support.teamdev.com/jxcapture
8.1. Reporting ProblemsIf you find any bugs, please submit the issue to us using a
special report form on the TeamDev integrated customer support and
troubleshooting center at: http://support.teamdev.com/forms/reportForm.jsf
The form will help you provide all necessary information. |
 | Copyright © 2002-2007 TeamDev Ltd. |  |
|
|