LibCoreAPI

[nightcracker]

Hi all!
I'm making a library to add some more functions to the WoW API and widget API. Mainly to make your life easier, and to shorten up your code. I'm asking YOU what you want added in it, so post here! This is what I have currently(I will be editing this post):

local metatables = {}
local dummy = function() end
 
for key, val in pairs(_G) do 
    if type(val)=="table" and val.GetObjectType then
        obj = val:GetObjectType()
        if not metatables[obj] then
            metatables[obj] = getmetatable(val).__index
        end
    end
end
 
local function destroy(self)
    self.Show = dummy
    self:Hide()
    if self.UnregisterAllEvents then
        self:UnregisterAllEvents()
    end
end
 
local function fireevent(self, event, ...)
    local handler = self:GetScript("OnEvent")
    if handler then
        handler(self, event, ...)
        return true
    end
    return false
end
 
local function fire(self, script, ...)
    local handler = self:GetScript(script)
    if handler then
        handler(self, ...)
        return true
    end
    return false
end
 
local function lock(self)
    self.ClearAllPoints = dummy
    self.SetPoint = dummy
    self.SetAllPoints = dummy
end
 
local function unlock(self)
    self.ClearAllPoints = nil
    self.SetPoint = nil
    self.SetAllPoints = nil
end
 
local function setsize(self, w, h)
    self:SetWidth(w)
    self:SetHeight(h or w)
end
 
local function getclassbycolor(r, g, b)
    r, g, b = floor(r*100+.5)/100, floor(g*100+.5)/100, floor(b*100+.5)/100
    for class, color in pairs(RAID_CLASS_COLORS) do
        if color.r==r and color.g==g and color.b==b then
            return class
        end
    end
    return false
end
 
local function getsize(self)
    return self:GetWidth(), self:GetHeight()
end
 
local function setclassicon(self, class)
    self:SetTexture("Interface\\WorldStateFrame\\Icons-Classes")
    if class then
        local classcoords = CLASS_BUTTONS[class]
        if classcoords then
            self:SetTexCoord(unpack(classcoords))
            return true
        else
            self:SetTexCoord(.5, .75, .5, .75)
            return false
        end
    end
    return false
end
 
local function islocked(self)
    if self.ClearAllPoints==dummy and self.SetPoint==dummy and self.SetAllPoints==dummy then
        return true
    end
    return false
end
 
local function isdestroyed(self)
    if self.Show==dummy and not self:IsShown() then
        return true
    end
    return false
end
 
local function toggle(self)
    if self:IsShown() then
        self:Hide()
        return false
    end
    self:Show()
    return true
end
 
local function setshown(self, show)
    if show then
        self:Show()
    else
        self:Hide()
    end
end
 
for key, val in pairs(metatables) do
    if val.Hide then -- Region object
        val.Destroy = destroy
        val.IsDestroyed = isdestroyed
        val.SetSize = setsize
        val.GetSize = getsize
        val.Lock = lock
        val.Unlock = unlock
        val.IsLocked = islocked
        val.Toggle = toggle
        val.SetShown = setshown
    end
    if val.RegisterEvent then -- Frame object
        val.FireEvent = fireevent
    end
    if val.GetScript then -- Any object with scripts
        val.Fire = fire
    end
    if val.SetTexture then -- Texture object
        val.SetClassIcon = setclassicon
    end
end
 
GetClassByColor = getclassbycolor

This adds the following API functions:

GetClassByColor(red, green, blue)
Returns the class associated with the color.

And the following API Widget functions:

Region:Destroy()
Permanently hides the region and unregisters events if associated.

Region:IsDestroyed()
Returns true if the region is destroyed, otherwise false.

Region:Lock()
Blocks all attempts of moving this region until it's unlocked.

Region:Unlock()
Unlocks the frame from the above function.

Region:IsLocked()
Returns true if the region is locked, otherwise false.

Region:SetSize(width, [height])
Sets the width and height of this region, if only one parameter is given both width and height will be set to the same value. Example: Region:SetSize(10, 15) sets the width to 10 and height to 15 while Region:SetSize(15) sets the width and height to 15.

Region:GetSize()
Returns the width and height of the region. Example: local width, height = Region:GetSize()

Region:Toggle()
Hides the region if shown, shows the region if hidden. Returns true if the region is now shown, false if the region is now hidden.

Region:SetShown(show)
If show is a true value(any value except nil and false) then the region is shown, else the region is hidden.

Frame:FireEvent(event, ...)
Fires the event handler of the frame with the parameter "event" as the event, and ... the parameters. The ... variable means there could be as many parameters as you want. You must not give the "self" variable in the parameters(this is done automaticly). Returns true if the handler has been executed, false if not.

Frame:Fire(script, ...)
Fires the event handler of the frame for the script "script" with parameters "...". For example, Frame:Fire("OnUpdate", 2) will run the OnUpdate handler for the frame as if 2 seconds have elapsed. Don't give the "self" variable in the parameters, this is done automaticly. Returns true if the handler has been executed, false if not.

Texture:SetClassIcon(class)
Set's the texture of this texture object to the class icon of the parameter given. The class parameter MUST be in the english version capitalized, not the localized version! If an invalid class is given the texture will be set to transparent. Example: Texture:SetClassIcon("WARRIOR") will set the texture of the object to the class icon of a warrior. No textures except blizzard's have been used for this function. Returns true if the class icon was found and set, false if not.

[nightcracker]

Woops, this should be in Pre-Beta Interfaces/Scripts, can someone move it please?

[xConStruct]

Region:SetShown(shown)
    if shown then
        self:Show()
    else
       self:Hide()
    end
end

This often bothered me

And I would suggest to make getter-functions for your new Set() ones:
- destroyed = Region:IsDestroyed()
- locked = Region:IsLocked()
- width, height = Region:GetSize()

And try to provide return values as often as possible to show if it was successful or not.
- success = Frame:FireEvent()
- success = Frame:Fire()
- success = Texture:SetClassIcon()

[nightcracker]

Originally Posted by Cargor Region:SetShown(shown) if shown then self:Show() else self:Hide() end end This often bothered me And I would suggest to make getter-functions for your new Set() ones: - destroyed = Region:IsDestroyed() - locked = Region:IsLocked() - width, height = Region:GetSize() And try to provide return values as often as possible to show if it was successful or not. - success = Frame:FireEvent() - success = Frame:Fire() - success = Texture:SetClassIcon()

Nice to see some interest, adding those! Also I'm adding a :Toggle() script.

EDIT: Added!

[nightcracker]

Should I loop _G like this for gathering all metatables, or should I run this once, write the names down, and always use these(subject to changes/deletion of frames by blizzard)?

local metatables = {}
for key, val in pairs(_G) do 
    if type(val)=="table" and val.GetObjectType then
        obj = val:GetObjectType()
        if not metatables[obj] then
            metatables[obj] = getmetatable(val).__index
        end
    end
end

[Slakah]

Originally Posted by nightcracker Should I loop _G like this for gathering all metatables, or should I run this once, write the names down, and always use these(subject to changes/deletion of frames by blizzard)? local metatables = {} for key, val in pairs(_G) do     if type(val)=="table" and val.GetObjectType then         obj = val:GetObjectType()         if not metatables[obj] then             metatables[obj] = getmetatable(val).__index         end     end end

You don't need to at all, all frames of the same type share the same metatable so muck about with one and you'll muck about with all of them (although there might be some frames which don't i.e. the ChatFrames)

But really imo a library shouldn't add methods to addons frames which don't use it.

[nightcracker]

Originally Posted by Slakah I never suggested that frames of different types have the same metatable: Anyway looping through a few frame types would be a lot easier than going through _G.

Finally the answer :P

Originally Posted by nightcracker Should I loop _G like this for gathering all metatables, or should I run this once, write the names down, and always use these(subject to changes/deletion of frames by blizzard)? local metatables = {} for key, val in pairs(_G) do     if type(val)=="table" and val.GetObjectType then         obj = val:GetObjectType()         if not metatables[obj] then             metatables[obj] = getmetatable(val).__index         end     end end

[Mikord]

I really wish addon authors would stop mucking about with the global environment. It's never a good idea. I've had to fix several "bugs" that are due to this type of stuff and frankly, it is frustrating.

You asked for an example earlier. Here is some example code that I've seen in a legitimate addon before that your changes would break:

local frame=CreateFrame("Frame")
 
'...
 
if someEventHasHappened then frame.Fire = true end
 
' ...Later in the code
 
' Check if some event should be fired
if frame.Fire then DoSomethingUseful() end

Because you've added a Fire entry that would be detected via the metatable, the check would always pass regardless and you've just hosed this code. It would have to be changed to use rawget. Making others code around you is not very responsible.

Also, what if I were to come behind you, decide to be clever too and create a metatable of my own with some functions *I* think are useful? In the process I blow away your metatables to use my own. Now every addon that makes use of your extensions will break.

I hope you can see why modifying the global environment is just a bad idea. Please don't do it.


Edit:

I see haste beat me to it above. Using LibStub with a specialized CreateFrame call is a much better approach.

Everybody using the global CreateFrame is unaffected as it should be and those who want to use your extensions have an easy way to do so.

[Saiket]

Feels like I'm forum muted.

[nightcracker]

My new system(which is immume to frame.Fire):

local version = 1.0
 
local metatables, registered = {}, {}
local noop = function() end
 
if LibCoreAPI then if LibCoreAPI.version<version then registered=LibCoreAPI.RegisteredAddons else return end end
 
for key, val in pairs(_G) do 
    if type(val)=="table" and val.GetObjectType then
        obj = val:GetObjectType()
        if not metatables[obj] then
            metatables[obj] = getmetatable(val).__index
        end
    end
end
 
local function registeraddon()
    registered[gsub(debugstack(2), ".*\\(.+)\\.+", "%1")] = true
end
 
local function destroy(self)
    self.Show = noop
    self:Hide()
    if self.UnregisterAllEvents then
        self:UnregisterAllEvents()
    end
end
 
local function fireevent(self, event, ...)
    local handler = self:GetScript("OnEvent")
    if handler then
        handler(self, event, ...)
        return true
    end
    return false
end
 
local function fire(self, script, ...)
    local handler = self:GetScript(script)
    if handler then
        handler(self, ...)
        return true
    end
    return false
end
 
local function lock(self)
    self.ClearAllPoints = noop
    self.SetPoint = noop
    self.SetAllPoints = noop
end
 
local function unlock(self)
    self.ClearAllPoints = nil
    self.SetPoint = nil
    self.SetAllPoints = nil
end
 
local function setsize(self, w, h)
    self:SetWidth(w)
    self:SetHeight(h or w)
end
 
local function getclassbycolor(r, g, b)
    r, g, b = floor(r*100+.5)/100, floor(g*100+.5)/100, floor(b*100+.5)/100
    for class, color in pairs(RAID_CLASS_COLORS) do
        if color.r==r and color.g==g and color.b==b then
            return class
        end
    end
    return false
end
 
local function getsize(self)
    return self:GetWidth(), self:GetHeight()
end
 
local function setclassicon(self, class)
    self:SetTexture("Interface\\WorldStateFrame\\Icons-Classes")
    if class then
        local classcoords = CLASS_BUTTONS[class]
        if classcoords then
            self:SetTexCoord(unpack(classcoords))
            return true
        else
            self:SetTexCoord(.5, .75, .5, .75)
            return false
        end
    end
    return false
end
 
local function islocked(self)
    if self.ClearAllPoints==noop and self.SetPoint==noop and self.SetAllPoints==noop then
        return true
    end
    return false
end
 
local function isdestroyed(self)
    if self.Show==noop and not self:IsShown() then
        return true
    end
    return false
end
 
local function toggle(self)
    if self:IsShown() then
        self:Hide()
        return false
    end
    self:Show()
    return true
end
 
local function setshown(self, show)
    if show then
        self:Show()
    else
        self:Hide()
    end
end
 
local methods = {
    Destroy = destroy,
    IsDestroyed = isdestroyed,
    SetSize = setsize,
    GetSize = getsize,
    Lock = lock,
    Unlock = unlock,
    IsLocked = islocked,
    Toggle = toggle,
    SetShown = setshown,
    FireEvent = fireevent,
    Fire = fire,
    SetClassIcon = setclassicon,
}
 
local dependencies = {
    Destroy = "Hide",
    IsDestroyed = "Hide",
    SetSize = "Hide",
    GetSize = "Hide",
    Lock = "Hide",
    Unlock = "Hide",
    IsLocked = "Hide",
    Toggle = "Hide",
    SetShown = "Hide",
    FireEvent = "RegisterEvent",
    Fire = "GetScript",
    SetClassIcon = "SetTexture",
}
 
local mt = {
    __index = function(tab, func)
        return registered[gsub(debugstack(2), ".*\\(.+)\\.+", "%1")] and methods[func] or nil
    end
}
 
for key, val in pairs(metatables) do
    setmetatable(val, mt)
end
 
LibCoreAPI = {
    GetClassByColor = getclassbycolor,
    Metatables = metatables,
    RegisteredAddons = registered,
    version = version,
}
 
setmetatable(LibCoreAPI, {
    __call = registeraddon,
})

If an addon calls LibCoreAPI() then it get's whitelisted and frameestroy() will return the correct function. If it's not whitelisted then frame.Fire will return an not found error.

[nightcracker]

OK, I screwed the metatables, if I use the above method then it taints the secure functions. LibStub it is!

The first uploaded BETA: http://www.wowinterface.com/download...reAPIBETA.html