Bars & Pipes Professional: Create-a-Tool

Overview

You can create and edit your own MacroTools in the Create-A-Tool window. A MacroTool is a Tool created by combining several Tools into one. Like the Tools provided with this program, a MacroTool has one input, one output, and an icon representing it. Not only is the use of MacroTools a convenient way to keep your PipeLines from overcrowding (you can take a string of commonly used Tools and create a MacroTool to replace them), but it's a very potent method for making specialized Tools of your own design.

The Create-A-Tool Window

The Create-A-Tool window enables you to design your own MacroTools. Access the Create-A-Tool window from the ToolBox by choosing the Create MacroTool... option from the ToolBox window.

If you'd like to edit an existing MacroTool, choose the Edit MacroTool... option after you've highlighted an existing MacroTool in the ToolBox. Alternatively, you can double-click on an existing MacroTool in the ToolBox to open its Create-A-Tool window.

MacroTools: A List of Ingredients

Each MacroTool contains several important parameters:

A Unique Name

Each MacroTool has a unique name and a four-letter identifier.

For example, a Tool that creates random harmonies could be called "Split-Quant-Counterpoint" and the identifier could be "SQCP." You use the full name, "Split-Quant-Counterpoint," to describe the Tool for your reference. Bars&Pipes Professional uses the identifier, in this case "SQCP," for internal operations that require speed and compact size.

If you choose not to give an identifier a name, Bars&Pipes Professional automatically assigns one.

An Icon

Each Tool must have an icon to display in the ToolBox, PipeLine and/or ToolPad. In addition, if the Tool has a branching output and can send data two places at once, it requires two icons: one for when the Tool is above the receiving Tool (the connector is on the bottom of the Tool) and one for when the Tool is below the receiving Tool. (The connector is on the top of the Tool.)

Tools

A MacroTool consists of a collection of interconnected Tools. You arrange these Tools on a grid of PipeLines, much like the PipeLines in the Main Screen.

For example, our Split-Quant-Counterpoint MacroTool feeds notes to a Keyboard Split Tool, which sends notes below the split point to an Echo Tool. The notes at or above the split point enter the Quantize Tool, then, the CounterPoint Tool.

Input And Output

A MacroTool can have only one input; therefore, you must identify the Tool that accepts incoming notes as the input of the MacroTool. Also you must label the last Tool in the MacroTool as the output. In addition, if this MacroTool is capable of sending a branched output, you must identify the Tool that sends notes down the branch.

Tool Parameters

Some of the Tools in the MacroTool may have parameters that can be preset.

For example, you might, in your MacroTool, use a Transpose Tool that always shifts a note by a predetermined interval. This requires presetting that component Tool in your MacroTool.

Constructing Your MacroTool

To construct a MacroTool, open the Create-A-Tool window by selecting Create MacroTool from the ToolBox menu. This menu is only available from the ToolBox window. The Create-A-Tool window opens with a new, blank MacroTool, ready to assemble.

Naming Your Macro Tool

Across the top of the window are two text entry fields, Tool Name: and Tool ID:. Bars&Pipes Professional automatically supplies a default name and a unique default ID. To name your Tool, click on the Name: field and enter a description of your Tool.

Note
Changing the ID is optional.

Painting The Macro Tool Icon

On the left side of the Create-A-Tool window is a box with an enlarged icon in it. Since a Tool can have two icons, both are displayed at their normal size to the left of this box. To choose which icon is enlarged, click on one of the two.

Below the box is a Palette of eight colors. To paint the icon, select the paint color by clicking on it in the Palette and draw your icon in the box. Like any other paint program, you draw by clicking down with the mouse and dragging it. The MacroTool window displays the selected color in the tall box to the left of the Palette.

From the Paint menu, you can choose from the following commands:

Clear

Clear sets the entire icon to the color currently selected in the Palette.

Copy

Copy duplicates your MacroTool icon. Bars&Pipes Professional needs the extra icon for MacroTools that branch off to Tools above or below. Alter the duplicate so that the placement of the output Pipe inverts. If you've created a branching MacroTool, draw your main icon, then duplicate it with the Copy command and edit the position of the outgoing Pipe to go up.

Flip...

Flip... turns your icon around an axis. To flip from top to bottom, choose Flip Vertically. To flip from left to right, choose Flip Horizontally.

Start With...

Start With... provides a choice of four pre-defined icons. To select a pre-defined icon (a time-saver), drag the mouse over your icon of choice and lift up. That icon now appears in the Paint Box.

Flood Fill

Flood Fill paints an entire area of the icon with the selected color. To use the Flood Fill command, first select the fill color and the Flood Fill command. Then, with the mouse, touch the area to be painted and click the mouse. For instance, if you have a red shape you'd like to make yellow, select yellow from the Palette, select Flood Fill from the menu, then click on the center of the shape. It's now filled with yellow.

Undo

Undo reverts the icon to the state that existed prior to your most recent action.

Adding And Connecting Tools

Once you've set up your MacroTool icon, you're ready to build your MacroTools using existing Tools.

Adding

In the large box on the right half of the Create-A-Tool window sit six PipeLines. To construct your MacroTool, drag your Tools of choice from the ToolBox and place them on any one of the PipeLines. Determine which PipeLine is the input line and place the first Tool there. Continue by placing the Tools that follow it to the right of the input Tool on the PipeLine. To reposition the placement of a Tool in the PipeLine, select it by clicking on it once. A red box appears around it. Then press either the Left or Right Arrow keys to move it.

Duplicating

To duplicate a Tool already in the Create-A-Tool window, drag the Tool to a new location. Bars&Pipes Professional creates an exact copy of the Tool, including its parameter settings.

Removing

To remove a Tool, select it, then press the Delete key.

Connecting

If a Tool has a branching output, place a Merge In Tool on another PipeLine. (The Merge In icon looks like a Pipe with another Pipe feeding into it above from the left.) This second PipeLine is now active and Tools can be placed in it as well. When you first place the Merge In Tool in the second PipeLine, it may not line up with the source Tool because they have not yet been connected. To connect a Merge In Tool with another Tool, click on the source Tool (the Branching Tool,) select Connect (Right Amiga - K) from the PipeTool menu, then click on the target Tool (the Merge In Tool). The two icons are now connected and the display is redrawn with everything positioned appropriately.

If your PipeLine is long and you start running out of room, scroll it forward by using the slider and arrows at the bottom of the display. Your MacroTool can be as long as you need.

Determining The Input And Output(s)

To the right of the PipeLine grid are three arrow-shaped icons. Drag these onto your Tool layout to specify the input and output(s).

Input

The top icon, the In arrow, is a blue arrow that selects the input. Drag and place it to the left of the first Tool in your MacroTool lineup. All notes coming into the MacroTool pass through here first. You cannot delete the input arrow. If you want to send the input to a different PipeLine, drag another blue arrow to it; the arrow to your previously selected PipeLine automatically disappears.

Normal Output

The middle icon the Out arrow, is a red arrow that represents the Normal Output. Drag it to the right of the last Tool in your Macro sequence. Whatever comes out of that last Tool comes out of the MacroTool as a whole. Unlike the Input arrow, you can have more than one Normal Output per MacroTool because you can use several PipeLines in your design. The MacroTool merges notes coming out of all Normal Output icons. If you want to remove a Normal Output icon, select it, then hit the Delete key.

Branching Output

The bottom icon, the Branch arrow, is a purple arrow that represents the Branching Output. This arrow is optional. Whereas every MacroTool requires an Input and an Output, a MacroTool requires a Branching Output only when the MacroTool needs to send events off to a second PipeLine. Install the Branching arrow in the same way that you install the Output arrow.

Once you have a Branching Output, the alternate icon, on the left of the Paint Box, comes into play. This alternate icon behaves identically to the original, except that it branches off in the opposite direction. In this way, you can have a MacroTool that connects to a Tool above and to a Tool below.

Setting The Tool's Controls

Many of the Tools that constitute your MacroTool have parameters that you can preset. For example, the Triad Tool uses two Transpose Tools to shift the input note up a third and up a fifth. It is an example of a MacroTool. If you load the Triad Tool into the ToolBox and then double-click on it, Create-A-Tool shows the structure of the MacroTool. You can then open the Control window of each Transpose Tool to see its parameter settings.

As an example, you can edit the parameters to create a chord inversion by changing the second Transpose Tool from shifting up a fifth to down a fourth.

Making Macro Tools Out Of Macro Tools

Like any other Tool, you can place a MacroTool in any other MacroTool you build; however, you cannot place it inside itself. Nor can you place it within another MacroTool that is contained within it. The Create-A-Tool Editor makes sure this doesn't happen. If you drag a MacroTool into the definition of itself, it won't stay there.

Installing, Removing, Using, Altering, and Testing

Installing

Once you have created a MacroTool, you must save it to disk. If you fail to do so, the MacroTool will be deleted when you exit Bars&Pipes Professional.

To save a MacroTool, click once on the MacroTool in the ToolBox, then select the Save option from the ToolBox menu. Bars&Pipes Professional opens its file requester. Create a new file name for your Tool.

Note
If you use the name of an existing Tool, Bars&Pipes ProfessIonal overwrites the older Tool.

Bars&Pipes Professional saves your MacroTool to that file. From now on, when Bars&Pipes Professional runs, it automatically loads your MacroTool.

Removing

If you don't like what you've created, you can remove your MacroTool by clicking on it in the ToolBox and selecting the Remove option from the ToolBox menu. Bars&Pipes Professional removes the MacroTool from the ToolBox, removes all copies of it from your composition, and no longer loads this MacroTool. The MacroTool, however, is still on your disk; you can leave it there or delete it by using the Workbench or CLI (Command Line Interface.)

Using

Use your MacroTool just as you would a normal Tool. You can place it in a PipeLine to process notes in real-time, or in a ToolPad, to process notes in a section, or on a note-by-note basis.

Altering

You can always go back and edit your MacroTool. To do so, double-click on the MacroTool's icon in the ToolBox. The Create-A-Tool Window opens with your MacroTool, and you can edit it in any way you'd like. If you have already used this MacroTool, versions that are in use are not affected by editing the master. Once you are satisfied with the changes you have made, you must once again save the MacroTool to disk.

Testing

To audition a MacroTool before saving it to disk, drag the Test Tool at the bottom right of the Create-A-Tool window into a PipeLine in the Sequencer window. If you don't like the results, you can continue editing the MacroTool. The Test Tool automatically incorporates the changes, so that you can quickly edit, test, and re-edit until you're satisfied with the MacroTool.