Events
# Events
events模块提供了监听手机通知、按键、触摸的接口。您可以用他配合自动操作函数完成自动化工作。
events本身是一个EventEmiiter, 但内置了一些事件、包括按键事件、通知事件、Toast事件等。
需要注意的是，事件的处理是单线程的，并且仍然在原线程执行，如果脚本主体或者其他事件处理中有耗时操作、轮询等，则事件将无法得到及时处理（会进入事件队列等待脚本主体或其他事件处理完成才执行）。例如：
```js
auto();
events.observeNotification();
events.on('toast', function(t){
//这段代码将得不到执行
log(t);
});
while(true){
//死循环
}
```
## events.emitter()
返回一个新的EventEmitter。这个EventEmitter没有内置任何事件。
## events.observeKey()
启用按键监听，例如音量键、Home键。按键监听使用无障碍服务实现，如果无障碍服务未启用会抛出异常并提示开启。
只有这个函数成功执行后, onKeyDown, onKeyUp等按键事件的监听才有效。
>w 该函数在安卓4.3以上才能使用。
## events.onKeyDown(keyName, listener)
- keyName {string} 要监听的按键名称
- listener {Function} 按键监听器。参数为一个KeyEvent。
注册一个按键监听函数，当有keyName对应的按键被按下会调用该函数。可用的按键名称参见Keys。
例如:
```js
//启用按键监听
events.observeKey();
//监听音量上键按下
events.onKeyDown("volume_up", function(event){
toast("音量上键被按下了");
});
//监听菜单键按下
events.onKeyDown("menu", function(event){
toast("菜单键被按下了");
exit();
});
```
> 以下非官方例子
长按返回退出当前程序：
```js
auto();
var 长按间隔 = 1500;
var timeoutId = null;
events.observeKey();
events.onKeyDown("back", function(event){
timeoutId = setTimeout(function(){
exitCurrentApp();
}, 长按间隔);
});
events.onKeyUp("back", function(event){
clearTimeout(timeoutId);
});
function exitCurrentApp(){
shell("am force-stop " + getCurrentPackage(), true);
};
```
## events.onKeyUp(keyName, listener)
- keyName {string} 要监听的按键名称
- listener {Function} 按键监听器。参数为一个KeyEvent。
注册一个按键监听函数，当有keyName对应的按键弹起会调用该函数。可用的按键名称参见Keys。
一次完整的按键动作包括了按键按下和弹起。按下事件会在手指按下一个按键的"瞬间"触发, 弹起事件则在手指放开这个按键时触发。
例如:
```js
//启用按键监听
events.observeKey();
//监听音量下键弹起
events.onKeyDown("volume_down", function(event){
toast("音量上键弹起");
});
//监听Home键弹起
events.onKeyDown("home", function(event){
toast("Home键弹起");
exit();
});
```
## events.onceKeyDown(keyName, listener)
- keyName {string} 要监听的按键名称
- listener {Function} 按键监听器。参数为一个KeyEvent
注册一个按键监听函数，当有keyName对应的按键被按下时会调用该函数，之后会注销该按键监听器。
也就是listener只有在onceKeyDown调用后的第一次按键事件被调用一次。
## events.onceKeyUp(keyName, listener)
- keyName {string} 要监听的按键名称
- listener {Function} 按键监听器。参数为一个KeyEvent
注册一个按键监听函数，当有keyName对应的按键弹起时会调用该函数，之后会注销该按键监听器。
也就是listener只有在onceKeyUp调用后的第一次按键事件被调用一次。
## events.removeAllKeyDownListeners(keyName)
- keyName {string} 按键名称
删除该按键的KeyDown(按下)事件的所有监听。
## events.removeAllKeyUpListeners(keyName)
- keyName {string} 按键名称
删除该按键的KeyUp(弹起)事件的所有监听。
## events.setKeyInterceptionEnabled([key, ]enabled)
- enabled {boolean}
- key {string} 要屏蔽的按键
设置按键屏蔽是否启用。所谓按键屏蔽指的是，屏蔽原有按键的功能，例如使得音量键不再能调节音量，但此时仍然能通过按键事件监听按键。
如果不加参数key则会屏蔽所有按键。
例如，调用events.setKeyInterceptionEnabled(true)会使系统的音量、Home、返回等键不再具有调节音量、回到主页、返回的作用，但此时仍然能通过按键事件监听按键。
该函数通常于按键监听结合。
>s 例如，想监听音量键并使音量键按下时不弹出音量调节框则为：
```js
events.setKeyInterceptionEnabled("volume_up", true);
events.observeKey();
events.onKeyDown("volume_up", ()=>{
log("音量上键被按下");
});
```
> 只要有一个脚本屏蔽了某个按键，该按键便会被屏蔽；当脚本退出时，会自动解除所有按键屏蔽。
## events.observeTouch()
启用屏幕触摸监听。（需要root权限）
只有这个函数被成功执行后, 触摸事件的监听才有效。
没有root权限调用该函数则什么也不会发生。
## events.setTouchEventTimeout(timeout)
- timeout {number} 两个触摸事件的最小间隔。单位毫秒。默认为10毫秒。如果number小于0，视为0处理。
设置两个触摸事件分发的最小时间间隔。
例如间隔为10毫秒的话，前一个触摸事件发生并被注册的监听器处理后，至少要过10毫秒才能分发和处理下一个触摸事件，这10毫秒之间的触摸将会被忽略。
建议在满足需要的情况下尽量提高这个间隔。一个简单滑动动作可能会连续触发上百个触摸事件，如果timeout设置过低可能造成事件拥堵。强烈建议不要设置timeout为0。
## events.getTouchEventTimeout()
返回触摸事件的最小时间间隔。
## events.onTouch(listener)
- listener {Function} 参数为Point的函数
注册一个触摸监听函数。相当于on("touch", listener)。
例如:
```js
//启用触摸监听
events.observeTouch();
//注册触摸监听器
events.onTouch(function(p){
//触摸事件发生时, 打印出触摸的点的坐标
log(p.x + ", " + p.y);
});
```
## events.removeAllTouchListeners()
删除所有事件监听函数。
## 事件: 'key'
- keyCode {number} 键值
- event {KeyEvent} 事件
当有按键被按下或弹起时会触发该事件。 例如：
```js
auto();
events.observeKey();
events.on("key", function(keyCode, event){
//处理按键事件
});
```
其中监听器的参数KeyCode包括：
1. keys.home 主页键
2. keys.back 返回键
3. keys.menu 菜单键
4. keys.volume_up 音量上键
5. keys.volume_down 音量下键
例如：
```js
auto();
events.observeKey();
events.on("key", function(keyCode, event){
if(keyCode == keys.menu && event.getAction() == event.ACTION_UP){
toast("菜单键按下");
}
});
```
## 事件: 'key_down'
- keyCode {number} 键值
- event {KeyEvent} 事件
当有按键被按下时会触发该事件。
```js
auto();
events.observeKey();
events.on("key_down", function(keyCode, event){
//处理按键按下事件
});
```
## 事件: 'key_up'
- keyCode {number} 键值
- event {KeyEvent} 事件
当有按键弹起时会触发该事件。
```js
auto();
events.observeKey();
events.on("key_up", function(keyCode, event){
//处理按键弹起事件
});
```
## 事件: 'exit`
当脚本正常或者异常退出时会触发该事件。事件处理中如果有异常抛出，则立即中止exit事件的处理（即使exit事件有多个处理函数）并在控制台和日志中打印该异常。
一个脚本停止运行时，会关闭该脚本的所有悬浮窗，触发exit事件，之后再回收资源。如果exit事件的处理中有死循环，则后续资源无法得到及时回收。 此时脚本会停留在任务列表，如果在任务列表中关闭，则会强制结束exit事件的处理并回收后续资源。
```js
log("开始运行")
events.on("exit", function(){
log("结束运行");
});
log("即将结束运行");
```
## events.observeNotification()
开启通知监听。例如QQ消息、微信消息、推送等通知。
通知监听依赖于通知服务，如果通知服务没有运行，会抛出异常并跳转到通知权限开启界面。（有时即使通知权限已经开启通知服务也没有运行，这时需要关闭权限再重新开启一次）
例如：
```js
events.obverseNotification();
events.onNotification(function(notification){
log(notification.getText());
});
```
## events.observeToast()
开启Toast监听。
Toast监听依赖于无障碍服务，因此此函数会确保无障碍服务运行。
## 事件: 'toast'
toast {Object}
getText() 获取Toast的文本内容
getPackageName() 获取发出Toast的应用包名
当有应用发出toast(气泡消息)时会触发该事件。但Auto.js软件本身的toast除外。
例如，要记录发出所有toast的应用：
```js
events.observeToast();
events.onToast(function(toast){
log("Toast内容: " + toast.getText() + " 包名: " + toast.getPackageName());
});
```
## 事件: 'notification'
notification Notification 通知对象
当有应用发出通知时会触发该事件，参数为Notification。
例如：
```js
events.observeNotification();
events.on("notification", function(n){
log("收到新通知:\n 标题: %s, 内容: %s, \n包名: %s", n.getTitle(), n.getText(), n.getPackageName());
});
```