ProjectMIDI, Part 2: Creating a Custom ProjectMIDI Assembly

Introduction

In my first article about ProjectMIDI, I described its basic architecture and operation. One of the strengths of ProjectMIDI is the ease with which it can be extended. In this article, I'm going to demonstrate how this is done. I'm assuming that you have already read the first ProjectMIDI article, and will be building upon the information in that article.

In this article, I will sequentially step through the process that I used to create the SampleAssembly code. The finished code is already a part of the original package. You can choose to recreate the file, or simply follow along in the source code as we go.

Quick Start

The code that I created in writing this article has already been added to the original article's download packages. Please download the code from the original article or from the ProjectMIDI website.

Background

In the first article, we learned that one of the primary objectives of ProjectMIDI is that it be easily extensible. I want to be able to quickly and easily create simple little applets to control various aspects of my MIDI equipment. In this article, I am going to show how easy it is to do this by walking you through the steps to creating the SampleAssembly code.

Create the New ProjectMIDI Assembly

OK, so here we go. The first step will be to create the basic .NET assembly, and then add the ProjectMidi interfaces to it. There are several ways that I can think of to do this. Maybe, in the future, I will create a Visual Studio Wizard to do this, but for now, we are stuck with doing it manually. The approach that I normally use is:

Use the Visual Studio IDE to create a new Class Library project and add it to the existing ProjectMIDI solution.

Cut and paste the required interface code from an existing assembly to the new assembly. TraceWindow is a good source for doing this, since it is a very simple assembly.

So, let's create a new assembly, and add it to the existing ProjectMIDI solution.

Download and install the ProjectMIDI source code.

Be sure to include Source code during installation.

Open the ProjectMidiAll solution in Visual Studio .NET.

Add a new project to the solution.

Right-click on Solution ProjectMidiAll in the Solution Explorer, and select Add -> New Project.

Select the Class Library template under Visual C# Projects.

Select a name for the new assembly. In this case, I am creating the SampleAssembly assembly. Give your assembly a new, unique name.

Select OK.

A new project will be created and added to the solution. The new .CS file should now be displayed in the IDE.

Change the default class1 name.

Unfortunately, the file that the IDE creates is named "class1.cs" instead of something more meaningful like "SampleAssembly.cs". To fix this, right click on the class1.cs file name in the Solution Explorer and select Rename to give it the name of your new assembly.

Likewise, edit the new file to change every occurrence of Class1 to match the name of your assembly.

In this case, I change every occurrence of Class1 to SampleAssembly.

OK, so now, we have a new assembly added to our ProjectMIDI solution. It should look something like this:

This isn't a ProjectMIDI assembly. As described in the first article, all ProjectMIDI assemblies need to derive from and implement the IProjectMidi interface. So, let's do that now.

Implementing the IProjectMidi Interface

To make cut-and-paste easier, I've opened up the TraceWindow.cs file in the IDE along with the new SampleAssembly.cs file. This way, I can easily switch back and forth between them.

If your new assembly is not going to implement a user interface, then things are a bit simpler, and you need only derive your class from IProjectMidi directly. Since SampleAssembly is going to implement a window, it needs to derive from both the System.Windows.Form.Form class as well as the IProjectMidi interface (or a derivative of it).

Add the appropriate using lines.

Copy the using ProjectMidiNS line. This will give us access to the ProjectMIDI namespace.

Copy the using System.Windows.Forms and using System.Drawing lines, if your assembly implements a user interface window.

Add references for each using statement copied in the step above.

Right-click on References for the new project in the Solution Explorer, and select Add Reference.

Select ProjectMidiInterfaces under the Projects tab for the using ProjectMidiNS reference.

Select System.Windows.Forms.dll under the .NET tab for the using System.Windows.Forms reference.

Select System.Drawing.dll under the .NET tab for the using System.Drawing reference.

Give your class a ProjectMidiAssemblyAttribute.

Copy the ProjectMidiAssemblyAttribute line to the line before your class statement. Change the name specified to match the name of your assembly. ProjectMIDI will use this name in its Assemblies list in the icon menu.

Derive your class from System.Windows.Forms.Form and IProjectMidi.

Copy the text to the right of publicclass TraceWindow and paste it to the right of your class name. Note, in this case, the interface is not IProjectMidi but instead IProjectMidiHideShow. This is an interface which derives from IProjectMidi, and adds a method to allow ProjectMIDI to hide and show this assembly's window via the status tray icon menu.

Copy the ProjectMidiParent property code

The ProjectMidiParent property is used to allow ProjectMidi to pass a back pointer to each assembly. This back pointer gives each assembly access to several useful properties and methods provided by the ProjectMidi core executable.

Copy the projectMidiParent member variable.

This variable is used by the ProjectMidiParent property copied in the step above.

Copy the PerformStartProcessing method code.

This method is called at strategic points during the ProjectMidi start up.

Copy the IProjectMidiHideShow members section.

The ProjectMidi core executable calls this method to toggle the visible state of each assembly.

At this point, your code should look like this, and should compile without errors:

At this point, we now have a working ProjectMidi assembly. It doesn't really do anything but display a blank window. There is some functionality provided by the core ProjectMidi executable, however:

The window's size and position will be saved and restored between sessions.

The window's name will be displayed in the system tray icon menu's Assemblies menu.

Selecting this will alternately hide and show the window.

Note that the assembly needs to be copied to ProjectMidi's Assemblies folder in order for it to be run. The easiest way to do this is to modify the new project's properties to create the assembly DLL in the runtime assemblies folder.

Right-click on the new project in the Solution Explorer.

Select Properties

Select Build under Configuration Properties.

Change the Output Path to ..\Runtime\Assemblies.

This assumes that you created your project at the same directory as the other ProjectMidi projects.

Now, when you build your project, it will automatically be placed into the runtime folder.

This is probably also a good time to change the properties for the ProjectMidiInterfaces reference. Visual Studio .NET will have set the Copy Local setting to True, by default. This will result in a copy of the ProjectMidiInterfaces.dll to be copied to the output directory each time you build the code. Before changing the output directory, this wasn't a problem. Now, however, it is going to put a copy of that DLL into the RunTime\Assemblies directory, which is not what we want. To change this:

Select ProjectMidiInterfaces under the References section in the Solution Explorer.

Change the Copy Local setting from True to False.

Test Run the New Blank Assembly

OK, let's give the code a test run to ensure that everything that we have done so far is working. Here're some things to check before proceeding:

Delete previous ProjectMidi registry settings.

If you have previously installed and/or run ProjectMidi, then it will have set the FoldersPath registry setting. This may be pointing to a directory other than where you are now putting your newly built assemblies. You can either change this setting, or delete it or all of the ProjectMidi settings from the Registry altogether. To do this, launch RegEdit (Start -> Run -> RedEdit) and locate the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\ProjectMidi\FoldersPath

This key needs to point to the parent folder where your Assemblies folder is located. If it doesn't, then you will need to change or delete it.

Ensure that you are working in the ProjectMidi solution.

You can't directly execute a ProjectMidi assembly. You need to build the assembly and copy it to the Assemblies folder, as described above. Then, you need to launch ProjectMidi.exe. ProjectMidi.exe will, in turn, load and execute the assembly.

Observe that the following behaviors are working:

Your new assembly's window is displayed.

The name of your assembly now appears in the icon menu Assemblies menu.

Using this menu item, you can hide or restore your window.

ProjectMidi will save and restore your window's size and position.

If you move and then close the window, upon restoring it later, it will appear at the same location and size.

By convention, I set the ShowInTaskbar setting of each ProjectMidi assembly form to false. I do this because there tend to be a lot of ProjectMidi windows showing, and I don't like cluttering up the task bar. You can set this parameter from the form's properties. These are displayed while viewing the form in the View Designer.

I also assign my standard ProjectMidi.ico icon to each window's Icon property. Maybe, someday, I'll get creative and give each window a unique icon.

Add Functionality

OK, now we get to start having some fun. Up until now, we have just been creating boiler-plate code. Now, we'll start adding real functionality.

Note: I realize that the above boiler-plate code could have been automatically created by a Visual Studio Wizard plug-in or something along those lines. That is a project that I'll put off for another time.

I'm going to add a few controls just to demonstrate how to do this. I don't expect that this will result in a logical grouping of controls, but it should be fun and give us something to play with.

Add a Button

A button can be used to trigger single value actions such as Increment Page Number.

Add a button to the form.

Create the button click event handler.

Display the Events properties for the button by clicking on the little lightning bolt in the properties window for the button. Then, double-click on the Click event.

Your code will be different depending on the name you give the button.

Add a Text Box

Add a text box to display the value of events connected to its action node.

Add a text box control to the form.

Create the following action code:

// Here is a sample action.
// The name specified in the attribute will be displayed in the connections list.
// The 2nd parameter specifies how many data values it expects; 128 in this case.
// The optional 3rd parameter can specify an auto-connect name.
// This action will be invoked whenever any events connected to it are fired.
// It will display the value passed in the list box.
[ProjectMidiActionAttribute("TextBox",128,
"GetSongNum","String or number to be displayed in the textbox.")]
publicvoid textBoxAction( object source, EventArgs e )
{
StringEventArgs eString = e as StringEventArgs;
IntEventArgs eInt = e as IntEventArgs;
if(eString != null)
{
TraceMessage( "Text Box Action: "+eString.str );
sampleTextBox.Text = eString.str;
}elseif(eInt != null)
{
TraceMessage( "Text Box Action: "+eInt.data );
sampleTextBox.Text = eInt.data.ToString();
}
}

Add a Trackbar

A TrackBar is interesting because it can be both an Action, receiving position information from a connection, as well as an Event, sending user selected position information to a connection.

Add a Trackbar control to the form.

Add a scroll event handler.

Create a scroll event handler and a ProjectMidi event as shown:

// This is the event associated with the track bar.
// It will be fired every time the track bar is moved.
// It is "auto-connected" to set the song #, but the user can change this.
[ProjectMidiEventAttribute("TrackBar",16,"SetSongNum",
ConnectionType.Normal,"Sent whenever the TrackBar is moved.")]
publicevent ProjectMidiEventHandler OnTrackBar;
privatevoid sampleTrackBar_Scroll(object sender, System.EventArgs e)
{
int newvalue = sampleTrackBar.Value;
try
{
IntEventArgs eInt = new IntEventArgs( newvalue );
if(OnTrackBar!=null) OnTrackBar(this,eInt);
}
catch(Exception err)
{
Console.WriteLine("Trackbar error: {0}",err.Message);
}
}

Add a ProjectMidi Action

Add code as shown to implement a ProjectMidi Action:

// Here is the action associated with the TrackBar.
// This allows having the TrackBar set by other controls.
// It is auto-connected to Song # so that it will track it if changed elsewhere.
[ProjectMidiActionAttribute("TrackBar",128,
"GetSongNum","Sets the position of the trackbar.")]
publicvoid trackBarAction( object source, EventArgs e )
{
IntEventArgs eInt = e as IntEventArgs;
if(eInt != null)
{
TraceMessage( "Sample TrackBar Action: "+eInt.data );
sampleTrackBar.Value = eInt.data;
}
}

Add a Context Menu

Context menus are one of my favorite items. By adding a context menu to your form, you allow the user to link to whatever actions they like. The context menu will be displayed whenever the user right-clicks on the form. The items displayed on the menu are specified by making connections from the event that we create for the context menu to any other action in any other ProjectMidi assembly! This is quite a powerful and useful feature.

As shown in the following code, implement a context menu using the following steps:

Add a ContextMenu control to the form.

Create a context menu popup handler method.

Select the ContextMenu control, then double-click the Popup property. This method is called prior to displaying the context menu. We'll add code to call each action connected to our context menu event, passing them a reference to the ContextMenu object.

Playing with SampleAssembly

Now that the code is complete, compile it, and copy the SampleAssembly.dll to ProjectMidi's Assemblies directory. Launch ProjectMidi.exe, and verify that the SampleAssemblies window is displayed. Now, let's play with it.

Make sure that the Connections dialog, the Sample dialog, and the SongSet dialog are all visible. If not, then right-click on the Project MIDI icon in the Task Bar to bring up the icon menu. Selecting any of the names listed in the Assemblies submenu will cause the associated assembly to alternately be displayed or hidden.

First, let's establish a connection from the SongSet song number to the SampleAssembly's text box. This way, whenever anything changes the song number, it will be displayed in the SampleAssembly text box.

Right click on the ID column of any connection on the Connection dialog. Select the New Connection menu item. This will create a new connection.

Click on the ID column header to sort the connections list by ID number. Then, scroll down to the bottom of the list to display the newly created connection.

Right-click on each of the columns of the new connection, and select the SongSet assembly, song number event, and the Sample dest assembly Text Box Action.

Test the connection by selecting different songs in the Song Set dialog. As each song is selected, its number should be displayed in the text box.

Now, let's connect the TrackBar to the song number.

Right click on the ID column of any connection on the Connection dialog. Select the New Connection menu item. This will create a new connection.

Click on the ID column header to sort the connections list by ID number. Then, scroll down to the bottom of the list to display the newly created connection.

Right-click on each of the columns of the new connection, and select the SongSet assembly, song number event, and the Sample dest assembly Track Bar Action.

Using the same procedure, create another new connection, and connect the Sample assembly TrackBar event to the SongSet assembly Song Number Action.

Now, the TrackBar is connected as both an Event and an Action to the Song Number.

Menu Connections

Let's create some Sample Assembly context menu entries to select the next or previous songs.

Menu items can be added directly to a menu. Alternatively, a submenu can be created, and menu items added to the submenu.

For this example, we will create a "Song" submenu, and add items to select the next or previous song.

Create a new connection.

Set the source of this connection in the Sample assembly ContextMenu event.

Now, make this connection a submenu by right-clicking on the dest assembly and selecting SubMenu.

Right-click on this new submenu connection item, and select "Edit Context Menu". This will allow you to edit the name of this item. Change the name to "Song".

Close the menu editor.

Now, create new connections from the Sample assembly Song event. This event is, in fact, the submenu you just created. Create connections from it to the SongSet assembly Prev Song and Next Song actions.

Now, when you right-click on the Sample Assembly dialog, a context menu will be displayed with two menu items: Set next song and Set previous song in a "Song" submenu.

Points of Interest

I'm hoping that this article has shown you how easy it can be to extend ProjectMIDI to suite your own unique needs. I hope many of you will feel motivated to create your own ProjectMidi assemblies to take control of your MIDI equipment.

Share

About the Author

Ron is a senior software engineer.
His hobbies include riding motorcycles, travel, and scuba diving.

He enjoys learning about science, particularly quantum physics and cosmology.

He is active with his church where he plays drums and keyboards with the contemporary church band each week.
He also designed and maintains his church and band websites (http://TheRockUMC.org and http://TheRockBand.org).

I've been playing around with ProjectMIDI for about a week now. This is a cool concept and, honestly, directing my programming curiosity toward something that's related to my personal interests is just what I needed.

Two quick questions:
1. Are there any particular assembly additions that you wanted? (i.e. additional functionality, or an assembly per device?)

2. Do you plan to post submitted assemblies here or do you have a place where you would be interested in posting assemblies that other coders have created?

I mention some ideas for future assemblies on the ProjectMIDI web page in the Future Plans page.

I've recently updated the code in the original article. Mostly clean-up type things.

I haven't given a lot of thought to how to integrate other folks' assemblies. I guess that it is going to depend on how big a reaction there is. If it amounts to only a dozen or so, then I guess I could simply add them to the package if the authors agree to that. Another option would be to simply post them to the ProjectMIDI web site.

Either option would be fine with me. I'll try to sit down over the next few weeks and develop some assemblies that would be beneficial to me. I have 5 different MIDI devices that I use, so I'll probably develop assemblies for a couple and send them to you.

I think it'd be cool to have a notation assembly that could either display staff/guitar tabs/or midi sequencer data. Maybe somebody'll beat me to it. Graphics are not my strength.

My current devices are:
- MidiVerb
- Alesis S4+ sound module
- Several Lexicon sound modules
- Feedback Destroyer Pro
I've got a Peavey C8P controller that I use to send presets to most of the devices during live gigs, but in the studio I usually use either Cakewalk PA8 or ProTools LE to handle the automation.

Nice setup. So you would need assemblies for the S4+ to be able to pick and remember your patches per-song. If you dynamically switch effects on the midiverb or other midi-enabled sound modules, then you'll need assemblies for those also.
You can look at the source for the XP30 assembly, which simply lists the possible preset names and allows selecting them per-song.
The TD8 assembly is more complex, and allows controlling every sound parameter on every pad.