From MP3Car.com Wiki
The following is preliminary information. 1.0.6.2 is the first version that supports .Net addins. NOTE: At this point, the addin format is to be considered a pre release format and will probably not be binary compatible with the final official release. The methods and parameters should not change, some methods may be added though. What this means is that you can start writing your addin now and it will work with future version, but possibly only if you recompile it first. In any case more then likely no code changes will be needed to get it to work with the final release version.
StreetDeck supports an Addin format, similar, but ultimatly different from Addins supported by many Microsoft products such as the Office suite, Visual Studio, and Mappoint. Basically an Addin is a COM server dll that implements the StreetDeck.IDualStreetDeckAddin interface defined as an embedded interface in the StreetDeck executable.
The following tutorial was created based on Visual Studio 2005 for C#. The process for other versions and languages should be similar.
[edit] Starting a New Addin Project in StreetDeck
This tutorial covers the most basic addin you can create in StreetDeck. It shows you how to create modules and overlays which allows you to make anything that does not play media. i.e. A weather DigitalMod. If you would like to make an addin that plays media (i.e. a sirius radio DigitalMod) you should read the Making a MediaManager DigitalMod (Addin) tutorial after completing this tutorial. If you don't know what a Module, Overlay, or Media Manager is yet, you should read The StreetDeck Windowing System (Panels, Modules, Overlays, and MediaManagers).
Note that StreetDeck will refer to some things as scripts when in reality, if you are creating an addin, there will be no scripting involved, just compiled code in the COM language of your choice. StreetDeck does also support scripting, that topic is not covered in this tutorial though. Before we get started writing code for your new Addin, the first step is to start StreetDeck in Developer Mode (Start | Programs | StreetDeck | Tools | Development Environment) and then create a new script project by going to File | New | Script Project.
This will automatically create a project and assign it a GUID. This GUID can be the same as the GUID you use to identify your addin to COM (explained below), but doesn't have to be. If we click on the new project in the module browser, the properties pane should be populated with the projects properties. You should fill in all applicable information to describe your addin to StreetDeck. If nothing else, you should at least fill in the Title property for your project.
Note, the value for GUID in the project properties, when your project was created a new folder was created for it under My Documents\StreetDeck\Scripts\<GUID> where <GUID> is your project's GUID. Browse to this folder now by choosing Project | Browse Project Folder from the menu. Note that there is just a single file in the folder now call Project.txt. You should never edit this file directly, rather it is used by the development enviornment to automatically store all the meta data about your project.
To be able to use this project folder for addins, you must create a sub folder call Addins. Your compiled binary (.dll) that implements the StreetDeck addin interface should be placed in this folder and the dll MUST be named after the ProgId for your addin. i.e. for a Prog Id of MyAddin.MyClass the file should be called ..\My Documents\StreetDeck\Scripts\<GUID>\Addins\MyAddin.MyClass.dll. Create the Addins sub folder now in windows explorer.
Close StreetDeck.
[edit] Building the Addin in Visual Studio
Start up Visual Studio 2005.
Create a new C# project by going to File | New | Project.
Choose Class Library from the list of C# projects.
Type a unique name for the project such as "StreetDeckTestAddin" and click 'Ok'
Add the following line to the top of the class file to include the COM interop services.
using System.Runtime.InteropServices;
Add a reference to the StreetDeck COM server by right clicking on the references folder in the solution explorer for your Addin project and choosing Add Reference then choose the Browse tab.
Select the StreetDeck.exe file usually located in C:\program files\StreetDeck and click OK
In the solution explorer, expand the properties folder and double click on AssemblyInfo.cs. Find the line where it says [assembly: ComVisible(false)] and change false to true so that it can register itself as a COM object.
In the solution explorer, double click on Class1.cs and add the following lines within the name space brakets.
[
GuidAttribute(""),
ProgId(""),
ComVisible(true)
]
Run the GuidGen tools by going to Tools | Create GUID. Generate a new Registry Format GUID and copy it. Place the generated GUID in the GuidAttribute quotes and add a progid which should be the human readable addin name followed by a . and the class name. i.e. After the changes the lines should look similar, but not exactly like the following, your GUID MUST be unique for each addin you create. Using the GuidGen tool assures the GUID will always be unique.
[
GuidAttribute("69CECAE8-7125-4cf4-8026-AF40503CC406"),
ProgId("StreetDeck.TestAddin"),
ComVisible(true)
]
For your addin to be loaded by StreetDeck, it must implement the StreetDeck.IDualStreetDeckAddin interface. To do this, change the automatically created Class1 interface to look as follows:
public class Class1 : StreetDeck.IDualStreetDeckAddin
Every addin should also implment the OnConnection and OnDisconnect events which are called when the addin is loaded and unloaded by StreetDeck they are the first and last events respectively. In the OnConnection event, you should create all Modules, Overlays, and Media Managers your addin will use and any other initialization your addin needs. NOTE: The methods to create these objects will unconditionally fail outside of the OnConnection event. You should cleanup everything allocated in the OnDisconnect event.
The following code implements the OnConnection event. On the first line of the event, we save a pointer to the app object given to us in the OnConnection event to a class member. The next line creates a module where we can place other panels (controls). We then create a single button panel in the new module and set the caption to say "Show Overlay". Next we create an overlay panel that will be shown when the button is clicked and sign up for the OnExec module event to process the button click.
StreetDeck.StreetDeckApp app;
StreetDeck.ScriptModule module;
StreetDeck.ScriptOverlay overlay;
//This OnConnection event is where we create all of the modules and overlay streetdeck needs
//This example creates one module and one overlay
void StreetDeck.IDualStreetDeckAddin.OnConnection(object o, StreetDeck.enumAddinConnectMode e)
{
//Save a pointer to the StreetDeck App object for future reference
app = (StreetDeck.StreetDeckApp)o;
//Create a single module that will show and hide an overlay
module = app.CreateModule("ModuleName");
//Create a button on our module that will show and hide the overlay
//We can create the button panel at the start of the client area by using the
//app.GetSystemMetric call. The width and height are ignored for buttons which take
//on the width and height of whatever the button class (skin image) is.
StreetDeck.Panel btnShowOverlay = (StreetDeck.Panel) module.CreatePanel(StreetDeck.enumCreatePanelType.eCPTButton, "BUTTON.LISTITEM_HIGH",
"ShowOverlay", // This is the function name that will be given back to us in any OnExec
// call and for all intents and purposes is the name of this panel
app.GetSystemMetric(StreetDeck.enumSystemMetrics.eSMGenericModuleClientX),
app.GetSystemMetric(StreetDeck.enumSystemMetrics.eSMGenericModuleClientY),
200, 200);
btnShowOverlay.Caption = "Show Overlay";
//Create an overlay that will contain the other controls. Overlays are global and will be shown
//above every other module
overlay = app.CreateOverlay("OverlayTest");
//Register for the OnExec event where we will process the button click event
module.OnExec += new StreetDeck.IModuleEvents_OnExecEventHandler(module_OnExec);
}
In the OnDisconnect event, we simply unregister for the events we registered for.
void StreetDeck.IDualStreetDeckAddin.OnDisconnect()
{
//Unregister the events
module.OnExec -= new StreetDeck.IModuleEvents_OnExecEventHandler(module_OnExec);
}
Finally, in the OnExec event, we process the button click event. Notice that we check that the Description parameter matches the function name we specified for the button exactly and we are looked for the select event which is sent when the button is pressed.
//The OnExec event for the module is where events from controls on the module are processed.
//Some of the events are also recieved by the controls themselves and can be processed in
//either place. You should return true if you process them here.
public bool module_OnExec(string Description, StreetDeck.enumExecMessage eEM, int wParam)
{
if (Description == "ShowOverlay")
{
if (eEM == StreetDeck.enumExecMessage.eEMSelect)
{
overlay.Visible = !overlay.Visible;
overlay.MsgBox("Overlay Visibility Changed!", "Button Clicked");
return true;
}
}
return false;
}
Thats it! Your addin should now compile and be runable. Pressing the "Show Overlay" button may not appear to do anything since no controls have been created on the overlay, but it is hiding and showing the overlay. You should experiment with creating different controls on the Overlay to get a feel for building StreetDeck addins.
[edit] Debugging your Addin with StreetDeck
To debug your addin as it runs in StreetDeck, you should right click on your project in the solution explorer and click Properties.
Under the Application tab, you must make sure the name of your .dll matches the ProgId of your com object. Set the Assembly name to match whatever you put for the ProgId of your addin. i.e. StreetDeck.TestAddin
Under the Build tab, set the output folder to your script directory, i.e. My Documents\StreetDeck\Scripts\<GUID>\Addins. You should also have Visual Studio automatically register your addin for you by checking the Register for COM interop setting.
Finally, under the debug tab, you should set the working directory to your installed StreetDeck location (usually C:\program files\StreetDeck). Set the command line arguments to -testmode and under the Start external program option browse to and select the StreetDeck.exe file.
You should now be able to run and debug your project.
When the StreetDeck starts up, you should be able to go to DigitalMods and choose your project from the list which will take you to a module in the project. If an overlay is in your addin and is set to visible, it will always be visible whenever StreetDeck is running.
[edit] Distributing and registering Your Addin
After you have created your addin, you should package it into a StreetDeck sdz file so it can be distributed and registered properly by StreetDeck. Since your addin is a COM object, it must be registered using regasm.exe (for .Net COM objects) or regsvr32.exe (for Non .Net languages). When an SDZ is extracted and imported by StreetDeck it automatically calls regsvr32.exe and regasm.exe /codebase on every .dll in the Addins sub folder for the addin. You MUST make sure you addin binary resides in this folder before exporting your addin. As long as it is, it will be automatically registered when an end user double clicks on the sdz file or otherwise imports it into StreetDeck.
To package your project, startup StreetDeck in developer mode. Now start using your addin in StreetDeck such that a screen shot that describes your addin is on the screen. A screen shot will be taken of the StreetDeck render window when you package your project. Next, select File | Package for Distribution. Then select your project from the list. All files and sub folders in your project's folder will be packaged into the specified sdz file. You should make sure your project has no dependancies outside of the project folder needed on the destination machine. If you need to register addional dependancies besides just your addin, you can do so by implmenting the CustomRegister and CustomUnregister events in your addin's class.
//
// This is called when the Addin is registered, you should register anything else the
// addin needs to be installed to work here.
//
[ComRegisterFunction]
public static void CustomRegister(Type t)
{
}
[ComUnregisterFunction]
public static void CustomUnregister(Type t)
{
}
[edit] Example Project
All projects are Visual Studio 2005 C# projects.
To use these projects, both the sdz project must be installed and the source code downloaded. To install the sdz file, simply double click on it, or drag and drop it onto a running instance of StreetDeck. For the c# project, you will have to change the output location and debugging options in the visual studio project properties for the dll after downloading to match the installed locations on your computer.
Example 1:
Basic StreetDeck Addin
This is the project created in the tutorial above and is the most basic addin you can create.
[Example 1 SDZ]
[C# Project]
Example 2:
Comprehensive StreetDeck Addin.
This is a project that demonstrates some of the most common things you would want to do with the StreetDeck SDK including creating controls, working with the navigation engine, sending functions to StreetDeck, Text to Speech, and Playing videos.
[Example 2 SDZ]
[C# Project]
[edit] Additional Information
Please see the following [page] for more information on creating a generic COM server.
More Information on building DigitalMods in StreetDeck
StreetDeck DigitalMods (Addins) other people created.
Integrate a windows application into a DigitalMod (Addin) Tutorial.
