Demonnic: Demonnic moved page Area 51/IDManager to Manual:IDManager without leaving a redirect: released with 4.14

2021-11-25T19:55:53Z

Demonnic moved page Area 51/IDManager to Manual:IDManager without leaving a redirect: released with 4.14

Demonnic: /* Introduction */

2021-10-18T23:14:49Z

Introduction

Demonnic: IDManager documentation

2021-10-17T00:27:02Z

IDManager documentation

New page

{{TOC right}}

= Introduction =

The IDManager is a new item available in Mudlet 4.14+ which allows you to create named tempTimers and event handlers. Mudlet comes with a set of functions for creating named timers and events, and these functions use a default IDManager which is created for the entire profile when you load it. If you want to isolate your named timers and event handlers from the rest of the profile so you don't have to worry as much about name collisions, then you can get your own IDManager object to register things with.

=== Motivation ===

Handling the IDs returned by tempTimer and registerAnonymousEventHandler is some of the most repeated code in Mudlet, and also some of the most frequently forgotten. We get a lot of people through the help channel with duplicated event handlers because they didn't know to capture and kill the previous handler ID first. It's been asked in the past several times if they could provide their own ID. We got asked one too many times and decided to fix it.

= Usage =

As these are the underlying functions which drive the named timers and event handlers for functions like registerNamedEventHandler, each function will be described and then a link to the corresponding documentation in the main API given. Also, events and timers differ largely in name, so I will cover them in tandem. All examples assume you've created an IDManager and stored it as myIDM.

=== Creation ===

Creating a new IDManager is as simple as requesting one from getNewIDManager(). It is recommended you do guard against overwriting these, as they contain all the references to the managed timers and events, and you don't want to lose that.

<syntaxhighlight lang="lua">
myIDM = myIDM or getNewIDManager()
</syntaxhighlight>

=== Register a new handler or timer ===

The registration functions return true if the handler or timer was registered successfully, or nil+error if something goes wrong. If you register something to the same name twice, the old handler or timer is killed and reregistered with the new information. This means duplicates with the same name are impossible. Timer names and handler names are checked separately, you can have one of each named "thing".

;See: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]

<syntaxhighlight lang="lua">
local ok,err = myIDM:registerEvent("vitals", "gmcp.Char.Vitals", demonnic.handleVitals)
if not ok then
cecho("Something went wrong registering the vitals handler! Panic!\n")
cecho("ERROR was: " .. err)
end

local ok,err = myIDM:registerTimer("balance", 1, demonnic.checkBalance)
if not ok then
cecho("Something went wrong registering the balance timer! PANIC!\n")
cecho("ERROR was: " .. err)
end
</syntaxhighlight>

=== Stop a handler or timer ===

A stopped handler or timer is available to be resumed.

;See: [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]

<syntaxhighlight lang="lua">
local ok = myIDM:stopEvent("vitals")
if not ok then
printDebug("'vitals' event not registered yet")
end

local ok = myIDM:stopTimer("balance")
if not ok then
printDebug("'balance' timer not registered yet")
end
</syntaxhighlight>

=== Resume a stopped handler or timer ===

Returns false if the handler or timer hasn't been registered yet. If it has, it cancels it if it's running currently and reregisters it with the saved information.

;See: [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]]

<syntaxhighlight lang="lua">
local ok = myIDM:resumeEvent("vitals")
if not ok then
printDebug("'vitals' event not registered yet")
end

local ok = myIDM:resumeTimer("balance")
if not ok then
printDebug("'balance' timer not registered yet")
end
</syntaxhighlight>

=== List handlers or timers ===

Sometimes you want to know what handlers or timers are already registered, whether for display purposes or checking configuration.

;See [[Manual:Lua_Functions#getNamedEventHandlers|getNamedEventHandlers()]], [[Manual:Lua_Functions#getNamedTimers|getNamedTimers()]]

<syntaxhighlight lang="lua">
local handlerList = myIDM:getEvents()
-- { "vitals" } if only a "vitals" handler has been registered

local timerList = myIDM:getTimers()
-- { "balance" } if only a "balance" timer has been registered
</syntaxhighlight>

=== Delete a handler or timer ===

A deleted handler or timer is gone forever unless reregistered. If you might use it again you may as well stop it instead.

;See: [[Manual:Lua_Functions#deleteNamedEventHandler|deleteNamedEventHandler()]], [[Manual:Lua_Functions#deleteNamedTimer|deleteNamedTimer()]]

<syntaxhighlight lang="lua">
local ok = myIDM:deleteEvent("vitals")
if not ok then
printDebug("'vitals' event not registered yet")
end

local ok = myIDM:deleteTimer("balance")
if not ok then
printDebug("'balance' timer not registered yet")
end
</syntaxhighlight>

=== Stop all handlers or timers ===

You can stop all of your registered handlers or timers at once using these functions

;See: [[Manual:Lua_Functions#stopAllNamedEventHandlers|stopAllNamedEventHandlers()]], [[Manual:Lua_Functions#stopAllNamedTimers|stopAllNamedTimers()]]

<syntaxhighlight lang="lua">
myIDM:stopAllEvents()

myIDM:stopAllTimers()

-- do both in one call
myIDM:emergencyStop()
</syntaxhighlight>

=== Delete all handlers or timers ===

For when you just want to clear it all out and start over.

;See: [[Manual:Lua_Functions#deleteAllNamedEventHandlers|stopAllNamedEventHandlers()]], [[Manual:Lua_Functions#deleteAllNamedTimers|stopAllNamedTimers()]]

<syntaxhighlight lang="lua">
myIDM:deleteAllEvents()

myIDM:deleteAllTimers()
</syntaxhighlight>

@@ Line 3: / Line 3: @@
 = Introduction =
-The IDManager is a new item available in Mudlet 4.14+ which allows you to create named tempTimers and event handlers. Mudlet comes with a set of functions for creating named timers and events, and these functions use a default IDManager which is created for the entire profile when you load it. If you want to isolate your named timers and event handlers from the rest of the profile so you don't have to worry as much about name collisions, then you can get your own IDManager object to register things with.
+The IDManager is a new item available in Mudlet 4.14+ which allows you to create named tempTimers and event handlers. Mudlet comes with a set of functions for creating named timers and events, and these functions create an IDManager for each "username" that registers one. This page is for if you decide you want direct access to your own IDManager instance rather than letting Mudlet handle it for you. For most people, simply using registerNamedEventHandler(userName, handlerName, eventName, functionReference) and accompanying functions will be sufficient, creating your own IDManager would mostly be for if you prefer an Object Oriented approach to things, or want to build your own functionality on top without using the existing functions as the intermediary.
 === Motivation ===

Manual:IDManager - Revision history

Demonnic: Demonnic moved page Area 51/IDManager to Manual:IDManager without leaving a redirect: released with 4.14

Demonnic: /* Introduction */

Demonnic: IDManager documentation