openFrameworks & ofxTweakbar

Anttweakbar is a nifty kind of GUI system. It's designed to be easily embedded in visualisation applications. For openFrameworks you can use the ofxTweakbar addon, which you can download from github. Read the article on installing the roxlu addons for openFrameworks using the github client.

This article assumes you know how to create an openFrameworks application and how to add an addon to your project. We mainly focus on code so you'll see lots of c++ below.

The ofxTweakbar addon was designed to be as simple as possible. I've used other GUI systems like the wonderfull ofxSimpleGuiToo created by Memo or the fantastic ofxControlPanel by Theo Watson. Both these addons provide a simplistic way to create a GUI. So you should have look at those as well and check which one you like best. I think what GUI you'll use is a personal choice. I choose AntTweakbar; When I created the API, I defined functions like addFloat, addInt, addColor3f, etc.. to add parameters to the GUI. This API provides a one-to-one mapping with the variable types you want to manipulate using a GUI.

Lets start by creating an ofxTweakbar. First maybe lets me explain you what a tweakbar is. A tweakbar is a GUI with sliders, toggles, buttons etc. that are used to tweak your variables. You can create as many tweakbars as you want. I tend to group similar settings into the same tweakbar.

Here is a screenshot so you know how ofxTweakbar looks like:

Creating tweakbars

To create an new "tweakbar" (GUI window), you must first include the correct file in your application. So open testApp.h and include "ofxTweakbarIncludes.h"

#include "ofxTweakbarIncludes.h"

Now lets create a member in the testApp to hold our tweakbar.

ofxTweakbar*  settings;

Open testApp.cpp and add this to your setup() function. Note that the first parameter must be a short name, witouth spaces and only alfanumerical characters. The second parameter is the title for the window.

settings = ofxTweakbars::create("settings", "Basic Settings");

Now that we've got our instance, we should draw it. In your draw() function add this line

ofxTweakbars::draw()

That's it! Build and run your application and you'll see a window you just created.

Adding variables to the tweakbar

Now that we've got a tweakbar instance we can add some variables to it. In testApp.h you can define the variables that you want to tweak. Lets create the following members:

float my_float;
int my_int;
float my_color[3];
bool my_bool;
float my_dir[3];

Now, we add gui elements to tweak these members.

settings->addFloat("my_float", &my_float);
settings->addInt("my_int", &my_int);
settings->addColor3f("my_color", &my_color);
settings->addBool("my_bool", &my_bool);
settings->addVec3f("my_dir", &my_dir);

This creates the entries on your tweakbar. Build and run and see the result. If you do not see anything you can press the ',' key to show/hide the tweakbar.

Saving and loading settings to file

By default ofxTweakbar is able to store the values of the different GUI elements to disk. Also we created a default shortcut key '.' (the dot) which stores the current settings to a file in your data directory. To load the data back from this file, you call the "load()" function of the specific tweakbar. It's important to call load() AFTER you've added all the variables to the tweakbar so we know to which element we need to set the values. See the use of settings->load() below where we load previously stored settings.

settings->addFloat("my_float", &my_float);
settings->addInt("my_int", &my_int);
settings->addColor3f("my_color", &my_color);
settings->addBool("my_bool", &my_bool);
settings->addVec3f("my_dir", &my_dir);

settings->load();

More advanced way of setting variables

You can also use a callback that is called when you press a button on the tweakbar. If you want to add a button with a callback function that's called once you click it, you have to create a function which follows this syntax:

static void TW_CALL functionName(void* pClientData);

You define this function in your testApp.h, and add the implementation in your testApp.cpp. Because we use a static function we cannot get access to our members in testApp. Therefore we can use the void* pClientData parameter. But because we need to define this parameter as a void* we need to cast this back to the testApp* type. We do this by using the static_cast keyword. So here is our function in testApp.cpp. We named our member function buttonCallback() here.

void TW_CALL testApp::buttonCallback(void* pApp) {
	testApp* app = static_cast(pApp);
	app->num_int = 500;
	app->settings->refresh();
}

In this function we change the num_int value of the testApp class. Of course you can do anything you like in this function. Also it's important to note the refresh() function here. Afther you've changed a variable value and you want the value to show up directly in the GUI, you need to refresh it. Therefore we call app->settings->refresh() here.

Storing/retrieving settings in a INI file.

ofxTweakbar was designed in such a way we can store the values in different formats. By default we use a simple data file, but it's also possible to store the settings in a INI file, using the ofxIni addon. For now I'll leave this up to you as an exercise. The example which is part of ofxIni shows how you can store the settings to an ini file. In short we do this:

Add the ofxIni addon to your project
Create an ofxIni instance
Create an ofxTweakbarIni instance
Use retrieve() and store() on this ofxTweakbarIni instance.
Have a look at the example files of this addon.

Note that you can find the storage class in the src_extra directory of the addon.

API

addFloat

ofxTweakbarFloat* addFloat(
  const char* pName
  ,void* pValue
  ,const char* pDef = "min = 0 max=1 step=0.01"
)

addBool

ofxTweakbarBool* addBool(
		const char* pName
		,void *pValue
		,const char* pDef = ""
);

addInt

ofxTweakbarInt* addInt(
		const char* pName
		,void *pValue
		,const char* pDef = "min=0 max=10 step=1"
);

addVec3f

ofxTweakbarVec3f* addVec3f(
		const char* pName
		,void *pValue
		,const char* pDef = ""
);

addColor3f

ofxTweakbarColor3f* addColor3f(
		const char* pName
		,void *pValue
		,const char *pDef = "colormode=rgb"
);

addSeparator

ofxTweakbarSeparator* addSeparator(
		 const char* pName = ""
		,const char* pDef = ""
);

addButton

ofxTweakbarButton* addButton(
		const char* pName
		,TwButtonCallback fCallback
		,void* pClientData = NULL
		,const char* pDef = ""
);

addQuat4f

ofxTweakbarQuat4f* addQuat4f(
		const char* pName
		,void *pValue
		,const char *pDef = ""
);