MDF File Format


The Module Definition File (MDF) describes how the plug-in module appears in the Hyperwire interface, and describes various resources that the plug-in uses. The MDF file is an ASCII file. The filename extension for MDF files is .mdf.

Tip: The Visual C++ editor is convenient for editing MDF files.

To create an MDF file, you can copy an existing MDF file for a similar plug-in, and then edit it to describe your plug-in. You can find sample MDF files in the directory \Hyperwire\Modules\Xtras\Samples\.

MDF File Entries

Some MDF file entries are single items. Others list multiple items. Multiple items are structured in Java-style block format. That is, blocks begin with an open brace ({) and end with a close brace (}), and they can be nested. The MDF parser is line-oriented, so open and close braces must be on their own lines. You can't enter a block on a single line.

Some entries are an exception to the block format and simply consist of multiple strings or identifiers, separated by spaces.

In general, order is not significant in the MDF file, except that the opening two lines must always be the same, and some blocks organize items into hierarchies that reflect the organization of the Hyperwire user interface.

You can include comments by preceding them on a line with two slashes (//).

The Sample.mdf file shows the appearance and structure of an MDF file. You can edit a copy of it to create an MDF file of your own.

MDF file keyword Description
kxKinetix The first line of an MDF file.
kxType The plug-in type. Should always equal kxRedJavaPlugIn.

Example: kxType = kxRedJavaPlugIn

kxModuleDefinition Begins a block that contains the remaining MDF description. The keyword kxModuleDefinition should be followed by a unique identifier for this class. (Usually it is the same as the name of the main plug-in class.)

Example:

kxModuleDefinition MapPlugIn = 
	{
		.
		.
		.
	}
	
kxPublicName A string that gives the name of the module as it appears in the user interface—on the Modules pull-down menu, on the Module panel, in the Wire view, and so on.

Example: kxPublicName = "Map"

kxVersion The version of the plug-in. Its value can be either a numeric value or a string. At present, Hyperwire does not do any version checking that uses this value, but it does display the value in the Module Definition Properties dialog. (You view this dialog by double-clicking a module in the Module panel.)

Examples:

kxVersion = 1.0
kxVersion = "beta2"
kxCreationTime A string with the time the plug-in was created. At present, Hyperwire doesn't use this value.

Example: kxCreationTime = "08/01/96 12:19:00 AM"

kxAuthor A string with the name of the plug-in�s creator.

Example: kxAuthor = "Amalgamated YoYoDyne PlugIns, Inc."

kxShortDescription A one-line description of the plug-in�s purpose.

Example: kxShortDescription = "Plots region maps."

kxLargeIcon Specifies the large (32x32 pixels) 16-color icon.
kxSmallIcon Specifies the small (16x16 pixels) 16-color icon.
kxLargeIcon24 Specifies the large 24-bit color icon. (Optional.)
kxSmallIcon24 Specifies the small 24-bit color icon. (Optional.)
Each icon descriptor consists of one to four entries, in sequence:
  1. The keyword kxBmFileType if the icon is a standalone bitmap file, the keyword kxBmResType if the icon is in a resource DLL, or the keyword kxBmEmbeddedType if the image is embedded in the MDF file.

  2. A string with the name of the bitmap or DLL file, or for an embedded image, a hexadecimal string that is the image itself, in DIB format.

    The easiest way to create these hex strings is to use Hyperwire. In the Module Definition Properties dialog, go to the icons panel and click Change Image for the icon you want to embed. In the subdialog, turn on the check box Embed Image In Module. When you click OK to accept this change, Hyperwire embeds the DIB string in the MDF file.

    Caution: Windows NT 4.0 allows DIB files of 16 and 32 bits per pixel, but Windows 95 and NT 3.51 allow only DIB files of 8 and 24 bits per pixel. If you use NT 4.0 to embed a 16-bit or 32-bit icon, the icon cannot display in Windows 95 or Windows NT 3.51. If it detects a DIB string it can't display, Hyperwire displays the default plug-in icon instead.

  3. If the icon is in a DLL file, this entry is a string with the name of the icon. If the icon is a bitmap file or is embedded, omit this entry.

  4. An optional hexadecimal value that specifies the icon�s transparent color.

    This is in Java-style hex format; schematically it is 0xRRGGBB. For example, 0x00000 is black and 0xffffff is white; pure red is 0xff0000, and so on. If you don�t specify a transparent color, the icon is opaque.

If you don�t have an icon for the plug-in, use the keyword kxNone so Hyperwire doesn�t try to display one.

Examples:

kxSmallIcon = kxBmResType "MdIcons.dll" "SM01"
kxLargeIcon24 = kxBmFileType "Fan.bmp"
kxSmallIcon24 = kxBmResType "MdIcons.dll" "SM02" 0xffffff
kxSmallIcon = kxBmEmbeddedType "ff0012bc ... ff80"
kxLargeIcon24 = kxNone	// No icon in 24-bit color
	
kxSmallTalkProxyClass The corresponding Smalltalk class (Hyperwire is implemented in Smalltalk). The value must equal either RedBasicProxy for a basic plug-in or RedVisualProxy for a visual plug-in.

Example: kxSmallTalkProxyClass = RedVisualProxy

kxPlugInPackage The name of the Java package that contains the plug-in�s Java code.

Example: kxPlugInPackage = "YoYoDyne"

kxHelpDoc A string with the URL of an HTML document that describes the plug-in.

Examples:

// Below the \Hyperwire root directory:
kxHelpDoc = "yoyo.html"

// On a Web server:
kxHelpDoc = "http://yoyodyne.com/yoyo.html"
kxPlugInClass The name of the main Java class that implements the plug-in. (This is a subclass of HwBasicUserPlugIn or HwVisualUserPlugIn.)

Example: kxPlugInClass = MapPlugIn

kxSize For visual plug-ins, the default size in the Layout view. The plug-in�s size can be fixed (see the next entry), in which case this size never changes. This is a Point value.

Example: kxSize = Point(200, 200)

kxIsFixedSize Whether or not the user can resize the plug-in in the Layout view. This is a boolean value.

Example: kxIsFixedSize = false

kxLayoutViewProxyClass The Hyperwire class that draws the Layout view representation for the plug-in. For a visual plug-in module you create yourself, set this to AuthorRepresentation. For a basic plug-in, you can omit this entry (if present in an MDF file for a basic plug-in, this line is ignored). For a subclass of a Hyperwire module, don't change the original setting of this entry.

Example: kxLayoutViewProxyClass = AuthorRepresentation

kxDrawImage For visual plug-ins, an image to draw in the Layout view. This is an image descriptor such as those used for icons.

Examples:

kxDrawImage = kxBmResType "MapPI.dll" "SFO"
kxDrawImage = kxBmFileType "Mona.bmp"
kxDrawImageIsStretched For visual plug-ins, whether an image is stretched to fit the plug-in size in the Layout view. This is a boolean value. If true, the image is stretched. If false, the image is tiled.

Example: kxDrawImageIsStretched = true

kxDrawImageIsLabelled For visual plug-ins, whether the plug-in�s label appears in its rectangle in the Layout view. This is a boolean value.

Example: kxDrawImageIsLabelled = false

kxDrawImageHasBorder For visual plug-ins, whether the plug-in appears with a border in the Layout view. This is a boolean value.

Example: kxDrawImageHasBorder = false

kxFlags Sets the kxEmbeddedWindow option. This entry must be present if the plug-in is to appear in its own child window rather than in the main applet window. The window is always drawn on top, and doesn�t use piDraw().

Note: If you look at the MDF files of native Hyperwire modules, you might notice kxFlags set to kxSystem. Don't use this option. It is meant for native Hyperwire modules only.

Example: kxFlags = kxEmbeddedWindow

kxPropertyEditors A list of names of the Hyperwire classes that handle properties. Each class corresponds to a tab in the plug-in�s Properties dialog. If the class name is present, that tab and its capabilities appear when the author sets module properties.

These are the possibilities for MDK plug-ins:

RedFieldsEditor
Edits module-specific property fields. For consistency with other modules' Properties dialogs in the Hyperwire interface, always include this editor as the first in the list, even if the module has no module-specific properties.

OpusLabelCommentEditor
Add a comment or change the label of the plug-in module. Should always be present.

ModuleStateEditor
Properties of a visual module. Include if the plug-in is visual, omit if it is a basic plug-in.

SizePositionEditor
Size and position of a visual module. Include if the plug-in is visual, omit if it is a basic plug-in.

SpecialEffectsEditor
Specifies transitions for visual modules. Include if the plug-in is visual, omit if it is a basic plug-in.

PortEditor
Lets the user (author) add or remove user ports. Should always be present.
Note: The tab for the color editor is not available to plug-in modules. If you want the user to set color values as a module property, use a module-specific property field and the RedFieldsEditor for this purpose.

Example:

kxPropertyEditors = RedFieldsEditor OpusLabelCommentEditor
   ModuleStateEditor SizePositionEditor
   SpecialEffectsEditor PortEditor
kxPersistentFields This is a block that specifies the plug-in�s persistent module-specific property fields. Each field is itself a sub-block with entries to define the data field�s type, the Java method that sets it, its label in the module-specific panel of the Properties dialog, and its default value.

The fields appear in the module-specific tab of the Properties dialog in the same order they appear in the kxPersistentFields block.

For the field to appear in the module's Properties dialog, RedFieldEditor must be present in the kxPropertyEditors list.

Example:

kxPersistentFields =
   {
      kxField Speed =
         {
            kxPublicName = "My Speed"
            kxJavaSignature = "I"
            kxAccessor = fiSetSpeed
            kxDescription = "Velocity Factor"
            kxDefault = 1
         }
      .
      .
      .
   }
kxField Sub-entry of kxPersistentFields. Begins a block that defines a field�s properties. The keyword kxField is followed by the name of the data field, which must be a single identifier (no spaces).

Example:

kxField Speed =
	{
		.
		.
		.
	}
	
kxPublicName Sub-entry of kxField. The label of the field as it appears in the module-specific panel of the plug-in module's Properties dialog.

Example: kxPublicName = "Velocity"

kxJavaSignature Sub-entry of kxField. The field�s data type, expressed as a string in Java field signature format, as defined in The Java Virtual Machine Specification by Sun Microsystems. The alternatives are as follows:
"B"
Signed byte
"C"
Character
"D"
Double-precision floating-point value
"F"
Single-precision floating-point value
"I"
Integer
"J"
Long integer
"L<classname>;"
An object of the class identified by <classname>
"S"
Signed short integer
"Z"
Boolean
Examples:
kxJavaSignature = "F"
kxJavaSignature = "LURL;"
	
kxAccessor Sub-entry of kxField. The method in the plug-in that sets this field.

Example: kxAccessor = fiSetCounter

kxDescription Sub-entry of kxField. A string with the label of the field. The label appears in the module-specific panel of the plug-in module's Properties dialog.

Example: kxDescription = "Count"

kxDefault Sub-entry of kxField. The field�s default value. The value appears within the field in the module-specific panel of the plug-in module's Properties dialog. The module uses this value unless the Hyperwire author changes it.

The default value must be of the data type specified in the field's kxJavaSignature entry.

Examples:

kxDefault = 10.0
kxDefault = Point(10, 20)
kxDefault = "a string"
kxDefault = Rectangle( 0, 0, 100, 200 )
kxDefault = URL("http://www.yoyodyne.com/help.htm")
	
kxInputPorts This is a block that specifies the plug-in�s input ports. Each port is itself a sub-block with entries to define the port�s method, the data signature of its parameters, and the labels associated with it in the Hyperwire interface.

A different block, kxInputPortsMenu, specifies the Input Ports pop-up menu for the plug-in module.

Example:

kxInputPorts =
   {
   // Include the basic input ports:
   kxInclude "Basic.ipt"
   kxPort = GetPlugIn =
      {
         kxJavaMethod = wiGetPlugIn
         kxJavaSignature = "()LObject;"
         kxPublicNames = "Get Map" "Map"
      }
      .
      .
      .
}
kxInclude An include directive for MDF files, most often used as a sub-entry of kxInputPorts and kxOutputPorts to include an additional port file in a ports block, and to include the corresponding menus in kxInputPortsMenu and kxOutputPortsMenu. For input ports, this should be set to the string "Basic.ipt". The Basic.ipt file is the basic, default input port specifier for Hyperwire modules. It resides in the \Hyperwire\Modules directory. You can create .ipt files for use by several plug-ins in common by placing them in this directory as well.

The same kxInputPorts block can contain multiple kxInclude entries.

Example: kxInclude "Basic.ipt"

kxPort Sub-entry of kxInputPorts. Begins a block that defines a port. The keyword kxPort is followed by the name of the port, which must be a single identifier (no spaces).

Example:

kxPort StartZoomIn =
   {
      kxJavaMethod = wiStartZoomIn
      kxJavaSignature = "()V"
      kxPublicNames = "Start Zooming In" "None"
   }
kxJavaMethod Sub-entry of kxPort. The method in the plug-in that handles this input port.

Example: kxJavaMethod = wiGetLength

kxJavaSignature Sub-entry of kxPort. The method�s signature, expressed as a string in Java method signature format, as defined in The Java Virtual Machine Specification by Sun Microsystems. A method signature has the format
(<arguments_signature>)<return_signature>
where <arguments_signature> specifies zero or more arguments in the Java field signature format. The <return_signature> is either a single signature, also in field signature format, or the letter V to indicate that the method is void and returns no value.

A field signature can be one of the following:

"B"
Signed byte
"C"
Character
"D"
Double-precision floating-point value
"F"
Single-precision floating-point value
"I"
Integer
"J"
Long integer
"L<classname>;"
An object of the class identified by <classname>
"S"
Signed short integer
"Z"
Boolean
"[<optional_size><field_signature>"
Array
Note: "V" for void is valid for the return value only, not for parameters.

Examples:

// No arguments or return value:
kxJavaSignature = "()V"

// Takes two integers, returns a point object:
kxJavaSignature = "(II)LPoint;"

// No arguments, returns a boolean:
kxJavaSignature = "()Z"

// Takes a five-element array of integers,
// has no return value:
kxJavaSignature = "([5I)V"
kxPublicNames Sub-entry of kxPort. The labels for the port and its arguments that are used in the Hyperwire interface. This entry should specify two or more strings, separated by spaces.
  • The first string is the name of the port as it appears on the Input Ports pop-up menu.

  • The last string is the name of the port�s return value.

    By convention, ports labeled "Get" should have a return value. For a port without a return value, set this string to "None."

  • The intervening strings are the names of the input port�s wire parameters. They correspond to the parameters specified in the Java signature.

    These names appear in the Wire editor.

Examples:
kxPublicNames = "Get Map" "Map"
kxPublicNames = "Start Zooming Out" "None"
kxPublicNames = "Set Point" "Point" "None"
	
kxInputPortsMenu This is a block that specifies the order and layout of the plug-in�s Input Ports pop-up menu. Each port is identified by its name, as specified in the kxPort entry of the kxInputPorts block.

Three special identifiers control menu layout. The identifier kxSeparator draws a separating line in the menu, the identifier kxBreak begins a new column in the menu, and the identifier kxMenu creates a submenu.

Example:

kxInputPortsMenu =
   {
      Reset
      kxSeparator
      GetPlugIn
      kxSeparator
      StartZoomIn
      StartZoomOut
      StopZoom
      kxMenu "More" =
         {
            kxInclude "Basic.imn"
         }
   }
kxSeparator Sub-entry of kxInputPortsMenu and kxOutputPortsMenu. Draws a line in the pop-up menu.
kxBreak Sub-entry of kxInputPortsMenu and kxOutputPortsMenu. Begins a new column in the pop-up menu.
kxMenu Sub-entry of kxInputPortsMenu and kxOutputPortsMenu. Introduces a submenu, grouped as a block. The keyword kxMenu should be followed by a string that is the submenu�s entry in the menu.

Example:

kxMenu "More" =
   {
      kxInclude "Basic.imn"
   }
kxInclude An include directive for MDF files, most often used as a sub-entry of kxInputPorts and kxOutputPorts to include an additional port file in a ports block, and to include the corresponding menus in kxInputPortsMenu and kxOutputPortsMenu. For the input ports menu, set this to the string "Basic.imn". This file defines the menu that corresponds to the input port file Basic.ipt. The file Basic.imn is the basic, default input port menu for Hyperwire modules. Like Basic.ipt, it resides in the \Hyperwire\Modules directory.

Example: kxInclude "Basic.imn"

kxOutputPorts This is a block that specifies the plug-in module�s output ports. The format is the same as for input ports except that an output port does not have a method entry (kxJavaMethod) in the MDF file.

The default, common output ports specifier is in the file \Hyperwire\Modules\Basic.opt.

Example:

kxOutputPorts =
{
   kxInclude "Basic.opt"
   kxPort ItsAMatch =
      {
         kxJavaSignature = "(LString;I)V
         kxPublicNames = "It's a Match!" "Position" "None"
      }

   kxPort ItsAMiss =
      {
         kxJavaSignature = "()V"
         kxPublicNames = "It's a Miss!" "None"
      }

   kxPort YouWin =
      {
         kxJavaSignature = "()V"
         kxPublicNames = "You Win!" "None"
      }

   kxPort YouLose =
      {
         kxJavaSignature = "()V"
         kxPublicNames = "You Lose!" "None"
      }
}
	
kxOutputPortsMenu This is a block that specifies the order and layout of the plug-in module�s Output Ports pop-up menu. The format is the same as for the Input Ports pop-up menu.

The default, common output ports menu is in the file \Hyperwire\Modules\Basic.omn.

Example:

kxOutputPortsMenu =
   {
      ItsAMatch
      ItsAMiss
      YouWin
      YouLose
      kxMenu "More" =
         {
            kxInclude "Basic.omn"
         }
   }
	
kxPlugInClassesInLibrary A boolean value. If true (the default), the classes that make up the plug-in are assumed to be in a class library (a CAB or JAR file), and are not published with the title. If false, the classes are published with the title.

Example: kxPlugInClassesInLibrary = true

kxPublishClasses A list of the classes used by this plug-in. These classes will be published lin a title's CAB, JAR, and ZIP files.

Include this list even if kxPlugInClassesInLibrary = true, because the classes must still be published in a ZIP file for use by older versions of Navigator, which don't support libraries.

You don't need to name the main plug-in class (specified with kxPlugInClass); this is implicitly included. Also, if a class name does not have a package specifier, the package is assumed to be the class named by kxPlugInClass.

Example:

	
kxPublishClasses = GameConstants Joystick
   Point316
	
kxPublishCABs A list of user-library CAB files that the plug-in requires. Each CAB library is specified by three consecutive strings, as follows:
  1. The filename of the CAB file, relative to the \Hyperwire root directory.
  2. The CAB library version, in the format "w,x,y,z".
  3. The class ID of the CAB file.

See the Microsoft CAB file documentation for more information about CAB file descriptors and the latter two strings.

Continue to "HwBasicUserPlugIn Class"

Return to Contents