ControlP5

ControlP5 is a GUI library written by Andreas Schlegel for the programming environment Processing.

The range of available controllers includes Slider, Button, Toggle, Knob, Textfield, RadioButton, Checkbox, Lists amongst others. These controllers can be easily added to a processing sketch, or displayed inside a separate control window. They can be organized in tabs or groups as well as rendered into PGraphics buffers. The state of a controller can be saved to file in JSON format.

Installation
How does ControlP5 work
Deprecated
History
Android
Javascript
Problems and Issues
Help
Digital Object Identifiers

<a name"install"></a>Installation

To install the library from inside the Processing IDE, use the Library Manager from the menu under Sketch → Import Library → Add Library and search for ControlP5.

If you want to install ControlP5 manually, download (the latest) version from the releases directory. Inside the downloaded .zip file you will find install_instructions that guide you through the installation details and tell you where the controlP5 folder needs to be put. In case you are looking for an earlier release, please check the archive on google code.

After you have installed ControlP5, restart the Processing IDE to make the library available.

Getting Started

To get started, here a simple example that demonstrates how to create a slider and automatically link the slider's value to variable v1.

example 1, see code below


	import controlP5.*;

	ControlP5 cp5;
	int v1;

	void setup() {
	  size(800, 400);  
	  noStroke();
	  cp5 = new ControlP5(this);
	  cp5.addSlider("v1")
	     .setPosition(40, 40)
	     .setSize(200, 20)
	     .setRange(100, 300)
	     .setValue(250)
	     .setColorCaptionLabel(color(20,20,20));
	}

	void draw() {
	  background(200, 200, 200);

	  pushMatrix();

	  pushMatrix();
	  fill(255, 255, 0);
	  rect(v1, 100, 60, 200);
	  fill(0, 255, 110);
	  rect(40, v1, 320, 40);
	  translate(200, 200);
	  rotate(map(v1, 100, 300, -PI, PI));
	  fill(255, 0, 128);
	  rect(0, 0, 100, 100);
	  popMatrix();

	  translate(600, 100);
	  for (int i=0; i<20; i++) {
	    pushMatrix();
	    fill(255);
	    translate(0, i*10);
	    rotate(map(v1+i, 0, 300, -PI, PI));
	    rect(-150, 0, 300, 4);
	    popMatrix();
	  }

	  popMatrix();
	}

example 1 example 2, a range of default ControlP5 controllers

<a name"how"></a>How does ControlP5 work?

ControlP5 provides a range of controllers, each controller comes with an example which is located inside the examples/controllers folder. This is a good place to get started with ControlP5.

Instantiate ControlP5

To create an instance of ControlP5, you need to call ControlP5's constructor and pass a reference of your sketch as argument, in most cases this will happen inside setup() and the argument for the constructor call is this - the reference to the current sketch object.


	import controlP5.*;
	ControlP5 cp5;

	void setup() {
		cp5 = new ControlP5(this);
	}

Alternatively, ControlP5 can be instantiated from other places as well for example from another object. Here, just as before, you need to pass a sketch reference as argument when instantiating the ControlP5 object.


	import controlP5.*;
	GUI gui;

	void setup() {
		gui = new GUI(this);
	}

	class GUI {
		ControlP5 cp5;
		GUI(PApplet thePApplet) {
			cp5 = new ControlP5(thePApplet);
		}
	}

<a name="#controllers"></a>Adding Controllers

To add controllers to a ControlP5 object, use the add function followed by the name of the Controller, for example to add a Slider use cp5.addSlider("mySlider"). Here function addSlider takes one argument which is the unique name of the controller to be added. In case a controller with the same name is already registered with ControlP5, the old controller will be overridden - this is then indicated and printed as a warning message in the console. All default add functions are implemented with class ControlP5Base; have a look at its source code for further reference.


	import controlP5.*;
	ControlP5 cp5;

	void setup() {
		size(400,400);
		cp5 = new ControlP5(this);
		cp5.addSlider("mySlider");
		cp5.addButton("myButton");
	}

	void draw() {}

The example above adds 2 controllers to your sketch and renders them on top of your sketch. To adjust the size, position, color, etc. ControlP5 uses method chaining and setter functions. For example setPosition(x,y) will change the position of a controller, setSize(width,height) will change the size of a controller; the naming convention is straight forward, a function does what it says, and the same goes for the other setters and getters as well. For further reference and overview, start with browsing the source code of class Controller and its implementations, furthermore have a look at the documentation.


	import controlP5.*;
	ControlP5 cp5;

	void setup() {
		size(400,400);
		cp5 = new ControlP5(this);
		cp5.addSlider("mySlider").setPosition(20,20).setSize(200,20);
		cp5.addButton("myButton").setPosition(20,60).setSize(100,40);
	}

	void draw() {}

Accessing Controllers

To access a controller in your program you can store the controller inside a variable, the example below uses a global variable slider as a reference to a Slider with name 'mySlider'


	import controlP5.*;
	ControlP5 cp5;
	Slider slider;
	
	void setup() {
		size(400,400);
		cp5 = new ControlP5(this);
		slider = cp5.addSlider("mySlider");
		slider.setPosition(20,20).setSize(200,20);
	}

	void draw() {
		println(slider.getValue());
	}

or you can access a controller by request using ControlP5's getter functions, this comes in handy if you are working with temporary controllers, or if you do not want to keep a long list of variables.


	import controlP5.*;
	ControlP5 cp5;

	void setup() {
	  size(400, 400);
	  cp5 = new ControlP5(this);
	  cp5.addSlider("mySlider").setPosition(20, 20).setSize(200, 20);
	}

	void draw() {
	  // cp5.getController returns a Controller object
	  Controller c = cp5.getController("mySlider");
	  println(c.getValue());

	  // cp5.get here returns a Slider object
	  Slider slider = cp5.get(Slider.class, "mySlider");
	  println(slider.getMin(), slider.getMax());
	}

Grouping Controllers

Controllers can be grouped in different ways, the 3 options are described in more detail below.

Tab

you can use Tabs to organize Controllers. By default a row of Tabs will be added to the top left corner of your sketch window. The first Tab is the default Tab, hence it's name. the label can be changed by calling the setLabel("new name here") method. To add a Controller to a particular Tab, use method moveTo("name of Tab") with the argument being the name of the Tab. If a Tab does not exist when method moveTo() is called, the Tab will be created automatically.


import controlP5.*;
ControlP5 cp5;

void setup() {
  
  size(400, 400);
  cp5 = new ControlP5(this);
  cp5.addSlider("s1")
     .setPosition(20, 100)
     .setSize(200, 20);
     
  cp5.addSlider("s2")
     .setPosition(20, 130)
     .setSize(200, 20)
     .moveTo("extra")
     ;
     
}

void draw() {
  background(20);
}

Group

Window

What do all these Controllers do?

Accordion use an accordion to arrange multiple groups in vertical order ControlP5accordion
Bang triggers an event on press without passing a value ControlP5bang
Button triggers an event and passes on a value ControlP5button
ButtonBar a horizontal multi-button bar ControlP5buttonBar
Canvas a abstract class to create and display an image buffer ControlP5canvas
CheckBox ControlP5checkBox
ColorPicker a 4 slider color picker to change the red, green, blue and alpha channel of a color ControlP5colorPicker
ColorWheel a color wheel picker, use the arrow on the left to change saturation ControlP5colorWheel
DropdownList (use ScrollableList instead)
Group for grouping and nesting controllers ControlP5group
Icon adds Icon support, an Icon behaves like a Button or Toggle ControlP5icon
ListBox (use ScrollableList instead)
Knob a rotary slider, mousewheel support ControlP5knob
Matrix a 2D array of toggles ControlP5matrix
Numberbox changes values when dragging horizontally or vertically, mousewheel support [ControlP5numberbox](examples/controllers/ControlP5numb

Controlp5

Install / Use

README