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:16] hfsr [Basic event example] 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 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}} | ||