ImageMeister Plugin Tutorial

This file describes how to create a plugin for ImageMeister. In this example, we'll assume that you want to create a plugin to view text files, and that the URL of your home page is the ( heretofore hypothetical address ) http://www.valzavala.com.

The source code and a CWPro2 project file for this example are included in the 'example' folder.

The 'docs' folder contains javadoc .html documentation for the ImageMeister classes and interfaces which are used by plugins.

In the simplest case, you need to create three classes which implement the following three interfaces:

COM.tolstoy.imagemeister.PluginFactoryI - registers your plugin(s) with ImageMeister
COM.tolstoy.imagemeister.PluginI - represents a plugin: returns information about the plugin, and creates viewer instances
COM.tolstoy.imagemeister.ImageViewerI - the object which displays the file

We will put the classes which implement these interfaces in their own package:

	COM.valzavala.TextViewer.*

The class which implements PluginFactoryI must be named 'IMPluginFactory'; because it will have your package name, it won't be confused with plugins from other vendors.

The class which implements PluginI does not have to be named anything in particular; in this example, we'll name it 'TextViewerPlugin'.

The class which implements ImageViewerI also does not have to be named anything in particular; in this example, we'll name it 'TextImageViewer'.

So, after putting these classes which we need to create in their own package, we decide we need to create the following three classes:


	COM.valzavala.TextViewer.IMPluginFactory
	COM.valzavala.TextViewer.TextViewerPlugin
	COM.valzavala.TextViewer.TextImageViewer

A description of each class follows.

COM.valzavala.TextViewer.IMPluginFactory

This class will be used to register your plugin with ImageMeister. The most important method which this class implements is registerPlugins(). When ImageMeister starts up, it will call this method. This method should then register any plugins with ImageMeister by calling the PluginManager singleton's addPlugin() method:

	COM.valzavala.TextViewer.TextViewerPlugin	plug;
	plug = new COM.valzavala.TextViewer.TextViewerPlugin();
	COM.tolstoy.imagemeister.PluginManager.addPlugin( plug, 0 );

COM.valzavala.TextViewer.TextViewerPlugin

This class represents the actual plugin. It returns information on the plugin, and creates instances of the 'TextImageViewer' class on request. The two most important methods which this class implements are 'canCreateImageViewer()' and 'createImageViewer()'. For instance, when 'canCreateImageViewer()' is called, this method should indicate whether this plugin can create image viewers for the file passed into the method:

	boolean canCreateImageViewer( FileSpecifier spec ) {
		examine the DiskObject or File contained by 'spec'

		if 'spec' specifies a text file
			return true
		else
			return false
	}

	COM.valzavala.TextViewer.TextImageViewer createImageViewer(
	ImageViewerOwner onr,
	FileSpecifier spec,
	Rectangle rect ) {
		examine the DiskObject or File contained by 'spec'

		if 'spec' specifies a text file
			return a new instance of COM.valzavala.TextViewer.TextImageViewer
		else
			return null
	}

COM.valzavala.TextViewer.TextImageViewer

This class extends java.awt.Panel, and displays the first line of the text file.

After writing these classes, we need to put them in a zip file, and then put the zip file in ImageMeister's 'plugins' folder. The name of the zip file is not important, except insofar as avoiding conflicts with plugins from other vendors is concerned. In this case, we've chosen to name the zip file 'vztv9832.zip'.

Windows Notes

The Mac shell application which runs ImageMeister scans the plugins folder for new plugins. Since the Windows version currently doesn't have a shell application, you need to do a couple extra steps on Windows:

Add your plugin to the classpath in the batch file which comes with ImageMeister.
Add the full name of your plugin's 'IMPluginFactory' class to the file 'plugins.txt', which is inside the 'data' folder.

So, using this example, we would add the following line to 'imrunSN.bat':

	set classpath=%classpath%;c:\samizdat\imeister\plugins\vztv9832.zip

And, we would add the following line to 'plugins.txt':

	COM.valzavala.TextViewer.IMPluginFactory

For final versions of the classes described above, see the sample project.

See the package documentation for the complete ImageMeister plugin API.