Hyperwire Module Development Kit (MDK) —Writing Hyperwire Modules in Java
Hyperwire Module Development Kit (MDK) —
The Hangman module in the Xtras folder is an example of a plug-in module created with Java. You can find the Java source for Hangman and other MDK examples in the file \Hyperwire\Classes\kinetix\hyperc1\userPlugIns.
As with regular Hyperwire modules, a plug-in module can be a nonvisual module that does processing. Or it can also have a visual component that appears in the Layout view and displays graphic images, has a graphical user interface, or both. A plug-in module can be a subclass of one of the standard Hyperwire module types.
To use the MDK, you should be familiar with Hyperwire. You should also be familiar with using Java to develop applets. To develop a Hyperwire plug-in module, a Java development environment such as Microsoft J++ or Symantec CAFE can be helpful.
Caution: If you use the Java Development Kit (JDK) that is available over the
Web from Sun Microsystems, or another Java development product, you might encounter
path conflicts between the Java compiler and interpreter provided with Hyperwire,
and those of the other product. To resolve conflicts, check the DOS autoexec.bat variables
PATH and CLASSPATH.
Hyperwire has its own runtime class library that communicates between an applet player and the Hyperwire modules, including plug-in modules. This runtime includes two interfaces with service methods that are available to the plug-in module for communicating with other modules via input and output ports, for handling the visual interface, and so on.
Tip: For miscellaneous methods that can be useful to an author in various situations, create a "miscellaneous" plug-in module to contain them.
Note: You can also create plug-in modules by using Hyperwire itself. Creating plug-in, custom modules with Hyperwire is described in the online Help topic "Creating Custom Modules," under "Examples."
At the very least, a plug-in module must subclass the
HwBasicUserPlugIn
class, whose methods handle communication between the plug-in module and the Hyperwire
runtime class library.
If the plug-in module is a visual plug-in, it must subclass
HwVisualUserPlugIn,
an extension of the basic class to support the visual interface.
By convention, the plug-in code file has the name of the module itself,
though this is not required.
For example:
import kinetix.hyperc1.runtime.*; . . . public class YoYoPlugIn extends HwVisualUserPlugInThe plug-in code should be in a Java package. It can reference any number of additional classes, either in the same package or in other packages.
Tip: If you want your Hyperwire applet to run with older browsers (for example, with pre-3.0 versions of Netscape Navigator or Internet Explorer), keep the number of classes to a minimum. In the older browsers, the Java class loader establishes a separate connection for each .class file. Typically, a connection is an HTTP connection—each connection can take from half a second to as long as 20 seconds to establish. (More current browsers establish a connection for an entire package or for a ZIP or CAB file, improving performance considerably.)
The MDF (.mdf) file (Module Definition File) is an ASCII file that describes the plug-in module and how it appears in the Hyperwire interface. You must create the MDF file, and then register the plug-in module with Hyperwire. After you register the plug-in module, it appears in the Hyperwire window as other modules do.
Small icons appear in the Modules pull-down menu and the Modules window. A large icon appears when the plug-in module is in the Wire view. These icons are Windows bitmap (.bmp) files.
For visual modules, you can also specify a bitmap that represents the module in the Layout view. The MDF entry kxDrawImage specifies this bitmap.
You might want to put all the icons, images, and dialog templates used
by your plug-in module in a single resource DLL.
You can also embed icons in the module's MDF file, using the keyword
kxEmbeddedType, as described below
kxLargeIcon and the
other icon descriptions.
In addition, you can group plug-in modules into a folder—a sub-menu—on the Modules pull-down menu. This folder can have a .bmp icon of its own. Place the .bmp file in the same directory as the other icons (see the following section), and give it the same name as the directory itself. This causes Hyperwire to display the icon on the pull-down menu.
Plug-in modules can use dynamically linked libraries (DLLs). For example, putting all a visual plug-in's images in a resource DLL improves performance and helps manage the plug-in components.
Documentation for the plug-in module can be an HTML file that the author using Hyperwire can display by using the plug-in�s Module Registration Properties dialog. You specify the URL for this file in the MDF file. See the MDF entry kxHelpDoc.
Be sure to place each kind of component in the proper location, so Hyperwire can locate it.
The plug-in module class (.class file) must be beneath the \Hyperwire\Classes directory. Create a single-vendor subdirectory (a package) for all your plug-ins. Create additional subdirectories to further organize your plug-ins; for example, \Hyperwire\Classes\yoyodyne\yoyo\.
The plug-in module's MDF file must be beneath the \Hyperwire\Modules directory. Create a single subdirectory with your corporate name. This directory can contain any number of MDF files, and subdirectories for further organization. The Modules pull-down menu lists modules in alphabetical order of the MDF filename; the menu displays the name string contained in the MDF file. You might want to begin each MDF filename with a sequence number to control the ordering, for example, 01yoyo.mdf, 02top.mdf, 03whistle.mdf, and so on.
Incidentally, custom modules created by an author using Hyperwire are also saved in subdirectories of \Hyperwire\Modules.
Place the small and large icons in a subdirectory of the \Hyperwire root directory. Group them by vendor, for example, \Hyperwire\Yoyodyne\.
An icon used for a Modules menu folder must have the same name as the subdirectory itself. This name is case sensitive. For example, if the subdirectory is called \Toys, the folder icon must be Toys.bmp. Hyperwire creates a folder labeled Toys on the Modules pull-down menu and uses the Toys.bmp image to represent the folder.
The folder icon should be 16 x 16 pixels with 4-bit color (16 colors).
Hyperwire treats areas of pure magenta (0xff00ff) as transparent.
Place DLLs in a child directory of the \Hyperwire root directory, like icons. This should be the same directory you use for icons; for example, \Hyperwire\Yoyodyne\.
If you document the plug-in module in HTML, include the URL of the document in the plug-in�s MDF file. This way, the user can view the document by using the plug-in�s Module Definition Properties dialog.
If you ship the document with the software, place it in your subdirectory of \Hyperwire; for example, \Hyperwire\Yoyodyne\. Make the URL a relative one that names this directory.
You also have the option of placing the document on a Web server. This lets you update the document at any time, but the user must be connected to the Web to read the document. Make the URL an absolute one that identifies the Web location.
To register a plug-in module:
If you installed the plug-in module correctly, its name and icon appear in the Modules pull-down menu and the Modules window. Authors using Hyperwire can now use the plug-in module.
If Hyperwire encounters an error in the MDF file, or can't find a plug-in component, it displays a message to that effect and doesn't register the module.
Note: Exiting and restarting Hyperwire will also register your plug-in module, provided you installed it correctly.
When an author uses the Hyperwire Run command to compile and run a title that includes plug-in modules, Hyperwire can detect compilation errors in the title's main class but not in the plug-in classes. Normally a compilation error displays an alert dialog that lets the author choose between cancelling the run or proceeding to run the title anyway. Since plug-in errors aren't detected, the title runs even if the plug-in contains bugs. In this case, the title behaves erratically. If this happens, look at the Java Console window for a complete listing of the compiler's output, including error messages.
A plug-in module has a small icon and a large icon. The two versions of these are a 16-color (4-bit color) icon and an optional truecolor (24-bit color) icon. The 16-color icon is the default, but Hyperwire will use the truecolor version if the display is capable of it.
Both versions of the small icon must be 16 pixels square (16x16). Both versions of the large icon must be 32 pixels square (32x32).
In the MDF file, you can specify a transparent color for the icon. Bits that have this color show through to the default background gray of the Modules pull-down menu and the Modules window.
The icon for a folder in the Modules pull-down menu does not have an MDF file entry because it is not specific to a single module. This icon should be 16 x 16 pixels with 4-bit color (16 colors). Hyperwire always uses pure magenta (in hexadecimal values, red = ff, green = 00, blue = ff) as the transparent color for this icon.