• World of Warcraft Addons
  • World of Warcraft
  • Average Rating:

  • Your Rating

  • Share
  • Report Abuse

CallbackHandler-1.0

  Download the Curse Client

Project Updated:
Files Updated: Sat, May 9 2009
Supports Game Version: 3.1.0
Category: Libraries
Tags:

[Edit Tags]

Project Manager: Nevcairiel
Additional Authors: Mikk
Current Version: 1.0.3.30100
License: BSD License
Avg Daily DL (last 30 days): 63
Downloads Total: 8,875
Favorites: 10
Comments: 0
  • About CallbackHandler-1.0
  •  

CallbackHandler is a back-end utility library that makes it easy for a library to fire its events to interested parties. It removes the need for addons to be aware of e.g. AceEvent.

CallbackHandler should not be a required dependency for addons wanting to use your library. Rather, embed it in your library. CallbackHandler is small enough that a few libraries pulling it in has no real impact. We (the Ace3 core team) would like to simplify the library inclusion process so that usually all you have to do is pull in the one single library you're interested in, rather than having to fullfill several dependencies to make it work.

Including CallbackHandler-1.0 into your project

Library authors should always hard-copy the CallbackHandler-1.0 files into their library distribution. Adding a dependency on another library is never a good idea.

AddOn authors can external CallbackHandler-1.0 like any other library. Make sure to only get the CallbackHandler-1.0 sub-folder, and not the .toc.

Example .pkgmeta syntax:

externals:
  libs/CallbackHandler-1.0: svn://svn.wowace.com/wow/callbackhandler/mainline/tags/1.0.3/CallbackHandler-1.0

Mixing in the CallbackHandler functions in your library

MyLib.callbacks = MyLib.callbacks or 
  LibStub("CallbackHandler-1.0"):New(MyLib)

This adds 3 methods to your library:

  • MyLib.RegisterCallback(self, "eventName"[, method, [arg]])
  • MyLib.UnregisterCallback(self, "eventname")
  • MyLib.UnregisterAllCallbacks(self)

Make sure that the passed in self is your addon, and not the library itself, so the double-colon syntax will not work.

The "MyLib.callbacks" object is the callback registry itself, which you need to keep track of across library upgrades.

Firing events

Assuming your callback registry is "MyLib.events", firing named events is as easy as:

MyLib.callbacks:Fire("EventName", arg1, arg2, ...)

All arguments supplied to :Fire() are passed to the functions listening to the event.

Advanced uses

Renaming the methods

You can specify your own names for the methods installed by CallbackHandler:

MyLib.callbacks= MyLib.callbacks or 
  LibStub("CallbackHandler-1.0"):New(MyLib, 
  "MyRegisterFunc", "MyUnregisterFunc", "MyUnregisterAllFunc" or false)

Giving false as the name for UnregisterAll means that you do not want to give users access to that API at all - it will not be installed.

Tracking events being used

In some cases, it makes sense to know which events are being requested by your users. Perhaps to enable/disable code needed to track them.

CallbackHandler will always call registry:OnUsed() and :OnUnused() when an event starts/stops being used:

function MyLib.callbacks:OnUsed(target, eventname)
  -- "target" is == MyLib here
  print("Someone just registered for "..eventname.."!")
end

function MyLib.callbacks:OnUnused(target, eventname)
  print("Noone wants "..eventname.." any more")
end

"OnUsed" is only called if the event was previously unused. "OnUnused" is only called when the last user unregisters from an event. In other words, you won't see an "OnUnused" unless "OnUsed" has been called for an event. And you won't ever see two "OnUsed" in a row without "OnUnused" in between for an event.

Multiple event registries

As you may or may not know, CallbackHandler is the workhorse of [[AceEvent-3.0|AceEvent]]. It is used twice in AceEvent: once for in-game events, which cannot be fired by users, and once for "messages", which can be fired by users.

Providing multiple registries in AceEvent was as easy as:

AceEvent.events = AceEvent.events or 
  LibStub("CallbackHandler-1.0"):New(AceEvent, 
    "RegisterEvent", "UnregisterEvent", "UnregisterAllEvents")

AceEvent.messages = AceEvent.messages or 
  LibStub("CallbackHandler-1.0"):New(AceEvent, 
    "RegisterMessage", "UnregisterMessage", "UnregisterAllMessages")

AceEvent.SendMessage = AceEvent.messages.Fire

Of course, there is also some code in AceEvent to do the actual driving of in-game events (using OnUsed and OnUnused), but this is really the core of it.

  • Downloads (2)
  •  
File Name Release Type Game Version Downloads Date
Addon Curse.com Beta 2.3.3 0 9/29/2008
  File Name Release Type Game Version Downloads Date  
  CallbackHandler-1.0 1.0.3.30100 Release 3.1.0 5,231 5/9/2009
  CallbackHandler-1.0 1.0.3 Release 3.0.2 3,644 9/29/2008
  • 1 page(s)
Advertisement
  • Comments

Add Comment  

Add

You need to login or register to post.

Benefits of Registration

  • Interact with hundreds of thousands of other gamers on an open social network.
  • Post your stories, news, images, videos, and other content to share.
  • Create a network with your fellow gamers or join an existing one.
  • Gain reputation for everything you do.
  • Similar Addons
  •  

Average downloads per day

  1. 1,229 LibRock-1.0 Libraries
  2. 881 Ace2 Libraries
  3. 774 Ace3 Libraries
  4. 536 LibBabble-Boss-3.0 Libraries
  5. 504 Addon Control Panel Libraries, Professions, and...