arg/scriptcraft
Archived
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Fixes issue #200 - added an extra param 'cancel' to event handlers. when called it will cancel the event (if it's cancelable)

Browse source
This commit is contained in:
walterhiggins 2015-01-18 20:27:37 +00:00
parent de5c95114f
commit 60e3e547bd
4 changed files with 108 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
docs/API-Reference.md
View file

@ -936,27 +936,53 @@ When resolving module names to file paths, ScriptCraft uses the following rules.
## events Module ## events Module
The Events module provides a thin wrapper around Bukkit's The Events module provides a thin wrapper around CanaryMod's or
Event-handling API. Bukkit's Events API makes use of Java Annotations Bukkit's Event-handling API. The Java-based CanaryMod and Bukkit
which are not available in Javascript, so this module provides a Events APIs make use of Java Annotations which are not available in
simple way to listen to minecraft events in javascript. Javascript, so this module provides a simple way to listen to
minecraft events in javascript.
### events.on() static method ### 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 #### 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 * 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:
* priority (optional - default: "HIGHEST") - The priority the - event : the event fired
listener/callback takes over other listeners to the same - cancel : a function which if invoked will cancel the event - not all event types are cancelable; this function only cancels cancelable events).
event. Possible values are "HIGH", "HIGHEST", "LOW", "LOWEST",
"NORMAL", "MONITOR". For an explanation of what the different * priority (optional - default: "CRITICAL" for CanaryMod or "HIGHEST" for Bukkit) -
priorities mean refer to bukkit's [Event API Reference][buk2]. 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 #### Returns
@ -967,7 +993,7 @@ 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 The following code will print a message on screen every time a block is broken in the game
```javascript ```javascript
events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) {
echo(evt.player, evt.player.name + ' broke a block!'); echo(evt.player, evt.player.name + ' broke a block!');
} ); } );
``` ```
@ -975,7 +1001,7 @@ events.on( org.bukkit.block.BlockBreakEvent, function( evt ) {
To handle an event only once and unregister from further events... To handle an event only once and unregister from further events...
```javascript ```javascript
events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) {
echo( evt.player, evt.player.name + ' broke a block!'); echo( evt.player, evt.player.name + ' broke a block!');
this.unregister(); this.unregister();
} ); } );
@ -989,13 +1015,15 @@ object which is returned by the `events.on()` function.
To unregister a listener *outside* of the listener function... To unregister a listener *outside* of the listener function...
```javascript ```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(); myBlockBreakListener.unregister();
``` ```
[buk2]: http://wiki.bukkit.org/Event_API_Reference [buk2]: http://wiki.bukkit.org/Event_API_Reference
[buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html [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) ## Events Helper Module (canary version)
The Events helper module provides a suite of functions - one for each possible event. The Events helper module provides a suite of functions - one for each possible event.

8
src/main/js/lib/events-bukkit.js
View file

@ -1,3 +1,4 @@
/*global Java, exports, org, __plugin */
var bkEventPriority = org.bukkit.event.EventPriority, var bkEventPriority = org.bukkit.event.EventPriority,
bkEventExecutor = org.bukkit.plugin.EventExecutor, bkEventExecutor = org.bukkit.plugin.EventExecutor,
bkRegisteredListener = org.bukkit.plugin.RegisteredListener, bkRegisteredListener = org.bukkit.plugin.RegisteredListener,
@ -43,7 +44,12 @@ exports.on = function(
var result = { }; var result = { };
eventExecutor = new bkEventExecutor( { eventExecutor = new bkEventExecutor( {
execute: function( l, evt ) { 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 );
} }
} ); } );
/* /*

7
src/main/js/lib/events-canary.js
View file

@ -25,8 +25,13 @@ exports.on = function(
var result = { }; var result = { };
eventExecutor = __plugin.getDispatcher( function(l,e){ eventExecutor = __plugin.getDispatcher( function(l,e){
function cancel(){
if (e.setCanceled){
e.setCanceled();
}
}
try { try {
handler.call(result, e); handler.call(result, e, cancel);
} catch ( error ){ } catch ( error ){
console.log('Error while executing handler:' + handler + console.log('Error while executing handler:' + handler +
' for event type:' + eventType + ' for event type:' + eventType +

59
src/main/js/lib/events.js
View file

@ -2,27 +2,53 @@
/************************************************************************ /************************************************************************
## events Module ## events Module
The Events module provides a thin wrapper around Bukkit's The Events module provides a thin wrapper around CanaryMod's or
Event-handling API. Bukkit's Events API makes use of Java Annotations Bukkit's Event-handling API. The Java-based CanaryMod and Bukkit
which are not available in Javascript, so this module provides a Events APIs make use of Java Annotations which are not available in
simple way to listen to minecraft events in javascript. Javascript, so this module provides a simple way to listen to
minecraft events in javascript.
### events.on() static method ### 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 #### 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 * 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:
* priority (optional - default: "HIGHEST") - The priority the - event : the event fired
listener/callback takes over other listeners to the same - cancel : a function which if invoked will cancel the event - not all event types are cancelable; this function only cancels cancelable events).
event. Possible values are "HIGH", "HIGHEST", "LOW", "LOWEST",
"NORMAL", "MONITOR". For an explanation of what the different * priority (optional - default: "CRITICAL" for CanaryMod or "HIGHEST" for Bukkit) -
priorities mean refer to bukkit's [Event API Reference][buk2]. 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 #### Returns
@ -33,7 +59,7 @@ 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 The following code will print a message on screen every time a block is broken in the game
```javascript ```javascript
events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) {
echo(evt.player, evt.player.name + ' broke a block!'); echo(evt.player, evt.player.name + ' broke a block!');
} ); } );
``` ```
@ -41,7 +67,7 @@ events.on( org.bukkit.block.BlockBreakEvent, function( evt ) {
To handle an event only once and unregister from further events... To handle an event only once and unregister from further events...
```javascript ```javascript
events.on( org.bukkit.block.BlockBreakEvent, function( evt ) { events.on( Packages.net.canarymod.hook.player.BlockDestroyHook, function( evt, cancel ) {
echo( evt.player, evt.player.name + ' broke a block!'); echo( evt.player, evt.player.name + ' broke a block!');
this.unregister(); this.unregister();
} ); } );
@ -55,16 +81,19 @@ object which is returned by the `events.on()` function.
To unregister a listener *outside* of the listener function... To unregister a listener *outside* of the listener function...
```javascript ```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(); myBlockBreakListener.unregister();
``` ```
[buk2]: http://wiki.bukkit.org/Event_API_Reference [buk2]: http://wiki.bukkit.org/Event_API_Reference
[buk]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/event/Event.html [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; var helper;
/*global __plugin, module, require*/
if (__plugin.canary){ if (__plugin.canary){
module.exports = require('events-canary'); module.exports = require('events-canary');
helper = require('events-helper-canary'); helper = require('events-helper-canary');