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 = <use link to construct line to add to tooltip>
frame:AddLine(newline);
end`

- frame is a `GameTooltip` object derived from `GameTooltipTemplate`
- link is a basic link (no colour/formatting info or displayable 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, when this event fires, LinkWrangler is guaranteed to be fully loaded and initialized

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. Do not include the initial "/lw " part of the command.
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" [, ...]] )
Register your callback function to be called by LinkWrangler when certain events occur.
"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 using `_G[]`
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", "item", "spell", "enchant", "achievement", "talent", "quest", "glyph". These correspond to the events described under the your callback function section. Some events were not available in earlier versions; refer to that same section for version numbers.
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, linktype = 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 a basic 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 : a string containing a link (item-link, spell-link, etc.), suitable for use in SetHyperlink.
textlink : a Link String containing link, name and colour codes, suitable for use in a chat message (not always available, may be nil)
name : a string containing the name of the linked item (or spell, etc.)
whisper : a string containing the name of the person who 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, will be nil
linktype : a string describing the type of link, e.g. "item" or "spell"
frame = OpenTooltip (link [,{options}]) (version 1.64 or later)
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)
{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; LinkWrangler only uses this if it cannot obtain a textlink by another method
openmin=true : causes the LinkWrangler window to be opened as a minimized window
(The options table can be reused, 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
ButtonClick (button) {Hook} (version 1.77 or later)
May be hooked to detect when one of the buttons on a tooltip is clicked. Use button:GetParent() to determine which tooltip.
The following extra values are defined:
button.ButtonType : key value (string) used to determine which type of button was clicked
button.IsCompare : true if the button belongs to a Compare tooltip
ButtonTypes: "CloseMain", "CloseComp", "Minimize", "Compare", "Whisper", "Relink", "Link", "Dressup", "Capture"

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 compatibility 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 the `AddLine` method or a similar function
If you added your function to `LINK_WRANGLER_CALLER` your function, in effect, receives "refresh" events
"item", "spell", "enchant", "achievement", "talent", "quest", "glyph": (version 1.8 or later)
One of these events immediately follows every refresh event, depending of the type of link displayed in the tooltip.
Allows you to direct each registered link type to a different callback function (by calling RegisterCallback multiple times)
Allows you to register to only receive 'refresh' events for links of the type(s) your AddOn can handle
"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.
The contents of the tooltip should not be modified during this event - any changes should be made during a refreshcomp event instead.
Note: the link is a Link String, with name and colour codes
"refreshcomp": (version 1.64 or later)
This parallels the refresh event, for Compare windows
Under current implementation, it always immediately 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#)

### 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).