# 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 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.
| 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.
| 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.
| The license files for JxCapture should be placed in the `META-INF` folder of your application's JAR file.
2. # 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");
3. Prepend the following code to the method to start the applet method:
       AppletHelper.getInstance().start();
4. 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: 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. |