# 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 Jython package from http://www.jython.org/, for compiling and testing the pyking plugin.
- A newer version of BeanShell, for the beanking plugin.

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.