EventListener

EventListener

Any of your classes can implement the EventListener interface, making it registrable within the EventBus and ready to begin handling events.

Implementing the interface

public class MyEventListener implements EventListener {
	// Your handling code here...
}

Registering the listener

EventBus bus = EventBus.getDefault();
bus.register(new MyEventListener());

Tip

This example uses the default interface of EventBus.

Handling events

You are now ready to handle your first event – See how to create an event.

All you need to do is annotate a method with the EventHandler tag and accept the event you wish to handle as its only parameter.

public class MyEventListener implements EventListener {
	@EventHandler
	public void onTestEvent(TestEvent event) {
		// Only invoked when a TestEvent or a derivate of the class is fired.
	}
}

Important

When handling an event, derivatives of the specified class will also trigger the method, unless stated otherwise in the EventHandler tag

Priority

It's possible to choose a priority for each EventHandler by specifying the priority in the annotation.

Priorities

The lower the priority, the sooner the handler is invoked, meaning that it has the lowest priority regarding the result of the operation, as it can be overwritten by any handler with higher priority.

List of valid priorities:

1. LOWEST
2. LOW
3. NORMAL
4. HIGH
5. HIGHEST
6. MONITOR

Note

The MONITOR priority should only be used to monitor the result of an event and shouldn't change the event's response.

Important

In addition, event handlers with the MONITOR priority are always triggered, whether the event was cancelled or its immediate propagation stopped.

Handling with priority

public class MyEventListener implements EventListener {
	@EventHandler(priority = EventPriority.HIGH)
	public void onTestEvent(TestEvent event) {
		// Invoked second
		event.setTestString("NewValue");
		// Overwrites the test string that had been set by the lower priority handler
	}

	@EventHandler(priority = EventPriority.LOW)
	public void onTestEventLow(TestEvent event) {
		// Invoked first
		event.setTestString("Value");
		// This test string will be overwritten by the higher priority handler
	}
}

Not handling derivatives

To only listen for the event itself and none of its subclasses the EventHandler annotation comes with an handleDerivatives boolean, which defaults to true

public class MyEventListener implements EventListener {
	@EventHandler(handleDerivatives = false)
	public void onTestEvent(TestEvent event) {
		// Only invoked when a TestEvent is fired, not for any class that extends TestEvent.
	}
}

Skip Cancelled Events

To ensure your event handler skips over events that have been cancelled, you can use the ignoreCancelled attribute of the @EventHandler annotation. Setting ignoreCancelled to true means that if an event is cancelled before reaching your handler, it won't be called, allowing you to focus on handling only the events that are still active.

Here's how you can implement it:

public class MyEventListener implements EventListener {
	@EventHandler(ignoreCancelled = true)
	public void onTestEvent(TestEvent event) {
		// Cancelled events won't trigger this event handler.
	}
}

This feature is particularly useful for event handlers that should only execute if the event is proceeding as planned, such as actions directly dependent on the outcome of earlier event handlers.