21

Image Encoder

Features of JCEncodeComponent  Classes and Interfaces  Constructors and Methods  Examples

---

21.1 Features of JCEncodeComponent

You can encode the image information for any component in your application with this utility. Since all the children of the chosen component are also encoded, you can capture a picture of your entire user interface for any well-behaved component hierarchy, or any single one of its child components. The utility encodes images in the public-domain Portable Network Graphics (PNG) format. Other common formats are available if you also have JClass PageLayout installed. JClass PageLayout is available as part of the JClass DesktopViews suite.

The advantages of using JCEncodeComponent include:

• Saving an image of a component in PNG format.
• A simple way to encode a component: just call JCEncodeComponent.encode().

Please note that the JPEG format is not supported because it loses information as a result of the compression.

Note: If you wish to export your images in GIF format, you'll need a license from the copyright holder, Unisys Corp. Quest Software will send you the GIF encoder class upon receipt of a copy of your license from Unisys.

---

21.2 Classes and Interfaces

The com.klg.jclass.util.swing.encode package contains an interface, a main class called JCEncodeComponent, and various helper classes that output the various supported image formats.

The interface that defines an image encoder contains a single method: encode(). Its parameters are the component whose image is to be encoded, and the stream on which to place the encoded information.

There is also an exception class, EncoderException. It is raised by JCEncodeComponent or one of its subclasses. The exception may be subclassed for exceptions thrown by subclasses of JCEncodeComponent. It represents any problem encountered while encoding an image. The message is used to state the type of error.

JCEncodeComponent has a public static inner class named Encoding that is used to provide instances of the various valid encodings or to supply an error message if an attempt fails.

---

21.3 Constructors and Methods

JCEncodeComponent

The Encode inner class is used to instantiate a particular encoding type, such as PDF. It defines methods that provide information about the encoder, including a failure message if the encoder fails to load.

getEncoder()	Returns an encoder for this encoding type.
getFailureMessage()	Message stating possible reasons for encoder load failure.
getLongName()	Returns the fully qualified name of the supported encoding type.
getShortName()	Returns the descriptive name of the supported encoding type.
toString()	Returns both the short name and the long name in a single String.

The array called ENCODINGS contains, as instances of Encode, the supported encoding types. You pass an element of this array to the encode method, along with your component and a Stream specifier, to produce an encoding of the component which is sent to the stream. The method is overloaded so that you can write the information to a file if you wish.

encode(Encoding   encoding, Component   component,   OutputStream output)	Invoke this method on a Java component to encode its image in the specified format, and send the encoded information to the specified stream.
encode(Encoding   encoding, Component   component,   File file)	Encodes the component's image in the specified format. Sends the encoded information to the specified file.

---

21.4 Examples

Below is an example that encodes an entire frame in PNG format, then stores the result in a file. Most of the code simply serves to create a frame containing a few components. Since the process of encoding can result in an exception being thrown, the single-line command that does all the work is enclosed in a try block.

import com.klg.jclass.util.swing.encode.JCEncodeComponent;
import com.klg.jclass.util.swing.JCExitFrame;
import java.io.File;
import javax.swing.JPanel;
import javax.swing.JLabel;
import javax.swing.JButton;
import javax.swing.JTextField;

public class EncoderExample {

public static void main(String[] args) {
JCExitFrame eFrame;
eFrame = new JCExitFrame("Encoder Example");
JPanel jp = new JPanel();
JLabel jl = new JLabel("PNG Encoding");
JButton jb = new JButton("Just a button");
JTextField jt = new JTextField("The entire frame will be encoded");
jp.add(jl);
jp.add(jb);
jp.add(jt);
jp.setVisible(true);
eFrame.getContentPane().add(jp);
eFrame.setSize(350, 100);
eFrame.setVisible(true);
File efps = new File("efps.png");
try {
JCEncodeComponent.encode(JCEncodeComponent.PNG, eFrame, efps);
} catch (Exception e) {
System.out.println("Exception caught: " + e);
}
}
}

Figure 53 :  The result of encoding the entire JCExitFrame.

You can find another example, Encode.java, in the examples/elements directory. In that example, a single component, a button, is encoded. A combo box lets you choose the encoding format, a text field displays the current choice, and a button-press initiates encoding to a file. This example is more realistic in that the encoding process is initiated by the end user through some action, such as a menu choice, or, as in this case, by pressing a button.

The result is shown in the next figure.

Figure 54 :  Encoding a single component using examples.elements.Encode.

If you attempt to encode a component using a GIF format, you will see the following error dialog:

Figure 55 :  The error dialog that appears if you do not have GIF encoding installed.

Note: You need JClass PageLayout to encode components in EPS, PS, PDF, or PCL. JClass PageLayout is available as a part of the JClass DesktopViews suite.