## 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 for this example is included in the 'imeister\SDK\example' folder. This folder also contains the compiled version of the classes in this folder, stored in the 'vztv9832.zip' file.

This folder also includes `macproj.sit`, a CodeWarrior Pro2 (Mac) project file and `make.bat`, a Windows batch file. If you aren't on Mac or Win, or if you don't have CodeWarrior, use your favorite environment or SDK to compile the .java files.

The documentation for the classes of ImageMeister which are used by plugins is included with the JConfig documentation in the main 'docs' folder. Click here for the ImageMeister docs

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.