Containment

It is not an accident that the components of a Hyperwire title are called modules. Consider what a module is. It is a self-contained piece of functionality that has inputs it can respond to and outputs it can trigger. To use a Hyperwire module, you don't need to know how it implements its functionality or what its internal code looks like. You only have to trust that it does what it is supposed to do, responds to its inputs correctly, and triggers its outputs when their associated events occur.

A Visual Container module is simply a Hyperwire module that you create yourself. There are three basic reasons for using a container:

• Organization and clarity

  The more complex your title is, the more modules and wires it has, and the more complicated Wire view becomes. Putting self-contained portions of code into containers simplifies the Wire view of the overall title, and helps clarify how your title works.

• Reusability

  Containers let you make a package of Hyperwire modules and logic that you can then reuse in various situations and in different titles.

  You can make a container into a reusable, custom module that you add to an application from the Modules menu or the Module panel, just as you do the modules provided with Hyperwire. Custom module's extend the functionality of Hyperwire titles.

• Reliability and Maintainability

  Separating the title's logic into containers can make it easier to debug and maintain your title. Once a container works the way you want it to, you don't need to worry about its logic any more.

A container in a title appears as a single module icon. You connect it to other modules by wiring its input and output ports as you do other kinds of modules.

To change the logic inside the container, first open it by clicking the Open button on the container's icon. Hyperwire opens a window to display the interior of the container. The open container window looks just like a title window (a title is in fact simply a top-level container). Edit the logic inside the container as needed, and then close the window.

    The Run Container button (or the menu choice Container/Run Container) runs the container so you can test it independently of the title as a whole.

There are two ways to create a container in Hyperwire. The following steps describe each way, with what is possibly the easier way first.

To create a container by selecting modules:

1. Select the modules you want to put into a container.

   Usually the easiest way to do this is to drag a selection box in Wire view.

   Wires that connect selected modules become part of the selection. A wire that connects a selected module to an unselected module does not become part of the selection, but Hyperwire creates a custom input or output port for that wire, so the connection between modules is not lost.

2. Choose Selection/Assemble Into Container.

   Hyperwire creates a Visual Container module and places the selected modules and wires inside it.

   If there are connections to unselected modules, Hyperwire creates custom ports for the container so the connections between modules are not lost.

3. Change the container's label to describe what it does.

4. If needed, create input and output ports for the container and wire these ports to modules in the container.

   To wire modules in a container to the container's ports, first open the container and then wire the modules to the container ports whose buttons appear along the lower edge of the open container window.

   After the wire is connected, the port appears in the Wire view of the open container as a "floating" input or output port icon.

To create a container by filling an empty container:

1. Add a Visual Container module to the title by choosing Modules/Visual Container or dragging a Visual Container module from the toolbar.

2. Change the container's label to describe what it does.

3. Open the container and create the modules inside it.
4. As needed, create input and output ports for the container and wire these ports to modules in the container.

   To wire modules in a container to the container's ports, first open the container and then wire the modules to the container ports whose buttons appear along the lower edge of the open container window.

   After the wire is connected, the port appears in the Wire view of the open container as a "floating" input or output port icon.

Exercise 7 demonstrates how to create a container "from scratch," by adding it to the title and then placing modules inside it.

You don't actually have to use a container to create a custom module, but if the custom module requires custom ports, a container is the most straightforward way to do this, as the steps below indicate.

To create a custom module:

1. Optional: Create the module as a container with custom ports.

   This container will become the custom module.

2. Select the code to put into the custom module.

   If you created a container, all you have to do is select the closed container.

3. Choose File/Save Selected, and save to the \Hyperwire\Modules\ directory or a subdirectory of it.

   Hyperwire saves the selected code as a .Ttl file.

   If you saved a container, you are now ready to add the module to the Hyperwire interface and begin using it.

   If you saved a collection of selected modules and wires, you must open the new title file in Hyperwire, and add custom ports to it as necessary, then save it again before you proceed to the next step.

4. Choose File/Rebuild Modules Menu.

   This adds the new module to the Hyperwire Modules menu and the Module panel.

5. Optional. Use a bitmap editor to create icons for the module. Double-click the module in the Module panel, and specify the icons in the Module Registration Properties dialog.

   This dialog also lets you enter comments and version information about the module, and identify yourself as the module's author.