Mercurial > wow > askmrrobot

annotate Libs/AceAddon-3.0/AceAddon-3.0.lua @ 57:01b63b8ed811 v21

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
total rewrite to version 21
author yellowfive
date Fri, 05 Jun 2015 11:05:15 -0700
parents
children
rev   line source
yellowfive@57 1 --- **AceAddon-3.0** provides a template for creating addon objects.
yellowfive@57 2 -- It'll provide you with a set of callback functions that allow you to simplify the loading
yellowfive@57 3 -- process of your addon.\\
yellowfive@57 4 -- Callbacks provided are:\\
yellowfive@57 5 -- * **OnInitialize**, which is called directly after the addon is fully loaded.
yellowfive@57 6 -- * **OnEnable** which gets called during the PLAYER_LOGIN event, when most of the data provided by the game is already present.
yellowfive@57 7 -- * **OnDisable**, which is only called when your addon is manually being disabled.
yellowfive@57 8 -- @usage
yellowfive@57 9 -- -- A small (but complete) addon, that doesn't do anything,
yellowfive@57 10 -- -- but shows usage of the callbacks.
yellowfive@57 11 -- local MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon")
yellowfive@57 12 --
yellowfive@57 13 -- function MyAddon:OnInitialize()
yellowfive@57 14 -- -- do init tasks here, like loading the Saved Variables,
yellowfive@57 15 -- -- or setting up slash commands.
yellowfive@57 16 -- end
yellowfive@57 17 --
yellowfive@57 18 -- function MyAddon:OnEnable()
yellowfive@57 19 -- -- Do more initialization here, that really enables the use of your addon.
yellowfive@57 20 -- -- Register Events, Hook functions, Create Frames, Get information from
yellowfive@57 21 -- -- the game that wasn't available in OnInitialize
yellowfive@57 22 -- end
yellowfive@57 23 --
yellowfive@57 24 -- function MyAddon:OnDisable()
yellowfive@57 25 -- -- Unhook, Unregister Events, Hide frames that you created.
yellowfive@57 26 -- -- You would probably only use an OnDisable if you want to
yellowfive@57 27 -- -- build a "standby" mode, or be able to toggle modules on/off.
yellowfive@57 28 -- end
yellowfive@57 29 -- @class file
yellowfive@57 30 -- @name AceAddon-3.0.lua
yellowfive@57 31 -- @release $Id: AceAddon-3.0.lua 1084 2013-04-27 20:14:11Z nevcairiel $
yellowfive@57 32
yellowfive@57 33 local MAJOR, MINOR = "AceAddon-3.0", 12
yellowfive@57 34 local AceAddon, oldminor = LibStub:NewLibrary(MAJOR, MINOR)
yellowfive@57 35
yellowfive@57 36 if not AceAddon then return end -- No Upgrade needed.
yellowfive@57 37
yellowfive@57 38 AceAddon.frame = AceAddon.frame or CreateFrame("Frame", "AceAddon30Frame") -- Our very own frame
yellowfive@57 39 AceAddon.addons = AceAddon.addons or {} -- addons in general
yellowfive@57 40 AceAddon.statuses = AceAddon.statuses or {} -- statuses of addon.
yellowfive@57 41 AceAddon.initializequeue = AceAddon.initializequeue or {} -- addons that are new and not initialized
yellowfive@57 42 AceAddon.enablequeue = AceAddon.enablequeue or {} -- addons that are initialized and waiting to be enabled
yellowfive@57 43 AceAddon.embeds = AceAddon.embeds or setmetatable({}, {__index = function(tbl, key) tbl[key] = {} return tbl[key] end }) -- contains a list of libraries embedded in an addon
yellowfive@57 44
yellowfive@57 45 -- Lua APIs
yellowfive@57 46 local tinsert, tconcat, tremove = table.insert, table.concat, table.remove
yellowfive@57 47 local fmt, tostring = string.format, tostring
yellowfive@57 48 local select, pairs, next, type, unpack = select, pairs, next, type, unpack
yellowfive@57 49 local loadstring, assert, error = loadstring, assert, error
yellowfive@57 50 local setmetatable, getmetatable, rawset, rawget = setmetatable, getmetatable, rawset, rawget
yellowfive@57 51
yellowfive@57 52 -- Global vars/functions that we don't upvalue since they might get hooked, or upgraded
yellowfive@57 53 -- List them here for Mikk's FindGlobals script
yellowfive@57 54 -- GLOBALS: LibStub, IsLoggedIn, geterrorhandler
yellowfive@57 55
yellowfive@57 56 --[[
yellowfive@57 57 xpcall safecall implementation
yellowfive@57 58 ]]
yellowfive@57 59 local xpcall = xpcall
yellowfive@57 60
yellowfive@57 61 local function errorhandler(err)
yellowfive@57 62 return geterrorhandler()(err)
yellowfive@57 63 end
yellowfive@57 64
yellowfive@57 65 local function CreateDispatcher(argCount)
yellowfive@57 66 local code = [[
yellowfive@57 67 local xpcall, eh = ...
yellowfive@57 68 local method, ARGS
yellowfive@57 69 local function call() return method(ARGS) end
yellowfive@57 70
yellowfive@57 71 local function dispatch(func, ...)
yellowfive@57 72 method = func
yellowfive@57 73 if not method then return end
yellowfive@57 74 ARGS = ...
yellowfive@57 75 return xpcall(call, eh)
yellowfive@57 76 end
yellowfive@57 77
yellowfive@57 78 return dispatch
yellowfive@57 79 ]]
yellowfive@57 80
yellowfive@57 81 local ARGS = {}
yellowfive@57 82 for i = 1, argCount do ARGS[i] = "arg"..i end
yellowfive@57 83 code = code:gsub("ARGS", tconcat(ARGS, ", "))
yellowfive@57 84 return assert(loadstring(code, "safecall Dispatcher["..argCount.."]"))(xpcall, errorhandler)
yellowfive@57 85 end
yellowfive@57 86
yellowfive@57 87 local Dispatchers = setmetatable({}, {__index=function(self, argCount)
yellowfive@57 88 local dispatcher = CreateDispatcher(argCount)
yellowfive@57 89 rawset(self, argCount, dispatcher)
yellowfive@57 90 return dispatcher
yellowfive@57 91 end})
yellowfive@57 92 Dispatchers[0] = function(func)
yellowfive@57 93 return xpcall(func, errorhandler)
yellowfive@57 94 end
yellowfive@57 95
yellowfive@57 96 local function safecall(func, ...)
yellowfive@57 97 -- we check to see if the func is passed is actually a function here and don't error when it isn't
yellowfive@57 98 -- this safecall is used for optional functions like OnInitialize OnEnable etc. When they are not
yellowfive@57 99 -- present execution should continue without hinderance
yellowfive@57 100 if type(func) == "function" then
yellowfive@57 101 return Dispatchers[select('#', ...)](func, ...)
yellowfive@57 102 end
yellowfive@57 103 end
yellowfive@57 104
yellowfive@57 105 -- local functions that will be implemented further down
yellowfive@57 106 local Enable, Disable, EnableModule, DisableModule, Embed, NewModule, GetModule, GetName, SetDefaultModuleState, SetDefaultModuleLibraries, SetEnabledState, SetDefaultModulePrototype
yellowfive@57 107
yellowfive@57 108 -- used in the addon metatable
yellowfive@57 109 local function addontostring( self ) return self.name end
yellowfive@57 110
yellowfive@57 111 -- Check if the addon is queued for initialization
yellowfive@57 112 local function queuedForInitialization(addon)
yellowfive@57 113 for i = 1, #AceAddon.initializequeue do
yellowfive@57 114 if AceAddon.initializequeue[i] == addon then
yellowfive@57 115 return true
yellowfive@57 116 end
yellowfive@57 117 end
yellowfive@57 118 return false
yellowfive@57 119 end
yellowfive@57 120
yellowfive@57 121 --- Create a new AceAddon-3.0 addon.
yellowfive@57 122 -- Any libraries you specified will be embeded, and the addon will be scheduled for
yellowfive@57 123 -- its OnInitialize and OnEnable callbacks.
yellowfive@57 124 -- The final addon object, with all libraries embeded, will be returned.
yellowfive@57 125 -- @paramsig [object ,]name[, lib, ...]
yellowfive@57 126 -- @param object Table to use as a base for the addon (optional)
yellowfive@57 127 -- @param name Name of the addon object to create
yellowfive@57 128 -- @param lib List of libraries to embed into the addon
yellowfive@57 129 -- @usage
yellowfive@57 130 -- -- Create a simple addon object
yellowfive@57 131 -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon", "AceEvent-3.0")
yellowfive@57 132 --
yellowfive@57 133 -- -- Create a Addon object based on the table of a frame
yellowfive@57 134 -- local MyFrame = CreateFrame("Frame")
yellowfive@57 135 -- MyAddon = LibStub("AceAddon-3.0"):NewAddon(MyFrame, "MyAddon", "AceEvent-3.0")
yellowfive@57 136 function AceAddon:NewAddon(objectorname, ...)
yellowfive@57 137 local object,name
yellowfive@57 138 local i=1
yellowfive@57 139 if type(objectorname)=="table" then
yellowfive@57 140 object=objectorname
yellowfive@57 141 name=...
yellowfive@57 142 i=2
yellowfive@57 143 else
yellowfive@57 144 name=objectorname
yellowfive@57 145 end
yellowfive@57 146 if type(name)~="string" then
yellowfive@57 147 error(("Usage: NewAddon([object,] name, [lib, lib, lib, ...]): 'name' - string expected got '%s'."):format(type(name)), 2)
yellowfive@57 148 end
yellowfive@57 149 if self.addons[name] then
yellowfive@57 150 error(("Usage: NewAddon([object,] name, [lib, lib, lib, ...]): 'name' - Addon '%s' already exists."):format(name), 2)
yellowfive@57 151 end
yellowfive@57 152
yellowfive@57 153 object = object or {}
yellowfive@57 154 object.name = name
yellowfive@57 155
yellowfive@57 156 local addonmeta = {}
yellowfive@57 157 local oldmeta = getmetatable(object)
yellowfive@57 158 if oldmeta then
yellowfive@57 159 for k, v in pairs(oldmeta) do addonmeta[k] = v end
yellowfive@57 160 end
yellowfive@57 161 addonmeta.__tostring = addontostring
yellowfive@57 162
yellowfive@57 163 setmetatable( object, addonmeta )
yellowfive@57 164 self.addons[name] = object
yellowfive@57 165 object.modules = {}
yellowfive@57 166 object.orderedModules = {}
yellowfive@57 167 object.defaultModuleLibraries = {}
yellowfive@57 168 Embed( object ) -- embed NewModule, GetModule methods
yellowfive@57 169 self:EmbedLibraries(object, select(i,...))
yellowfive@57 170
yellowfive@57 171 -- add to queue of addons to be initialized upon ADDON_LOADED
yellowfive@57 172 tinsert(self.initializequeue, object)
yellowfive@57 173 return object
yellowfive@57 174 end
yellowfive@57 175
yellowfive@57 176
yellowfive@57 177 --- Get the addon object by its name from the internal AceAddon registry.
yellowfive@57 178 -- Throws an error if the addon object cannot be found (except if silent is set).
yellowfive@57 179 -- @param name unique name of the addon object
yellowfive@57 180 -- @param silent if true, the addon is optional, silently return nil if its not found
yellowfive@57 181 -- @usage
yellowfive@57 182 -- -- Get the Addon
yellowfive@57 183 -- MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
yellowfive@57 184 function AceAddon:GetAddon(name, silent)
yellowfive@57 185 if not silent and not self.addons[name] then
yellowfive@57 186 error(("Usage: GetAddon(name): 'name' - Cannot find an AceAddon '%s'."):format(tostring(name)), 2)
yellowfive@57 187 end
yellowfive@57 188 return self.addons[name]
yellowfive@57 189 end
yellowfive@57 190
yellowfive@57 191 -- - Embed a list of libraries into the specified addon.
yellowfive@57 192 -- This function will try to embed all of the listed libraries into the addon
yellowfive@57 193 -- and error if a single one fails.
yellowfive@57 194 --
yellowfive@57 195 -- **Note:** This function is for internal use by :NewAddon/:NewModule
yellowfive@57 196 -- @paramsig addon, [lib, ...]
yellowfive@57 197 -- @param addon addon object to embed the libs in
yellowfive@57 198 -- @param lib List of libraries to embed into the addon
yellowfive@57 199 function AceAddon:EmbedLibraries(addon, ...)
yellowfive@57 200 for i=1,select("#", ... ) do
yellowfive@57 201 local libname = select(i, ...)
yellowfive@57 202 self:EmbedLibrary(addon, libname, false, 4)
yellowfive@57 203 end
yellowfive@57 204 end
yellowfive@57 205
yellowfive@57 206 -- - Embed a library into the addon object.
yellowfive@57 207 -- This function will check if the specified library is registered with LibStub
yellowfive@57 208 -- and if it has a :Embed function to call. It'll error if any of those conditions
yellowfive@57 209 -- fails.
yellowfive@57 210 --
yellowfive@57 211 -- **Note:** This function is for internal use by :EmbedLibraries
yellowfive@57 212 -- @paramsig addon, libname[, silent[, offset]]
yellowfive@57 213 -- @param addon addon object to embed the library in
yellowfive@57 214 -- @param libname name of the library to embed
yellowfive@57 215 -- @param silent marks an embed to fail silently if the library doesn't exist (optional)
yellowfive@57 216 -- @param offset will push the error messages back to said offset, defaults to 2 (optional)
yellowfive@57 217 function AceAddon:EmbedLibrary(addon, libname, silent, offset)
yellowfive@57 218 local lib = LibStub:GetLibrary(libname, true)
yellowfive@57 219 if not lib and not silent then
yellowfive@57 220 error(("Usage: EmbedLibrary(addon, libname, silent, offset): 'libname' - Cannot find a library instance of %q."):format(tostring(libname)), offset or 2)
yellowfive@57 221 elseif lib and type(lib.Embed) == "function" then
yellowfive@57 222 lib:Embed(addon)
yellowfive@57 223 tinsert(self.embeds[addon], libname)
yellowfive@57 224 return true
yellowfive@57 225 elseif lib then
yellowfive@57 226 error(("Usage: EmbedLibrary(addon, libname, silent, offset): 'libname' - Library '%s' is not Embed capable"):format(libname), offset or 2)
yellowfive@57 227 end
yellowfive@57 228 end
yellowfive@57 229
yellowfive@57 230 --- Return the specified module from an addon object.
yellowfive@57 231 -- Throws an error if the addon object cannot be found (except if silent is set)
yellowfive@57 232 -- @name //addon//:GetModule
yellowfive@57 233 -- @paramsig name[, silent]
yellowfive@57 234 -- @param name unique name of the module
yellowfive@57 235 -- @param silent if true, the module is optional, silently return nil if its not found (optional)
yellowfive@57 236 -- @usage
yellowfive@57 237 -- -- Get the Addon
yellowfive@57 238 -- MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
yellowfive@57 239 -- -- Get the Module
yellowfive@57 240 -- MyModule = MyAddon:GetModule("MyModule")
yellowfive@57 241 function GetModule(self, name, silent)
yellowfive@57 242 if not self.modules[name] and not silent then
yellowfive@57 243 error(("Usage: GetModule(name, silent): 'name' - Cannot find module '%s'."):format(tostring(name)), 2)
yellowfive@57 244 end
yellowfive@57 245 return self.modules[name]
yellowfive@57 246 end
yellowfive@57 247
yellowfive@57 248 local function IsModuleTrue(self) return true end
yellowfive@57 249
yellowfive@57 250 --- Create a new module for the addon.
yellowfive@57 251 -- The new module can have its own embeded libraries and/or use a module prototype to be mixed into the module.\\
yellowfive@57 252 -- A module has the same functionality as a real addon, it can have modules of its own, and has the same API as
yellowfive@57 253 -- an addon object.
yellowfive@57 254 -- @name //addon//:NewModule
yellowfive@57 255 -- @paramsig name[, prototype|lib[, lib, ...]]
yellowfive@57 256 -- @param name unique name of the module
yellowfive@57 257 -- @param prototype object to derive this module from, methods and values from this table will be mixed into the module (optional)
yellowfive@57 258 -- @param lib List of libraries to embed into the addon
yellowfive@57 259 -- @usage
yellowfive@57 260 -- -- Create a module with some embeded libraries
yellowfive@57 261 -- MyModule = MyAddon:NewModule("MyModule", "AceEvent-3.0", "AceHook-3.0")
yellowfive@57 262 --
yellowfive@57 263 -- -- Create a module with a prototype
yellowfive@57 264 -- local prototype = { OnEnable = function(self) print("OnEnable called!") end }
yellowfive@57 265 -- MyModule = MyAddon:NewModule("MyModule", prototype, "AceEvent-3.0", "AceHook-3.0")
yellowfive@57 266 function NewModule(self, name, prototype, ...)
yellowfive@57 267 if type(name) ~= "string" then error(("Usage: NewModule(name, [prototype, [lib, lib, lib, ...]): 'name' - string expected got '%s'."):format(type(name)), 2) end
yellowfive@57 268 if type(prototype) ~= "string" and type(prototype) ~= "table" and type(prototype) ~= "nil" then error(("Usage: NewModule(name, [prototype, [lib, lib, lib, ...]): 'prototype' - table (prototype), string (lib) or nil expected got '%s'."):format(type(prototype)), 2) end
yellowfive@57 269
yellowfive@57 270 if self.modules[name] then error(("Usage: NewModule(name, [prototype, [lib, lib, lib, ...]): 'name' - Module '%s' already exists."):format(name), 2) end
yellowfive@57 271
yellowfive@57 272 -- modules are basically addons. We treat them as such. They will be added to the initializequeue properly as well.
yellowfive@57 273 -- NewModule can only be called after the parent addon is present thus the modules will be initialized after their parent is.
yellowfive@57 274 local module = AceAddon:NewAddon(fmt("%s_%s", self.name or tostring(self), name))
yellowfive@57 275
yellowfive@57 276 module.IsModule = IsModuleTrue
yellowfive@57 277 module:SetEnabledState(self.defaultModuleState)
yellowfive@57 278 module.moduleName = name
yellowfive@57 279
yellowfive@57 280 if type(prototype) == "string" then
yellowfive@57 281 AceAddon:EmbedLibraries(module, prototype, ...)
yellowfive@57 282 else
yellowfive@57 283 AceAddon:EmbedLibraries(module, ...)
yellowfive@57 284 end
yellowfive@57 285 AceAddon:EmbedLibraries(module, unpack(self.defaultModuleLibraries))
yellowfive@57 286
yellowfive@57 287 if not prototype or type(prototype) == "string" then
yellowfive@57 288 prototype = self.defaultModulePrototype or nil
yellowfive@57 289 end
yellowfive@57 290
yellowfive@57 291 if type(prototype) == "table" then
yellowfive@57 292 local mt = getmetatable(module)
yellowfive@57 293 mt.__index = prototype
yellowfive@57 294 setmetatable(module, mt) -- More of a Base class type feel.
yellowfive@57 295 end
yellowfive@57 296
yellowfive@57 297 safecall(self.OnModuleCreated, self, module) -- Was in Ace2 and I think it could be a cool thing to have handy.
yellowfive@57 298 self.modules[name] = module
yellowfive@57 299 tinsert(self.orderedModules, module)
yellowfive@57 300
yellowfive@57 301 return module
yellowfive@57 302 end
yellowfive@57 303
yellowfive@57 304 --- Returns the real name of the addon or module, without any prefix.
yellowfive@57 305 -- @name //addon//:GetName
yellowfive@57 306 -- @paramsig
yellowfive@57 307 -- @usage
yellowfive@57 308 -- print(MyAddon:GetName())
yellowfive@57 309 -- -- prints "MyAddon"
yellowfive@57 310 function GetName(self)
yellowfive@57 311 return self.moduleName or self.name
yellowfive@57 312 end
yellowfive@57 313
yellowfive@57 314 --- Enables the Addon, if possible, return true or false depending on success.
yellowfive@57 315 -- This internally calls AceAddon:EnableAddon(), thus dispatching a OnEnable callback
yellowfive@57 316 -- and enabling all modules of the addon (unless explicitly disabled).\\
yellowfive@57 317 -- :Enable() also sets the internal `enableState` variable to true
yellowfive@57 318 -- @name //addon//:Enable
yellowfive@57 319 -- @paramsig
yellowfive@57 320 -- @usage
yellowfive@57 321 -- -- Enable MyModule
yellowfive@57 322 -- MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
yellowfive@57 323 -- MyModule = MyAddon:GetModule("MyModule")
yellowfive@57 324 -- MyModule:Enable()
yellowfive@57 325 function Enable(self)
yellowfive@57 326 self:SetEnabledState(true)
yellowfive@57 327
yellowfive@57 328 -- nevcairiel 2013-04-27: don't enable an addon/module if its queued for init still
yellowfive@57 329 -- it'll be enabled after the init process
yellowfive@57 330 if not queuedForInitialization(self) then
yellowfive@57 331 return AceAddon:EnableAddon(self)
yellowfive@57 332 end
yellowfive@57 333 end
yellowfive@57 334
yellowfive@57 335 --- Disables the Addon, if possible, return true or false depending on success.
yellowfive@57 336 -- This internally calls AceAddon:DisableAddon(), thus dispatching a OnDisable callback
yellowfive@57 337 -- and disabling all modules of the addon.\\
yellowfive@57 338 -- :Disable() also sets the internal `enableState` variable to false
yellowfive@57 339 -- @name //addon//:Disable
yellowfive@57 340 -- @paramsig
yellowfive@57 341 -- @usage
yellowfive@57 342 -- -- Disable MyAddon
yellowfive@57 343 -- MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
yellowfive@57 344 -- MyAddon:Disable()
yellowfive@57 345 function Disable(self)
yellowfive@57 346 self:SetEnabledState(false)
yellowfive@57 347 return AceAddon:DisableAddon(self)
yellowfive@57 348 end
yellowfive@57 349
yellowfive@57 350 --- Enables the Module, if possible, return true or false depending on success.
yellowfive@57 351 -- Short-hand function that retrieves the module via `:GetModule` and calls `:Enable` on the module object.
yellowfive@57 352 -- @name //addon//:EnableModule
yellowfive@57 353 -- @paramsig name
yellowfive@57 354 -- @usage
yellowfive@57 355 -- -- Enable MyModule using :GetModule
yellowfive@57 356 -- MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
yellowfive@57 357 -- MyModule = MyAddon:GetModule("MyModule")
yellowfive@57 358 -- MyModule:Enable()
yellowfive@57 359 --
yellowfive@57 360 -- -- Enable MyModule using the short-hand
yellowfive@57 361 -- MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
yellowfive@57 362 -- MyAddon:EnableModule("MyModule")
yellowfive@57 363 function EnableModule(self, name)
yellowfive@57 364 local module = self:GetModule( name )
yellowfive@57 365 return module:Enable()
yellowfive@57 366 end
yellowfive@57 367
yellowfive@57 368 --- Disables the Module, if possible, return true or false depending on success.
yellowfive@57 369 -- Short-hand function that retrieves the module via `:GetModule` and calls `:Disable` on the module object.
yellowfive@57 370 -- @name //addon//:DisableModule
yellowfive@57 371 -- @paramsig name
yellowfive@57 372 -- @usage
yellowfive@57 373 -- -- Disable MyModule using :GetModule
yellowfive@57 374 -- MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
yellowfive@57 375 -- MyModule = MyAddon:GetModule("MyModule")
yellowfive@57 376 -- MyModule:Disable()
yellowfive@57 377 --
yellowfive@57 378 -- -- Disable MyModule using the short-hand
yellowfive@57 379 -- MyAddon = LibStub("AceAddon-3.0"):GetAddon("MyAddon")
yellowfive@57 380 -- MyAddon:DisableModule("MyModule")
yellowfive@57 381 function DisableModule(self, name)
yellowfive@57 382 local module = self:GetModule( name )
yellowfive@57 383 return module:Disable()
yellowfive@57 384 end
yellowfive@57 385
yellowfive@57 386 --- Set the default libraries to be mixed into all modules created by this object.
yellowfive@57 387 -- Note that you can only change the default module libraries before any module is created.
yellowfive@57 388 -- @name //addon//:SetDefaultModuleLibraries
yellowfive@57 389 -- @paramsig lib[, lib, ...]
yellowfive@57 390 -- @param lib List of libraries to embed into the addon
yellowfive@57 391 -- @usage
yellowfive@57 392 -- -- Create the addon object
yellowfive@57 393 -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon")
yellowfive@57 394 -- -- Configure default libraries for modules (all modules need AceEvent-3.0)
yellowfive@57 395 -- MyAddon:SetDefaultModuleLibraries("AceEvent-3.0")
yellowfive@57 396 -- -- Create a module
yellowfive@57 397 -- MyModule = MyAddon:NewModule("MyModule")
yellowfive@57 398 function SetDefaultModuleLibraries(self, ...)
yellowfive@57 399 if next(self.modules) then
yellowfive@57 400 error("Usage: SetDefaultModuleLibraries(...): cannot change the module defaults after a module has been registered.", 2)
yellowfive@57 401 end
yellowfive@57 402 self.defaultModuleLibraries = {...}
yellowfive@57 403 end
yellowfive@57 404
yellowfive@57 405 --- Set the default state in which new modules are being created.
yellowfive@57 406 -- Note that you can only change the default state before any module is created.
yellowfive@57 407 -- @name //addon//:SetDefaultModuleState
yellowfive@57 408 -- @paramsig state
yellowfive@57 409 -- @param state Default state for new modules, true for enabled, false for disabled
yellowfive@57 410 -- @usage
yellowfive@57 411 -- -- Create the addon object
yellowfive@57 412 -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("MyAddon")
yellowfive@57 413 -- -- Set the default state to "disabled"
yellowfive@57 414 -- MyAddon:SetDefaultModuleState(false)
yellowfive@57 415 -- -- Create a module and explicilty enable it
yellowfive@57 416 -- MyModule = MyAddon:NewModule("MyModule")
yellowfive@57 417 -- MyModule:Enable()
yellowfive@57 418 function SetDefaultModuleState(self, state)
yellowfive@57 419 if next(self.modules) then
yellowfive@57 420 error("Usage: SetDefaultModuleState(state): cannot change the module defaults after a module has been registered.", 2)
yellowfive@57 421 end
yellowfive@57 422 self.defaultModuleState = state
yellowfive@57 423 end
yellowfive@57 424
yellowfive@57 425 --- Set the default prototype to use for new modules on creation.
yellowfive@57 426 -- Note that you can only change the default prototype before any module is created.
yellowfive@57 427 -- @name //addon//:SetDefaultModulePrototype
yellowfive@57 428 -- @paramsig prototype
yellowfive@57 429 -- @param prototype Default prototype for the new modules (table)
yellowfive@57 430 -- @usage
yellowfive@57 431 -- -- Define a prototype
yellowfive@57 432 -- local prototype = { OnEnable = function(self) print("OnEnable called!") end }
yellowfive@57 433 -- -- Set the default prototype
yellowfive@57 434 -- MyAddon:SetDefaultModulePrototype(prototype)
yellowfive@57 435 -- -- Create a module and explicitly Enable it
yellowfive@57 436 -- MyModule = MyAddon:NewModule("MyModule")
yellowfive@57 437 -- MyModule:Enable()
yellowfive@57 438 -- -- should print "OnEnable called!" now
yellowfive@57 439 -- @see NewModule
yellowfive@57 440 function SetDefaultModulePrototype(self, prototype)
yellowfive@57 441 if next(self.modules) then
yellowfive@57 442 error("Usage: SetDefaultModulePrototype(prototype): cannot change the module defaults after a module has been registered.", 2)
yellowfive@57 443 end
yellowfive@57 444 if type(prototype) ~= "table" then
yellowfive@57 445 error(("Usage: SetDefaultModulePrototype(prototype): 'prototype' - table expected got '%s'."):format(type(prototype)), 2)
yellowfive@57 446 end
yellowfive@57 447 self.defaultModulePrototype = prototype
yellowfive@57 448 end
yellowfive@57 449
yellowfive@57 450 --- Set the state of an addon or module
yellowfive@57 451 -- This should only be called before any enabling actually happend, e.g. in/before OnInitialize.
yellowfive@57 452 -- @name //addon//:SetEnabledState
yellowfive@57 453 -- @paramsig state
yellowfive@57 454 -- @param state the state of an addon or module (enabled=true, disabled=false)
yellowfive@57 455 function SetEnabledState(self, state)
yellowfive@57 456 self.enabledState = state
yellowfive@57 457 end
yellowfive@57 458
yellowfive@57 459
yellowfive@57 460 --- Return an iterator of all modules associated to the addon.
yellowfive@57 461 -- @name //addon//:IterateModules
yellowfive@57 462 -- @paramsig
yellowfive@57 463 -- @usage
yellowfive@57 464 -- -- Enable all modules
yellowfive@57 465 -- for name, module in MyAddon:IterateModules() do
yellowfive@57 466 -- module:Enable()
yellowfive@57 467 -- end
yellowfive@57 468 local function IterateModules(self) return pairs(self.modules) end
yellowfive@57 469
yellowfive@57 470 -- Returns an iterator of all embeds in the addon
yellowfive@57 471 -- @name //addon//:IterateEmbeds
yellowfive@57 472 -- @paramsig
yellowfive@57 473 local function IterateEmbeds(self) return pairs(AceAddon.embeds[self]) end
yellowfive@57 474
yellowfive@57 475 --- Query the enabledState of an addon.
yellowfive@57 476 -- @name //addon//:IsEnabled
yellowfive@57 477 -- @paramsig
yellowfive@57 478 -- @usage
yellowfive@57 479 -- if MyAddon:IsEnabled() then
yellowfive@57 480 -- MyAddon:Disable()
yellowfive@57 481 -- end
yellowfive@57 482 local function IsEnabled(self) return self.enabledState end
yellowfive@57 483 local mixins = {
yellowfive@57 484 NewModule = NewModule,
yellowfive@57 485 GetModule = GetModule,
yellowfive@57 486 Enable = Enable,
yellowfive@57 487 Disable = Disable,
yellowfive@57 488 EnableModule = EnableModule,
yellowfive@57 489 DisableModule = DisableModule,
yellowfive@57 490 IsEnabled = IsEnabled,
yellowfive@57 491 SetDefaultModuleLibraries = SetDefaultModuleLibraries,
yellowfive@57 492 SetDefaultModuleState = SetDefaultModuleState,
yellowfive@57 493 SetDefaultModulePrototype = SetDefaultModulePrototype,
yellowfive@57 494 SetEnabledState = SetEnabledState,
yellowfive@57 495 IterateModules = IterateModules,
yellowfive@57 496 IterateEmbeds = IterateEmbeds,
yellowfive@57 497 GetName = GetName,
yellowfive@57 498 }
yellowfive@57 499 local function IsModule(self) return false end
yellowfive@57 500 local pmixins = {
yellowfive@57 501 defaultModuleState = true,
yellowfive@57 502 enabledState = true,
yellowfive@57 503 IsModule = IsModule,
yellowfive@57 504 }
yellowfive@57 505 -- Embed( target )
yellowfive@57 506 -- target (object) - target object to embed aceaddon in
yellowfive@57 507 --
yellowfive@57 508 -- this is a local function specifically since it's meant to be only called internally
yellowfive@57 509 function Embed(target, skipPMixins)
yellowfive@57 510 for k, v in pairs(mixins) do
yellowfive@57 511 target[k] = v
yellowfive@57 512 end
yellowfive@57 513 if not skipPMixins then
yellowfive@57 514 for k, v in pairs(pmixins) do
yellowfive@57 515 target[k] = target[k] or v
yellowfive@57 516 end
yellowfive@57 517 end
yellowfive@57 518 end
yellowfive@57 519
yellowfive@57 520
yellowfive@57 521 -- - Initialize the addon after creation.
yellowfive@57 522 -- This function is only used internally during the ADDON_LOADED event
yellowfive@57 523 -- It will call the **OnInitialize** function on the addon object (if present),
yellowfive@57 524 -- and the **OnEmbedInitialize** function on all embeded libraries.
yellowfive@57 525 --
yellowfive@57 526 -- **Note:** Do not call this function manually, unless you're absolutely sure that you know what you are doing.
yellowfive@57 527 -- @param addon addon object to intialize
yellowfive@57 528 function AceAddon:InitializeAddon(addon)
yellowfive@57 529 safecall(addon.OnInitialize, addon)
yellowfive@57 530
yellowfive@57 531 local embeds = self.embeds[addon]
yellowfive@57 532 for i = 1, #embeds do
yellowfive@57 533 local lib = LibStub:GetLibrary(embeds[i], true)
yellowfive@57 534 if lib then safecall(lib.OnEmbedInitialize, lib, addon) end
yellowfive@57 535 end
yellowfive@57 536
yellowfive@57 537 -- we don't call InitializeAddon on modules specifically, this is handled
yellowfive@57 538 -- from the event handler and only done _once_
yellowfive@57 539 end
yellowfive@57 540
yellowfive@57 541 -- - Enable the addon after creation.
yellowfive@57 542 -- Note: This function is only used internally during the PLAYER_LOGIN event, or during ADDON_LOADED,
yellowfive@57 543 -- if IsLoggedIn() already returns true at that point, e.g. for LoD Addons.
yellowfive@57 544 -- It will call the **OnEnable** function on the addon object (if present),
yellowfive@57 545 -- and the **OnEmbedEnable** function on all embeded libraries.\\
yellowfive@57 546 -- This function does not toggle the enable state of the addon itself, and will return early if the addon is disabled.
yellowfive@57 547 --
yellowfive@57 548 -- **Note:** Do not call this function manually, unless you're absolutely sure that you know what you are doing.
yellowfive@57 549 -- Use :Enable on the addon itself instead.
yellowfive@57 550 -- @param addon addon object to enable
yellowfive@57 551 function AceAddon:EnableAddon(addon)
yellowfive@57 552 if type(addon) == "string" then addon = AceAddon:GetAddon(addon) end
yellowfive@57 553 if self.statuses[addon.name] or not addon.enabledState then return false end
yellowfive@57 554
yellowfive@57 555 -- set the statuses first, before calling the OnEnable. this allows for Disabling of the addon in OnEnable.
yellowfive@57 556 self.statuses[addon.name] = true
yellowfive@57 557
yellowfive@57 558 safecall(addon.OnEnable, addon)
yellowfive@57 559
yellowfive@57 560 -- make sure we're still enabled before continueing
yellowfive@57 561 if self.statuses[addon.name] then
yellowfive@57 562 local embeds = self.embeds[addon]
yellowfive@57 563 for i = 1, #embeds do
yellowfive@57 564 local lib = LibStub:GetLibrary(embeds[i], true)
yellowfive@57 565 if lib then safecall(lib.OnEmbedEnable, lib, addon) end
yellowfive@57 566 end
yellowfive@57 567
yellowfive@57 568 -- enable possible modules.
yellowfive@57 569 local modules = addon.orderedModules
yellowfive@57 570 for i = 1, #modules do
yellowfive@57 571 self:EnableAddon(modules[i])
yellowfive@57 572 end
yellowfive@57 573 end
yellowfive@57 574 return self.statuses[addon.name] -- return true if we're disabled
yellowfive@57 575 end
yellowfive@57 576
yellowfive@57 577 -- - Disable the addon
yellowfive@57 578 -- Note: This function is only used internally.
yellowfive@57 579 -- It will call the **OnDisable** function on the addon object (if present),
yellowfive@57 580 -- and the **OnEmbedDisable** function on all embeded libraries.\\
yellowfive@57 581 -- This function does not toggle the enable state of the addon itself, and will return early if the addon is still enabled.
yellowfive@57 582 --
yellowfive@57 583 -- **Note:** Do not call this function manually, unless you're absolutely sure that you know what you are doing.
yellowfive@57 584 -- Use :Disable on the addon itself instead.
yellowfive@57 585 -- @param addon addon object to enable
yellowfive@57 586 function AceAddon:DisableAddon(addon)
yellowfive@57 587 if type(addon) == "string" then addon = AceAddon:GetAddon(addon) end
yellowfive@57 588 if not self.statuses[addon.name] then return false end
yellowfive@57 589
yellowfive@57 590 -- set statuses first before calling OnDisable, this allows for aborting the disable in OnDisable.
yellowfive@57 591 self.statuses[addon.name] = false
yellowfive@57 592
yellowfive@57 593 safecall( addon.OnDisable, addon )
yellowfive@57 594
yellowfive@57 595 -- make sure we're still disabling...
yellowfive@57 596 if not self.statuses[addon.name] then
yellowfive@57 597 local embeds = self.embeds[addon]
yellowfive@57 598 for i = 1, #embeds do
yellowfive@57 599 local lib = LibStub:GetLibrary(embeds[i], true)
yellowfive@57 600 if lib then safecall(lib.OnEmbedDisable, lib, addon) end
yellowfive@57 601 end
yellowfive@57 602 -- disable possible modules.
yellowfive@57 603 local modules = addon.orderedModules
yellowfive@57 604 for i = 1, #modules do
yellowfive@57 605 self:DisableAddon(modules[i])
yellowfive@57 606 end
yellowfive@57 607 end
yellowfive@57 608
yellowfive@57 609 return not self.statuses[addon.name] -- return true if we're disabled
yellowfive@57 610 end
yellowfive@57 611
yellowfive@57 612 --- Get an iterator over all registered addons.
yellowfive@57 613 -- @usage
yellowfive@57 614 -- -- Print a list of all installed AceAddon's
yellowfive@57 615 -- for name, addon in AceAddon:IterateAddons() do
yellowfive@57 616 -- print("Addon: " .. name)
yellowfive@57 617 -- end
yellowfive@57 618 function AceAddon:IterateAddons() return pairs(self.addons) end
yellowfive@57 619
yellowfive@57 620 --- Get an iterator over the internal status registry.
yellowfive@57 621 -- @usage
yellowfive@57 622 -- -- Print a list of all enabled addons
yellowfive@57 623 -- for name, status in AceAddon:IterateAddonStatus() do
yellowfive@57 624 -- if status then
yellowfive@57 625 -- print("EnabledAddon: " .. name)
yellowfive@57 626 -- end
yellowfive@57 627 -- end
yellowfive@57 628 function AceAddon:IterateAddonStatus() return pairs(self.statuses) end
yellowfive@57 629
yellowfive@57 630 -- Following Iterators are deprecated, and their addon specific versions should be used
yellowfive@57 631 -- e.g. addon:IterateEmbeds() instead of :IterateEmbedsOnAddon(addon)
yellowfive@57 632 function AceAddon:IterateEmbedsOnAddon(addon) return pairs(self.embeds[addon]) end
yellowfive@57 633 function AceAddon:IterateModulesOfAddon(addon) return pairs(addon.modules) end
yellowfive@57 634
yellowfive@57 635 -- Event Handling
yellowfive@57 636 local function onEvent(this, event, arg1)
yellowfive@57 637 -- 2011-08-17 nevcairiel - ignore the load event of Blizzard_DebugTools, so a potential startup error isn't swallowed up
yellowfive@57 638 if (event == "ADDON_LOADED" and arg1 ~= "Blizzard_DebugTools") or event == "PLAYER_LOGIN" then
yellowfive@57 639 -- if a addon loads another addon, recursion could happen here, so we need to validate the table on every iteration
yellowfive@57 640 while(#AceAddon.initializequeue > 0) do
yellowfive@57 641 local addon = tremove(AceAddon.initializequeue, 1)
yellowfive@57 642 -- this might be an issue with recursion - TODO: validate
yellowfive@57 643 if event == "ADDON_LOADED" then addon.baseName = arg1 end
yellowfive@57 644 AceAddon:InitializeAddon(addon)
yellowfive@57 645 tinsert(AceAddon.enablequeue, addon)
yellowfive@57 646 end
yellowfive@57 647
yellowfive@57 648 if IsLoggedIn() then
yellowfive@57 649 while(#AceAddon.enablequeue > 0) do
yellowfive@57 650 local addon = tremove(AceAddon.enablequeue, 1)
yellowfive@57 651 AceAddon:EnableAddon(addon)
yellowfive@57 652 end
yellowfive@57 653 end
yellowfive@57 654 end
yellowfive@57 655 end
yellowfive@57 656
yellowfive@57 657 AceAddon.frame:RegisterEvent("ADDON_LOADED")
yellowfive@57 658 AceAddon.frame:RegisterEvent("PLAYER_LOGIN")
yellowfive@57 659 AceAddon.frame:SetScript("OnEvent", onEvent)
yellowfive@57 660
yellowfive@57 661 -- upgrade embeded
yellowfive@57 662 for name, addon in pairs(AceAddon.addons) do
yellowfive@57 663 Embed(addon, true)
yellowfive@57 664 end
yellowfive@57 665
yellowfive@57 666 -- 2010-10-27 nevcairiel - add new "orderedModules" table
yellowfive@57 667 if oldminor and oldminor < 10 then
yellowfive@57 668 for name, addon in pairs(AceAddon.addons) do
yellowfive@57 669 addon.orderedModules = {}
yellowfive@57 670 for module_name, module in pairs(addon.modules) do
yellowfive@57 671 tinsert(addon.orderedModules, module)
yellowfive@57 672 end
yellowfive@57 673 end
yellowfive@57 674 end