Les Event Listeners

Dans le but d’écouter un événement, un event listener doit être inscrit. Cela se fait en créant une méthode, peu importe son nom, ayant pour premier (et seul) paramètre le type de l’événement désiré, et en apposant l’annotation Listener à la méthode, comme illustré ci-dessous.

import org.spongepowered.api.event.Listener;

@Listener
public void onSomeEvent(SomeEvent event) {
    // Do something with the event
}

En plus, la classe contenant ces méthodes doit être inscrite auprès du gestionnaire d’événements:

Astuce

Pour les event listeners présents dans la classe principale de votre plugin (annotée par Plugin), vous n’avez pas besoin d’inscrire son instance car Sponge le fera déjà automatiquement.

Note

The event bus supports supertypes. For example, ChangeBlockEvent.All extends ChangeBlockEvent. Therefore, a plugin could listen to ChangeBlockEvent and still receive ChangeBlockEvent.Alls. However, a plugin listening to just ChangeBlockEvent.All would not be notified of other types of ChangeBlockEvent.

Inscription et Désinscription des Event Listeners

To register event listeners annotated by @Listener that are not in the main plugin class, you can use EventManager#registerListeners(PluginContainer, Object), which accepts a reference to the plugin and an instance of the class containing the event listeners.

Exemple: Inscription des Event Listeners dans d’autres classes

import org.spongepowered.api.Sponge;

public class ExampleListener {

    @Listener
    public void onSomeEvent(SomeEvent event) {
        // Do something with the event
    }
}

Sponge.eventManager().registerListeners(this, new ExampleListener());

Inscription dynamique des Event Listeners

Certains plugins (comme les plugins de scripting) peuvent avoir besoin d’inscrire un event listener dynamiquement. Dans ce cas, l’event listener n’est pas une méthode annotée de @Listener, mais une classe implémentant l’interface EventListener. Cet event listener peut ensuite être inscrit avec la méthode EventManager#registerListener, qui prend en paramètres, dans l’ordre: une référence au plugin, sa Class, et le listener lui-même. Optionnellement, vous pouvez spécifier un ordre Order d’exécution en troisième paramètre (avant l’instance du listener), ou un booléen en quatrième argument qui déterminera s’il faut appeler le listener avant ou bien après toute modification effectuée par le serveur.

Exemple: Implémenter l’interface EventListerner

import org.spongepowered.api.event.EventListener;
import org.spongepowered.api.event.block.ChangeBlockEvent;

public class ExampleListener implements EventListener<ChangeBlockEvent.All> {

    @Override
    public void handle(ChangeBlockEvent.Break event) throws Exception {
        [...]
    }
}

Exemple: Inscription dynamique de l’Event Listener

EventListener<ChangeBlockEvent.All> listener = new ExampleListener();
EventListenerRegistration registeration = EventListenerRegistration
    .builder(ChangeBlockEvent.All.class)
    .listener(listener)
    .plugin(pluginContainer)
    .build();
Sponge.eventManager().registerListener(registeration);

Astuce

Pour les event listeners créés via l’annotation @Listener, l’ordre d’exécution peut être configuré (voir aussi About @Listener). Pour les listeners inscrits dynamiquement cela est possible en passant à la méthode EventManager#registerListener un Order en troisième paramètre.

Désinscription des Event Listeners

Pour désinscrire un seul event listener, vous pouvez utiliser la méthode EventManager#unregisterListeners(Object), qui prend en paramètre une instance de la classe contenant les event listeners.

EventListener listener = ...;
Sponge.getEventManager().unregisterListeners(listener);

Alternativement, vous pouvez utiliser la méthode EventManager#unregisterPluginListeners(Object), en passant en paramètre une instance du plugin, pour désinscrire tous les events listeners qui lui sont associés. Notez que cela inclue ceux inscrits via les annotations @Listener.

PluginContainer plugin = ...;
Sponge.eventManager().unregisterListeners(plugin);

A propos de @Listener

L’annotation @Listener a quelques champs configurables:

order est l’ordre dans lequel l’event listener doit être exécuté. Voir l’énumération Order de SpongeAPI pour voir les options disponibles.
beforeModifications spécifie si l’event listener doit être appelé avant les autres mods serveur, tels que les mods Forge. Par défaut, il est défini sur false.

Par défaut, l’annotation @Listener est configurée de manière à ce que l’event listener ne soit pas appelé si l’événement en question est annulable et a été annulé (par un autre plugin, par exemple).

RefreshGameEvent

To prevent all plugins providing their own reload commands, Sponge provides a built-in callback for plugins to listen to, and when executed, perform any refresh actions. What constitutes as a “refresh action” is purely up to the plugin to decide. The RefreshGameEvent will fire when a player executes the /sponge plugins refresh command. The event is not necessarily limited to reloading configuration.

import org.spongepowered.api.event.lifecycle.RefreshGameEvent;

@Listener
public void refresh(GameRefreshEvent event) {
    // Do refresh stuff
}

Notez que c’est différent de ce qui est généralement considéré “reload”, puisque l’événement est purement une fonction de rappel (Callback) pour les plugins et ne fait lui-même aucun rechargement.

Déclenchement d’Événements

Pour envoyer un événement, vous avez besoin d’un objet qui implémente l’interface Event.

Vous pouvez déclencher des événements en utilisant le bus d’événements (EventManager):

boolean cancelled = Sponge.eventManager().post(theEventObject);

La méthode retourne true si l’événement a été annulé, false sinon.