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.
For examples on how to implement these specs, see How to provide a dataobject.
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.
|type Required||string|| Set to
|text Required||string||The text to be shown.|
|value||string|| Raw value from the text, for example text
|suffix||string|| The “unit” appended to the end of text. For example text
|label||string||A title for your feed, often shown to the left of the text, user might choose to hide this. If missing, the dataobject’s name may be used instead.|
|icon||string||Full path to a texture, often shown to the left of the label or text.|
|OnClick||function||An OnClick script handler to be directly attached to the display frame. Receives the usual args an OnClick receives (self, button).|
|OnTooltipShow||function||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. The display shouldn’t pass a non-GameTooltip frame unless it mimics the API of GameTooltip.|
|OnEnter||function||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 tooltip to that frame accordingly.|
|OnLeave||function||An OnLeave script handler to be directly attached to the display frame. Usually used to hide the toolip.|
|tooltip||frame||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.|
The different tooltip specs might seem a bit overboard, but they each have their reasons. So, to clear up a bit of the confusion…
This method is designed for displays that want control over how the tooltip is anchored and displayed. This is probably the most frequent case. In this design, the display handles everything except filling the tooltip with data. Naturally, it must pass the tooltip to be filled to the callback, some display addons might use their own tooltip instead of the global GameTooltip. This method should never be passed a frame that doesn’t support the methods GameTooltip supports, nor should the function called use methods that don’t exist for GameTooltips.
-- Don't let the mixed use of dot- (.) and colon-notation (:) confuse you here! -- -- In the data source addon... function dataobj:OnTooltipShow() self:AddLine("This is a test!") self:AddLine("Don't mind me...") end -- In the display addon... local function OnEnter(self) GameTooltip:SetOwner(self, "ANCHOR_NONE") GameTooltip:SetPoint("TOPLEFT", self, "BOTTOMLEFT") GameTooltip:ClearLines() dataobj.OnTooltipShow(GameTooltip) GameTooltip:Show() end
This design is needed by plugins that wish to provide a clickable tooltip. Because the clickable tip is more complex, the plugin needs to manage when it is hidden, it can’t simply hide the tip when the base frame loses mouse focus. These functions should be attached directly to the display frame’s OnEnter and OnLeave scripts.
This option is a bit of a merge between the OnEnter/OnLeave and OnTooltipShow designs. Here the plugin provides a frame (it’s likely not a GameTooltip) for the display to anchor and show. The plugin can use the frame’s OnShow to refresh the data in the frame when it is shown. This allows the plugin to use a custom frame instead of a GameTooltip, but still allows the display control over how the frame is anchored and shown.
Tooltips and display addons
It’s possible that a source addon may provide more that one tooltip method. The display addon should only use one of these (even if it support all three in the spec). The generally preferred order is: tooltip > OnEnter/OnLeave > OnTooltipShow.
Generally speaking, tooltip is not likely to be implemented along with another render method. OnEnter may also provide (and use) OnTooltipShow, in this case it’s usually preferred that the display simply set the OnEnter handler directly to the frame, thus bypassing the display’s tooltip handling code and never calling OnTooltipShow from the display.
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.
Quicklaunchers should never expect a secure frame to be used, therefore actions like spellcasting are not possible.
|type Required||string|| Set to
|icon Required||string||Full path to a texture for display.|
|OnClick Required||function||An OnClick script handler to be directly attached to the display frame. Receives the usual args an OnClick receives (self, button).|
|tocname||string||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||string||A label to use for the launcher, overriding the dataobject name.|
Extension or Deviations of Data Source and Launcher
There are a number of extensions or alterations in use for data source and launchers. Here is a fluid list of those additions and variations. Authors of data provider addons or display addons that support extensions or alterations are strongly encourages to document this here so that third parties can consider these additions for their needs.
Fields for both Data Source and Launcher
|Field||Type||Display Support||Source Support|
|label||string||StatBlockCore||Any addon setting .label|
|A label to use for the launcher. This is an alternation. Instead of the display setting this, it is in fact to be set either by the data source/launcher. This field can be written to by displays to allow the user editable labels. SavedVariable handling is as yet open.|
|The red component value to be used when coloring the icon.|
|The green component value to be used when coloring the icon.|
|The blue component value to be used when coloring the icon.|
|A table containing the arguments to be supplied to SetTexCoord() on the icon texture. Combined with icon, iconR, iconG and iconB this attribute provides a way for addons to use icons that require TexCoords (such as re-using the icons from the default user interface without the button background). This is currently used by TomTom to display a spinning arrow that points towards your current waypoint.|
|A function to call when the display wants to show a tooltip. This is an extension. 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. Common use is to explain the mapping of click buttons to function (e.g. left click for hide window, right click for config window etc.).|
Creating your own custom spec
LDB is designed to be very generic. If you wish you can create your own custom spec to allow the plugin-display design within your own addons. The only requirement for these custom specs is to set the
type attribute to a unique string so that other display addons will not try to render your custom dataobjects. For example, the Quicklauncher spec sets this attribute to “launcher” and the Data Display spec uses “data source”.