Basic Run Service Interface for Hyperwire Plug-Ins

BasicRunService Interface

The BasicRunService interface provides general utility methods for all plug-ins. It includes query methods for properties that Hyperwire maintains internally (such as local data options), and the methods for sending data across output ports. The interface is specified in the file BasicRunService.java

package kinetix.hyperc1.runtime;

import java.applet.Applet;
import java.awt.Graphics;
import java.util.Vector;
public interface BasicRunService
{

To call these methods, use the instance variable ("handle") mRunService inherited from the HwBasicPlugIn class. For example, mRunService.siGetApplet().

siGetApplet

Prototype:

public HwApplet siGetApplet();

Returns:

HwApplet A reference to the applet.

Description: Returns a reference to the applet. HwApplet is a subclass of applet specific to Hyperwire.

siGetPlugIns

Prototype:

public Vector siGetPlugIns();

Returns:

Vector A list of the modules in the applet.

Description: Returns a list of all modules in the applet currently running. The list includes both plug-ins and standard Hyperwire modules.

siGetChildPlugIns

Prototype:

public Vector siGetChildPlugIns();

Returns:

Vector A list of the modules that are immediate children of the plug-in.

Description: Returns a list of the modules in the applet that are immediate children of the plug-in module. The list includes both plug-ins and standard Hyperwire modules.

The list does not include the calling module itself.

siGetNumChildPlugIns

Prototype:

public int siGetNumChildPlugIns();

Returns:

int The number of modules that are immediate children of the plug-in.

Description: Returns the number of modules that are immediate children of the plug-in module.

siGetDescendentPlugIns

Prototype:

public Vector siGetDescendentPlugIns();

Returns:

Vector A list of the modules that are descendants of the plug-in.

Description: Returns a list of the modules in the applet that are descendants of the plug-in module. A descendant module can be an immediate child module, a child of a child, and so on. The list includes both plug-ins and standard Hyperwire modules.

The list does not include the calling module itself.

siGetSiblingPlugInNamed

Prototype:

public BasicRunPlugIn siGetSiblingPlugInNamed(String name);

Returns:

BasicRunPlugIn The module of the specified name in the same container as the caller. Returns null if no module of that name is found.

Parameters:

name The module to find.

Description: Finds a module instance of the specified name in the same container as the module that calls this method (called a sibling because it's in the same container). Returns null if it can't find a module of that name.

siGetCurrentFocus

Prototype:

public BasicRunPlugIn siGetCurrentFocus();

Returns:

BasicRunPlugIn The module that currently has input focus, or null if focus is not assigned.

Description: Returns a reference to the module that currently has input focus.

siGetEmbeddedData

Prototype:

public HwObject siGetEmbeddedData();

Returns:

HwObject The plug-in module�s embedded data.

Description: Returns the embedded data defined for the plug-in.

siGetModuleName

Prototype:

public String siGetModuleName();

Returns:

String The name of the module.

Description: Returns the name of the module that calls this method.

siGetOwner

Prototype:

public BasicRunPlugIn siGetOwner();

Returns:

BasicRunPlugIn The Visual Container module that contains the plug-in, or null if the parent is the title itself.

Description: Returns the owner (parent) of the plug-in.

siGetAbsParentRect

Prototype:

public Rectangle siGetAbsParentRect();

Returns:

Rectangle The bounding rectangle of the plug-in�s parent. This is Rectangle(0, 0, 0, 0) if the parent is the title itself.

Description: Returns the bounding rectangle for the plug-in�s parent container, relative to the applet.

siPerformInput

Prototypes:

public HwObject siPerformInput(String aName)
	throws HwException;

public HwObject siPerformInput(String aName, HwObject[] args)
	throws HwException;

public HwObject siPerformInput(String aName, HwObject arg1)
	throws HwException;

public HwObject siPerformInput(String aName, HwObject arg1, HwObject arg2)
	throws HwException;

public HwObject siPerformInput(String aName, HwObject arg1, HwObject arg2,
	HwObject arg3)
	throws HwException;

Returns:

HwObject The input port method�s return value, defined by the plug-in.

Parameters:

aName The input port to trigger.

args An array of one or more parameters for the input port to receive.

arg1, arg2, arg3 One to three arguments (wire parameters).

Description: Triggers the wire message for the input port aName.

This method works only for input ports you have defined for the plug-in module and defined in the MDF file. It does not work for the standard Hyperwire module inputs.

The data must be "wrapped" in a Hyperwire data type, as described in "Output Ports."

This method lets the plug-in do its own input triggering.

siPerformOutput

Prototypes:

public HwObject siPerformOutput(String aName, HwObject[] args)
	throws HwException;

public HwObject siPerformOutput(String aName)
	throws HwException;

public HwObject siPerformOutput(String aName, HwObject arg1)
	throws HwException;

public HwObject siPerformOutput(String aName, HwObject arg1, HwObject arg2)
	throws HwException;

public HwObject siPerformOutput(String aName, HwObject arg1, HwObject arg2,
	HwObject arg3) throws HwException;

Returns:

HwObject The output port method�s return value, defined by the plug-in.

Parameters:

aName The output port to trigger.

args An array of arguments (wire parameters).

arg1, arg2, arg3 One to three arguments (wire parameters).

Description: Sends data across the specified output port. The data must be "wrapped" in a Hyperwire data type, as described in "Output Ports."

If your plug-in triggers an output port with great frequency, you might want to cache the port locally to improve performance. See siGetOutput() for a description of how to use caching.

siLogException

Prototype:

public void siLogException(Exception e);

Parameter:

e The exception.

Description: Writes an exception to the error output. Don�t call this method unless the plug-in is not going to throw another exception. In other words, call this method only at the base of the calling stack that generated the exception, or in a system callback.

siProcessException

Prototype:

public HwException siProcessException(Exception e, String errMsg);

Returns:

HwException The Hyperwire exception.

Parameters:

e The exception.

errMsg A description of why the exception was logged. Can be null.

Description: Converts a general exception to a Hyperwire exception and appends errMsg, which must describe the context in which the exception occurred. If you call siProcessException(), you must then rethrow the HwException it returns, unless the calling code is at the base of the calling stack that generated the exception.

siProcessRangeException

Prototype:

public HwException siProcessRangeException(RangeException e, String errMsg)
	throws RangeException;

Returns:

HwException The Hyperwire exception.

Parameters:

e The range exception.

errMsg A description of why the exception was logged. Can be null.

Description: Call to log a range exception, appending errMsg, which must describe the context in which the exception occurred. If you want to treat out-of-range exceptions as true exceptions, rethrow the HwException that this method returns. Otherwise, you can continue from the point where the exception occurred.

siGetOutput

Prototype:

public MessageTableEntry siGetOutput(String aName);

Returns:

MessageTableEntry A message table object that represents the named port, stored as a local variable.

Parameter:

aName The name of the output port.

Description: Returns a MessageTableEntry for the output port aName. The plug-in can then use the message table to manage the output port. For example, it can evaluate the message table entry by sending the message evaluateWith() or evaluate().

Use a cache instead of siPerformOutput() calls when you need to improve performance for an output port that is used frequently. After you cache the port at initialization time, subsequent evaluations are very fast. For example, this can be useful in inner-loop code where the output port is triggered many thousands of times per second.

Example:

   private MessageTableEntry mMyFooCacheIV;
   private boolean mFooPortHasWires;

   public void piEventAppletInit(Applet theApplet) throws HwException
       {
       mMyFooCacheIV = aRunService.siGetOutput("Foo");
       mFooPortHasWires = (mMyFooCacheIV != null) && mMyFooCacheIV.hasWires();
      .
      .
      .
      }
 
   private void someFunctionInMyPlugIn()
      {
      if (mFooPortHasWires)
         {
         for (int i = 0; i < GIZILLION; i++)
         mMyFooCacheIV.evaluate();
         }
      }

The MessageTableEntry object has the methods shown in the following table.

Name Prototype Description

evaluateWith
public HwObject evaluateWith(HwObject[] args) throws HwException;
Triggers the output port and sends the parameters passed to it.

evaluate
public HwObject evaluate() throws HwException;
Triggers the output port without sending parameters.

hasWires
public boolean hasWires();
Returns true if the port has wires attached to it, false if it doesn't.

getNumParms
abstract public int getNumParms();
Returns the number of parameters for this output port.

Name	Prototype	Description
`evaluateWith`	public HwObject evaluateWith(HwObject[] args) throws HwException;	Triggers the output port and sends the parameters passed to it.
`evaluate`	public HwObject evaluate() throws HwException;	Triggers the output port without sending parameters.
`hasWires`	public boolean hasWires();	Returns `true` if the port has wires attached to it, `false` if it doesn't.
`getNumParms`	abstract public int getNumParms();	Returns the number of parameters for this output port.

siPlugInWantsTicks

Prototype:

public boolean siPlugInWantsTicks(boolean wantTick);

Returns:

boolean true if the call caused a state change, false otherwise.

Parameter:

wantTick true if the plug-in wants refresh daemon ticks, false if it does not.

Description: Call this method to register your plug-in with the refresh daemon so it will receive refresh ticks. Refresh ticks enable plug-ins with animation to synchronize themselves with other Hyperwire modules.

See WavyPlugIn.java for an example.

Caution: The refresh daemon is not initialized until after piInit() time, so don't call siPlugInWantsTicks() until a later time. Your implementation of piEventAppletStart() is a good place to put the call to siPlugInWantsTicks().

siPlugInWantsKeyEvents

Prototype:

public boolean siPlugInWantsKeyEvents(boolean wantsKeys);

Returns:

boolean true if the call caused a state change, false otherwise.

Parameter:

wantsKeys true if the plug-in wants key up/down events, false if it does not.

Description: Call this method to register your plug-in so it will receive key-up and key-down events.

siPropertiesChanged

Prototype:

public void siPropertiesChanged();

Description: If your plug-in changes the value of a module-specific property field (a property that the author can set in the module-specific tab of the module's Properties dialog), call this method to inform the system that the field has changed. This sets a "dirty bit" that informs the runtime that your plug-in should receive a piRestoreInitialRunState() call at reset time.

siReset

Prototype:

public void siReset()
	throws HwException;

Description: Triggers an explicit reset (piRestoreInitialRunState()) of the plug-in.

siSetCurrentFocus

Prototype:

public void siSetCurrentFocus(BasicRunPlugIn aPlugIn);

Parameter:

aPlugIn Identifies the plug-in that is to receive focus.

Description: Call this method to change the current input focus to a specified plug-in.

siSetRadioNodule

Prototype:

public void siSetRadioNodule();

Description: Call this method to become the active radio button module among mutually exclusive modules in an applet or container. To become active, a plug-in module should call this method and then wait for a piSetRadioState() call with the parameter set to true. See "Radio Button Modules."

siGetRefreshDaemon

Prototype:

public RefreshDaemon siGetRefreshDaemon();

Returns:

RefreshDaemon A refresh daemon instance.

Description: Returns the refresh daemon instance for this applet.

siSetCapture

Prototype:

public BasicRunPlugIn siSetCapture(BasicRunPlugIn aPlugIn);

Returns:

BasicRunPlugIn The module that previously had mouse capture, or null.

Parameter:

aPlugIn The visual module to capture the mouse from.

Description: Captures the mouse from a visual module. This is similar to the Windows SetCapture() function. The module that captures the mouse receives piMouseDown(), piMouseUp(), piMouseMove(), and piMouseDrag() events directly, bypassing the usual broadcast mechanism.

This method returns null if no module previously had mouse capture.

The method siReleaseCapture() releases the current mouse capture. The method siGetCapture() returns which plug-in has captured the mouse.

Passing a null parameter is equivalent to calling siReleaseCapture().

siReleaseCapture

Prototype:

public BasicRunPlugIn siReleaseCapture();

Returns:

BasicRunPlugIn The module that previously had mouse capture, or null.

Description: Releases a captured mouse. This is similar to the Windows ReleaseCapture() function. After this call, no module has mouse capture.

This method returns null if no module previously had mouse capture.

The method siSetCapture() captures the mouse. The method siGetCapture() returns which plug-in has captured the mouse.

siGetCapture

Prototype:

public BasicRunPlugIn siGetCapture();

Returns:

BasicRunPlugIn The module that currently has mouse capture, or null.

Description: Gets the module that has mouse capture. This is similar to the Windows GetCapture() function.

This method returns null if no module currently has mouse capture.

The method siSetCapture() captures the mouse. The method siReleaseCapture() releases the current mouse capture.