Creating a Jython plug-in
=========================

This file provides a very quick overview of the essentials of writing
a Jython-based plug-in. The Jython support in JGimp is based loosely
on the PyGimp architecture developed by James Henstridge, so if you
are familiar with that architecture you should be able to get going
pretty quickly with Jython scripts. HOWEVER, note that it is a
completely different class library, so while there are some
similarities, there are definitely more differences between the two.

Modules to import
=================
To create a Jython script, you'll need to import two modules:
jgimp_core and gimpenums. These provide basic capabilities like a
function to install your plug-in, constants, etc.

The basics of a Jython plug-in function
=======================================
The easiest way to create a Jython plug-in is to define a new function
that takes three parameters: gimpApp, pluginName, and paramList, and
returns an integer value representing whether it is successful or
not (PDB_SUCCESS or PDB_EXECUTION_ERROR).

gimpApp is a pointer to a org.gimp.jgimp.GimpApp object, which
provides the methods to communicate with the GIMP.

pluginName is the name of the plug-in called.

paramList is a list of parameters passed in to your function. If your
plug-in is a typical filter, it will contain at least three
items: runInteractive, image, and drawable.

The first item (runInteractive) is simply a boolean flag that
indicates whether your plug-in should provide a user interface for the
user to set values; a non-zero value indicates you should provide an
interface, a zero-value means you are being called by another script.

The second item is a JGimpImage object representing the target
image.

The third item is a JGimpLayer object representing the layer to
operate on.

Once you have done all your evil bidding in the filter, make sure you
return a value of PDB_SUCCESS or PDB_EXECUTION_ERROR to let the GIMP
now whether you were successful in taking over the world or not.


Installing the plug-in (in code)
================================
With the function defined, you need to install it. The jgimp_core
module has a function called install_plugin that you must call to
install your plug-in. But wait! You need to pass in a whole bunch of
parameters so the GIMP knows what to do with your plug-in. You need to
pass in:
- a unique string identifying your plug-in. Others can call your
  plug-in using this name
- A string describing the plug-in (for users to read)
- A help message
- The author's name
- The copyright information
- The date it was created (string)
- The menu path to install it in, e.g.,
    "<Image>/Filters/Colors/My Cool Filter"
- The types of images it can operate on (string)
- A list of tuples describing the params
- A list of tuples describing the return values
- The pointer to your function that you built in the first part of
  this README

That's a lot of stuff, so read the source or check out the manual to
learn more about the details regarding what valid menu paths are, the
different image type designations, and so on. If you have used the
PyGimp plug-in, then much of this should already be familiar to you.


Where to install the script (file system)
=========================================
Once your beautiful script is written, copy it to:
<gimpbasedir>/lib/gimp/1.2/jgimp/jython_scripts

Then it will be automatically loaded by the GIMP at start-up.


Random note of advice
=====================
The Jython extension to JGimp will automatically transform your
return arguments from a list to a single item if there is only
one item in the list. This is much more convenient than making
everything return a list, then forcing you to grab the first
element of a 1-member list.


For more info...
================
Read the sample scripts, and definitely check out the javadocs and
full manual. The javadocs document the entire JGimp library at your
disposable.
