EditRocket Plugin Guide
EditRocket provides the ability for developers to write plugins, which are programs that can interact with EditRocket to produce custom results. This guide describes the process for registering plugins with EditRocket, and gives examples for making calls to the exposed methods of the EditRocket plugin API.
Language Requirements:
EditRocket requires plugins to be written using the Java programming language. To ensure compatibility with all versions of EditRocket, it is recommended that plugins be written using Java Runtime Environment (JRE) version 1.4.2. However, if compatibility across EditRocket versions and operating systems is not a concern, plugins can be written in any JRE version 1.4.2 or greater.
Plugin Requirements:
Plugin code must be placed in a JAR file. There must be a Java class contained in the JAR file with the same name as the name of the JAR file. This class must implement the editrocket.plugins.EditRocketPlugin interface and must be a member of the following package:
editrocket.plugins
Listed below is the EditRocketPlugin interface:
public void load();
public String getName();
public String getVersion();
public String getDescription();
Plugin Example:
Example:
Create the following file (PluginTest.java):
package editrocket.plugins;
import javax.swing.*;
public class PluginTest implements EditRocketPlugin
{
public void load()
{
System.out.println("in load() Plugin Test");
EditRocketPluginManager pluginManager =
EditRocketPluginManagerFactory.getInstance();
pluginManager.log("in load() in PluginTest ");
//add a menu item to the Plugins menu
JMenuItem menuItem = new JMenuItem("Plugin Test");
pluginManager.addPluginMenuItem(menuItem);
}
public String getName()
{
return "Plugin Test";
}
public String getVersion()
{
return "1.0";
}
public String getDescription()
{
return "An Example Plugin";
}
}
Compiling
To compile PluginTest.java, the pluginAPI.jar file that ships with EditRocket needs to be placed in the CLASSPATH.
The pluginAPI.jar file is located in the <EDITROCKET_INSTALL_DIR>/plugin_api/ directory.
Note: On Mac's, the pluginAPI.jar file is located inside the EditRocket.app under
Contents/Resources/Java/plugin_example
Storing
Once the PluginTest.java class is compiled, create a JAR file called PluginTest.jar that contains the following file:
editrocket/plugins/PluginTest.class
After creating the jar file, either use the Tools -> Plugins -> Import Plugin option to import the plugin into EditRocket, or move the jar file to the following location:
<user_home>/.editrocket/plugins/
The next time EditRocket loads, PluginTest will be available via the Plugins menu.
NOTE: The PluginExample below and the EditRocketPluginManager and EditRocketPlugin source can be found in the File -> New from Template -> plugins menu option.
EditRocketPluginManager API
EditRocket exposes an EditRocketPluginManager class that contains methods to allow plugins to interact with EditRocket. Here is the EditRocketPluginManager interface:
public interface EditRocketPluginManager
{
/**
* Returns the current major version of EditRocket in int format.
* For example, if using EditRocket version 1.04, 1 would be returned
* If using EditRocket version 10.4, 10 would be returned
*/
public int getMajorVersion();
/**
* Returns the current minor version of EditRocket in int format.
* For example, if using EditRocket version 1.04, 4 would be returned
* If using EditRocket version 1.4, 40 would be returned.
*/
public int getMinorVersion();
/**
* Returns the version as as String. If using EditRocket 1.04,
* 1.04 would be returned.
*/
public String getVersionString();
/**
* Adds a menu item to the plugin menu.
*/
public void addPluginMenuItem(JMenuItem item);
/**
* Returns the text of the editor in the
* currently displayed tab in String format
*/
public String getText();
/**
* Returns the text of the editor in the currently
* displayed tab in String format starting at the start position
* until the specified length
*/
public String getText (int start, int length);
/**
* Returns the selected text of the editor in the currently
* active tab, or null if there is no text selected
*/
public String getSelectedText();
/**
* Sets the text in the editor in the currently displayed tab
*/
public void setText (String text);
/**
* Replaces the current selection with the text, or
* if there is not selection, inserts the text into the editor
* at the current cursor position
*/
public void setSelectedText (String text);
/**
* Returns the line number (0 based) that the cursor is currently on
*/
public int getCursorLine();
/**
* Returns the offset in the editor for the cursor position
*/
public int getCursorPosition();
/**
* Returns the line number which contains the passed in position
*/
public int getLineForPosition (int position);
/**
* Returns the total number of lines in the editor
*/
public int getLineCount();
/**
* Returns the text of the line for the lineNumber
*/
public String getLineText (int lineNumber);
/**
* Selects text from start to end
*/
public void select (int start, int end);
/**
* Sets the cursor position to the specified position
*/
public void setCursorPosition (int position);
/**
* Logs to the EditRocket log file
* The logfile is located in the editrocket/logs
* directory under $USER_HOME directory. $USER_HOME
* is retrieved by doing a System.getProperty("user.home")
*/
public void log(Object obj);
/**
* Returns whether or not the user has a registered
* copy of EditRocket
*/
public boolean isRegistered();
}
Complete Plugin Example
Here is an example plugin that shows some of the uses of EditRocketPluginManager.
package editrocket.plugins;
import javax.swing.*;
import java.awt.event.*;
import java.util.*;
public class PluginExample implements EditRocketPlugin
{
public void load()
{
EditRocketPluginManager pluginManager =
EditRocketPluginManagerFactory.getInstance();
pluginManager.log("in load() in PluginExample ");
//add a menu item to the Plugins menu
JMenuItem menuItem = new JMenuItem("Plugin Example");
pluginManager.addPluginMenuItem(menuItem);
//add an ActionListener to perform operations when the
//menu item is selected
menuItem.addActionListener(new PluginExampleListener());
}
public String getName()
{
return "Plugin Example";
}
public String getVersion()
{
return "1.0";
}
public String getDescription()
{
return "Example of how to use EditRocket plugins";
}
private static class PluginExampleListener implements ActionListener
{
public PluginExampleListener()
{}
public void actionPerformed(ActionEvent e)
{
EditRocketPluginManager pluginManager =
EditRocketPluginManagerFactory.getInstance();
pluginManager.log("in actionPerformed");
int majorVersion = pluginManager.getMajorVersion();
int minorVersion = pluginManager.getMinorVersion();
String versionString = pluginManager.getVersionString();
boolean registered = pluginManager.isRegistered();
String editorText = pluginManager.getText();
String selectedText = pluginManager.getSelectedText();
int lineCount = pluginManager.getLineCount();
int cursorPosition = pluginManager.getCursorPosition();
int cursorLine = pluginManager.getCursorLine();
JPanel testPanel = new JPanel();
JTextArea textArea = new JTextArea(20,50);
JScrollPane scrollPane = new JScrollPane(textArea);
testPanel.add(scrollPane);
textArea.append("Major Version: "+majorVersion);
textArea.append("\n");
textArea.append("Minor Version: "+minorVersion);
textArea.append("\n");
textArea.append("Version String: "+versionString);
textArea.append("\n");
textArea.append("Registered: "+registered);
textArea.append("\n");
textArea.append("Selected Text: "+selectedText);
textArea.append("\n");
textArea.append("Line Count: "+lineCount);
textArea.append("\n");
textArea.append("Cursor Position: " +cursorPosition);
textArea.append("\n");
textArea.append("Cursor Line: " +cursorLine);
textArea.append("\n");
textArea.append("Editor Contents: " +editorText);
textArea.setCaretPosition(0);
JFrame testFrame = new JFrame("PluginExample");
testFrame.setSize(400,400);
testFrame.getContentPane().add(testPanel);
testFrame.pack();
testFrame.setVisible(true);
}
}
}
