Brass SSE Developer Guide - Tutorials
Tutorial 1 - Your First Plugin
The easiest way to learn something is by seeing
it in action and working through it, so that's the way we're going
to learn how to create SSE's.
Before we start let's cover a couple of conventions.
In the tutorials certain text styles will be used to signify specific
meanings:
this is a piece of code: declare
MyString string;
this is an instruction: Select "Configuration"
from the menu
this is an important boxout, take note
of anything in here
this is an information bubble, this might
help you or provide a useful tip
Easy enough. Let's get started.
Starting a Plugin
Every plugin begins life in SSEdit as an SSN file.
That's just a fancy custom extension that SSEdit registers with
Windows - really they are just plain text files. Let's open SSEdit
and get started.
Run SSEdit from the Brass
program group on the Start menu
SSEdit will start up with a blank file for you.
We're going to write a few lines of code "blind"
to start with. The idea is to get a feel for the basic process of
writing code, deploying it to Brass and testing it - we'll go over
each stage in detail next so that you understand exactly what you're
doing.
Beginning Event Handlers
All SSEs are based around event handlers. Something
happens, your plugin responds to it. The most common thing all plugins
do is display some output on screen. If you've ever written any
kind of Windows program in Visual Basic or C, you'll know that the
way Windows works is to tell your code when it needs to update the
display. Brass works in exactly the same way. When your plugin should
update its display Brass will call your plugin's Render handler.
Whenever your plugin's display needs updating,
Brass will call your plugin's Render handler
Adding handlers in SSEdit is extremely easy. On
the right side of the toolbar is the Handler Wizardbar, on which
is a combobox that lists all the handlers you can write code for.
Let's add the Render handler now.
Make sure the Render handler
is selected in the combobox and click "Add Handler"
SSEdit will add a chunk of code to the editor window:
This skeleton function is the beginnings of your
Render handler. You could of course just type the function definition
yourself, but then you don't get the handy comment added for you.
Plus, it's more work!
If you've programmed in other languages, you're
probably noticing some similarities in Shiny. This is completely
intentional - you'll find a lot of the knowledge you have of
BASIC, C, PHP and similar languages directly translates to Shiny.
As we discussed, the Render handler is called whenever
your plugin needs to display something on screen. Let's display
some text to get us started.
Inside the Render function,
in between the braces, type the following code:
drawtext("My
first Brass plugin!", 0, 0);
Note the semicolon at the end of the line. All
statements end with a semicolon, just like C, C++ or PHP.
In the Shiny language, all statements
end with a semicolon. If you get a syntax error while compiling,
check your semicolons!
As you type the code you'll see "drawtext"
turn blue. SSEdit has recognised it as a keyword and syntax-highlighted
it for you. Your editor window should now look like this:
The drawtext statement pretty unsurprisingly draws
some text on the screen. The first parameter is the text you want
to display. The second and third parameters specify the X &
Y position of the top left of the text within the plugin display
panel. We've specified 0, 0 here so the text will appear in the
top left of the panel.
Comments are a great way to remind yourself
what each part of your code does. They're ignored by the compiler,
so you can write whatever you like. Simply type a double forward-slash
("//"), and everything for the rest of the line will
be ignored as a comment. SSEdit turns comments green so you
can see them clearly.
That's it! You've just finished your first plugin!
Let's see it in action.
Compiling your code
As you probably know, Brass runs SSE's as compiled
"virtual executables" inside its virtual machine. So to
get our plugin working in Brass we have to compile it. Don't worry,
it's easy.
SSEdit saves source code to .ssn files - these
are actually plain text files, but the .ssn extension is associated
with SSEdit. This allows you to double click a source file in
Windows Explorer and automatically load it in SSEdit.
First up, save your plugin source code somewhere
safe. I'll save mine to C:\SSECode.
Select "Save As"
from the File menu, and save your plugin as "plugin1.ssn"
Now it's time to compile your code. This is the
real scary part - ready?
Click the "Compile"
icon ( 
)on the toolbar, or select "Compile" from the Build menu
The compiler output window will pop up and let
you know what happened:
Surprised how easy it was? Don't be - the entire
Brass, SSEdit and Shiny system were designed to be as simple but
as powerful as possible. At the bottom of the compiler output you
can see that no errors were found, which means your plugin has been
compiled to an SSE and is ready for testing.
Testing SSEs with the SSEdit -
Brass integration
Time to test your SSE in debug mode. SSEdit and
Brass have 2 ways to run SSE's - "Release" and "Debug".
We'll cover these modes in more detail in a later tutorial as there
are some useful differences, but for now just carry on with the
tutorial.
Click the "Execute"
icon ( 
) on the toolbar, or select "Run in Brass" from the Build
menu
Your plugin will now be deployed to Brass.
If Brass is already running, SSEdit will ask if
the same plugin has already been loaded. If it has, the existing
plugin will be unloaded and replaced by the new plugin. This ensures
you're always testing the newest build of your plugin. Brass then
auto-loads your plugin.
If Brass isn't running SSEdit will automatically
start it. Then, once loaded, SSEdit will tell Brass to auto-load
your plugin.
Once SSEdit has deployed the plugin it will minimize
itself and the main Brass window so you can see your plugin in all
its glory!
Um, okay. That's not what we were expecting. We've
got a Brass plugin panel, but what happened to the text?
The Auto-Configuration System
Yeah, yeah, you guessed it. This was just a sneaky
way to introduce a very cool feature of SSE's. If you've used any
Brass plugin you'll know that they all have a standard configuration
window where you can set window transparency, background colour,
background image and more.
SSE's have access to exactly the same configuration
system, all without you writing a single line of code! Open the
Brass main window by double clicking the tray icon, then double
click your plugin ("plugin1.sse") in the Active Plugins
list. You'll see the SSE config window:
All that functionality is available to your plugin
and you don't need to write a single line of code! As you may have
guessed, the reason the display panel started off with no text was
because we were writing black text on a black background. Let's
solve that now.
Click the "Solid background
colour" button and select light grey from the colour wheel
Now when you OK the configuration dialog, your
plugin will look a lot more like this:
A Quick Recap
Congratulations, you just wrote your first plugin!
Well ok, really you just wrote one line of code and clicked a few
buttons, but you learned all the basic principles behind plugin
coding. Don't worry if you're not sure why you're doing certain
things, all will be explained in detail as we work through the tutorials.
In this tutorial you saw:
- How to add an event handler
- How to compile and run your plugin
- How to display text in the plugin
display panel
- The configuration system all
SSE's automatically have access to
In the next tutorial we're going to write a bit
more code, so if you're happy with everything you read in this tutorial
let's get started on the next!
|
