Events

Introduction

Events let you start a function asynchronously. When an event is broadcast, the event’s callback function is started in its own task (thread), so your main code can continue running at the same time.

Important: An event object stores one callback. If you register another function with the same event object, it replaces the previous callback.

If you want multiple things to happen from one trigger, either:

• Call multiple helper functions from a single callback, or

• Use multiple event objects and broadcast each one.

• Use separate threads to run tasks independently.

In order to create and then use an Event, follow these steps in order:

1. Create the event with event.

2. Set the event’s callback using the event name (ex: myEvent(myCallback);).

3. Broadcast an event:

   • broadcast — Triggers all registered functions in an event object to run in parallel.

   • broadcastAndWait — Triggers all registered functions in an event object and waits for them to finish before continuing.

Create an Event

The event constructor creates an event object. You can create an event with or without a callback.

Default Usage:
event myEvent;

Overload Usages:
event myEvent(callback);

Parameter	Description
myEvent	The name of the event.
callback	A function that is previously defined to execute when the event is broadcasted.

// Create a callback function
void onMyEvent() {
  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Event fired!");
}

int main() {
  vexcodeInit();

  Brain.Screen.print("Broadcasting in 2 seconds...");

  // Create an event called myEvent
  // Set onMyEvent as the callback function
  event myEvent(onMyEvent);

  wait(2, seconds);

  // Trigger the event
  myEvent.broadcast();
}

Set a Callback to an Event

Setting a callback means the function will run when the event is broadcast.

Note: Setting a callback again replaces the previous callback.

Usage:
eventName(callback);

Parameter	Description
eventName	The name of the previously created event object.
callback	A previously defined callback function that is called automatically when the event is broadcast. The function must match the required callback signature. See Callback Functions for more information.

void drawSquare() {
  Brain.Screen.clearScreen();
  Brain.Screen.drawRectangle(40, 40, 120, 120);
}

void drawCircle() {
  Brain.Screen.clearScreen();
  Brain.Screen.drawCircle(100, 100, 60);
}

int main() {
  vexcodeInit();

  // Create the event drawEvent
  event drawEvent;

  Brain.Screen.print("Drawing a square...");

  // Set the event to drawSquare
  drawEvent(drawSquare);

  wait(1, seconds);

  // Trigger the event
  drawEvent.broadcast();

  wait(1, seconds);

  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Drawing a circle...");

  // Replace drawSquare with drawCircle
  drawEvent(drawCircle);

  wait(1, seconds);

  // Trigger the event a second time
  drawEvent.broadcast();
}

Broadcast an Event

broadcast

broadcast starts the event’s callback and continues immediately.

Usage:
myEvent.broadcast();

Parameter	Description
myEvent	The name of the previously created event object.

// Create a callback function
void onMyEvent() {
  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1)
  Brain.Screen.print("Event fired!");
}

int main() {
  vexcodeInit();

  Brain.Screen.print("Broadcasting in 2 seconds...");

  // Create an event called myEvent
  // Set onMyEvent as the callback function
  event myEvent(onMyEvent);

  wait(2, seconds);

  // Trigger the event
  myEvent.broadcast();
}

broadcastAndWait

broadcastAndWait starts the callback and waits until it finishes (or times out).

Note: Use this only with callbacks that end (no infinite loops).

Usage:
myEvent.broadcastAndWait(timeout);

Parameter	Description
myEvent	The name of the previously created event object.
timeout	The amount of milliseconds to wait as a double before the code starts executing again.

void startDriving() {
  Drivetrain.drive(forward);
  wait(2, seconds);
}

int main() {
  vexcodeInit();

  Brain.Screen.print("Starting drive...");

  event driveEvent(startDriving);
  // Give the event time to be set
  wait(0.25, seconds);

  // Run the event and wait until it finishes
  driveEvent.broadcastAndWait();

  // Stop driving after 2 seconds
  Drivetrain.stop();
  Brain.Screen.clearScreen();
  Brain.Screen.print("Drive complete!");
}