HwBasicUserPlugIn Class

A plug-in module must subclass methods of the HwBasicUserPlugIn class, specified in the source file HwBasicUserPlugIn.java. 

package kinetix.hyperc1.runtime;

import kinetix.hyperc1.runtime.*;

import java.applet.Applet;
import java.awt.Event;
import java.awt.MediaTracker;

public class HwBasicUserPlugIn extends HwBasicPlugIn
{

Description: This class performs the minimum required handshaking between Hyperwire and the plug-in module. Plug-ins that display graphics or have a graphical user interface must subclass the HwVisualUserPlugIn class instead.

All HwBasicUserPlugIn methods have a default implementation that in most cases does nothing. You need to override only those methods that are critical to the operation of your plug-in; for example, piEventAppletStart() and piEventAppletStop().

Your plug-in package can include other classes. See "Java Plug-In Code" for an overall description of the interface to Hyperwire.

piInit

Prototype: 

public void piInit(BasicRunService aRunService)
	throws HwException;

Parameter:
aRunService A handle to the system run service.

Description: The Hyperwire runtime calls this method when the plug-in is created. Your implementation should do the following:

  1. Save the run-service handle in the instance variable mRunService. This is a public field variable declared in HwBasicPlugIn. You can assign mRunService in one of two ways. Either assign it directly. For example: 

    	mRunService = aRunService;

    Or call super.piInit(). For example: 

    	super.piInit(aRunService);
  2. Create any dynamic data structures the plug-in needs.

When piInit() is called, the plug-in cannot assume that other modules are active yet. It should initialize its data structures, but not attempt to communicate with other modules.

piEventAppletInit

Prototype: 

public void piEventAppletInit(Applet theApplet)
	throws HwException;

Parameter:
theApplet Identifies the applet using the plug-in.

Description: The Hyperwire runtime calls this method when it receives an init() call from the applet player.

piEventAppletStop

Prototype: 

public void piEventAppletStop(Applet theApplet)
	throws HwException;

Parameter:
theApplet Identifies the applet using the plug-in.

Description: The Hyperwire runtime calls this method when the applet containing the plug-in is no longer visible. This is triggered by a stop() call from the applet player.

The precise behavior of piEventAppletStop() is browser specific. This is because different browsers call the stop() method at different times. See third-party Java literature for additional details.

piEventAppletDestroy

Prototype: 

public void piEventAppletDestroy(Applet theApplet)
	throws HwException;

Parameter:
theApplet Identifies the applet using the plug-in.

Description: The Hyperwire runtime calls this method when the applet is about to be destroyed. This is triggered by a destroy() call from the applet player.

If the plug-in has dynamic data structures, this method should release them.

Caution: Different browsers and applet viewers call the destroy() method at different times. In particular, Appletviewer does not destroy the applet correctly, so when you restart the applet it might not run correctly.

piEventAppletStart

Prototype: 

public void piEventAppletStart(Applet theApplet)
	throws HwException;

Parameter:
theApplet Identifies the applet using the plug-in.

Description: The Hyperwire runtime calls this method when the applet containing the plug-in becomes visible. This is triggered by a start() call from the applet player.

piTerminate

Description: Don't implement or call this method. It is for internal use, and is subject to change in a future release.

piGetRunService

Prototype: 

public BasicRunService piGetRunService();

Returns:
BasicRunService The handle to the system run service that is sent to the plug-in in the piInit() call.

Description: Don�t change the default implementation of this method. It returns the run-service handle mRunService, an instance variable inherited from the HwBasicPlugIn class.

By returning the run service instance, piGetRunService() makes the run service—input/output and other handling—available to the plug-in. Use the run-service handle to call run-service methods. For example: 

	HwObject embedded = piGetRunService() .siGetEmbeddedData();

piIsContainer

Prototype: 

public boolean piIsContainer();

Returns:
boolean true if the plug-in is a container, false otherwise.

Description: In this release of the MDK, piIsContainer() must always return false. Don�t change the default implementation of this method.

piIsVisual

Prototype: 

public boolean piIsVisual();

Returns:
boolean true if the plug-in is visual, false otherwise.

Description: Don�t change the default implementation of this method.

piEventParentMovedBy

Prototype: 

public void piEventParentMovedBy(VisualRunPlugIn aParent, int xOffset, int yOffset)
	throws HwException;

Parameters:
aParent The parent plug-in.
xOffset How far the parent moved in the X direction.
yOffset How far the parent moved in the Y direction.

Description: In most cases, only visual plug-ins that use dialog widgets from the Java abstract windows toolkit (AWT) need to implement this method.

The Hyperwire runtime calls this method when the user moves the plug-in�s parent. The plug-in should update its appearance and internal state as needed. This method is called before the plug-in�s bounding rectangle is translated by the runtime. It is primarily for plug-ins that don�t rely on the visual method piDraw() to draw themselves.

All descendant modules of the container that was moved receive this call.

Note: In this MDK release, only visual modules receive calls to piEventParentMovedBy().

piRestoreInitialRunState

Prototype: 

public void piRestoreInitialRunState()
	throws HwException;

Description: The Hyperwire runtime calls this method to reset the plug-in in the following cases:

The plug-in should reinitialize its data, as necessary.

When a reset triggers piRestoreInitialRunState(), the plug-in can assume that other modules are active. If it shares data with other modules, this method—not piInit()—is the place to transfer that data.

piEventRefreshDaemonTick

Prototype: 

public void piEventRefreshDaemonTick(long timeNow, RefreshDaemon worldMover)
	throws HwException;

Parameters:
timeNow The current tick time, in milliseconds.
worldMover The Hyperwire refresh daemon.

Description: Implement this method if your plug-in performs some timed activity—for example, playing an animation—that should be synchronized with other timed modules. The plug-in receives this call only if it has requested to be notified of timer events by calling the BasicRunService method siPlugInWantsTicks(). The Hyperwire runtime calls registered plug-ins when a refresh daemon tick occurs. The method's implementation should check the value of timeNow and do what it needs to do to synchronize itself with other modules.

See WavyPlugIn.java for an example of how to use piEventRefreshDaemonTick().

piPerformUserPort

Prototype: 

public HwObject piPerformUserPort(String portName, HwObject args[])
	throws HwException;

Returns:
HwObject A Hyperwire object.

Parameters:
portName The name of the user input port that was triggered.
args[] Data that accompanied the user-defined port.

Description: The Hyperwire runtime calls this method when a user-added input port is triggered. ("User" in this case refers to the Hyperwire author.) The default implementation of this method simply returns null. Implement this method only if you want your plug-in to perform some special handling of user-defined ports.

User ports are typically used with container modules, and plug-ins can�t be containers. However, some plug-ins have a use for user ports. For example, you might implement a plug-in that provides an exclusive switch between N different inputs, where N is the number of user ports.

piEventKeyDown

Prototype: 

public boolean piEventKeyDown(Event evt, int key)
	throws HwException;

Returns:
boolean false to allow other modules to receive this event, true to consume the event and prevent other modules from receiving it.

Parameters:
evt The handle of the key-down event.
key The value of the key that the user pressed.

Description: The plug-in receives this call only if it has requested to be notified of key events by calling the BasicRunService method siPlugInWantsKeyEvents(). The Hyperwire runtime calls this method when a key-down event occurs. If you implement this method, it should return false except under exceptional circumstances.

Note: Key events are not generated when a UI widget such as an edit field has local focus of the keyboard.

piEventKeyUp

Prototype: 

public boolean piEventKeyUp(Event evt, int key)
	throws HwException;

Returns:
boolean false to allow other modules to receive this event, true to consume the event and prevent other modules from receiving it.

Parameters:
evt The handle of the key-up event.
key The value of the key that the user released.

Description: The plug-in receives this call only if it has requested to be notified of key events by calling the BasicRunService method siPlugInWantsKeyEvents(). The Hyperwire runtime calls this method when a key-up event occurs. If you implement this method, it should return false except under exceptional circumstances.

Note: Key events are not generated when a UI widget such as an edit field has local focus of the keyboard.

piPrepareMedia

Prototype: 

public void piPrepareMedia(HwMediaTracker theTracker, int priority)

Parameters:
theTracker The media tracker object.
priority The module's drawing priority or ID.

Description: This method implements the Preload input port and the Media Loaded output port for media modules. The media tracker currently accepts only java.awt.Images. It doesn't yet support sound.

This method is called during initialization, after piInit() and before piEventAppletInit(). If you want to implement the Preload and Media Loaded ports, add the images your plug-in will use to the media tracker.

The HwMediaTracker class supports the same interface as the Java 1.0 class java.awt.MediaTracker. To add images, call theTracker.addImage(anImage, priority) for all images that don't need scaling. Call theTracker.addImage(anImage, priority, width, height) for images that need scaling.

To start loading the images you have added to the media tracker, call theTracker.checkID(priority, true). This method returns true if the images are already loaded. You can start image loading immediately after you add the images to the media tracker, or you can defer loading them (the checkID() call) to a later point in your code. If you start the load at a later time, you have to save the parameters in instance variables.

Caution: Don't change the value of priority in your calls to the media tracker. The media tracker uses this value to identify your images.

If your plug-in doesn't call theTracker.checkID() and the title doesn't use the module's Preload input port, the Media Loaded output port never fires.

piMouseDown

Prototype: 

public boolean piMouseDown(Event evt, int x, int y)
	throws HwException;

Returns:
boolean false to allow other modules to receive this event, true to consume the event and prevent other modules from receiving it.

Parameters:
evt The handle of the mouse-down event.
x The X location of the mouse.
y The Y location of the mouse.

Description: For visual modules, the Hyperwire runtime calls this method when the user depresses the mouse within the plug-in�s clickable extents. The plug-in must update its appearance and internal state as necessary.

For nonvisual modules, the Hyperwire runtime calls this method when the plug-in module has captured the mouse by calling siSetCapture().

piMouseMove

Prototype: 

public boolean piMouseMove(Event evt, int x, int y)
	throws HwException;

Returns:
boolean false to allow other modules to receive this event, true to consume the event and prevent other modules from receiving it.

Parameters:
evt The handle of the mouse-move event.
x The X location of the mouse after the move.
y The Y location of the mouse after the move.

Description: For visual modules, the Hyperwire runtime calls this method when the user moves the mouse with button up within the plug-in�s bounding rectangle. The plug-in must update its appearance and internal state as necessary.

For nonvisual modules, the Hyperwire runtime calls this method when the plug-in module has captured the mouse by calling siSetCapture().

piMouseDrag

Prototype: 

public boolean piMouseDrag(Event evt, int x, int y)
	throws HwException;

Returns:
boolean false to allow other modules to receive this event, true to consume the event and prevent other modules from receiving it.

Parameters:
evt The handle of the mouse-drag event.
x The X location of the mouse after the drag.
y The Y location of the mouse after the drag.

Description: For visual modules, the Hyperwire runtime calls this method when the user moves the mouse with button down within the plug-in�s bounding rectangle. This event occurs only if the plug-in is not movable—if the plug-in is movable, a user drag triggers a call to piEventDragTranslate() instead. The plug-in must update its appearance and internal state as necessary.

For nonvisual modules, the Hyperwire runtime calls this method when the plug-in module has captured the mouse by calling siSetCapture().

piMouseUp

Prototype: 

public boolean piMouseUp(Event evt, int x, int y)
	throws HwException;

Returns:
boolean false to allow other modules to receive this event, true to consume the event and prevent other modules from receiving it.

Parameters:
evt The handle of the mouse-up event.
x The X location of the mouse when released.
y The Y location of the mouse when released.

Description: For visual modules, the Hyperwire runtime calls this method when the user releases the mouse button within the plug-in�s clickable area. The plug-in must update its appearance and internal state as necessary.

For nonvisual modules, the Hyperwire runtime calls this method when the plug-in module has captured the mouse by calling siSetCapture().

piSetRadioState

Prototype: 

public boolean piSetRadioState(boolean state)
	throws HwException;

Returns:
boolean true if the module was previously active, false if the module was previously inactive.

Parameter:
state true tells the module it is active. false tells the module to become inactive.

Description: Implement this method if you want to have mutually exclusive, radio button modules within a single applet or container. Only one of the modules is active at a time.

When one of the plug-in modules is to become active, it calls siSetRadioNodule(). The Hyperwire runtime then sends a piSetRadioState() call to all modules in the same container. The modules receive a state of false except for the one that called siSetRadioNodule(). This ensures that only one module is active at a time.

The implementation of piSetRadioState() should check the state parameter. If state is false, the plug-in should become inactive. If state is true, the plug-in should become active. To avoid conflict, the plug-in should never become active without first calling siSetRadioNodule() and then receiving a piSetRadioState() call with state set to true.

piPrepareImage

Prototype: 

public void piPrepareImage(HwMediaTracker theTracker, int priority)
	throws HwException;

Parameters:
theTracker The media tracker object.
priority The priority of the request.

Description: Don�t call this method or override it. It is retained for backward compatibility of developmental plug-ins, and is the default implementation of piPrepareMedia(). (It was originally in the visual plug-in interface.) Use piPrepareMedia instead.

Continue to "HwVisualUserPlugIn Class"

Return to Contents