This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
api:event [2017/01/08 03:24] byteoflogic Unbalanced parenthesis on function documentation "event.pullFiltered" |
api:event [2019/06/01 19:13] (current) everyos [Functions] |
||
|---|---|---|---|
| Line 20: | Line 20: | ||
| **event** - name of the signal to listen to.\\ | **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.\\ | **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` | - `event.ignore(event: string, callback: function): boolean` | ||
| Unregister a previously registered event listener. | Unregister a previously registered event listener. | ||
| Line 34: | Line 34: | ||
| **Returns:** a timer ID that can be used to cancel the timer at any time.\\ | **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. | //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: number): boolean` | ||
| Cancels a timer previously created with `event.timer`. | Cancels a timer previously created with `event.timer`. | ||
| Line 45: | 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.\\ | **...** - 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: | 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: | 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. | Pulls and returns the next available event from the queue, or waits until one becomes available but allows filtering by specifying filter function. | ||
| Line 58: | Line 57: | ||
| local allowedPlayers = {"Kubuxu", "Sangar", "Magik6k", "Vexatos"} | local allowedPlayers = {"Kubuxu", "Sangar", "Magik6k", "Vexatos"} | ||
| local function filter(name, ...) | 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 | return false | ||
| end | end | ||
| local nick | local nick | ||
| - | if name == "click" then | + | if name == "touch" then |
| nick = select(3, ...) | nick = select(3, ...) | ||
| else | else | ||
| Line 75: | Line 74: | ||
| end | 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) | - `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)` | - `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. | 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. | 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 ===== | ===== Interrupts ===== | ||
| - | Interrupts are a type of messaging intended to close or stop a process. In OpenOS the `event.pull*()` methods generate the two types of 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. | ||
| - | They are especially useful when `event.pull*()` is called without time limit and without 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 |
| - | - Soft interrupts are generated by pressing `Ctrl+C` 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 interrupts are generated by pressing `Ctrl-Alt-C`. It forcibly exits the `event.pull*()` method by throwing a `"interrupted"` error. | - Hard interrupts are generated by pressing `Ctrl-Alt-C`. It forcibly exits the `event.pull*()` method by throwing a `"interrupted"` error. | ||