Represents an abstract HTML document.
netscape.plugin.composer package
java.lang.Object
The Document object is the HTML document upon which the Composer plug-in operates. A Document object contains HTML text and a work directory. You must place images and other embedded files you are inserting into the document in this directory.
The document's name is a relative URL (universal resource locator). The plug-in uses Document methods to find the URLs of the document and its work directory.
Document methods use Char streams to access document text. You do not subclass from this class.
This table summarizes Document class methods:
| Constructor | Description |
|---|---|
| Document() | Creates an instance of the Document class |
| Methods | Description |
| editDocument(String) | Opens a URL for editing |
| getBase() | Gets the base URL of the document |
| getDocumentURL() | Gets the document URL (if known) for this document |
| getEventName() | Gets the event that triggers this plug-in |
| getInput() | Gets an input stream for a document |
| getOutput() | Gets an output stream for a document |
| getText() | Gets the entire raw HTML text of the document as a string |
| getWorkDirectory() | Gets the work directory of the document |
| getWorkDirectoryURL() | Gets the work directory of the document as a URL |
| redirectDocumentOpen( String) |
Redirects the edit event to a new document URL |
| setText(String) | Sets the entire raw HTML text of the document |
Factory, ImageEncoder, ImageEncoderFactory, Plugin
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Creates an instance of the Document class.
Document class
public Document()
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Opens a URL for editing.
Document class
public static void editDocument(String url)
url |
String containing the URL to be edited |
You can use this method to programmatically open a URL for editing by the user. You do not have to call this method from within a Composer Plug-in; you can call it from any Java or JavaScript running in Communicator. editDocument operates asynchronously.
To see how this method works, see the EditHomePage sample.
This method returns no errors or status information.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the base URL of the document.
Document class
public abstract URL getBase()
Any relative URLs included in the document are relative to its base URL.
The base URL of the document.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the document URL (if known) for this document.
Document class
public URL getDocumentURL()
During a publish event or a save event, this method returns the URL of the destination to which the document is being published or saved.
The document URL (if it is known) for this document, or null if no document URL is available.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the event that triggers this plug-in.
Document class
public String getEventName()
This method gets the event that triggered this plug-in invocation. The standard events are:
For information about using this method and Composer Plug-in events, see "How Composer Plug-ins Handle Events."
The event that triggered the plug-in invocation, or null if this is a normal invocation. The event name is null when the plug-in is invoked from a menu (the Tools menu) rather than in response to an event.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets an input stream for a document.
Document class
public abstract Reader getInput() throws IOException
The input stream is used for reading information from the document. Before creating another input stream for the same document, the caller must finish with the stream and close it with the out.close method.
Use this method rather than getText if you plan to tokenize the raw HTML code of the document. Use getText if you want to perform string-based operations on the raw HTML code of the document.
An input stream for the document.
IOException
The Composer Plug-in API uses standard Java exceptions and exception handling. For more information, see your Java documentation.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets an output stream for a document.
Document class
public abstract Writer getOutput() throws IOException
You use this function to write information into a document. Before creating another output stream for the same document, the caller must finish with the stream and close it with the out.close method.
Use this method rather than setText if you are processing tokenized HTML. Use setText if you have performed string-based operations on the raw HTML code of the document.
An output stream for the document.
IOException
The Composer Plug-in API uses standard Java exceptions and exception handling. For more information, see your Java documentation.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the entire raw HTML text of the document as a string.
Document class
public abstract String getText() throws IOException
This method reads information from a document and closes the output stream.
Use this method rather than getInput if you want to perform string-based operations on the raw HTML code of the document. Use getInput if you plan to tokenize the HTML.
The entire raw HTML text of the document as a string.
IOException
The Composer Plug-in API uses standard Java exceptions and exception handling. For more information, see your Java documentation.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the work directory of the document.
Document class
public abstract File getWorkDirectory()
You need to know the work directory in order to add files to the document. Any files that you add to your document must be placed in its work directory.
The work directory for the document.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the work directory of the document as a URL.
Document class
public abstract URL getWorkDirectoryURL()
You need this URL in order to add files to the document; files added to the document must be placed in this directory.
The work directory for the document as a URL.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Redirects the edit event to a new document URL.
Document class
public void redirectDocumentOpen(String newURL)
newURL |
URL, expressed as a string, to use to edit the document |
The plug-in substitutes the address specified in this method for that of the current document when the user clicks Edit on a web page. It opens the specified document rather than the current document.
This method is only meaningful when the event is edit. It can be useful when the publishing URL is different from the editing URL, for example, when you use an FTP server to access the backing store of an HTTP server.
To see how this method works, see the RedirectTest sample, which changes a request to edit pages from a web site into a request to edit pages from an FTP site.
An output stream for the document.
IOException
The Composer Plug-in API uses standard Java exceptions and exception handling. For more information, see your Java documentation.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Sets the entire raw HTML text of the document.
Document class
public abstract void setText(String text) throws IOException
text |
The new entire raw HTML text of the document |
This method writes information into a document and closes the input stream.
Use this method rather than getOutput if you have performed string-based operations on the raw HTML code of the document. Use getOutput if you are processing tokenized HTML.
The entire raw HTML text of the document as a string.
IOException
The Composer Plug-in API uses standard Java exceptions and exception handling. For more information, see your Java documentation.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Used to create plug-ins at runtime.
netscape.plugin.composer package
java.lang.Object
The Factory object is used for menu structure building. You can use a Factory class to create plug-ins at runtime.
When Netscape Composer starts up, it examines each plug-in file's netscape_plugin_composer.ini file to check whether it defines the property netscape.plugin.composer.Factory.
Most developers do not need to use this class; you can simply use the netscape.plugin.composer.classes property to name your plug-in classes directly. However, the Factory class provides additional flexibility. Here are some possible uses for a Factory class:
This table summarizes Factory class methods:
| Constructor | Description |
|---|---|
| Factory() | Creates an instance of the Factory class |
| Method | Description |
| getPlugins(File, Properties) | Returns an enumeration of plug-ins |
Document, ImageEncoder, ImageEncoderFactory, Plugin
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Creates an instance of the Factory class.
Factory class
public Factory()
A default constructor must be public to allow your class to be instantiated by name. Your class should be public, too, so that classes in other packages can have access to its methods.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Returns an enumeration of plug-ins.
Factory class
public Enumeration getPlugins(File pluginFileName,
Properties properties)
pluginFileName |
Plug-in file to scan |
| properties | Properties of the plug-in file to scan |
This method is responsible for creating and returning an array of plug-ins. By default, this method searches the netscape_plugin_composer.ini file for the property netscape.plugin.composer.classes, and creates one instance of each of the plug-in names in that string.
List of plug-ins to add to Composer.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Allows arbitrary transformations of the Composer's current document.
netscape.plugin.composer package
java.lang.Object
All composer plug-ins extend the Plugin class. This class is like the Java Applet or Application classes, in that it is the main class of its program. A plug-in is instantiated when the first Composer window opens, and is deleted when the application exits.
When you write a plug-in, you must override the methods of the Plugin class. The perform method does the actual work of the plug-in. When a plug-in is invoked, its perform method is called with the current document, which it can examine and modify. The document can change arbitrarily between calls to perform. You may even be given two different documents on two successive calls to perform.
Three Plugin methods identify the plug-in in the user interface and allow menu access to it, including the plug-in name, category, and a hint message that shows up when the user moves the cursor over the plug-in name on the menu. If the plug-in is registered as a menu option plug-in, its name and category appear on the Tools menu of the Composer window after it is installed.
This table summarizes Plugin class methods:
| Constructor | Description |
|---|---|
| Plugin() | Creates an instance of the Plugin class |
| Methods | Description |
| getCategory() | Gets the human readable category text of the plug-in |
| getHint() | Gets the human readable hint text for the plug-in |
| getName() | Gets the human readable name of the plug-in |
| perform(Document) | Executes the plug-in |
Document, Factory, ImageEncoder, ImageEncoderFactory
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Creates an instance of the Plugin class.
Plugin class
public Plugin()
A default constructor must be public so that your plug-in can be instantiated by name. Your class should be public, too, so that classes in other packages can have access to its methods.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Get the human readable category text of the plug-in.
Plugin class
public String getCategory()
The category is the title of the submenu that contains the plug-in on the Tools menu. The default is the name of the plug-in class. If several plug-ins have the same category, they all appear in the same menu.
In the user interface, categories collect plug-ins in groups that are meaningful to users. You can put all of your product's plug-ins into one category or you can place your plug-ins in several different ones. The sample plug-ins included with the Composer Plug-in Kit are assigned categories based on their functions.
The human readable category of the plug-in.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the human readable hint text of the plug-in.
Plugin class
public String getHint()
The hint is a one-sentence description of what the plug-in does. The default is the name of the plug-in class. The hint appears in the status line as the user moves the cursor over the menu item that activates the plug-in.
The human readable hint for the plug-in.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the human readable name of the plug-in.
Plugin class
public String getName()
This is the name of the menu item that activates the plug-in on the Tools menu. The default is the name of the plug-in class.
The human readable name of the plug-in.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Executes the plug-in.
Plugin class
public boolean perform(Document document) throws IOException
| document | The current document; the HTML document on which the plug-in is operating |
You override this method to perform most of the plug-in's work and to call other methods used by the plug-in. Use the overridden perform method to get the text from the document, analyze it, interact with the user, and modify the text.
Because the rest of the Composer user interface is held in a modal state while the plug-in is executing, consider finishing quickly or displaying a progress message to the user.
For information about preparing your plug-in's perform method so that you can test the plug-in in the Composer Testbed, see "Preparing for Running in the Testbed."
IOException
The Composer Plug-in API uses standard Java exceptions and exception handling. For more information, see your Java documentation.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Extends the image file formats that Composer can write.
netscape.plugin.composer package
java.lang.Object
An image encoder is a special type of Composer Plug-in that encodes image data to match specific image formats, allowing you to increase the number of 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.
Starting with Communicator 4.0, you can use image encoders to encode any kind of image that is natively supported by the Navigator, including JPEG, GIF, and XPM.
ImageEncoder is like the Composer plugin and Java Applet and Application classes, in that it is the main class of your program. This is where control passes from the Composer window to the plug-in.
The image encoder is built like a plug-in and shares its development issues. It differs from plug-ins in several ways. For more information and directions for writing and compiling image encoders, see "Writing and Using Image Encoders." To package and install image encoders, you follow the same procedures as for any Composer Plug-in.
This table summarizes ImageEncoder class methods:
| Constructor | Description |
|---|---|
| ImageEncoder() | Creates an instance of the ImageEncoder class |
| Methods | Description |
| encode(ImageProducer, OutputStream) |
Encodes the image |
| encoders() | Returns a listing of the encoders currently loaded into Communicator |
| getFileExtension() | Gets the standard file extension of the image format |
| getFileType(byte[]) | Gets the Mac OS file type of the image format |
| getHint() | Gets the human readable hint text for the image encoder |
| getName() | Gets the human readable name of the image encoder |
| needsQuantizedSource() | Finds whether the source image should be quantized (reduces the number of required bits per pixel) |
| register(ImageEncoder) | Used to register an encoder with the system |
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Creates an instance of the ImageEncoder class.
ImageEncoder class
public ImageEncoder()
A default constructor must be public to allow your image encoder to be instantiated by name. Your class should be public, too, so that classes in other packages can have access to its methods.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Encodes the image.
ImageEncoder class
public boolean encode(ImageProducer source,
OutputStream output) throws IOException
source |
The image to encode. |
| output | Output stream to which to write the encoded information. |
Override this method to perform the bulk of the image encoder's work. In this method, the image encoder reads the image information from the image source, interacts with the user, and writes the encoded information to the output stream.
ImageEncoder.encode corresponds to Plugin.perform, in that this method performs the work of the image encoder.
IOException
The Composer Plug-in API uses standard Java exceptions and exception handling. For more information, see your Java documentation.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Returns an enumeration of all the encoders currently loaded into Communicator.
ImageEncoder class
public static Enumeration encoders()
Your plug-in can call this method to get all the encoders currently loaded into Communicator. From this list, the user can choose an encoder and call its encode method.
Returns
An enumeration of all the encoders currently loaded into Communicator.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the standard file extension of the image encoder.
ImageEncoder class
public String getFileExtension()
This method gets the standard file extension of the image format, not including the period. Communicator uses the file extension to determine the MIME type of the file.
The human readable category for the image encoder or an empty string (default).
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Mac OS only
Gets the Mac OS file type of the image format.
ImageEncoder class
public void getFileType(byte type[])
type |
Four-byte array for the file type of the image format. |
Like the MIME type, the Mac OS file type is a way of specifying the type of a file. The MIME type is operating system independent, while the Mac OS file type is specific to the Mac OS. An image encoder does not require a MIME type because the file extension returned from getFileExtension is used to determine the MIME type.
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.
Mac OS file type of the image format or '????' (default).
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the human readable hint text for the image encoder.
ImageEncoder class
public String getHint()
The hint is a one-sentence description of what the image encoder does. This text shows up in the status line as the user moves the cursor over the image encoder's menu name.
The human readable hint for the image encoder or the name of the image encoder class (the default).
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Gets the human readable name of the image encoder.
ImageEncoder class
public String getName()
This is the name of the menu item that activates the image encoder on the Tools menu. The default is the name of the image encoder class.
The human readable name of the image encoder.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Finds whether the source image should be quantized.
ImageEncoder class
public Boolean needsQuantizedSource()
This method determines whether the source image should be quantized before it is passed to encode. Quantizing reduces the number of required bits per pixel from 24 to 8 bits per pixel (reduces distinct colors in the document to 256 or fewer), and is used when image formats require a lower number of bits/colors.
If this method returns true, then the source image is quantized to contain 256 or fewer distinct colors. If you want to use a specific quantization technique, or if you want to make quantization an option for the user, then you should return false from this method and supply your own quantization code.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Registers an encoder with the system.
ImageEncoder class
public static void register(ImageEncoder encoder);
encoder |
The encoder to register. |
Registering an encoder makes it available for any program to use.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Used to create image encoders at runtime.
netscape.plugin.composer package
netscape.plugin.composer.ImageEncoderFactory
When Composer starts up, it examines each plug-in's netscape_plugin_composer.ini file to see whether it defines the property netscape.plugin.composer.ImageEncoderFactory. If so, Composer assumes that the value of that property is the name of a class derived from ImageEncoderFactory. It instantiates that class, and its getImageEncoders method is called. This method creates and returns an enumerator of image encoders.
Most developers do not need to use the ImageEncoderFactory class. They can simply use the netscape.plugin.composer.ImageEncoder.classes property to name their ImageEncoder classes directly. However, the ImageEncoderFactory class provides additional flexibility. Here are some possible uses for an ImageEncoderFactory class:
This table summarizes ImageEncoderFactory class methods:
| Constructor | Description |
|---|---|
| ImageEncoderFactory() | Creates an instance of the ImageEncoderFactory class |
| Method | Description |
| getImageEncoders( File, Properties) |
Returns an enumeration of plug-ins |
Document, Factory, ImageEncoder, Plugin
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Creates an instance of the ImageEncoderFactory class.
ImageEncoderFactory class
public ImageEncoderFactory()
A default constructor must be public to allow the image encoder to be instantiated by name. Also, the image encoder factory class should be public so that classes in other packages can have access to its methods.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Returns an enumeration of plug-ins.
ImageEncoderFactory class
public Enumeration getImageEncoders(File pluginFileName,
Properties properties)
pluginFileName |
Plug-in file to scan. |
| properties | Properties of the plug-in file to scan. |
This function searches the properties for the property netscape.plugin.composer.ImageEncoder.classes and creates one instance of each of the plug-in names in that string.
A list of image encoders to add to the Composer.
[Top] [Plug-in Composer Package Classes] [Composer Plug-in API Reference]
Copyright © 1997 Netscape Communications Corporation