Instructions for making your AddOn compatible with LinkWrangler:

Basic Instructions for making your AddOn compatible with LinkWrangler:

1.) Add a function to your AddOn that will handle the content you wish to add to a LinkWrangler Tooltip. It should match the following prototype, but can have any name you wish (i.e. only the function arguments are required). The function may be a local function.

function MyAddOn_AddStuff(frame,link)

    local newline =
<construct line to add to tooltip>

    frame:AddLine(newline);

end

frame is a window derived from GameTooltipTemplate
link is an Item String: a string containing the link ID of the item, but no colour/formatting info or item name. link is usually a copy of the first parameter originally passed to SetItemRef

2.) Register the VARIABLES_LOADED event, i.e. add the following code to your AddOn’s OnLoad Handler:

self:RegisterEvent("VARIABLES_LOADED");

VARIABLES_LOADED is chosen as the earliest single event (as far as most AddOns can tell) where LinkWrangler is guaranteed to be loaded

3.) Add the following code to your AddOn's OnEvent handler:

if (event ==
"VARIABLES_LOADED") then

    if (LinkWrangler ~= nil) then

       
LinkWrangler.RegisterCallback ("MyAddOnName", MyAddOn_AddStuff,
"refresh");

    end

end

RegisterCallback has additional options
The the first parameter used in RegisterCallback should be a String containing your AddOn's name – this value is used as a "key", and needs to be unique to your AddOn. Note that the user can view this name, to find out which AddOns are currently registered, so it must be printable
The second parameter of RegisterCallback accepts either a string containing the global name of your function, or a reference to the function itself
Once your callback function is registered, it will be called when any LinkWrangler window is opened or needs to be redrawn

The LinkWrangler global variable

This is a table holding exportable functions and variables for the new LinkWrangler-API. The following are documented:

Version
A floating point number containing the current version number. E.g.
if LinkWrangler.Version >= 1.6 then ...

CloseAllWindows ()
Function to close all LinkWrangler windows

MinimizeAllWindows () (version 1.63 or later)
Function which toggles states of open windows as follows:
If all open windows are already minimized, then all windows become maximized
Otherwise all windows become minimized.

MasterSwitch ("option" [,flag])
Function to enable or disable LinkWrangler, where "option" is one of "enable", "disable", "toggle" or "switch".
If "switch" is used, LinkWranger is enabled or disabled according to whether the optional flag parameter tests as true or false
Note: When LinkWrangler is disabled, all windows will be closed. It will also stop any background activities, such as tracking names in chat for the Whisper buttons.

SlashHandler (<command>)
Feeds the specified command string to the LinkWrangler slash command handler.
Note: The command set accepted by the slash handler is likely to change between versions.
Available commands are documented in SlashCommands.htm

RegisterCallback ("AddOnName", CallbackFunction , "event" [, "event" [, ...]] )

"AddOnName" is a key used to identify your addon - preferably it should be the name of your AddOn, as this means it will probably be unique, and allows the user to identify which addons are registered with LinkWrangler. It must be a string.

CallbackFunction is the function in your addon that you want LinkWrangler to call. This parameter must be one of the following:

A string containing the name of your function. The name must be a global variable which resolves to a function when using 'getglobal'
A reference to your function. In this case your function may be local.
nil : this removes a function that you have previously registered.

"event" must be 1 or more string parameters from the following: "refresh", "show", "hide", "maximize", "minimize", "allocate", "showcomp", "refreshcomp", "hidecomp", "allocatecomp"

success [, value[, value]] = CallbackData ("AddOnName", "command")
Request onformation about or modify the way LinkWrangler handles your AddOn.
Commands

"enable": enable the named AddOn for main windows
"disable": disable the named AddOn for main windows
"enablecomp": enable the named AddOn for compare windows
"disablecomp": disable the named AddOn for compare windows
Each of the 4 commands above, if succesful, return true, <main enable status>, <compare enable status>
"test": Test the state of the named AddOn.

If it exists, returns true, <main enable status>, <compare enable status>
If it doesn't exist, returns nil
The test command will never return any error messages

If an error is detected, returns nil and an error message string (and depending on debug settings, may pop up an error window).
An AddOn which has been 'disabled' will no longer receive events from LinkWrangler windows. The settings for main and compare windows are independant.
Note: This function should not be used during the "ADDON_LOADED" event for LinkWrangler, but should be valid any time after that event.

frame, state, link, textlink, name, whisper = GetLinkInfo ( tooltipframe | link | textlink )
The parameter must be one of the following:

tooltipframe: a reference to one of the LinkWrangler tooltip windows (e.g. a frame value received by your callback function)
link: a string containing an item link (no colour or name info) - tries to find an open LinkWrangler window displaying this link
textlink: a string containing full link, colour and name info (as received from GetItemInfo) - looks for an open LinkWrangler window holding this text link - note that if the stored link is localised to a different language it will not match

Return values:

frame : reference to the tooltip window - will be nil if no match was found
state : a number representing the current state of the frame:-

0 or negative: The window is closed. All return values following state should be treated as invalid (probably nil)
1 : Window is open
2 : Window is minimized
Other values may be returned. Assume that the other return values will be valid if and only if state >= 1

link : an Item String containing the item's link, suitable for use in SetHyperlink. Could also be a Recipe, Spell or Quest link.
textlink : a Link String containing link, name and colour codes, suitable for use in a chat message (if available)
name : a string containing the name of the item
whisper : a string containing the name of the character that most recently linked this item into chat - i.e. the person you would get if you click the Whisper button on the tooltip. If there is no whisperer, may be "" or nil

frame = OpenTooltip (link [,{options}]) (version 1.63 or later, options table added 1.632)
Opens a LinkWrangler tooltip window using the supplied link.

link: Expected to be of the same format as the first parameter of SetItemRef. Will accept any string containing a substring of this type (for example, a full Link String containing colour values - in this special case, LinkWrangler may use this Link String for it's Relink functions)
{options}: if supplied, must be a table where the following keys & values may be set:

whisper=<string> : sets whisper function to the character named in <string>
textlink=<string> : supplies a string which may be used for relinking. Current version of LinkWrangler would only use this for a Recipe or Enchant link
openmin=true : causes the LinkWrangler window to be opened as a minimized window

Note: The options table can be recycled or discarded after this function returns

Return values

frame : the window that LinkWrangler will attempt to open with the link. Will be nil if an error was encountered. Note that at the time this function returns, the window may not yet have opened - use GetLinkInfo to check the state, or register the refresh or open event

Undocumented Exports
Several functions and values are also exported in the LinkWrangler table, which are used internally by LinkWrangler, and which are not documented above. These are subject to change, so should not be called or hooked by any other AddOns at this time.

Your Callback function

The function should follow this prototype:
function MyAddon_Callback (frame, link [, event])

frame will be a reference to the LinkWrangler frame, which is derived from GameTooltipTemplate
link will normally be an Item String containing the link ID of the current item, with no name or colour codes. In certain circumstances, may be nil
event will be a string containing the name of the event. Will be nil for refresh events.

The optional event parameter will be one of the following codes; note that while multiple events may be passed to RegisterCallback (to register the same function for multiple events), the callback function will only receive one event code each time it is called.

refresh (note: the event parameter passed to your function will always be nil, instead of a string, for a refresh event - this is for compatability with older versions)

This is called whenever the text within a tooltip needs to be redrawn - this can happen fairly frequently
Intended for the majority of addons, which add content to a tooltip using AddLine or a similar function
If you added your function to LINK_WRANGLER_CALLER your function, in effect, receives "refresh" events

"maximize":

Called just before a tooltip gets de-minimized
Followed by refresh event

"minimize":

Called just before a tooltip gets minimized.

"show":

Called when the window is first opened, after the basic (Blizzard) data for the tooltip is loaded, but before other addons have modified the tooltip
Normally, but not always, followed by refresh event
Please do not modify text within a tooltip during this event (refresh should be used for that purpose)

"hide":

Called when a tooltip is about to be closed, but before the data in the tooltip is cleared

"allocate":

Called when a LinkWrangler frame is dynamically allocated
When an AddOn requests this event, it will immediately receive callbacks for any/all windows that already exist
Use this event if you want to implement your own hooks into LinkWranglerTooltip# frames
Note: the link parameter will usually be nil when this callback occurs.

"showcomp":

Called when a Compare window is opened, after basic (SetHyperlink) text has been set.
Now that the new refreshcomp event has been added, it is suggested that you do not modify tooltip text during this event
Note: the link is a Link String, with name and colour codes

"refreshcomp": (version 1.632 or later)

This parallels the refresh event, for Compare windows; under current implementation, it always follows a showcomp event, but this could change in future
Use this event to add or change text within a Compare tooltip. However please remember that Compare tooltips were intended as "mini" extensions to the main tooltip, and so should remain as small as possible.
The link parameter is a Link String, with name and colour codes

"hidecomp":

Called just before a Compare window is closed.
Note: The link is a Link String, with name and colour codes (though this is probably not relevant as the window is being hidden).

"allocatecomp":

As "allocate" but for Compare frames (LinkWranglerCompare#)

"scan": (obsolete)

LinkWrangler ignores requests for this callback (removed in version 1.704)
Originally intended for AddOns that want to scan all the text in a tooltip after it has finished being modifed
However some AddOns use alternative hooking methods, or could otherwise modify the tooltip after this event
meaning that this event can almost certainly never be made to work correctly as it was intended

"destroy": (obsolete)

Event not implemented. LinkWrangler accepts it, but does nothing with it.
There is an explanation below

"destroycomp": (obsolete)

Event not implemented. LinkWrangler accepts it, but does nothing with it.
There is an explanation below

LINK_WRANGLER_CALLER

LINK_WRANGLER_CALLER should not be used when writing new AddOns. The information provided here is intended to help any developer trying to troubleshoot an old AddOn.

This was the old method of registering your function to be called back by LinkWrangler. It will continue to be supported, so that any AddOns that use it do not need to be rewritten.

Typical usage (in the event handler) was:

if IsAddOnLoaded ("LinkWrangler") then
    LINK_WRANGLER_CALLER [ "AddOnName"] = "CallbackFunction"
end

or alternatively:

if LINK_WRANGLER_CALLER then <etc.>

Note that the original specification required the name of the callback function to be passed in a string. This prevents you from using a local name for the function.
Otherwise the requirements of AddOnName and CallbackFunction are as for RegisterCallback
The current version of Linkwrangler simply redirects LINK_WRANGLER_CALLER into RegisterCallback (effectively registering a refresh event).

More Coding Ideas

As an alternative to using a loading event (such as VARIABLES_LOADED), you may set LinkWrangler as an Optional Dependancy for your AddOn. This means that if LinkWrangler is installed, WoW will always load it before your AddOn. You can then put the registration code anywhere in your load code.

Frame De-Allocation - or not...

I had originally planned to allow for frames to be destroyed (de-allocated) to free up memory. However, according to some sources, it is not possible to completely free up the resources used by a frame (there are non-lua resources that can never be freed using lua code).
Therefore the "destroy" callback functions above will probably never be implemented. LinkWrangler will silently ignore any RegisterCallback requests for those events.