Brass - Dynamic Windows Enhancement

Brass SSE Developer Guide - Tutorials

Tutorial 2 - Variables and Fonts

In tutorial 1 you saw how to display some text on the screen. Static text in that system font isn't particularly interesting though so in this tutorial we'll learn how to use variables, and how to display text in different styles.

Starting the Plugin

Let's start a new plugin. Run SSEdit (or select File - New) to create a blank document to start coding on. We want to change what's displayed on-screen, so make sure "Render" is selected in the Handler Wizardbar again and click "Add Handler". Your editor window should look exactly like it did in tutorial 1:

Let's do something with variables.

A Quick Noteme

Here's something you'll find very handy. SSEdit recognizes a special keyword - note. When you use this keyword with a string, the compiler will display the string during the compiling process. It makes it perfect for leaving yourself "To do" or "Bug" notes in your code. Use it like this:

#note "I must remember this"

You don't need to add a semicolon to the end, and it doesn't affect your code in any way (it's not included in your plugin at all). The # symbol indicates it's a "directive", in other words it's an instruction to SSEdit to do something other than compile it as code.

Give it a try later!

Variable Types

Shiny has 5 basic variable types. If you've written programs before these will be instantly recognizable to you:

Variable Type Contains

string Any text string: "My name is Bob", "Brass is great" etc.

int A whole number: 1, 99, 2500

bool A boolean value, either True or False

double A whole number or floating point number: 5, 27, 3.1415

dword A base 16, 4 byte value: 0xffffffff, 0x12345678

The types you'll use most often are string and int, so don't worry about the rest (especially that whole dword thing) for now.

Before you can use a variable you must declare it. Declaring a variable says to Shiny, "I want to use this variable later in my code, and it should be of this specific type". It's the equivalent of the Visual Basic "Dim" statement.

If you've used Visual Basic in the past it's handy to know that Shiny and SSEdit behave exactly the same way as the Option Explicit statement in VB.

There are 2 ways to declare a variable. Both work exactly the same way so just pick the one you're most comfortable with.

Type 1: The Visual Basic "Dim" style:

declare MyString string;

Type 2: The C/C++ declaration style:

string MyString;

Both of these give exactly the same result - a variable called "MyString" is declared as a string type. Declaring any type of variable is done in exactly the same way.

Shiny supports "dual syntax" for a lot of the conventions and keywords - where 2 different code statements, one that looks like VB and another that looks like C, produce the same result. Just pick the style you're most comfortable with.

If you don't declare your variables before using them the compiler will generate an error, usually mentioning "uninitialized type" or "incompatible types". This is because the compiler doesn't know what type of variable you want. As an example, this code:

function MyFunc()
{
MyUnDeclaredVar = 2;
}

would generate this compiler error:

(Line 3) =: Assignment to uninitialized type

Variable conversions

We'll cover this briefly now and come back to it in detail later. Shiny is a type-safe, implicit type conversion language. What that incomprehensible sentence means is that all the basic types can be assigned to each other automatically.

In some languages (C, Java, PHP) you must convert variable types to match each other before you can use them in an expression. For example, in C this is illegal:

int a = 5;
char* szNumber[] = "10";
a = a + szNumber;

That piece of code is trying to assign a string type (the char*) to an integer type, and it won't be allowed.

Shiny allows exactly this type of conversion, and it happens automatically. Shiny can understand what types you're using and what type you want the result to be, then perform the conversion for you. Here's an example:

string NumberAsString = "10";
int RealNumber = 5;
RealNumber = RealNumber + NumberAsString

In that sample, NumberAsString will be automatically converted to an integer on the last line (at the addition expression), meaning that RealNumber will be set to 15 when the code runs.

Did you see the new style in the code snippet above? When declaring variables using the C/C++ declaration style, you can also assign them a value at declaration time.

Don't worry if this was confusing, we're going to come back to it in more detail later. It will be much clearer as you see it happening in code.

Writing some code

Theory is all well and good, but it's better to see things in practice. Let's update our code from tutorial 1 to use variables. Instead of displaying a static string at a fixed position, let's display a string variable at a position also specified by variables.

In your Render() handler function, add the following code:

declare MyText string;
declare PosX int;
declare PosY int;

That's our variables declared. Now we need to assign some values to them.

Underneath the declare statements, add the following code:

MyText = "A plugin with variables!";
PosX = 10;
PosY = 50;

The last thing to do is to actually use the variables in our original drawtext statement.

Underneath all the code you've written, add the drawtext statement:

drawtext(MyText, PosX, PosY);

When you've finished your code should look exactly like this. Don't forget your semicolons at the end of each line!

Save your code as plugin2.ssn and compile it.

Click the "Compile" icon ( )on the toolbar, or select "Compile" from the Build menu

The compiler should inform you that no errors were found (if you did get some errors, review the code you typed very carefully - if necessary, copy and paste it from this webpage).

Test your Plugin

Let's test the SSE in Brass and check out all our hard work.

Click the "Execute" icon ( ) on the toolbar, or select "Run in Brass" from the Build menu

SSEdit will minimize itself and Brass will load your new plugin. Ah, problem. We're back to that black text on a black background issue we had in tutorial 1. We could just go into the SSE configuration and change the background colour again, but this time let's change the text colour instead.

Using Fonts

As well as the basic variable types covered above, Shiny has a number of advanced variable types. These are special variables that don't represent a single value but instead represent a set of data or configuration settings.

One of these types is the font type. This type represents a font for displaying text - it's font name, size, colour, and whether it's bold or italic. There are 3 steps to using a font:

Declare a variable of type font

Set the font style (font name, size etc)

Tell Brass to use the font for displaying text

Declaring a font type is exactly the same as declaring any of the basic types:

Type 1: The Visual Basic "Dim" style:

declare MyFont font;

Type 2: The C/C++ declaration style:

font MyFont;

Let's add the declaration to our code. As long as we declare it before we need to use it (we need it for the drawtext statement, remember!) we can add it anywhere we want. I'll add it immediately after the PosY = 50; statement.

Add the following declaration to your code, before the drawtext statement:

declare MyFont font;

Next we need to set the style of the font, using the createfont() statement.

Underneath the font declaration, add the following code:

createfont(MyFont, "Arial", 12);

As you guessed, the createfont() statement initialises our font variable with the settings we provide. Here's its prototype:

createfont(variable as type font,
           typeface name as string,
           font pointsize as integer,
           optional bold as boolean,
           optional italic as boolean);

Notice the last 2 parameters are optional. If we don't specify them, createfont() assumes we don't want the font to be bold or italic. Less typing for us!

Now that our font has been created, we need to tell Brass to use it.

Underneath the createfont statement, add the following code:

selectfont(MyFont);

The selectfont() statement tells Brass to select the font we specify as the font to use for all subsequent text display.

When you've finished writing the code, your editor window should look like this:

Time to compile and execute your code!

Click the "Compile" icon ( )on the toolbar, or select "Compile" from the Build menu

Click the "Execute" icon ( ) on the toolbar, or select "Run in Brass" from the Build menu

Your plugin will be compiled then deployed to Brass. If you didn't unload the plugin from our first attempt don't worry - Brass will automatically unload the old version, install the new version and then load it.

If everything went OK your plugin display should now look like this:

Wow - that's exactly what we were after!

Changing the font colour

Before we wrap this tutorial up let's look at one last important item. Changing the colour of a font is extremely easy and is done by the setfontcol() statement. Here's its prototype:

setfontcol(variable as type font, rgb colour as integer);

The first parameter is straight-forward, just like selectfont and createfont we supply the font variable that we want to change. The second parameter is a little more awkward.

If you've used the RGB statement in Visual Basic or the RGB macro in Visual C++ then you can skip to the bottom of this section - the Shiny RGB statement works in exactly the same way.

If you've never written programs before, you may not be aware that colours are usually represented as RGB - red, green and blue components. With these 3 components you can make any colour, which is why you see RGB in paint packages like Paintshop Pro. Traditionally each of the 3 components are specified on a scale of 0 to 255, with 0 being "none of this component" and 255 being "all of this component". An RGB of R = 0, G = 0, B = 255 has no red or green components, but a full intensity blue component. Therefore that RGB value produces the colour blue. Similarly R = 0, G = 0, B = 0 has no components at all and produces black, whilst R = 255, G = 255, B = 255 has full intensity of all components and produces white.

It's normal to roll these 3 Red, Green and Blue values up into a single number for convenience, which is what Shiny does with the RGB() expression. You don't need to worry about why or how it does this. All you need to know is how to specify a colour. Here's the prototype:

RGB(red as integer, green as integer, blue as integer);

For example, to specify the colour green (which has zero red or blue components, but a full green component) you would use:

RGB(0, 255, 0);

Simple! So how do we use this with setfontcol to set our font colour? We use the RGB expression as the second parameter:

setfontcol(MyFont, RGB(0, 0, 255));

That piece of code would set MyFont to the colour blue. Let's add that code to our plugin now.

Above the call to drawtext, add the following code:

setfontcol(MyFont, RGB(0, 0, 255));

Your code should now look like this:

That's all the code finished, let's compile and run the plugin.

Click the "Compile" icon ( )on the toolbar, or select "Compile" from the Build menu

Click the "Execute" icon ( ) on the toolbar, or select "Run in Brass" from the Build menu

If all went well your plugin display should look like this:

Well it's a little hard to read, but you can see the font is now blue!

A Quick Recap

Nice work, you learned a lot this time. The basic building blocks of any plugin (and in fact all applications in any language) is displaying output and using variables.

In this tutorial you saw:

How to declare variables

How to create a font

How to set a colour using the RGB expression

How to display text on-screen

In the next tutorial we're going to see how to respond to user input and how to use some of the other event handlers. By the end you'll know enough to write a little game!