This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
api:event:zh [2023/09/24 10:00] hfsr [Functions] translate to zh_cn |
api:event:zh [2023/10/12 17:25] hfsr [概述] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Event(事件) API ====== | ====== Event(事件) API ====== | ||
| - | Event(事件) API为用户提供了一套基本的事件处理系统，可利用其编写响应操作系统或其他程序/运行库传递的[[component:signals|signals]]代码。 | + | Event(事件) API为用户提供了一套基本的事件处理系统，可利用其编写代码以响应操作系统或其他程序/运行库传递的[[component:signals|信号]]。 |
| 例如，你可以利用此API捕获按下的按键、在外接显示器连接到电脑或断开连接时进行响应，或是处理传入的网络信息。 | 例如，你可以利用此API捕获按下的按键、在外接显示器连接到电脑或断开连接时进行响应，或是处理传入的网络信息。 | ||
| Line 7: | Line 7: | ||
| event API主要有两种用法: | event API主要有两种用法: | ||
| - | - 让程序在后台运行时能够对事件作出响应(驱动模式)。 | + | - 让程序在后台运行时对事件作出响应(驱动模式)。 |
| - 让程序在作为前台程序执行时处理事件(优先模式)。 | - 让程序在作为前台程序执行时处理事件(优先模式)。 | ||
| Line 13: | Line 13: | ||
| 而在优先模式下，你无需在程序中注册事件，可以直接使用`events.pull()`函数进行处理。 | 而在优先模式下，你无需在程序中注册事件，可以直接使用`events.pull()`函数进行处理。 | ||
| - | //注意://虽然从技术层面上讲可以同时使用两种工作模式，但不推荐这样做。为了保证所有进行了注册的函数都能接收到事件，事件的一次触发只有在所有函数都被调用后才算结束。因此如果你将处理函数(handler)进行了注册，又执行了拉取(pull)操作，那么同一个事件会被响应两次。 | + | //注意://虽然从技术层面上讲可以同时使用两种工作模式，但不推荐这样做。为了保证所有已注册的函数都能接收到事件，事件的一次触发只有在所有函数都被调用后才算结束。因此如果你将处理函数(handler)进行了注册，又执行了拉取(pull)操作，那么同一个事件会被响应两次。 |
| ===== 函数 ===== | ===== 函数 ===== | ||
| Line 85: | Line 85: | ||
| - | ===== Interrupts ===== | + | ===== 中断 ===== |
| - | Starting In OpenOS 1.6.4 and later, interrupts have been cleaned up. The following two methods are now obsolete | + | 在OpenOS 1.6.4及更高版本，中断功能已经被删除。下列两个函数现在已经过时。 |
| - | - `event.shouldSoftInterrupt(): boolean` (Since 1.5.9 and removed in 1.6.4) | + | - `event.shouldSoftInterrupt(): boolean` (自1.5.9起添加，在1.6.4被移除) |
| - | - `event.shouldInterrupt(): boolean` (Since 1.5.9 and removed in 1.6.4) | + | - `event.shouldInterrupt(): boolean` (自1.5.9起添加，在1.6.4被移除) |
| - | Interrupts are a type of messaging intended to close or stop a process. In OpenOS the `computer.pullSignal()`, and thus any wrapper, generates 2 types of events. | + | 中断是一类用于关闭或停止进程的消息。在OpenOS中`computer.pullSignal()`函数和修饰过的此函数会产生两种类型的事件。 |
| - | They are especially useful when `event.pull*()` is called without time limit and with a filter. In some cases this means that `event.pull*()` could be waiting indefinitely. | + | 若`event.pull*()`函数在指定了过滤器但不指定超时时间的情况下执行，一定情况下意味着无限期执行。这两种事件非常有用。 |
| - | - Soft interrupts are an event signal generated by pressing `Ctrl+C`. The signal returns two fields, the event name `"interrupted"` and the computer uptime | + | - 软件中断是在按下`Ctrl+C`时产生的事件信号。信号包含两个参数，事件名称`"interrupted"` (中断)和电脑运行时间。 |
| - | - Hard interrupts are generated by pressing `Ctrl-Alt-C`. It forcibly exits the `event.pull*()` method by throwing a `"interrupted"` error. | + | - 硬件中断在按下`Ctrl-Alt-C`时产生。它会通过抛出`"interrupted"`(中断)异常以强制停止`event.pull*()`函数。 |
| - | ===== Basic event example ===== | + | ===== 简易事件处理样例 ===== |
| - | Typically user scripts care about one or two events, and don't care to handle the rest. It is good to handle "interrupted" for soft interrupts. | + | 通常用户编写的脚本只会涉及一两个事件，不涉及其他事件的处理。建议将"interrupted"事件作为软件中断处理。 |
| ```lua | ```lua | ||
| Line 114: | Line 114: | ||
| ``` | ``` | ||
| - | ===== General purpose event handler ===== | + | ===== 通用事件处理函数 ===== |
| - | Here is a clever solution for providing a general purpose event handler. In this example the primary functionality uses the event id returned by `event.pull()` as a key for a table of callbacks, using metamethods to handle undefined events. Note that `event.pull` puts the program on hold until there is an event available. | + | 此处提供了一个较好的通用事件处理函数。此样例的主要功能是以`event.pull()`函数返回的事件ID作为回调函数列表的键，用元方法来处理未定义事件。请注意`event.pull`函数会让程序进入等待状态，直到出现可用事件。 |
| ```lua | ```lua | ||
| - | local event = require "event" -- load event table and store the pointer to it in event | + | local event = require "event" --加载事件列表，将指向它们的指针存储到event变量中 |
| - | local char_space = string.byte(" ") -- numerical representation of the space char | + | local char_space = string.byte(" ") --用数字代替空格字符 |
| - | local running = true -- state variable so the loop can terminate | + | local running = true --存储状态的变量，便于循环停止执行 |
| function unknownEvent() | function unknownEvent() | ||
| - | -- do nothing if the event wasn't relevant | + | --如果事件为无关事件，则不进行处理 |
| end | end | ||
| - | -- table that holds all event handlers | + | --存储所有事件处理函数的列表 |
| - | -- in case no match can be found returns the dummy function unknownEvent | + | --会返回占位假函数unknownEvent，以防无法匹配 |
| local myEventHandlers = setmetatable({}, { __index = function() return unknownEvent end }) | local myEventHandlers = setmetatable({}, { __index = function() return unknownEvent end }) | ||
| - | -- Example key-handler that simply sets running to false if the user hits space | + | --简易按键处理函数样例，当用户按下空格键时将running变量设为false |
| function myEventHandlers.key_up(adress, char, code, playerName) | function myEventHandlers.key_up(adress, char, code, playerName) | ||
| if (char == char_space) then | if (char == char_space) then | ||
| Line 138: | Line 138: | ||
| end | end | ||
| - | -- The main event handler as function to separate eventID from the remaining arguments | + | --主事件处理函数，将事件ID(eventID)从其他参数中分离出来 |
| function handleEvent(eventID, ...) | function handleEvent(eventID, ...) | ||
| - | if (eventID) then -- can be nil if no event was pulled for some time | + | if (eventID) then --如果一段时间内没有事件被拉取，值可能为nil |
| - | myEventHandlers[eventID](...) -- call the appropriate event handler with all remaining arguments | + | myEventHandlers[eventID](...) --调用对应的事件处理函数，并传递剩下的所有参数 |
| end | end | ||
| end | end | ||
| - | -- main event loop which processes all events, or sleeps if there is nothing to do | + | --主事件拉取循环，处理所有事件。在没有任务时会等待。 |
| while running do | while running do | ||
| - | handleEvent(event.pull()) -- sleeps until an event is available, then process it | + | handleEvent(event.pull()) --等待可用事件出现，然后进行处理 |
| end | end | ||
| ``` | ``` | ||
| - | If you work in driver mode, you need to register the events instead, by either registering a global event handler like the one in the example above, or by registering each individual handler on its own. If you would write the example above to work in the background, the `while running do` loop would be replaced like this: | + | 如果程序以驱动模式运作，你需要注册事件作为替代。可以将所有事件注册到像上面样例一样的全局事件处理函数，也可以将每个事件注册到对应的处理函数。如果你希望上面的样例在后台运行，`while running do`循环需要替换为类似下面的代码： |
| ```lua | ```lua | ||
| - | event.listen("key_up", handleEvent) -- register handleEvent to be called on key_up then end the program | + | event.listen("key_up", handleEvent) --注册handleEvent函数，使其在key_up事件发生时被调用，然后结束程序 |
| ``` | ``` | ||
| - | It would also be possible to register `myEventHandlers.key_up` directly, in which case it would receive an additional parameter (the event name) as the first parameter. | + | 也可以直接注册`myEventHandlers.key_up`，这样的话它会额外收到一个参数(事件名称)作为第一个参数。 |
| 目录 | 目录 | ||
| ----------- | ----------- | ||
| {{page>api:contents:zh&noheader&noeditbutton&nouser&nofooter}} | {{page>api:contents:zh&noheader&noeditbutton&nouser&nofooter}} | ||