Created API/Event (markdown)

API-Event.md

@@ -0,0 +1,23 @@
+This API provides a rudimentary event system. It is primarily intended to be used by libraries, to allow them to be notified of signals. For example, this is used to automatically bind the primary screen to the primary GPU, to check whether the [[terminal|API/Term]] is available, and to execute autorun programs on newly installed file systems.
+
+- `event.listen(name: string, callback: function): boolean`  
+  Register a new event listener that should be called for events with the specified name. When registering for signal events, this is the name of the signal. Returns `true` if the listener was successfully registered, `false` if it already was registered for this event type.
+- `event.ignore(name: string, callback: function): boolean`  
+  Unregister a previously registered event listener. Returns `true` if the event listener was removed, `false` if the listener was not registered.
+- `event.timer(interval: number, callback: function[, times: number]): number`  
+  Starts a new timer that will be called after the time specified in `interval`. Per default, timers only fire once. Pass `times` with a value larger than one to have it fire as often as that number specifies. Pass `math.huge` to create an infinitely repeating interval.  
+  This returns a number that identifies the created timer, and can be used in `timer.cancel` to destroy it, possibly before it even ran once.
+  **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: function): boolean`  
+  Cancels a timer previously created with `event.timer`. Returns `true` if the timer was stopped, `false` if there was no timer with the specified ID.
+- `event.pull([timeout: number], [name: string], ...): string, ...`  
+  This, besides `os.sleep()` should be the primary way for programs to "yield". This function can be used to await signals from the queue, while having unrelated signals dispatched as events. It also drives timers created with `event.timer`, so it should be called regularly anyway.  
+  If the first parameter is a number, it is expected to be the time to wait for the signal, before returning `nil`, the second parameter then has to be the event name. Otherwise the first parameter has to be the event name. The event name can be `nil`, however, to not filter for a specific event.  
+  Any further parameters are used as a direct filter. The function will only return events that match this filter - meaning the parameters are equal to those provided in the filter (direct equality for all parameters, regular expressions are possible for the event name, see `string.match`).  
+  For example, the `click` 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", _, _, "Steve")`
+- `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.
+- `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.