From 60e3e547bd3f24a550f14d3d0985d2fce0fe5091 Mon Sep 17 00:00:00 2001 From: walterhiggins Date: Sun, 18 Jan 2015 20:27:37 +0000 Subject: [PATCH] Fixes issue #200 - added an extra param 'cancel' to event handlers. when called it will cancel the event (if it's cancelable) --- docs/API-Reference.md | 64 ++++++++++++++++++++++--------- src/main/js/lib/events-bukkit.js | 8 +++- src/main/js/lib/events-canary.js | 11 ++++-- src/main/js/lib/events.js | 65 +++++++++++++++++++++++--------- 4 files changed, 108 insertions(+), 40 deletions(-) diff --git a/docs/API-Reference.md b/docs/API-Reference.md index f0c3365..0decf23 100644 --- a/docs/API-Reference.md +++ b/docs/API-Reference.md @@ -936,27 +936,53 @@ When resolving module names to file paths, ScriptCraft uses the following rules. ## events Module -The Events module provides a thin wrapper around Bukkit's -Event-handling API. Bukkit's Events API makes use of Java Annotations -which are not available in Javascript, so this module provides a -simple way to listen to minecraft events in javascript. +The Events module provides a thin wrapper around CanaryMod's or +Bukkit's Event-handling API. The Java-based CanaryMod and Bukkit +Events APIs make use of Java Annotations which are not available in +Javascript, so this module provides a simple way to listen to +minecraft events in javascript. ### events.on() static method -This method is used to register event listeners. +This method is used to register event listeners. This method is called by all of the Event Helper methods. +The `events` object has functions for registering listeners for each type of event. For example, you can register a block-break listener using events.on: + +```javascript +events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) { + echo(evt.player, evt.player.name + ' broke a block!'); +} ); +``` + +or you can (and probably should) use the more succinct: + +```javascript +events.blockDestroy( function( evt, cancel ) { + echo(evt.player, evt.player.name + ' broke a block!'); +} ); +``` + +The events.on method can be used to register standard CanaryMod/Bukkit +events and can also be used to register non-standard events - that is +- events provided by plugins. #### Parameters - * eventName - A Java class. See [Bukkit API][buk] for details of the many bukkit event types. + * eventType - A Java class. See the [CanaryMod Hook API][cmEvtApi] or [Bukkit Event API][buk] for details of the many event types. * callback - A function which will be called whenever the event - fires. The callback should take a single parameter, event (the event fired). + fires. The callback in turn takes 2 parameters: + + - event : the event fired + - cancel : a function which if invoked will cancel the event - not all event types are cancelable; this function only cancels cancelable events). - * priority (optional - default: "HIGHEST") - The priority the - listener/callback takes over other listeners to the same - event. Possible values are "HIGH", "HIGHEST", "LOW", "LOWEST", - "NORMAL", "MONITOR". For an explanation of what the different - priorities mean refer to bukkit's [Event API Reference][buk2]. + * priority (optional - default: "CRITICAL" for CanaryMod or "HIGHEST" for Bukkit) - + The priority the listener/callback takes over other listeners to the same event. + Possible values for CanaryMod are "CRITICAL", "HIGH", "LOW", "NORMAL" and "PASSIVE". + For an explanation of what the different CanaryMod Hook priorities + mean, refer to CanaryMod's [Hook Priority class][cmPriority]. + Possible values for Bukkit are "HIGH", "HIGHEST", "LOW", "LOWEST", "NORMAL", "MONITOR". + For an explanation of what the different Bukkit Event priorities + mean, refer to bukkit's [Event API Reference][buk2]. #### Returns @@ -967,17 +993,17 @@ An object which can be used to unregister the listener. The following code will print a message on screen every time a block is broken in the game ```javascript -events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { - echo(evt.player, evt.player.name + ' broke a block!'); +events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) { + echo(evt.player, evt.player.name + ' broke a block!'); } ); ``` To handle an event only once and unregister from further events... ```javascript -events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { - echo( evt.player, evt.player.name + ' broke a block!'); - this.unregister(); +events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) { + echo( evt.player, evt.player.name + ' broke a block!'); + this.unregister(); } ); ``` @@ -989,13 +1015,15 @@ object which is returned by the `events.on()` function. To unregister a listener *outside* of the listener function... ```javascript -var myBlockBreakListener = events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { ... } ); +var myBlockBreakListener = events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt ) { ... } ); ... myBlockBreakListener.unregister(); ``` [buk2]: http://wiki.bukkit.org/Event_API_Reference [buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html +[cmEvtApi]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/Hook.html +[cmPriority]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/plugin/Priority.html ## Events Helper Module (canary version) The Events helper module provides a suite of functions - one for each possible event. diff --git a/src/main/js/lib/events-bukkit.js b/src/main/js/lib/events-bukkit.js index b90949b..7cb6335 100644 --- a/src/main/js/lib/events-bukkit.js +++ b/src/main/js/lib/events-bukkit.js @@ -1,3 +1,4 @@ +/*global Java, exports, org, __plugin */ var bkEventPriority = org.bukkit.event.EventPriority, bkEventExecutor = org.bukkit.plugin.EventExecutor, bkRegisteredListener = org.bukkit.plugin.RegisteredListener, @@ -43,7 +44,12 @@ exports.on = function( var result = { }; eventExecutor = new bkEventExecutor( { execute: function( l, evt ) { - handler.call( result, evt ); + function cancel(){ + if (evt instanceof org.bukkit.event.Cancellable){ + evt.setCancelled(true); + } + } + handler.call( result, evt, cancel ); } } ); /* diff --git a/src/main/js/lib/events-canary.js b/src/main/js/lib/events-canary.js index 1b90657..63ba758 100644 --- a/src/main/js/lib/events-canary.js +++ b/src/main/js/lib/events-canary.js @@ -25,12 +25,17 @@ exports.on = function( var result = { }; eventExecutor = __plugin.getDispatcher( function(l,e){ + function cancel(){ + if (e.setCanceled){ + e.setCanceled(); + } + } try { - handler.call(result, e); + handler.call(result, e, cancel); } catch ( error ){ console.log('Error while executing handler:' + handler + - ' for event type:' + eventType + - ' error: ' + error); + ' for event type:' + eventType + + ' error: ' + error); } }); /* diff --git a/src/main/js/lib/events.js b/src/main/js/lib/events.js index 64076dc..4712837 100644 --- a/src/main/js/lib/events.js +++ b/src/main/js/lib/events.js @@ -2,27 +2,53 @@ /************************************************************************ ## events Module -The Events module provides a thin wrapper around Bukkit's -Event-handling API. Bukkit's Events API makes use of Java Annotations -which are not available in Javascript, so this module provides a -simple way to listen to minecraft events in javascript. +The Events module provides a thin wrapper around CanaryMod's or +Bukkit's Event-handling API. The Java-based CanaryMod and Bukkit +Events APIs make use of Java Annotations which are not available in +Javascript, so this module provides a simple way to listen to +minecraft events in javascript. ### events.on() static method -This method is used to register event listeners. +This method is used to register event listeners. This method is called by all of the Event Helper methods. +The `events` object has functions for registering listeners for each type of event. For example, you can register a block-break listener using events.on: + +```javascript +events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) { + echo(evt.player, evt.player.name + ' broke a block!'); +} ); +``` + +or you can (and probably should) use the more succinct: + +```javascript +events.blockDestroy( function( evt, cancel ) { + echo(evt.player, evt.player.name + ' broke a block!'); +} ); +``` + +The events.on method can be used to register standard CanaryMod/Bukkit +events and can also be used to register non-standard events - that is +- events provided by plugins. #### Parameters - * eventName - A Java class. See [Bukkit API][buk] for details of the many bukkit event types. + * eventType - A Java class. See the [CanaryMod Hook API][cmEvtApi] or [Bukkit Event API][buk] for details of the many event types. * callback - A function which will be called whenever the event - fires. The callback should take a single parameter, event (the event fired). + fires. The callback in turn takes 2 parameters: + + - event : the event fired + - cancel : a function which if invoked will cancel the event - not all event types are cancelable; this function only cancels cancelable events). - * priority (optional - default: "HIGHEST") - The priority the - listener/callback takes over other listeners to the same - event. Possible values are "HIGH", "HIGHEST", "LOW", "LOWEST", - "NORMAL", "MONITOR". For an explanation of what the different - priorities mean refer to bukkit's [Event API Reference][buk2]. + * priority (optional - default: "CRITICAL" for CanaryMod or "HIGHEST" for Bukkit) - + The priority the listener/callback takes over other listeners to the same event. + Possible values for CanaryMod are "CRITICAL", "HIGH", "LOW", "NORMAL" and "PASSIVE". + For an explanation of what the different CanaryMod Hook priorities + mean, refer to CanaryMod's [Hook Priority class][cmPriority]. + Possible values for Bukkit are "HIGH", "HIGHEST", "LOW", "LOWEST", "NORMAL", "MONITOR". + For an explanation of what the different Bukkit Event priorities + mean, refer to bukkit's [Event API Reference][buk2]. #### Returns @@ -33,17 +59,17 @@ An object which can be used to unregister the listener. The following code will print a message on screen every time a block is broken in the game ```javascript -events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { - echo(evt.player, evt.player.name + ' broke a block!'); +events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) { + echo(evt.player, evt.player.name + ' broke a block!'); } ); ``` To handle an event only once and unregister from further events... ```javascript -events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { - echo( evt.player, evt.player.name + ' broke a block!'); - this.unregister(); +events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) { + echo( evt.player, evt.player.name + ' broke a block!'); + this.unregister(); } ); ``` @@ -55,16 +81,19 @@ object which is returned by the `events.on()` function. To unregister a listener *outside* of the listener function... ```javascript -var myBlockBreakListener = events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { ... } ); +var myBlockBreakListener = events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt ) { ... } ); ... myBlockBreakListener.unregister(); ``` [buk2]: http://wiki.bukkit.org/Event_API_Reference [buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html +[cmEvtApi]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/hook/Hook.html +[cmPriority]: https://ci.visualillusionsent.net/job/CanaryLib/javadoc/net/canarymod/plugin/Priority.html ***/ var helper; +/*global __plugin, module, require*/ if (__plugin.canary){ module.exports = require('events-canary'); helper = require('events-helper-canary');