Document API

API Reference
...     Document API

Constructors

public MyPlugin(java.util.Properties props)
Should call super(props)

public MyPlugin()
Should call super(); or if you use java.util.Properties use super to initialize the properties you intend to use. For example:
   public MyPlugin() throws Exception {
     super(prop1, value1, prop2, value2, ...);
     ...
   }

Methods Called by the Constructor

public setInputSize(int in)
Sets input size. Required.

public setOutputSize(int out)
Sets output size. Required.

public setLedSize(int ledSize)
Determines number of leds that appear in plugin body (default: 0) .

public setLedRadix(int ledRadix)
Determines the radix used in the led display (default: 16).

public setLabels(String label0, String label1, ...)
Designates labels used on pins.

public setInMap(int n0, int n1, ...)
public setOutMap(int n0, int n1, ...)
Determines pin bundling.

Initialization

public void init()
User-defined initialization of plugin state (default method is empty). This method is called only after a view has been attached to the document, so it may call view methods.

public void reInit()
Must be called after any re-invocation of the constructor (or constructor-optional) methods listed above. If overridden, be sure to invoke super.reInit().

Logical methods

public void evalState(int source, int val)
This method must be implemented. It is called when an input state changes.

Parameters:
source     pin number of input source that changed
val new state value (0 or 1)

public void evalBundle(int pos, long val)
This new plug-in method (as of v. 3b3.04) takes advantage of bus event aggregation. It is called on a position number (rather than a pin number) and its value is the binary value determined from the set of pins mapped to the bundle in that position (in little-endian format). This method is called whenever any of the pins in the bundle sees a new value, and so can be used even with aggregation turned off.

The plug-in may now extend either evalBundle or evalState (or both). The default versions of these methods prints a console message in verbose mode, so "call super" if you want this message printed.

public void prime()
Used to initialize the plug-in's output. The default implemention outputs 0 on all pins.

Pin ↔ Pos Conversion

See Document Architecture: Pin indexing for a discussion of pin and pos indexing.
public int pinToPos(int pinNo)
Returns the position number ("pos" number) of the pin at pin number pinNo

public int posToPin(int pos, int offset)
Returns the pin number of the pin in position given by offset at pos number posNo.

public int posToPin(int pos)
Equivalent to pinToPos(pos, 0).

Binary Input/Output

These methods input or output a single binary state value on a specified pin.

public int getState(int pinNo)
Returns current input state at pin number pinNo.

protected void putState(int pinNo, int value)
Outputs state value to pin pinNo.

protected int getStatePos(int posNo, int offset)
Returns current input state at the pin in position given by offset at pos number posNo.

protected int getStatePos(int posNo)
Equivalent to getStatePos(posNo, 0).

protected void putStatePos(int pos, int offset, int value)
Outputs value at the pin in position given by offset at pos number posNo.

protected void putStatePos(int pos, int value)
Equivalent to putStatePos(pos, 0, value).

Input/Output properties

public int getInputSize()
Returns the number of input pins.

public int getOutputSize()
Returns the number of output pins.

public int getInputPosSize()
Returns the number of input positions.

public int getOutputPosSize()
Returns the number of output positions.

public boolean isInput(int pinNo)
Returns true if pinNo is an input pin.

public boolean isOutput(int pinNo)
Returns true if pinNo is an output pin.

Integer ↔ Boolean Conversion

protected boolean intToBool(int x)
Returns true if x == 1, false otherwise

protected boolean boolToInt(boolean b)
returns 1 if x == true, 0 otherwise

Binary ↔ Integer Conversion

protected int binToInt(int least, int most)
protected long binToLong(int least, int most)
Returns the binary value of the pins between least and most (inclusive) as a binary number. If least < most, the bit sequence uses little-endian ordering; otherwise it uses big-endian ordering.

protected void intToBin(int least, int most, int val)
protected void longToBin(int least, int most, long val)
Outputs val as a binary number on the pins between least and most (inclusive). If least < most, the bit sequence uses little-endian ordering; otherwise it uses big-endian ordering.

protected long getBundle(int posNo)
protected long getBundle(int posNo, int offset, int length)
returns the value of the pins at pos number posNo as a long value. The bundle may be up to 64 bits wide (use casts for char and int assignments). The first version returns the entire bundle at the given position. The second version returns the smaller bundle specified by the offset and length parameters.

protected void putBundle(int posNo, int val)
protected void putBundle(int posNo, int val, int offset, int length)
protected void putBundle(int posNo, long val)
protected void putBundle(int posNo, long val, int offset, int length)
Outputs val as a binary number on the pins at pos number posNo The second version outputs only to a portion of the bundle, leaving the other pins unchanged.

protected void putBundle(int posNo, int[] val)
protected void putBundle(int posNo, int[] val, int offset, int length)
Same, but val is treated as an array of bits, output on the sequence of pins starting at posNo.

Led management

protected int getLedSize()
Returns the length of the led array.

public void setLed(int ledNo, int value)
Sets led number ledNo with value value.

public void setLeds(int lo, int len, int val)
Sets the array of leds of length len starting at led number lo with the value val.

public void setLeds(val)
Equivalent to setLeds(0, getLedSize(), val).

protected int getLed(int ledno)
Returns the value displayed by led ledno.

Action menu

public void setActions(String... actions)
Sets the user-defined actions of the action menu for this plugin. Actions are indexed by their order in this method call.

public String[] getActions()
Returns the array of user-defined actions added by this plugin to the action menu, in the order in which they were listed in setActions.

public void performAction(int idx)
Handler invoked when a user-defined action is selected from the action menu. idx is the index of the selected action in the array returned by getActions().

performAction may call any of the methods listed above as required (or optional) in the constructor, but must call reInit() if it does so.

public boolean actionIsEnabled(int idx)
Returns true if action idx is enabled.

public void setActionEnabled(int idx, boolean enabled)
public void actionEnable(int idx) {deprecated}
public void actionDisable(int idx) {deprecated}
Enables/disables action idx.

Properties

Properties are stored in the XML representation and passed to the constructor.
public void setProperty(String property, String value)
public void setProperty(String property, Integer value)
public void setProperty(String property, Long value)
public void setProperty(String property, Float value)
public void setProperty(String property, Double value)
Sets property to value.

UserPluginView API Methods

public String getProperty(String property)
public Integer getIntegerProperty(String property)
public Long getLongProperty(String property)
public Float getFloatProperty(String property)
public Double getDoubleProperty(String property)
Returns current value of property. Note: type-conversion failure will result in run-time error.

Labels

public String getLabel(int pinNo)
Returns the label associated with pin number pinNo, or null if no label has been assigned.

public String getLabelPos(int posNo)
Returns the label associated with pos number posNo, or null if no label has been assigned.

Simulation

protected boolean isSimOn()
Returns true if simulation is on.

protected int getSimTime()
Returns current simulation time.

protected void startListeningForSimTimeEvents()
Adds plugin as a listener for simulation time interrupts.

protected void stopListeningForSimTimeEvents()
Removes plugin as a listener for simulation time interrupts.

protected void processSimEvent(int time)
User-defined handler called at each simulation timer event (if plugin is a listener). time is the current simulation time. Default implementation is empty.

protected void simReset()
User-defined handler for simulation reset events. Default implementation is empty.

PluginInfo

public static PluginInfo info = new PluginInfo(String... desc)
If declared, displays the strings passed to the PluginInfo constructor in the plugin menu.

Miscellaneous getters and setters

public ProtoPluginView getView()
Returns view object.

public int getLedRadix()
Returns current LED radix.

public int[] getInMap()
Returns current input map.

public int[] getOutMap()
Returns current output map.

public String getPrintName()
public void setPrintName(String printName)
Get (set) plugin name (default: plugin classname).

Plugin reflection

protected Collection<DLPlugIn> getPluginSet()
Returns a collection of all plugin objects at the same level as the caller.