Goals

  • Understanding Events and Listeners
    • Components Generate Events
    • Events and the Event Class
    • Listeners and Event Handlers
    • ControlP5 Example
    • import ControlP5

Resources

ControlP5
ControlP5 Example
Java World - Events

"A chief event of life is the day in which we have encountered a mind that startled us." ~ Ralph Waldo Emerson

Components

A special object, one that belongs to a larger system is usually referred to in the Java world as a component. These components usually have some relationship with other parts of a library that performs a certain function.

For this lesson in Events and Listeners we will be looking a the ControlP5 library, components of the library are:

  • Bang - on mouse press
  • Button - on mouse release
  • Toggle - on and off
  • Slider - values
  • Knob - values
  • Number Box - values

Components of the ControlP5 library are called components and not objects because they are related to the rest of the library. Simply making a new ControlP5 Button is not enough to use the library.

Each component will generate events. However, these events do nothing without a proper listener.

A component is an object that is part of a library which usually must be used in combination with other library components to perform functions.

Events

In the Event Listener pattern we have already seen components. We also know that components generate events. But what are events and how are they used?

An event in the Java world is an instance of some event class, which usually describes the events. Event objects represent the who, what, where, when, why, and how of the event that occurred. Here is an example

  • User presses Button
  • Button generates new "MouseEvent" object
  • "MouseEvent" object has fields for mouseX, mouseY, mouseButton
  • "MouseEvent" fields are initialized by Button
  • On next loop, Listener receives "MouseEvent"

Events come in all different kinds:

  • Mouse Interaction
  • Keyboard Interaction
  • Touch Interaction
  • Data Received
  • Data Analyzed
  • and more...

Making Custom Events

Creating your own event classes that can represent custom events can be extremely useful. If your application works with a lot of data input or special types of user interaction, you will probably want to look at building your own event model.

Events are simply objects that capture an instance of data input.
Components generate Events and initialize their fields so the instance of the Event is captured and can be interpreted by the Listener.

Listeners and Event Handlers

Now that we know what a Component and Event are we can talk about the crucial piece of the Event Listener pattern that must exist for anything to happen: the Listener method, commonly referred to as the Event Handler.

We've actually been using 2 (sometimes more) listeners in our sketches the entire time. Let's take a look:

void setup() { ... } //this method is an event handler
setup will listen for the event that the sketch has started
Once the event is fired, the setup method is called

void draw() { ... } //this method is an event handler
draw listens for a special timer event based on the frameRate set in your sketch
Once the event is fired, the draw method is called

void keyPressed() { ... } //this method is an event handler
keyPressed listens for an event based on any key on the keyboard being pressed
Once the event is fired, the keyPressed method is called

void mousePressed() { ... } //this method is an event handler
We know what this method does...

Traditional Event Handlers

The Listener methods built into processing are special to the processing language, and some don't behave like a traditional Event Handler method. Normally, every Event Handler has a parameter to receive the Event that was fired. When using ControlP5 this is true. Let's see an example:

Notice the parameter to the controlEvent method is a reference variable of the type ControlEvent? This is the actual event that was generated by one of the ControlP5 components in our sketch.

When the component was interacted with, it generated an instance of ControlEvent and populated it's fields. Since the component was only a simple button, the event only knows that it was activated by a controller and has the name of that controller stored in one of it's fields.

Finally, since all the information stored in an event is Private, in order to query the ControlEvent object, we must access it's fields through public methods that will return the correct information to us.

Listeners (Event Handlers) are special methods that are called when events are fired.
A Listener method has a parameter of type Event, and should query that Event parameter to determine what course of action to take.

Save your sketch somewhere.

Download controlP5 here.

Unzip the file in the libraries folder named "controlP5.jar".

Use the sketch menu, select "Add File", add "controlP5.jar" to the sketch.

Double check now that "controlP5.jar" is inside a folder named "code" in your sketch folder.

Add the following line to your sketch at the beginning:
import controlP5.*;