Difference between revisions of "Extending OpenRocket"

From OpenRocket wiki
Jump to: navigation, search
Line 64: Line 64:
  
 
A single simulation extension provider can be used to provide multiple simulation extensions.  For example, the provider could scan a directory for scripts and provide a simulation extension for each script file.  The abstract class assumes you are only providing a single simulation extension.
 
A single simulation extension provider can be used to provide multiple simulation extensions.  For example, the provider could scan a directory for scripts and provide a simulation extension for each script file.  The abstract class assumes you are only providing a single simulation extension.
 +
 +
=== Simulation extension configurator ===
 +
 +
The separate configurator provides a Swing GUI dialog to configure a single instance of a simulation extension.  It is implemented as a separate plugin so that the plugin itself can be used also on platforms not supporting Swing (such as Android).
 +
 +
<code>SwingSimulationExtensionConfigurator</code> provides a ready framework where you only need to implement the <code>getConfigurationComponent</code> method, where you add the necessary components to a ready <code>JPanel</code>.

Revision as of 01:00, 27 December 2014

OpenRocket is built to be extensible using plugins. You can implement your own functionality or download plugins implemented by others.

This document describes how to implement your own extensions to OpenRocket.


Plugins

Extensions to OpenRocket are implemented as plugins. All interfaces that may have multiple implementations should be implemented using plugin interfaces internally. That way, external plugins may create new implementations.

A plugin is compiled into a JAR file and placed into the OpenRocket plugin directory. These JAR files are included in the OpenRocket classpath at startup and scanned for classes and interfaces annotated with @Plugin.

  • A plugin interface is a Java interface that is annotated with the @Plugin annotation. These interfaces are scanned from the classpath at startup and can be queried by the code.
  • A plugin implementation is a Java class that implements a plugin interface and is annotated with the @Plugin annotation.

In practise the plugin interfaces are defined by the internal OpenRocket code, and are extension points which internal and external plugins can implement.

Note: Many of the internal interfaces have not yet been changed to use the plugin interface. They will be migrated one by one. Help is appreciated.


Simulation extensions

Simulation extensions allow modifying simulations before or during a simulation. They allow controlling almost every aspect of a simulation.

A simulation extensions typically consists of 2-4 Java classes described below. The recommended way of implementing these interfaces is by extending the abstract classes. This allows maximum compatibility with future versions of OpenRocket when new methods are added to the interfaces.


Interface / abstract class Description
Simulation extension SimulationExtension
AbstractSimulationExtension
Contains the extension configuration for a single simulation and a method that is called whenever the simulation is started. A new instance is created for each simulation that has the extension defined.
Simulation extension provider SimulationExtensionProvider
AbstractSimulationExtensionProvider
An OpenRocket plugin that functions as a factory class for the simulation extension. It provides the extension ID, location in the UI menu and instances of the extension.
Simulation extension configurator SwingSimulationExtensionConfigurator
AbstractSwingSimulationExtensionConfigurator
An (optional) OpenRocket plugin that provides a GUI for configuring the simulation extension.
Simulation listener SimulationListener
SimulationComputationListener
SimulationEventListener

AbstractSimulationListener
A listener that can be attached to a simulation at runtime. The listener is notified of all actions during the simulation and it can modify and affect the simulation while it is being run. The simulation extension may add a simulation listener to the simulation run when it is started.


Simulation extension class

An instance of the simulation extension class is attached to each simulation that has the extension defined. It contains the configuration of the extension and a method that is called when the simulation is run.

You need to extend AbstractSimulationExtension and implement at least the initialize method. This method is called whenever a simulation run is started. It can modify the SimulationConditions, which contains the launch conditions of the simulation. It can also attach simulation listeners to the simulation, which allows interacting with the simulation while it is running.

Simulation extension provider

The provider is a factory class that creates instances of the simulation extension. It also provides an ID string identifying the simulation extension and the name and menu location of the extension.

When using AbstractSimulationExtensionProvider you only need to provide the constructor the simulation extension class and the name and menu location.

A single simulation extension provider can be used to provide multiple simulation extensions. For example, the provider could scan a directory for scripts and provide a simulation extension for each script file. The abstract class assumes you are only providing a single simulation extension.

Simulation extension configurator

The separate configurator provides a Swing GUI dialog to configure a single instance of a simulation extension. It is implemented as a separate plugin so that the plugin itself can be used also on platforms not supporting Swing (such as Android).

SwingSimulationExtensionConfigurator provides a ready framework where you only need to implement the getConfigurationComponent method, where you add the necessary components to a ready JPanel.