The BLOCKS SDK
Dynamic Parameters

Introduction

Learn how to use BLOCKS CODE metadata to interact with your BLOCKS using dynamic parameters.

Launch the BLOCKS CODE application and open the script called DynamicParameters.littlefoot. You can find the script in the littlefoot/scripts/Example Scripts folder. If you don't have the BLOCKS CODE IDE installed on your system, please refer to the section Getting started with BLOCKS CODE for help.

Adding Parameters

Let's start by adding parameters to the side panel of BLOCKS CODE that will appear under the Parameters tab.

These are created using an XML format enclosed between multiline comment blocks and <metadata> tags at the top of the file. Variables are created between <variables> tags and they can also be grouped using <groups> tags as follows:

<metadata description="Dynamic Parameters">
<groups>
<group name="pos" displayName="Position" />
<group name="size" displayName="Size" />
<group name="colour" displayName="Colour" />
</groups>
<variables>
<variable group="pos" name="xPos" type="int" min="0" max="15" value="6" />
<variable group="pos" name="yPos" type="int" min="0" max="15" value="6" />
<variable group="size" name="width" type="int" min="1" max="15" value="3" />
<variable group="size" name="height" type="int" min="1" max="15" value="3" />
<variable group="colour" name="alpha" type="float" min="0" max="255" value="255" />
<variable group="colour" name="red" type="int" min="0" max="255" value="255" />
<variable group="colour" name="green" type="int" min="0" max="255" value="0" />
<variable group="colour" name="blue" type="int" min="0" max="255" value="0" />
<variable name="draw" type="bool" value="true" />
</variables>
</metadata>

Within the variable declaration, the string given to the "name" attribute becomes the variable name in the subsequent littlefoot code.

Parameters in Blocks Code

Let's now implement the repaint() function of the littlefoot program. This function is called periodically at approximately 25Hz on the device and is used to control the LEDs on a Lightpad.

In the following piece of code, we first call the clearDisplay() function which will reset the screen to a blank state so that any LEDs that were turned on in the previous iteration of the repaint() function are turned off.

void repaint()
{
clearDisplay();
if (draw)
fillRect (makeARGB (int (alpha), red, green, blue), xPos, yPos, width, height);
}
makeARGB
int makeARGB(int alpha, int red, int green, int blue)
Combines a set of 8-bit ARGB values into a 32-bit colour and returns the result.
fillRect
void fillRect(int rgb, int x, int y, int width, int height)
Fills a rectangle on the display with a specified colour.
repaint
void repaint()
Use this method to draw the display.
clearDisplay
void clearDisplay()
Clears the display and sets all the LEDs to black.

Then we use the fillRect() function to draw a rectangle on the screen using the variables defined before, only if the draw button is checked. The fillRect() function takes as argument the colour retrieved by the makeARGB() helper function and the position and size of the rectangle we wish to draw.

Summary

In this example, we learnt how to add parameters that can be tweaked at runtime to control the behaviour of a program in realtime.

See also

All content © ROLI Ltd.