Simplify readme, all docs have been moved into GitHub wiki pages
This commit is contained in:
Tekkub
parent
1ec2d8b707
commit
6684021962
187
README.textile
187
README.textile
|
|
@ -1,180 +1,13 @@
|
|||
LibDataBroker is a small WoW addon library designed to provide a "MVC":http://en.wikipedia.org/wiki/Model-view-controller interface for use in various addons.
|
||||
LDB's primary goal is to "detach" plugins for TitanPanel and FuBar from the display addon.
|
||||
Plugins can provide data into a simple table, and display addons can receive callbacks to refresh their display of this data.
|
||||
LDB also provides a place for addons to register "quicklaunch" functions, removing the need for authors to embed many large libraries to create minimap buttons.
|
||||
Users who do not wish to be "plagued" by these buttons simply do not install an addon to render them.
|
||||
|
||||
h2. Using LibDataBroker-1.1
|
||||
Due to it's simple generic design, LDB can be used for any design where you wish to have an addon notified of changes to a table.
|
||||
|
||||
h3. Embedding the library
|
||||
h2. Links
|
||||
|
||||
LibDataBroker is designed to be embedded into the addons that use it.
|
||||
The user should never have to worry about what version of the library they have, or even really be aware of the library's existence.
|
||||
|
||||
Embedding the library is a fairly simple task. Simply include LibDataBroker-1.1.lua in your addon's files and add it into your TOC to be loaded.
|
||||
Make sure that you include "LibStub":http://www.wowwiki.com/LibStub and "CallbackHandler-1.0":http://www.wowace.com/wiki/CallbackHandler-1.0 as well, and that they load before LDB.
|
||||
If you use Ace3 in your addon, you probably already have LibStub and CallbackHandler, just make sure they're loaded before LDB.
|
||||
|
||||
h3. Providing a dataobject
|
||||
|
||||
Before anyone can do anything, we need some data to display.
|
||||
For our first example, we'll provide a static dataobject that is simply declared on load and never changed after that.
|
||||
This implements the "Quicklauncher" spec below to create a button to open our config panel.
|
||||
|
||||
<pre>
|
||||
LibStub:GetLibrary("LibDataBroker-1.1"):NewDataObject("MyAddonName", {
|
||||
launcher = true,
|
||||
icon = "Interface\\Icons\\Spell_Nature_StormReach",
|
||||
OnClick = function(clickedframe, button) InterfaceOptionsFrame_OpenToFrame(myconfigframe) end,
|
||||
})
|
||||
</pre>
|
||||
|
||||
Pretty simple eh? Now why don't we make a dataobject that implements the "data display" spec.
|
||||
This data can be used by a display addon to create an always-up frame, like a FuBar plugin would.
|
||||
|
||||
<pre>
|
||||
local UPDATEPERIOD, elapsed = 0.5, 0
|
||||
local dataobj = LibStub:GetLibrary("LibDataBroker-1.1"):NewDataObject("myFPS", {text = "75.0 FPS"})
|
||||
local f = CreateFrame("frame")
|
||||
|
||||
f:SetScript("OnUpdate", function(self, elap)
|
||||
elapsed = elapsed + elap
|
||||
if elapsed < UPDATEPERIOD then return end
|
||||
|
||||
elapsed = 0
|
||||
local fps = GetFramerate()
|
||||
dataobj.text = string_format("%.1f FPS", fps)
|
||||
end)
|
||||
|
||||
function dataobj.OnEnter(self)
|
||||
GameTooltip:SetOwner(self, "ANCHOR_NONE")
|
||||
GameTooltip:SetPoint("TOPLEFT", self, "BOTTOMLEFT")
|
||||
GameTooltip:ClearLines()
|
||||
GameTooltip:AddLine("myFPS")
|
||||
GameTooltip:Show()
|
||||
end
|
||||
|
||||
function dataobj.OnLeave()
|
||||
GameTooltip:Hide()
|
||||
end
|
||||
</pre>
|
||||
|
||||
Here our dataobject gets updated every half-second with the current FPS.
|
||||
We also provide OnEnter and OnLeave script handlers.
|
||||
If the display addon chooses to attach these to the frame it uses for our data, the user will get a tooltip when they hover over that frame.
|
||||
|
||||
h3. Using a dataobject
|
||||
|
||||
So, we have a source of data now, how do we pull it into an addon and know when to update things? Easy!
|
||||
LDB uses Ace3's "CallbackHandler":http://www.wowace.com/wiki/CallbackHandler-1.0 to trigger callbacks in nearly the exact same way as "AceEvent3":http://www.wowace.com/wiki/AceEvent-3.0 does.
|
||||
|
||||
h4. Registering a callback
|
||||
|
||||
To receive updates from the library, we must register a callback function. There are three ways you can call <code>RegisterCallback</code>
|
||||
|
||||
<pre>
|
||||
local ldb = LibStub:GetLibrary("LibDataBroker-1.1")
|
||||
myTable.RegisterLDBCallback = ldb.RegisterCallback
|
||||
|
||||
myTable:RegisterLDBCallback("eventName"[, method[, arg]])
|
||||
ldb.RegisterCallback(myTable, "eventName"[, method[, arg]])
|
||||
ldb.RegisterCallback("myAddonId", "eventName"[, method[, arg]])
|
||||
</pre>
|
||||
|
||||
|_. Arg |_. Type |_. Description |
|
||||
|_. "eventName" | string | The name of the event you want to listen to. |
|
||||
|_. method | string or function | Which method to call. If string, self["method"] will be called. If left out (nil), self["eventName"] will be called. |
|
||||
|_. arg | optional | If present (even nil), this value will be passed to the receiving function. |
|
||||
|
||||
h4. Callback events
|
||||
|
||||
LDB provides 5 basic callbacks, one that is fired for for new dataobject registrations, and 4 that are fired any time a dataobject attribute is changed.
|
||||
|
||||
|_. Event name |_. Args passed |_. Description |
|
||||
|_. LibDataBroker_DataObjectCreated | name, dataobj | Fires when a new dataobject is created. Passes the DO's name and object. |
|
||||
|_. LibDataBroker_AttributeChanged | name, attr, value, dataobj | Fires for ALL attribute changes across ALL dataobjects. Passes the DO name, name of the attribute changed, new value of the attribute, and the dataobject. |
|
||||
|_. LibDataBroker_AttributeChanged_<name> | name, attr, value, dataobj | Fires for ALL attribute changes on the named dataobject. Passes the same args as <code>LibDataBroker_AttributeChanged</code> |
|
||||
|_. LibDataBroker_AttributeChanged_<name>_<attr> | name, attr, value, dataobj | Fires for changes to the named attribute on the named dataobject. Passes the same args as <code>LibDataBroker_AttributeChanged</code> |
|
||||
|_. LibDataBroker_AttributeChanged__<attr> | name, attr, value, dataobj | Fires for changes to the named attribute across ALL dataobjects. Passes the same args as <code>LibDataBroker_AttributeChanged</code> |
|
||||
|
||||
h4. Example
|
||||
|
||||
This code will register the "all changes" callback and print to the chat frame any time an attribute is changed on any dataobject.
|
||||
|
||||
<pre>
|
||||
local function mycallback(event, name, key, value, dataobj)
|
||||
ChatFrame1:AddMessage("LDB: "..name.. ".".. key.. " was changed to ".. tostring(value))
|
||||
end
|
||||
LibStub:GetLibrary("LibDataBroker-1.1").RegisterCallback("MyAnonCallback", "LibDataBroker_AttributeChanged", mycallback)
|
||||
</pre>
|
||||
|
||||
h3. Other API
|
||||
|
||||
LDB also provides a few basic functions for accessing dataobjects.
|
||||
|
||||
|_. Function |_. Description |
|
||||
|_. ldb:GetDataObjectByName(dataobjectname) | Retrieve a dataobject |
|
||||
|_. ldb:GetNameByDataObject(dataobject) | Lookup a dataobject's name |
|
||||
|_. ldb.DataObjectIterator() | Iter over all registered dataobjects. Works like <code>pairs</code><br/><pre>for name,dataobj in ldb.DataObjectIterator() do ...</pre> |
|
||||
|
||||
h2. Data Specifications
|
||||
|
||||
Provided below are two suggested data specs.
|
||||
These specs are very open to modification and enhancement by display addons, but plugins providing data should not expect that anything except the required fields are supported in the display.
|
||||
|
||||
h3. Data Display
|
||||
|
||||
Data display addons provide a LDB "feed" for an always-up addon to display.
|
||||
These addons can be thought of like RSS feeds, where the display addon is similar to an RSS reader.
|
||||
Display addons could include FuBar, Titan Panel, StatBlocks, LegoBlocks, or any other design out there.
|
||||
|
||||
h4. Fields
|
||||
|
||||
|_. text _Required_ | The text to be shown. |
|
||||
|_. label | A title for your feed, often shown to the left of the text, user might choose to hide this. |
|
||||
|_. icon | Full path to a texture, often shown to the left of the label or text. |
|
||||
|_. OnClick | An OnClick script handler to be directly attached to the display frame. Receives the usual args an OnClick receives (self, button). |
|
||||
|_. tooltiptext | A string for the display addon to pass directly to GameTooltip:SetText() when a tooltip is needed. |
|
||||
|_. OnTooltipShow | A function to call when the display wants to show a tooltip. The display will manage positioning, clearing and showing the tooltip, all this handler needs to do is populate the tooltip using :AddLine or similar. The display should pass the tooltip to this callback, in case it isn't using GameTooltip. |
|
||||
|_. OnEnter | An OnEnter script handler to be directly attached to the display frame. Usually used to display a tooltip. This handler should check the position of the frame it is passed and anchor the tolltip to that frame accordingly. |
|
||||
|_. OnLeave | An OnLeave script handler to be directly attached to the display frame. Usually used to hide the toolip. |
|
||||
|_. tooltip | A frame to be displayed when the display frame is entered. The display addon is responsible for anchoring, showing and hiding this frame as needed. The tooltip frame's OnShow can be used to refresh the frame. Note that this frame doesn't have to be a GameTooltip. |
|
||||
|
||||
h3. Quicklauncher
|
||||
|
||||
A quicklauncher is a LDB object that does not provide any data, but instead provides an OnClick handler to allow fast access to config panels, toggle settings, or perform other actions.
|
||||
|
||||
<em> Quicklaunchers should never expect a secure frame to be used, therefore actions like spellcasting are not possible. </em>
|
||||
|
||||
h4. Fields
|
||||
|
||||
|_. launcher _Required_ | Set to true, indicates that this data object is a launcher and does not provide any data to be rendered in an always-up frame. |
|
||||
|_. icon _Required_ | Full path to a texture for display. |
|
||||
|_. OnClick _Required_ | An OnClick script handler to be directly attached to the display frame. Receives the usual args an OnClick receives (self, button). |
|
||||
|_. tocname | The name of the addon providing the launcher, if it's name does not match the dataobject's name. Used by displays to get TOC metadata about the addon. |
|
||||
|_. label | A label to use for the launcher, overriding the dataobject name. |
|
||||
|
||||
h2. Addons using LDB
|
||||
|
||||
<div style="float:left; margin-right:2em;">
|
||||
|
||||
h3. Data Display addons
|
||||
|
||||
* Fortress (Unreleased)
|
||||
* StatBlockCore (Unreleased)
|
||||
* tekBlocks (Unreleased)
|
||||
|
||||
</div>
|
||||
|
||||
<div style="float:left; margin-right:2em;">
|
||||
|
||||
h3. Quicklaunch addons
|
||||
|
||||
* "Quickie":http://github.com/tekkub/quickie (Proof of concept)
|
||||
|
||||
</div>
|
||||
|
||||
<div style="float:left; margin-right:2em;">
|
||||
|
||||
h3. Misc
|
||||
|
||||
* FuBar2LDB (Unreleased)
|
||||
|
||||
</div>
|
||||
|
||||
<br style="clear:both" />
|
||||
* "API documentation":http://github.com/tekkub/libdatabroker-1-1/wikis/api
|
||||
* "Data specifications":http://github.com/tekkub/libdatabroker-1-1/wikis/data-specifications
|
||||
* "Addons using LDB":http://github.com/tekkub/libdatabroker-1-1/wikis/addons-using-ldb
|
||||
|
|
|
|||
Loading…
Reference in New Issue