annotate Libs/AceAddon-3.0/AceAddon-3.0.lua @ 15:21cefa363c73 tip

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