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.