From 5ba1a7d19e1d7aaaaa173354f9629e9b0ec03fa8 Mon Sep 17 00:00:00 2001 From: Insality Date: Sun, 28 Apr 2024 14:09:05 +0300 Subject: [PATCH] Update README --- README.md | 181 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 106 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index be912b8..96f5320 100644 --- a/README.md +++ b/README.md @@ -46,36 +46,6 @@ https://github.com/Insality/defold-event/archive/refs/tags/2.zip The project already includes the [Lua Script Instance](https://github.com/DanEngelbrecht/LuaScriptInstance/) library. If Lua Script Instance is listed in your project's dependencies, remove it to prevent duplication. -### Logger Configuration - -**Setting a Predefined Logger** - -To log event activities, assign a logger instance to the Event library: - -```lua -local log = require("log.log") -local event = require("event.event") - -event.set_logger(log.get_logger("event")) -``` - -**Implementing a Custom Logger** - -Create a custom logger by following this interface: - -```lua -local event = require("event.event") - -local logger = { - trace = function(_, message, context) end, - debug = function(_, message, context) end, - info = function(_, message, context) end, - warn = function(_, message, context) end, - error = function(_, message, context) end -} - -event.set_logger(logger) -``` ### Memory Allocation Tracking @@ -95,7 +65,26 @@ memory_threshold_warning = 50 Memory allocation tracking is turned off in release builds, regardless of the `game.project` settings. -## API Documentation +## API Reference + +### Quick API Reference + +```lua +event.set_logger(logger) +event.create(callback, [callback_context]) +event:subscribe(callback, [callback_context]) +event:unsubscribe(callback, [callback_context]) +event:is_subscribed(callback, [callback_context]) +event:trigger(...) +event:is_empty() +event:clear() +events.subscribe(name, callback, [callback_context]) +events.unsubscribe(name, callback, [callback_context]) +events.is_subscribed(name, callback, [callback_context]) +events.trigger(name, ...) +events.clear(name) +events.clear_all() +``` ### Setup and Initialization @@ -105,12 +94,54 @@ To start using the Event module in your project, you first need to import it. Th local event = require("event.event") ``` +### Configuration Functions + +**event.set_logger** +--- +Customize the logging mechanism used by Event module. You can use **Defold Log** library or provide a custom logger. + +```lua +event.set_logger([logger_instance]) +``` + +- **Parameters:** + - `logger_instance` (optional): A logger object that follows the specified logging interface, including methods for `trace`, `debug`, `info`, `warn`, `error`. Pass `nil` to remove the default logger. + +- **Usage Example:** + +Using the [Defold Log](https://github.com/Insality/defold-log) module: +```lua +-- Use defold-log module +local log = require("log.log") +local event = require("event.event") + +event.set_logger(log.get_logger("event")) +``` + +Creating a custom user logger: +```lua +-- Create a custom logger +local logger = { + trace = function(_, message, context) end, + debug = function(_, message, context) end, + info = function(_, message, context) end, + warn = function(_, message, context) end, + error = function(_, message, context) end +} +event.set_logger(logger) +``` + +Remove the default logger: +```lua +event.set_logger(nil) +``` + ### Core Functions **event.create** --- ```lua -event.create(callback, callback_context) +event.create(callback, [callback_context]) ``` Generate a new event instance. This instance can then be used to subscribe to and trigger events. @@ -134,7 +165,7 @@ Once an event instance is created, you can interact with it using the following **event:subscribe** --- ```lua -event:subscribe(callback, callback_context) +event:subscribe(callback, [callback_context]) ``` Subscribe a callback to the event. The callback will be invoked whenever the event is triggered. @@ -153,7 +184,7 @@ on_click_event:subscribe(callback, self) **event:unsubscribe** --- ```lua -event:unsubscribe(callback, callback_context) +event:unsubscribe(callback, [callback_context]) ``` Remove a previously subscribed callback from the event. @@ -172,7 +203,7 @@ on_click_event:unsubscribe(callback, self) **event:is_subscribed** --- ```lua -event:is_subscribed(callback, callback_context) +event:is_subscribed(callback, [callback_context]) ``` Determine if a specific callback is currently subscribed to the event. @@ -247,106 +278,106 @@ Global events module requires careful management of subscriptions and unsubscrip local events = require("event.events") ``` -**events.trigger** +**events.subscribe** --- ```lua -events.trigger(name, ...) +events.subscribe(name, callback, [callback_context]) ``` -Throw a global event with the specified name. All subscribed callbacks will be executed. +Subscribe a callback to the specified global event. - **Parameters:** - - `name`: The name of the global event to trigger. - - `...`: Any number of parameters to be passed to the subscribed callbacks. + - `name`: The name of the global event to subscribe to. + - `callback`: The function to be executed when the global event occurs. + - `callback_context` (optional): The first parameter to be passed to the callback function. - **Usage Example:** ```lua -events.trigger("on_game_over", "arg1", "arg2") +events.subscribe("on_game_over", callback, self) ``` -**events.clear** +**events.unsubscribe** --- ```lua -events.clear(name) +events.unsubscribe(name, callback, [callback_context]) ``` -Remove all callbacks subscribed to the specified global event. +Remove a previously subscribed callback from the specified global event. - **Parameters:** - - `name`: The name of the global event to clear. + - `name`: The name of the global event to unsubscribe from. + - `callback`: The callback function to unsubscribe. + - `callback_context` (optional): The first parameter to be passed to the callback function. - **Usage Example:** ```lua -events.clear("on_game_over") +events.unsubscribe("on_game_over", callback, self) ``` -**events.clear_all** +**events.is_subscribed** --- ```lua -events.clear_all() +events.is_subscribed(name, callback, [callback_context]) ``` -Remove all callbacks subscribed to all global events. +Determine if a specific callback is currently subscribed to the specified global event. + +- **Parameters:** + - `name`: The name of the global event in question. + - `callback`: The callback function in question. + - `callback_context` (optional): The first parameter to be passed to the callback function. + +- **Return Value:** `true` if the callback is subscribed to the global event, `false` otherwise. - **Usage Example:** ```lua -events.clear_all() +local is_subscribed = events.is_subscribed("on_game_over", callback, self) ``` -**events.subscribe** +**events.trigger** --- ```lua -events.subscribe(name, callback, callback_context) +events.trigger(name, ...) ``` -Subscribe a callback to the specified global event. +Throw a global event with the specified name. All subscribed callbacks will be executed. - **Parameters:** - - `name`: The name of the global event to subscribe to. - - `callback`: The function to be executed when the global event occurs. - - `callback_context` (optional): The first parameter to be passed to the callback function. + - `name`: The name of the global event to trigger. + - `...`: Any number of parameters to be passed to the subscribed callbacks. - **Usage Example:** ```lua -events.subscribe("on_game_over", callback, self) +events.trigger("on_game_over", "arg1", "arg2") ``` -**events.unsubscribe** +**events.clear** --- ```lua -events.unsubscribe(name, callback, callback_context) +events.clear(name) ``` -Remove a previously subscribed callback from the specified global event. +Remove all callbacks subscribed to the specified global event. - **Parameters:** - - `name`: The name of the global event to unsubscribe from. - - `callback`: The callback function to unsubscribe. - - `callback_context` (optional): The first parameter to be passed to the callback function. + - `name`: The name of the global event to clear. - **Usage Example:** ```lua -events.unsubscribe("on_game_over", callback, self) +events.clear("on_game_over") ``` -**events.is_subscribed** +**events.clear_all** --- ```lua -events.is_subscribed(name, callback, callback_context) +events.clear_all() ``` -Determine if a specific callback is currently subscribed to the specified global event. - -- **Parameters:** - - `name`: The name of the global event in question. - - `callback`: The callback function in question. - - `callback_context` (optional): The first parameter to be passed to the callback function. - -- **Return Value:** `true` if the callback is subscribed to the global event, `false` otherwise. +Remove all callbacks subscribed to all global events. - **Usage Example:** ```lua -local is_subscribed = events.is_subscribed("on_game_over", callback, self) +events.clear_all() ``` The **Events** module provides a powerful and flexible way to manage global events in your Defold projects. Use it to create modular and extensible systems that can respond to events from anywhere in your game.