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
Le bus d’événements supporte les supertypes. Par exemple, la classe ChangeBlockEvent.Break hérite de la classe ChangeBlockEvent. Donc un plugin pourrait écouter l’événement ChangeBlockEvent
et toujours recevoir des événements ChangeBlockEvent.Break
. Toutefois, un plugin n’écoutant que l’événement ChangeBlockEvent.Break
ne sera pas averti des autres types de l’événement ChangeBlockEvent
.
Inscription et Désinscription des Event Listeners
Pour enregistrer les event listeners annotés de @Listener
qui ne sont pas dans la classe principale de votre plugin, vous pouvez utiliser la méthode EventManager#registerListeners(Object, Object), qui pend en paramètres une instance du plugin et une instance de la classe contenant les events 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.getEventManager().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.Break> {
@Override
public void handle(ChangeBlockEvent.Break event) throws Exception {
...
}
}
Exemple: Inscription dynamique de l’Event Listener
EventListener<ChangeBlockEvent.Break> listener = new ExampleListener();
Sponge.getEventManager().registerListener(this, ChangeBlockEvent.Break.class, listener);
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
.
MyPlugin plugin = ...
Sponge.getEventManager().unregisterPluginListeners(plugin);
A propos de @Listener
L’annotation @Listener
a quelques champs configurables:
order
est l’ordre dans lequel le gestionnaire d’événement doit être exécuté. Voir l’énumération Order de Sponge 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).
GameReloadEvent
Pour éviter que tous les plugins fournissent leur propre commande de reload, Sponge fournit une une fonction de rappel (Callback) pour que les plugins puissent l’écouter, et quand elle est exécutée, effectuer une action de rechargement. C’est au plugin de décider ce qui constitue l””action de rechargement”. Le GameReloadEvent est appelé quand un joueur exécute la commande /sponge plugins reload
. L’événement n’est pas nécessairement restraint à recharger la configuration.
import org.spongepowered.api.event.game.GameReloadEvent;
@Listener
public void reload(GameReloadEvent event) {
// Do reload 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.getEventManager().post(theEventObject);
La méthode retourne true
si l’événement a été annulé, false
sinon.
Déclenchement d’Événements Sponge
Il est possible de générer des instances d’événements intégrés avec la SpongeEventFactory
statique. Cette classe est générée automatiquement, donc il n’y a pas de Javadocs. Utilisez l’autocomplétion de votre IDE pour lister les méthodes existantes. Les événements créés par la SpongeEventFactory
sont alors passés au EventManager#post(Event).
Example: Le LightningEvent
import org.spongepowered.api.event.SpongeEventFactory;
import org.spongepowered.api.event.action.LightningEvent;
import org.spongepowered.api.event.cause.Cause;
LightningEvent lightningEvent = SpongeEventFactory.createLightningEvent(Cause.source(plugin).build());
Sponge.getEventManager().post(lightningEvent);
Avertissement
Une Cause ne peut jamais être vide. Au minimum, elle devrait contenir votre plugin.