JxCapture Programmer's Guide


Version: 1.0
Last Updated: September 19, 2007

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 Guide

This 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 JxCapture

As 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 Requirements

The following are general requirements for running JxCapture on the following supported platforms:

  • Windows

    • OS: Windows 2000, XP and Vista.

    • Java: Java 2 SDK/JRE 1.4.x and later.

There are no specific memory or hardware requirements for developing an application based on JxCapture.

2.1.1. Other Platforms

Support for other platforms like Linux and Mac OS X is planned for the future.

2.2. Package Contents

The JxCapture package consists of the following main files required for work:

  • Library JAR files: jniwrap-<version>.jar and jxcapture-<version>.jar. Where <version> is the product version, for example "1.0".

  • Native code library

    • For Windows - jniwrap.dll

  • License files

    • jniwrap.lic

    • jxcapture.lic

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 Files

The 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 Library

The 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.

Important

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:

  • on Windows - the root of Windows installation or Windows\System32

  • on Linux - <java_home>/lib/i386 or <java_home>/jre/lib/i386

  • on Mac OS X - /usr/lib

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 Files

Placing the license files is very simple: They should be located in the same folder where the native JNIWrapper library (jniwrap.dll file) resides.

Important

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.

Figure 4-1.

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 Operations

Simple 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 Operations

Sometimes 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 Dialog

In 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.

Important

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:

  1. 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).

  2. 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");
  3. Prepend the following code to the method to start the applet method:

    AppletHelper.getInstance().start();

    This call starts a NativeResourceCollector thread of JNIWrapper.

  4. Append the following code to the method to stop the applet method:

    AppletHelper.getInstance().stop();

    This call stops a NativeResourceCollector thread of JNIWrapper.

  5. The license files (jniwrap.lic and jxcapture.lic) can be included in any JAR file of a JWS application, in the META-INF subfolder.

  6. 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:

  • Installation instructions

  • Programmer's Guide

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 Problems

If 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.

Chapter 9. Where to Get a New Version


To get the latest version of JxCapture, please visit:

http://www.teamdev.com/jxcapture/downloads.jsf

Copyright © 2002-2007 TeamDev Ltd.