Brass SSE Developer Guide - Distributing Your Plugin

How SSEdit links your panel layout with your plugin

The first time you create a plugin pack that includes a default panel layout (one you created with the Panel Designer), you might be a bit confused how everything works together.

The "problem" is that SSEdit handles all the packing and distribution setup for you, so until you understand exactly what SSEdit does it will probably look a bit like magic!

The Panel Designer and the Pack Creator

As you learned when skinning controls for the first time, the Panel Designer allows you to specify images for each part of a control. When you provide these images, the Panel Designer automatically adds the files to your resource list.

As you develop and test your plugin, SSEdit keeps the path and filenames of the images exactly as you specified them. In other words, if you skinned a button with C:\MyImages\NormalButton.gif, that exact path and filename will be stored in your default layout file. You can check this easily by opening the .SLX file in Notepad.

Why does SSEdit keep the original paths and filenames? Simple. When you code your plugin then test it in Brass (using the button), SSEdit knows that Brass is obviously running (or at least installed) on the same computer. That means Brass also has access to the same files as SSEdit no matter where they are stored, so there's no need to copy them to the plugin's resource folder (<Brass Install Folder>\SSE\<PluginName>). If Brass and SSEdit didn't work together like this, every time you wanted to test your code all the images used by your skinned controls would have to be copied around your harddrive. Very slow, and very inefficient.

However, there's a bit of a problem. Keeping all your images in C:\MyImages is fine when you're coding plugins for yourself, but when you distribute your plugin to other people there's no way they'll have that exact folder available. This is why the Pack Creator places all the plugin's resources into <Brass Install Folder>\SSE\<PluginName> - it's tidy and it's guaranteed to work no matter what computer you install the plugin pack on.

But now we're left with a question. The Panel Designer lets you specify any image file in any folder you want, but the Pack Creator always rewrites the paths so that all images are installed into <Brass Install Folder>\SSE\<PluginName>. How do these different systems work together?

Pack Creator Path Rewriting

When you create your plugin pack SSEdit does something clever. Before your default layout is packed, SSEdit works its way through the entire layout and rewrites all the paths to the images you've used. This is done invisibly, in memory, so you'll never see it happen and it doesn't alter your source code or layout file.

The end result is that your plugin pack will always install the resources into the <Brass Install Folder>\SSE\<PluginName> folder, and the default layout file stored in the plugin pack will always look for the resources in that same folder. Even better, this is all done without affecting the plugin code or the layout file - the next time you go back into the Panel Designer all your images will still be in their original paths.

In a sentence - the Pack Creator makes sure that your plugin is configured and distributed with all the files it needs to run on any computer.

Here's a little flowchart to clarify things:

Flowchart 1

1. You create a new plugin called Button.SSN
2. You create a new layout for the plugin, using the Panel Designer
3. In your layout you add a button
4. You skin the button with C:\MyImages\Normal.gif and C:\MyImages\Pressed.gif
5. You close the Panel Designer with the OK button
6. The Panel Designer notifies SSEdit that you used C:\MyImages\Normal.gif and C:\MyImages\Pressed.gif
7. SSEdit adds those 2 GIF files to your resource list
8. You add the loadlayout() and savelayout() statements to your code

At this point you've just created a normal plugin. Now it's time to test your plugin by using the Run In Brass option (or clicking the button in SSEdit). This is what happens next:

Flowchart 2

1. SSEdit prompts you to compile your code - you click Yes
2. Your plugin code is compiled to Button.SSE
3. Your panel layout is saved to Button.SLD, still using the images in C:\MyImages
4. The Button.SSE is copied to the <Brass Install Folder>\SSEDev folder
5. The Button.SLD is renamed to default_layout.sld and copied to <Brass Install Folder>\SSEDev
6. Brass is notified a new plugin build has been deployed for testing
7. Brass loads your plugin, using the default_layout.sld and the images in C:\MyImages

Nothing unusual there, that's the normal deployment process. But let's look at what happens when you create an SSP using the Pack Creator:

Flowchart 3

1. You open the Pack Creator window using the button
2. SSEdit transfers all the resources in the resource list (flowchart 1, step 7) to the Pack Creator
3. SSEdit transfers the layout you created to the Pack Creator
4. The Pack Creator saves each resource file to the pack using the relative path of Button\<Filename>
   (for example: "C:\MyImages\Normal.gif" is saved to the pack as "Button\Normal.gif")
5. The Pack Creator loads the layout data into memory
6. The Pack Creator scans the layout data and changes all explicit paths to relative paths
   (so all references to "C:\MyImages\Normal.gif" are changed to "Button\Normal.gif")
7. The Pack Creator then packs the updated layout data into the SSP and deletes it from memory
   

As you can see, steps 5, 6 and 7 make sure that the layout file stored in the SSP uses relative paths and will therefore always work wherever the pack is installed. And all this is done without affecting the Button.SLD file, so the code and layout files you work on always remain the same.

Copyright 32Bits.co.uk 2005. All rights reserved.