WowAce

LibNameplateRegistry-1.0 public API documentation

Check the Callbacks' page if you want details about those.

Here is a fully working little add-on as an example displaying nameplates' information as they become available.
You can download a ready to go archive of this example add-on from GitHub

For a more advanced usage example you can take a look at the latest version of HHTD.

Example

local ADDON_NAME, T = ...;

-- Create a new Add-on object using AceAddon
T.Example = LibStub("AceAddon-3.0"):NewAddon("Example", "LibNameplateRegistry-1.0");

-- You could also use LibNameplateRegistry-1.0 directly:
T.Example2 = {};
LibStub("LibNameplateRegistry-1.0"):Embed(T.Example2); -- embedding is optional of course but way more convenient


local Example = T.Example;

function Example:OnEnable()
    -- Subscribe to callbacks
    self:LNR_RegisterCallback("LNR_ON_NEW_PLATE"); -- registering this event will enable the library else it'll remain idle
    self:LNR_RegisterCallback("LNR_ON_RECYCLE_PLATE");
    self:LNR_RegisterCallback("LNR_ON_GUID_FOUND");
    self:LNR_RegisterCallback("LNR_ERROR_FATAL_INCOMPATIBILITY");
end

function Example:OnDisable()
    -- unregister all LibNameplateRegistry callbacks, which will disable it if
    -- your add-on was the only one to use it
    self:LNR_UnregisterAllCallbacks();
end


function Example:LNR_ON_NEW_PLATE(eventname, plateFrame, plateData)
    print(ADDON_NAME, ":", plateData.name, "'s nameplate appeared!");
    print(ADDON_NAME, ":", "It's a", plateData.type, "and", plateData.reaction,
          plateData.GUID and ("we know its GUID: " .. plateData.GUID) or "GUID not yet known");
end


function Example:LNR_ON_RECYCLE_PLATE(eventname, plateFrame, plateData)
    print(ADDON_NAME, ":", plateData.name, "'s nameplate disappeared!");
end


function Example:LNR_ON_GUID_FOUND(eventname, frame, GUID, findmethod)
    -- This is now rarely useful since WoW 7 since GUIDs are linked directly on nameplate appearance.
    -- Sometimes though some data about a unit may not be available right away due to heavy lag.
    print(ADDON_NAME, ":", "GUID found using", findmethod, "for", self:GetPlateName(frame), "'s nameplate:", GUID);
end


function Example:LNR_ERROR_FATAL_INCOMPATIBILITY(eventname, icompatibilityType)
    -- Here you want to check if your add-on and LibNameplateRegistry are not
    -- outdated (old TOC) and display a nice error message to your user.
end

addon:EachPlateByName

(name) Returns an iterator to iterate through all nameplates sharing an identical name

Used to iterate through nameplates using their names.

Since nameplates are not necessary unique it's best to always use this method to get a nameplate's frame through it's name.

Parameters

name

The name you want to iterate with

Return value

iterator

Usage

    for frame, plateData in self:EachPlateByName(unitName) do
    -- code
    end

addon:GetPlateByGUID(GUID)

Gets a platename's frame and known associated plateData using a GUID

Parameters

GUID

a unit GUID as returned by UnitGUID() WoW API

Return value

plateFrame, plateData or nil

addon:GetPlateGUID(plateFrame)

Gets a nameplate's unit's GUID if known

Parameters

plateFrame

the platename's root frame

Return value

associated unit's GUID as returned by the UnitGUID() WoW API or nil if the GUID is unknown

addon:GetPlateName(plateFrame)

Returns a nameplate's unit's name (removing the " (*)" suffix if present)

Parameters

plateFrame

the platename's root frame

Return value

The name of the unit as displayed on the nameplate or nil

addon:GetPlateReaction(plateFrame)

Gets a nameplate's unit's reaction toward the player

Parameters

plateFrame

the platename's root frame

Return value

either "FRIENDLY", "NEUTRAL", "HOSTILE", "TAPPED" or nil

addon:GetPlateRegion(plateFrame, internalRegionNormalizedName)

(DEPRECATED) Gets a platename's frame specific region using a normalized name.
Since WoW 7 nameplates can be linked to unit IDs to get the proper information directly using the standard WoW API thus GetPlateRegion should not be used anymore.

Use this API to get an easy and direct access to a specific sub-frame of any nameplate. This is useful if you want to access data for which LibNameplateRegistry provides no API (yet).

The result is cached for each frame making subsequent identical calls very fast.

The following regions are supported: 'name', 'statusBar', 'raidIcon'. If you need to access a specific region which is not supported, please make a feature request using the ticket system.

Parameters

plateFrame

the platename's root frame

internalRegionNormalizedName

a normalized name referring to a specific region

Return value

region or throws an error if asked an unsupported region's name.

addon:GetPlateType(plateFrame)

Gets a nameplate's unit's type

Parameters

plateFrame

the platename's root frame

Return value

either "NPC", "PLAYER" or nil

addon:LNR_RegisterCallback

(callbackName [, method] [, extraArg] ) Registers a LibNameplateRegistry callback
It's simply wrapping CallbackHandler-1.0's RegisterCallback() method.

Parameters

callbackName

name of a callback (see the Callbacks' page)

method

(optional) The method to call when the callback fires, if ommitted, addon:eventname is used

...

(optional) An optional extra argument that is past to your handler as first argument (after 'self')

addon:LNR_UnregisterAllCallbacks()

Unregisters all LibNameplateRegistry callbacks

addon:LNR_UnregisterCallback(callbackName)

Unregisters a LibNameplateRegistry callback (see CallbackHandler-1.0 documentation)

Parameters

callbackName

the callback to stop tracking