Sample Plugins for KiNG
This document describes the basics of creating new plugins for the KiNG
3-D graphics program and provides several simple examples. The examples
were written by Ian W. Davis
(ian.davis@duke.edu) and Andrea Mantler (mantler@cs.unc.edu), and were
last tested against KiNG 1.30.
Getting Started
In order to compile and test these plugins, you'll want the following
resources:
- The complete KiNG source code, which you can download for free
from http://kinemage.biochem.duke.edu.
- The "Hacking KiNG" document, included with the source code in the
king/doc/ folder. This
document provides a detailed overview of the program structure with
specific details on creating plugins.
- The KiNG Javadocs, also included with the source code. These
serve as a useful reference for developing plugin functionality.
- A Java Development Kit (JDK) for Java 1.4.x or newer.
- The Ant build tool (http://ant.apache.org/).
Optional equipment includes:
The sample_plugins folder
should be in the same place as the king, chiropraxis, and driftwood folders, like this:
source_code
|
+-- king
| |
| +-- doc
| |
| .
| .
|
+-- driftwood
|
+-- javadocs
|
+-- sample_plugins
| |
| +-- demoPlugin
| .
| .
.
.
Basic steps
In outline form, here are the basic steps you must take to create and
test a new KiNG plugin. See "Hacking KiNG" for more detail, and see the
sample projects included here for example code.
- Create a Java class that extends king.Plugin or king.BasicTool.
- Implement getToolsMenuItem().
- (Optional) Implement
one or more of getHelpURL(), getDependencies, isAppletSafe().
- Create a META_INF/services/king.Plugin
file that lists the fully qualified name of your plugin class(es).
- (Optional) Create a king/king_prefs file that
describes which menu your plugin will appear in.
- Package the above into a JAR file.
- Place the JAR file in the plugins/
folder of your current copy of KiNG, and then (re)start KiNG.
demoPlugin
Andrea Mantler's code creates an empty kinemage and fills it with
random lines and balls. This is a great demo of a fully-functional
plugin complete with help documentation. Among other things, it shows
how to create new graphics objects and how to update the graphics
display afterwards. The code is very well commented, but be sure to see
her doc/readme file as
well.
BeanKing
BeanKing is about as bare-bones a plugin as you can write. It uses the
excellent BeanShell library to give KiNG an interpretted scripting
language. This means you can write short, Java-like scripts as KiNG is
running and see what they do! This is a great way to experiment with
programming KiNG, and may help you in developing other plugins. Try
reading the BeanShell website to learn about built-in functions like editor().
PyKing
PyKing is very similar to BeanKing, except that the scripting language
is Python instead of a variant of Java. PyKing uses the Jython library,
which is a Python interpretter coded in pure Java. Because Jython is
rather large, it's not bundled with this distribution -- you'll have to
download and install it separately.
PyKing allows you write Python scripts interactively while KiNG is
running, just like BeanKing does. This is a fun way to test KiNG's
functionality. However, PyKing itself is written in Python and compiled to
some Java class files. Thus, if you're more comfortable writing in
Python than in Java, you can use this as a template for writing
pre-compiled, full-featured KiNG plugins in the Python language.
However, you're still going to have to learn some Java if you want to
make much use of either the Java GUI classes (Swing/AWT) or of KiNG's
functionality, a fact which is quite obvious in the PyKing source code.