tutorial 3.3:

Working with interaction using the controlP5 library

In this tutorial we will work with a contributed library for Processing. The many available libraries add functionality to Processing, allowing you to more easily accomplish certain types of programming tasks. ControlP5 is a library that provides a range of graphic elements such as sliders, checkboxes, and buttons that can be used to interactively control aspects of your visualization.



You will first need to download the controlP5 library here, and unzip controlP5 in the 'libraries' folder within your Processing sketchbook. Restart Processing, and you should then be able to access the examples for controlP5 under 'contributed libraries' in the examples list (File > Examples). You can learn about the types of functions available using this library by looking at the examples and by reading the online documentation.

1) Start your sketch by importing the controlP5 library.

This must be in the first lines of your code, before you declare any variables.

import controlP5.*;    // import controlP5 library



2) Declare a new controlP5 object

In object-oriented syntax you need to declare a name for your object before using the constructor function to create a new instance of this object. In the code below, 'ControlP5' is the name of the class and 'cp5' is the name for the particular instance of this class that I will use in the example. A Class is a structure that contains data structures and methods, or functions, which allow you to do particular things with an instance of that class.

ControlP5 cp5;   // controlP5 object

This declaration must happen at the beginning of the sketch, before the setup().

3) Add graphic elements using the 'cp5' object in the setup().

Using dot-syntax, we can access the methods of the ControlP5 class in order to create graphic elements and define their characteristics:

cp5 = new ControlP5(this);

// description : a toggle can have two states, true and false
cp5.addToggle("toggle_display")
 .setPosition(370, 30)
 .setSize(40,20)
 .setValue(true)
 .setMode(ControlP5.SWITCH)
 ;

// description : a slider is either used horizontally or vertically.
//               width is bigger, you get a horizontal slider
//               height is bigger, you get a vertical slider.  
cp5.addSlider("mySlider")
 .setPosition(370, 70)
 .setSize(20,200)
 .setRange(0,18)
 .setValue(5)
 ;



4) Create functions to define the response to change in these interactive elements.

ControlP5 allows you to monitor change in each of the graphic elements you create using a function with the same name:

void toggle_display(boolean theFlag) {
  if(theFlag==true) {
    displayType = 1;
  } else {
    displayType = 2;
  }
  println("a toggle event.");
}

void mySlider(float theValue) {
  colorThreshold = int(theValue);
  println("a slider event. colorThreshold  "+colorThreshold);
}



5) Do something with the input from the sliders

You can use the input from sliders to filter the data, change the way the data is displayed, or introduce other aspects of interactivity to your visualization.



You can download the full text for this example here.