WoW:UIOBJECT GameTooltip: Difference between revisions

{{widget}}

Tooltips are notoriously difficult to handle in WoW UI code, as the interaction of GameTooltip methods can be quite complicated. This page has some examples for the use of tooltips, and a collection of advanced points to note about the finer details. For an indepth analysis of GameTooltip methods, see [[Tooltip Pseudo Code]] for a Lua-ish pseudo code representation of every GameTooltip method. See [[Widget API]] for a reference list of all GameTooltip methods.  

The game engine assumes that there is a GameTooltip object called GameTooltip, and that it has a number of known fontstrings in it. The GameTooltip:Set___() methods manipulate the object and its children directly and then show the tooltip object. When you mouse over things in the game world, the game engine internally calls the equivalent of :Set____() - not the actual Lua method. In particular, this means that hooked GameTooltip methods will never trigger for engine-generated tooltips. Hooks will however catch all other tooltips generated from the UI itself. For non-item/unit tooltips you will even see :AddLine and :AddDoubleLine calls.

Each line of text from the game tooltip is represented by one of these objects, replace <num> with the appropriate line number (from 1 to the number of lines returned from GameTooltip:NumLines()). To obtain the text of a line call the [[API FontString GetText|GameTooltipTextLeft''<num>'':GetText()]] function.

     for i = 1, select("#", ...) do

         local region = select(i, ...)

function EnumerateTooltipLines(tooltip) -- good for script handlers that pass the tooltip as the first argument.

     EnumerateTooltipLines_helper(tooltip:GetRegions())

* The tooltip displayed when the mouse is hovering over players and/or NPCs on the minimap is such that all the units being displayed are actually only on the first tooltip line.  So, if the tooltip showed 4 players, the names are all in the first tooltip line, delimited by "\n".

Some tooltips have both left- and right-aligned sections. In order to get at the right-aligned section, use one of these objects instead of a GameTooltipTextLeft. Otherwise, the functionality is identical.

The definition of the tooltip in your XML should look like this:

When actually using the tooltip in your code, you need to do:

where SetX could be SetInventorySlot, SetBagItem, SetAction, SetUnitBuff etc. The explicit call to MyScanningTooltip:ClearLines() is necessary becuase a SetX call usually doesn't clear the tooltip if called with invalid arguments, e.g. an empty bag slot or nonexistent buff. Care must be taken so that MyScanningTooltip:Show() or MyScanningTooltip:Hide() doesn't get called at any time, otherwise the tooltip becomes unusable. Note that the way SetOwner was called, the tooltip will never be visible on the screen, and therefore it's not necessary to hide it.

Instead of the above, here is an alternative solution. It is sufficient to have this in your XML:

Each time you want to use the tooltip however, you must explicitly set the owner like this:

This solution is safer and more robust to potential changes to tooltip behaviour in future patches. However, this solution incurs significant performance penalty. Repeatedly calling MyScanningTooltip:SetOwner in an OnUpdate handler can cause significant frame-rate drop. Hence this solution is recommended for tooltip scans that occur in response to for example key presses, whereas the previous solution is recommended for repeated, frequent scans.

* Showing the parent of the tooltip causes Show to be called on the tooltip.

* It is therefore recommended practice to not set a parent to your tooltip, and especially not UIParent.