[Contents] [Previous] [Next] [Last]
An image encoder is a plug-in that encodes image data to match specific image formats, thus extending the image file formats that Composer can write. An image encoder examines the input data, communicates with the user as necessary, and then writes the encoded image to the output stream. Image encoders have the same basic structure and are constructed in the same way as other Composer Plug-ins, with a few notable exceptions.
This chapter describes developing and using image encoders and compares them with other Composer Plug-ins.
Just as all plug-ins extend the Plugin class, all image encoders extend the ImageEncoder class. Plugin and ImageEncoder are like the Java Applet and Application classes, in that each is the main class of its program type. Like Plugin, ImageEncoder represents the point at which the flow of control transfers from the Composer window to the plug-in.
An encoder matches image data to specific image formats. Starting with Communicator 4.0, you can use image encoders to encode any kind of image that is natively supported by Communicator. This list includes JPEG, GIF, and XPM file formats. You can also write encoders for image formats that Communicator 4.0 does not support, but these will not show up in the Composer window.
[Top]
To encode an image in the Composer interface, the user puts an image in the clipboard and pastes that image into the document. After taking the default filename that is offered or entering a new one, the user can choose between JPEG format (the default), or GIF (if the GIF sample is present in the Plugins folder).
The encoder is instantiated when the first Composer window is opened and is deleted when the application exits. Composer Plug-ins can also find and use existing image encoders to write image files.
When encoding begins, the image encoder's encode method is called with the image data and an output stream. The encoder examines the input data, communicates with the user as necessary, and then writes the encoded image to the output stream.
The rest of the Composer user interface is held in a modal state while the image encoder is executing. If the image encoder cannot finish quickly, it could display a progress indicator or otherwise keep the user informed of the encoder's progress.
The advantage the image encoder offers the user is that, unlike the Composer Insert Image menu item, the image encoder does not require an existing file. It can create an image file directly from the clipboard. This makes it very easy to insert screen shots or any other graphics data into a document.
Another possible use for an image encoder is in a plug-in that performs processing. For example, you could write a pie chart plug-in that charts the relationship of numbers that the user enters.
[Top]
[Top]
You approach writing the image encoder much as you do a plug-in; there are many similarities and few differences between the two processes. The TextImageEncoder sample, provided in the Composer Plug-in Kit, is an example of an image encoder. This section shows the parallels between constructing an image encoder and a plug-in.
Note:
The TextImageEncoder sample contains all the parts
you need to create an image encoder, but it does not produce a visible
image. 
Image encoders extend the ImageEncoder class. This class has an encode method, which takes an image source and an output stream as parameters, rather than a perform method, like the Plugin class. Rather than providing a getcategory method, the image encoder provides two other types of information: file extension and Mac OS file type.
Like the MIME type, the Mac OS file type is a way of specifying the type of a file. They differ in that the MIME type is operating system independent, while the Mac OS FileType is specific to the Mac OS. To get the Mac OS FileType of the image format, use the ImageEncoder.getFileType method.
To run on the Mac OS, an Image Encoder must implement getFileType. For more information about FileType, refer to your Apple Developer Technical Support or the Apple Macintosh OS documentation.
Unlike a plug-in, the image encoder does not take a document as an argument. Instead, it takes an ImageProducer object (a standard Java AWT class) and an output stream. The developer's job is to take the image from the image producer, encode it, and put it in the output stream.
After you complete and package your image encoder, you install it just as you do any Composer Plug-in. Follow the directions in "Installing Composer Plug-ins."
[Top]
Import the packages you need, as in this code:
package netscape.test.plugin.composer; import netscape.plugin.composer.*; import java.io.*; import java.awt.image.*; import java.util.*;
[Top] [Writing an Image Encoder] [Next Step]
Define the image encoder class. Image encoders extend the ImageEncoder class. As with plug-ins, you use standard Java syntax.
public class TextImageEncoder extends ImageEncoder {
}
[Top] [Writing an Image Encoder] [Next Step]
You can include a main method so that you can test the encoder in the Composer Testbed. See "Devlopment Overview" for information about preparing a plug-in to run in the Testbed. For an image encoder, you use netscape.test.plugin.composer.ImageEncoderTest.encode rather than Test.perform in the main method.
public class TextImageEncoder extends ImageEncoder {
public static void main(String[] args){
ImageEncoderTest.Test(args, new TextImageEncoder());
}
[Top] [Writing an Image Encoder] [Next Step]
Just as you do when you write other types of Composer Plug-ins, you override two types of image encoder methods, those that provide basic information, and those that do the work of the image encoder.
The next step is to override the ImageEncoder class methods getName, getFileType, getFileExtension, and getHint, which store basic information about the image encoder. You can use a resource bundle to make it easier to localize your plug-in.
/* Get the human readable name of the image encoder. */
public String getName(){
return "Text Image Encoder";
}
/* Mac OS only: Get the Mac OS FileType of the image format. */
public void getFileType(byte[] type){
type[0] = 'T';
type[1] = 'E';
type[2] = 'X';
type[3] = 'T';
}
/* Get the standard file extension of the image format. */
public String getFileExtension(){
return "txt";
}
/* Get the human readable hint text for the image encoder. */
public String getHint(){
return "Text Image Format";
}
Override the method that does the actual work of your plug-in in the Composer. For a plug-in, this is the perform method; for an image encoder, the encode method. As the value of its input parameter, it takes an ImageProducer object. As the value of its output parameter, it takes an OutputStream object. This method reads the image information from the image source, interacts with the user, and writes the encoded information to the output stream.
public boolean encode(ImageProducer input, OutputStream output)
throws IOException {
PrintStream s = new PrintStream(output);
s.println("I am a test. The image is:");
ImageConsumer consumer = new TextImageConsumer(s);
input.addConsumer(consumer);
input.requestTopDownLeftRightResend(consumer);
input.removeConsumer(consumer);
return true;
}
}
[Top] [Overriding Methods] [Next Step]
At this point, write the additional classes and methods your encoder requires. For example, the TextImageEncoder sample image encoder defines the TextImageConsumer class, which extends ImageConsumer, and calls a number of methods, several of which are defined in the sample. The complete text of the TextImageEncoder sample is in the source directory of the Composer Plug-in Kit.
class TextImageConsumer implements ImageConsumer {
public TextImageConsumer(PrintStream s) {
stream = s;
}
public void imageComplete(int status){
stream.println("imageComplete(" + status + ")");
}
public void setColorModel(ColorModel model){
stream.println("setColorModel(" + model + ")");
}
public void setDimensions(int x , int y) {
stream.println("setDimensions(" + x + ", " + y + ")");
}
public void setHints(int hint) {
stream.println("setHints(" + hint + ")");
}
public void setPixels(int x, int y, int w, int h,
ColorModel model, byte pixels[], int offset, int scansize) {
stream.println("setPixels(" + x + ", " + y + ", "
+ w + ", " + h + ", " + model + ", " + pixels
+ ", " + offset + ", " + scansize + ")");
for(int j = 0; j < h; j++ ) {
stream.print("[" + j + "]");
for (int i = 0; i < w; i++ ) {
stream.print(" " + Integer.toHexString(
pixels[scansize * j + i + offset]));
}
stream.println();
}
}
[Top] [Writing an Image Encoder] [Next Step]
To register your plug-in as an image encoder, you create a configuration file called netscape_plugin_composer.ini, in standard Java Properties file format. In this file, place the names and the user interface strings for all of the image encoder classes you are going to place in your zip or JAR archive when packaging the encoder. For each class, cite one of these two "well-known" properties, which are used by the Composer Plug-in framework:
For example, this is the configuration file for the plug-in sample TextImageEncoder:
netscape.plugin.composer.ImageEncoder.classes=\
netscape.test.plugin.composer.TextImageEncoder
For more information about the netscape_plugin_composer.ini file, see "Registering a Plug-in as a Menu Option or Event Handler."
[Top] [Writing an Image Encoder] [Next Step]
To package an image encoder, follow the same steps as you use to package other Composer Plug-ins. See "Packaging Composer Plug-ins."
For information about arranging for your users to download and install Composer Plug-ins, see "Installing Composer Plug-ins."
[Top] [Writing an Image Encoder] [Contents] [Previous] [Next] [Last]
Copyright © 1997 Netscape Communications Corporation