Differences

This shows you the differences between two versions of the page.

--- api:event [2015/05/02 14:18]
sulljason [Functions]
+++ api:event [2019/06/01 19:13] (current)
everyos [Functions]
@@ Line 10: / Line 10: @@
 - Have your program handle events while being the foreground program executed (primary mode).
-In driver mode your program needs to register callbacks for events then it should exit to return execution to the primary program (usually the shell). In primary mode your program does not need to register events, it can handle them directly using `event.pull()`.
+In driver mode your program needs to register callbacks for events (using `event.listen()`) then it should exit to return execution to the primary program (usually the shell). In primary mode your program does not need to register events, it can handle them directly using `event.pull()`.
 //Note:// While it is technically possible to do both at the same time it is not recommended to do so. To make sure that events are received by all registered functions, they are consumed only after all functions have been called. So if you register your handler and pull at the same time, you would receive events twice.
-===== Interrupts =====
-Interrupts are working during `event.pull*()` methods. They are mean to forcibly return form the function. They are especially useful when `event.pull*()` is called without time limit and filter. In some cases this means that `event.pull*()` could be waiting indefinitely.
-There are two types of interrupts:
-- Soft interrupt is called on `Ctrl+C` keys combination and is only effective if `event.pull*()` allows for returning this type of event (`"interrupted"`). It also returns one additional result which is time spent in `event.pull*()`.
-- Hard interrupt is run on `Ctrl-Alt-C` keys combination. It forcibly exits the `event.pull*()` method by throwing a `"interrupted"` error.
-===== Basic event handling =====
-The primary functionality uses the function `event.pull()` to get the top event currently in the queue, or - if there is currently no event - puts the program on hold until one is available.
-A simple example primary event handler:
-```lua
-local event = require "event" -- load event table and store the pointer to it in event
-local char_space = string.byte(" ") -- numerical representation of the space char
-local running = true -- state variable so the loop can terminate
-function unknownEvent()
-  -- do nothing if the event wasn't relevant
-end
--- table that holds all event handlers, and in case no match can be found returns the dummy function unknownEvent
-local myEventHandlers = setmetatable({}, { __index = function() return unknownEvent end })
--- Example key-handler that simply sets running to false if the user hits space
-function myEventHandlers.key_up(adress, char, code, playerName)
-  if (char == char_space) then
-    running = false
-  end
-end
--- The main event handler as function to separate eventID from the remaining arguments
-function handleEvent(eventID, ...)
-  if (eventID) then -- can be nil if no event was pulled for some time
-    myEventHandlers[eventID](...) -- call the appropriate event handler with all remaining arguments
-  end
-end
--- main event loop which processes all events, or sleeps if there is nothing to do
-while running do
-  handleEvent(event.pull()) -- sleeps until an event is available, then process it
-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:
-```lua
-event.listen("key_up", handleEvent) -- register handleEvent to be called on key_up then end the program
-```
-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.
-**Important:** If you use event handling in driver mode, then event functions will be called from the environment of the OS event handler and variables local to your program will **not** be visible!
 ===== Functions =====
@@ Line 73: / Line 20: @@
 **event** - name of the signal to listen to.\\
 **callback** - the function to call if this signal is received. The function will receive the event name it was registered for as first parameter, then all remaining parameters as defined by the [[component:signals|signal]] that caused the event.\\
-**Returns:** `true` if the event was successfully registered, `false` if this function was already registered for this event type.
+**Returns:** `number`, the event id which can be canceled via `event.cancel`, if the event was successfully registered, `false` if this function was already registered for this event type.
 - `event.ignore(event: string, callback: function): boolean`
 Unregister a previously registered event listener.
@@ Line 87: / Line 34: @@
 **Returns:** a timer ID that can be used to cancel the timer at any time.\\
 //Note//: the timer resolution can vary. If the computer is idle and enters sleep mode, it will only be woken in a game tick, so the time the callback is called may be up to 0.05 seconds off.
-**Important**: timers are driven by the `event.pull` function. If you always pull signals directly from `os.pullSignal` and never call `event.pull`, timers will not work!
+- `event.cancel(timerId: number): boolean`
-- `event.cancel(timerId: function): boolean`
 Cancels a timer previously created with `event.timer`.
 **timerId** - a timer ID as returned by `event.timer`.\\
@@ Line 98: / Line 44: @@
 **...** - any number of parameters in the same order as defined by the [[component:signals|signal]] that is expected. Those arguments will act as filters for the additional arguments returned by the signal. Direct equality is used to determine if the argument is equal to the given filter. Can be `nil` in which case this particular argument will not be filtered.\\
 Filter example:
-The `click` signal (when a player clicks on a tier two or three screen) has the signature ` screenX: number, screenY: number, playerName: string`
+The `touch` signal (when a player clicks on a tier two or three screen) has the signature ` screenX: number, screenY: number, playerName: string`
 To only pull clicks by player "Steve" you'd do:
-  `local _, x, y = event.pull("click", nil, nil, "Steve")`
+  `local _, x, y = event.pull("touch", nil, nil, "Steve")`
-- `event.pullFiltered(([timeout: number], [filter: function]): string, ...` (Since 1.5.9)
+- `event.pullFiltered([timeout: number], [filter: function]): string, ...` (Since 1.5.9)
 Pulls and returns the next available event from the queue, or waits until one becomes available but allows filtering by specifying filter function.
 **timeout** - if passed the function will wait for a new event for this many seconds at maximum then returns `nil` if no event was queued during that time.\\
@@ Line 111: / Line 57: @@
 local allowedPlayers = {"Kubuxu", "Sangar", "Magik6k", "Vexatos"}
 local function filter(name, ...)
-  if name ~= "key_up" and name ~= "key_down" and name ~= "click" then
+  if name ~= "key_up" and name ~= "key_down" and name ~= "touch" then
     return false
   end
   local nick
-  if name == "click" then
+  if name == "touch" then
     nick = select(3, ...)
   else
@@ Line 128: / Line 74: @@
 end
-local e = {event.pullFiltered(filter)}  -- We are pulling key_up, key_down and click events for unlimited amount of time. The filter will ensure that only evets caused by players in allowedPlayers are pulled.
+local e = {event.pullFiltered(filter)}  -- We are pulling key_up, key_down and click events for unlimited amount of time. The filter will ensure that only events caused by players in allowedPlayers are pulled.
 ```
 - `event.pullMultiple(...): ...` (Since 1.5.9)
-As its arguments `pullMutliple` accepts multiple event names to be pulled, allowing basic filtering of multiple events at once.
+As its arguments `pullMultiple` accepts multiple event names to be pulled, allowing basic filtering of multiple events at once.
-- `event.shouldSoftInterrupt(): boolean` (Since 1.5.9)
-This function is called by `event.pull` after each signal was processed, to check whether it should abort early. If this returns `true`, `event.pull` will return an `interrupted` event if the filtering allows for that.
-Per default, this returns `true` if the combination `Ctrl + C` is pressed.
-This should usually not be called by your programs.
-- `event.shouldInterrupt(): boolean`
-This function is called by `event.pull` after each signal was processed, to check whether it should abort early. If this returns `true`, `event.pull` will throw an `interrupted` error.
-Per default, this returns `true` if the combination `Ctrl + Alt + C` is pressed.
-This should usually not be called by your programs, except if you need to do some cleanup if the program is manually interrupted.
 - `event.onError(message: any)`
 Global event callback error handler. If an event listener throws an error, we handle it in this function to avoid it bubbling into unrelated code (that only triggered the execution by calling `event.pull`). Per default, this logs errors into a file on the temporary file system.
 You can replace this function with your own if you want to handle event errors in a different way.
+- `event.push(name: string[, ...])`
+This is only an alias to [[api:computer|computer.pushSignal]]. This does not modify the arguments in any way. It seemed logical to add the alias to the event library because there is also an `event.pull` for signals.
+===== Interrupts =====
+Starting In OpenOS 1.6.4 and later, interrupts have been cleaned up. The following two methods are now obsolete
+- `event.shouldSoftInterrupt(): boolean` (Since 1.5.9 and removed in 1.6.4)
+- `event.shouldInterrupt(): boolean`  (Since 1.5.9 and removed in 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.
+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.
+- Soft interrupts are an event signal generated by pressing `Ctrl+C`. The signal returns two fields, the event name `"interrupted"` and the computer uptime
+- Hard interrupts are generated by pressing `Ctrl-Alt-C`. It forcibly exits the `event.pull*()` method by throwing a `"interrupted"` error.
+===== 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.
+```lua
+while true do
+  local id, _, x, y = event.pullMultiple("touch", "interrupted")
+  if id == "interrupted" then
+    print("soft interrupt, closing")
+    break
+  elseif id == "touch" then
+    print("user clicked", x, y)
+  end
+end
+```
+===== 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.
+```lua
+local event = require "event" -- load event table and store the pointer to it in event
+local char_space = string.byte(" ") -- numerical representation of the space char
+local running = true -- state variable so the loop can terminate
+function unknownEvent()
+  -- do nothing if the event wasn't relevant
+end
+-- table that holds all event handlers
+-- in case no match can be found returns the dummy function unknownEvent
+local myEventHandlers = setmetatable({}, { __index = function() return unknownEvent end })
+-- Example key-handler that simply sets running to false if the user hits space
+function myEventHandlers.key_up(adress, char, code, playerName)
+  if (char == char_space) then
+    running = false
+  end
+end
+-- The main event handler as function to separate eventID from the remaining arguments
+function handleEvent(eventID, ...)
+  if (eventID) then -- can be nil if no event was pulled for some time
+    myEventHandlers[eventID](...) -- call the appropriate event handler with all remaining arguments
+  end
+end
+-- main event loop which processes all events, or sleeps if there is nothing to do
+while running do
+  handleEvent(event.pull()) -- sleeps until an event is available, then process it
+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:
+```lua
+event.listen("key_up", handleEvent) -- register handleEvent to be called on key_up then end the program
+```
+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.
 Contents
 -----------
 {{page>api:contents&noheader&noeditbutton&nouser&nofooter}}