WowAce

LibQTip-1.0

LibQTip-1.0 acts as a tooltip Factory.

:Acquire(key[, numColumns, column1Justification, column2justification, ...])

Create or retrieve the tooltip with the given key. If additional arguments are passed, they are passed to :SetColumnLayout for the acquired tooltip.

Arguments

key

string or table - the tooltip key. Any value that can be used as a table key is accepted though you should try to provide unique keys to avoid conflicts. Numbers and booleans should be avoided and strings should be carefully chosen to avoid namespace clashes - no "MyTooltip" - you have been warned!

Return values

tooltip

Frame object - the acquired tooltip.

Sample

 -- Acquire a tooltip with at least 5 columns, justification : left, center, left, left, left
 local tip = LibStub('LibQTip-1.0'):Acquire('MyFooBarTooltip', 5, "LEFT", "CENTER")

:IsAcquired(key)

Check if a given tooltip has been acquired and not released.

Arguments

key

string or table - the key to check

Return values

isAcquired

boolean - true if the tooltip with the given key has been acquired.

:Release(tooltip)

Return an acquired tooltip to the heap. The tooltip is cleared and hidden.

Arguments

tooltip

Frame object - the tooltip to release. Any invalid values are silently ignored.

:IterateTooltips()

Return an iterator on the acquired tooltips.

Return values

tooltipIterator

iterator - iterator to be used in "for in" statement.

Sample

 for key, tooltip in LibQTip:IterateTooltips() do
    -- do something with tooltip.
 end

:CreateCellProvider(baseProvider)

Convenience method to create a new cell provider. Although one can use anything that matches the CellProvider and Cell interfaces, this method provides an easy way to create new providers.

Please note that this methods provides a fully-fledged CellProvider with additional methods and requirements. See standard CellProvider API for more details and sample.

Arguments

baseProvider (optional)

CellProvider object - an existing provider the new provider should be based on.

Return values

provider

CellProvider object - the new cell provider. It can be used with :SetCell.

cellPrototype

table - the prototype of the new cell. It must be extended with the mandatory :InitializeCell() and :SetupCell() methods.

baseCellPrototype

table - the prototype of baseProvider cells. It may be used to call base cell methods.

.LabelProvider

.LabelProvider is a built-in CellProvider used by default to create the tooltip cells.

Tooltip

Each tooltip is a proper Frame instance with all Frame methods plus the following methods:

:SetDefaultProvider(provider)

Define the cellprovider to be used for all cell functionality.

Arguments

provider

CellProvider object - the new default cellprovider.

:GetDefaultProvider()

Return the cellprovider used for cell functionality.

Return values

provider

CellProvider object - the current default cellprovider.

:SetColumnLayout(numColumns[, column1Justification, column2justification, ...])

Ensure the tooltip has at least the passed number of columns, adding new columns if need be. The justification of existing columns is reset to the passed values.

Arguments

numColumns

number - minimum number of columns

columnXJustification (optional)

"LEFT", "CENTER" or "RIGHT" - default justification of each column, defaults to "LEFT".

Samples

 -- Ensured to have at least 3 columns with justification: left, right, center
 tip:SetColumnLayout(3, "LEFT", "RIGHT", "CENTER")
 
 -- Ensured to have at least 5 columns, all left-justified
 tip:SetColumnLayout(5)

:AddColumn([justification])

Add a new column to the right of the tooltip.

Arguments

justification (optional)

"LEFT", "CENTER" or "RIGHT" - the default justification of cells in this column, defaults to "LEFT"

Return values

colIndex

number - the index of the newly added column.

Sample

 -- Add a new left-justified column
 tip:AddColumn()

:UpdateScrolling(maxheight)

Resizes the tooltip to fit the screen and show a scrollbar if needed.

:Clear()

Reset the contents of the tootip. The column layout is preserved but all lines are wiped.

:SetFont(font)

Define the font used when adding new lines.

Arguments

font

Font object - the new regular font.

Sample

 -- Use a red font based on GameTooltipText for regular line
 local myFont = CreateFont("MyFont")
 myFont:CopyFontObject(GameTooltipText)
 myFont:SetTextColor(1,0,0)
 tip:SetFont(myFont)

:GetFont()

Return the font used for regular lines.

Return values

font

Font object - the regular font.

:SetHeaderFont(font)

Define the font used when adding new header lines.

Arguments

font

Font object - the new header font.

:GetHeaderFont()

Return the font used for header lines.

Return values

font

Font object - the header font.

:AddLine([column1Value, column2Value, ...])

Add a new line at the bottom of the tooltip.

You can provide values to be displayed on the line with the regular font. Nil values are ignored. If the number of values is greater than the number of columns, an error is raised.

Arguments

columnXValue

mixed - label to be shown in each column of the line.

Return value

lineIndex

number - the index of the newly added line.

columnIndex

number or nil - the index of the next empty cell in the line or nil if it is full.

Samples

 -- Add a line with two values, any 
 tip:AddLine("First column", "Second column")
 
 -- Add a line with nothing in the first column
 tip:AddLine(nil, "Second column")
 
 -- Add an empty line (with an height equal to 0 until a cell is added)
 tip:AddLine()
 
 -- Add an empty line with a proper height
 tip:AddLine(" ")
 
 -- Add a newline, filling each column with the values of a table
 -- while preventing any error if the table has more values
 -- than the tooltip has columns.
 tip:AddLine(unpack(t, 1, tip:GetColumnCount())

:AddHeader([col1Value, col2Value, ...])

Add a new header line at the bottom of the tooltip. Basically works as AddLine but using the header font.

You can provide values to be displayed on the line with the header font. Nil values are ignored. If the number of values is greater than the number of columns, an error is raised.

Arguments

columnXValue

mixed - label to be shown in each column of the line.

Return value

lineIndex

number - the index of the newly added line.

columnIndex

number or nil - the index of the next empty cell in the line or nil if it is full.

:AddSeparator([height][, r][, g][, b][, a])

Adds a graphical separator line at the bottom of the tooltip.

Arguments

height (optional)

number - Height, in pixels, of the separator. Defaults to 1.

r (optional)

number - Red color value of the separator. Defaults to NORMAL_FONT_COLOR.r

g (optional)

number - Green color value of the separator. Defaults to NORMAL_FONT_COLOR.g

b (optional)

number - Blue color value of the separator. Defaults to NORMAL_FONT_COLOR.b

a (optional)

number - Alpha level of the separator. Defaults to 1.

Return value

lineIndex

number - the index of the newly added line.

columnIndex

number or nil - the index of the next empty cell in the line or nil if it is full.

:SetColumnColor(colNum[, r][, g][, b][, a])

Sets the color of the specified column of the tooltip.

Arguments

colNum

number - Column number to set. Mandatory: must be a valid column.

r (optional)

number - Red color value of the column. Defaults to the tooltip's current red value.

g (optional)

number - Green color value of the column. Defaults to the tooltip's current green value.

b (optional)

number - Blue color value of the column. Defaults to the tooltip's current blue value.

a (optional)

number - Alpha level of the column. Defaults to 1.

:SetColumnTextColor(colNum[, r][, g][, b][, a])

Sets the color of the text for the specified column of the tooltip.

Arguments

colNum

number - Column number to set. Mandatory: must be a valid column.

r (optional)

number - Red color value of the column text. Defaults to the red value of the tooltip's current font.

g (optional)

number - Green color value of the column text. Defaults to the green value of the tooltip's current font.

b (optional)

number - Blue color value of the column text. Defaults to the blue value of the tooltip's current font.

a (optional)

number - Alpha level of the column's text. Defaults to 1.

:SetLineColor(lineNum[, r][, g][, b][, a])

Sets the color of the specified line of the tooltip.

Arguments

lineNum

number - Line number to set. Mandatory: must be a valid line.

r (optional)

number - Red color value of the line. Defaults to the tooltip's current red value.

g (optional)

number - Green color value of the line. Defaults to the tooltip's current green value.

b (optional)

number - Blue color value of the line. Defaults to the tooltip's current blue value.

a (optional)

number - Alpha level of the line. Defaults to 1.

:SetLineTextColor(lineNum[, r][, g][, b][, a])

Sets the color of the text for the specified line of the tooltip.

Arguments

lineNum

number - Line number to set. Mandatory: must be a valid line.

r (optional)

number - Red color value of the line text. Defaults to the red value of the tooltip's current font.

g (optional)

number - Green color value of the line text. Defaults to the green value of the tooltip's current font.

b (optional)

number - Blue color value of the line text. Defaults to the blue value of the tooltip's current font.

a (optional)

number - Alpha level of the line text. Defaults to 1.

:SetCellColor(lineNum, colNum[, r][, g][, b][, a])

Sets the color of the specified cell in the tooltip.

Arguments

lineNum

number - Line number where the cell resides. Mandatory: must be a valid line.

colNum

number - Column number where the cell resides. Mandatory: must be a valid column.

r (optional)

number - Red color value of the cell. Defaults to the tooltip's current red value.

g (optional)

number - Green color value of the cell. Defaults to the tooltip's current green value.

b (optional)

number - Blue color value of the cell. Defaults to the tooltip's current blue value.

a (optional)

number - Alpha level of the cell. Defaults to 1.

:SetCellTextColor(lineNum, colNum[, r][, g][, b][, a])

Sets the color of the text for the specified cell in the tooltip.

Arguments

lineNum

number - Line number where the cell resides. Mandatory: must be a valid line.

colNum

number - Column number where the cell resides. Mandatory: must be a valid column.

r (optional)

number - Red color value of the cell text. Defaults to the red value of the tooltip's current font.

g (optional)

number - Green color value of the cell text. Defaults to the green value of the tooltip's current font.

b (optional)

number - Blue color value of the cell text. Defaults to the blue value of the tooltip's current font.

a (optional)

number - Alpha level of the cell text. Defaults to 1.

:SetCellScript(lineNum, colNum, script, func[, arg])

Assign a script to a cell at the given line and column indices.

Arguments

lineNum

number - line index of the cell.

colNum

number - column index of the cell.

script

One of: "OnEnter", "OnLeave", "OnMouseUp", or "OnMouseDown".

func

function - The function which is called when the script is run.

arg

mixed - Optional.

:SetColumnScript(colNum, script, func[, arg])

Assign a script to a column at the given index.

Arguments

colNum

number - column index.

script

One of: "OnEnter", "OnLeave", "OnMouseUp", or "OnMouseDown".

func

function - The function which is called when the script is run.

arg

mixed - Optional.

:SetLineScript(lineNum, script, func[, arg])

Assign a script to a line at the given index.

Arguments

lineNum

number - line index.

script

One of: "OnEnter", "OnLeave", "OnMouseUp", or "OnMouseDown".

func

function - The function which is called when the script is run.

arg

mixed - Optional.

:SetHighlightTexture(texture) or :SetHighlightTexture(red, green, blue [, alpha])

Sets the texture of the highlight when mousing over a line or cell that has a script assigned to it. Works identically to the default UI's texture:SetTexture() API.

:SetHighlightTexCoord(left, right, top, bottom) or :SetHighlightTexCoord(ULx, ULy, LLx, LLy, URx, URy, LRx, LRy)

Works identically to the default UI's texture:SetTexCoord() API, for the tooltip's highlight texture.

:SetCell(lineNum, colNum, value[, font][, justification][, colSpan][, provider][, leftPadding][, rightPadding][, maxWidth][, minWidth][, ...])

Add or replace a cell at the given line and column indices. The additional arguments override the tooltip defaults.

This is the low-level, core method of the tooltip.

Arguments

lineNum

number - line index of the cell. Indexes greater than tooltip:GetLineCount() raise an error.

colNum

number - column index of the cell. Indexes greater than tooltip:GetColumnCount() raise an error.

value

mixed - the value to display in the cell.

font (optional)

Font object or nil - the rendering font. Defaults to regular font.

justification (optional)

"LEFT", "CENTER", "RIGHT" or nil - cell-specific justification to use. Defaults to column justification.

colSpan (optional)

number or nil - create a cell spanning this number of columns. Defaults to 1.

provider (optional)

CellProvider object - the CellProvider to use instead of the default one. Defaults to LibQTip.LabelProvider.

leftPadding (optional)

number or nil - creates padding on the left side of the cell's value equal to the supplied number. Defaults to 0.

rightPadding (optional)

number or nil - creates padding on the right side of the cell's value equal to the supplied number. Defaults to 0.

maxWidth (optional)

number or nil - specify the maximum width (in pixels) of the cell. If the cell's value is textual and exceeds this width, it will wrap to a new line. If specified, must not be less than the value of minWidth.

minWidth (optional)

number or nil - specify the minimum width (in pixels) of the cell. Must not exceed the value of maxWidth, if it is specified.

... (optional)

mixed - additional arguments to pass to the cell:SetupCell method (see Cell interface below).

Return value

lineIndex

number - the index of the newly added line.

columnIndex

number or nil - the index of the next empty cell in the line or nil if it is full.

Samples

 -- Add an empty line we will add cell to
 local y ,x = tip:AddLine()
 
 -- Put a label in the first column of the line
 tip:SetCell(y, 1, "First column")
 
 -- Put a label in the second column with another font
 tip:SetCell(y, 2, "Second column", myFont)
 
 -- Put a centered label in the third column
 tip:SetCell(y, 3, "Third column", "CENTER")
 
 -- Put a 2-column-wide, right-justified cell in the fourth column
 tip:SetCell(y, 4, "Fourth column", "RIGHT", 2)
 
 -- Put a value provided by an imaginary money cell provider in the 6th column
 tip:SetCell(y, 6, 10025, moneyCellProvider)

 -- Create a new line
 -- Add a cell that spans every column but the rightmost one
 -- Add a cell on the rightmost column
 local y, x = tip:AddLine()
 y, x = tip:SetCell(y, x, "Label", -1)
 y, x = tip:SetCell(y, x, 5)

:SetCellMarginH(size)

Sets the horizontal margin size of all cells within the tooltip.

This function can only be used before the tooltip has had lines set.

Arguments

size

number - The desired margin size. Must be a positive number or zero.

:SetCellMarginV(size)

Sets the vertical margin size of all cells within the tooltip.

This function can only be used before the tooltip has had lines set.

Arguments

size

number - The desired margin size. Must be a positive number or zero.

:GetLineCount()

Returns the total number of lines of the tooltip.

Return values

lineCount

number - number of lines added using :AddLine or :AddHeader.

:GetColumnCount()

Returns the total number of columns of the tooltip.

Return values

columnCount

number - number of columns added using :SetColumnLayout or :AddColumn.

:SetAutoHideDelay(delay, alternateFrame, releaseHandler)

Sets the length of time in which the mouse pointer can be outside of the tooltip, or an alternate frame, before the tooltip is automatically hidden and then released.

Arguments

delay

float - either whole or fractional seconds.

alternateFrame

Frame object - if specified, the tooltip will not be automatically hidden if the mouse pointer is over this.

releaseHandler

function - Called when the tooltip is released. Generally used to clean up a reference an AddOn has to the tooltip frame, since another AddOn can subsequently acquire it.

Samples

-- Disable auto-hiding (default)
tooltip:SetAutoHideDelay()

-- Hide after 0.25 seconds outside of tooltip
tooltip:SetAutoHideDelay(0.25)

-- Hide after 0.25 seconds outside of the tooltip or an LibDataBroker data object
function LDB_DO:OnEnter(self)
	tooltip = LibStub('LibQTip-1.0'):Acquire('MyFooBarTooltip', 5, "LEFT", "CENTER")
	tooltip:SmartAnchorTo(self)
	tooltip:SetAutoHideDelay(0.25, self)
	DisplayTooltip() -- Tooltip population function
end

:SmartAnchorTo(frame)

Smartly anchor the tooltip to the given frame and ensure that it is always on screen.

Arguments

frame

Frame object - the frame to anchor the tooltip to.

CellProvider interface

This interface describes the minimal set of methods that must be implemented by a custom CellProvider in order to be used by LibQTip.

:AcquireCell(tooltip)

Acquire a new cell to be displayed in the tooltip. LibQTip manages parent, framelevel, anchors, visibility and size of the cell.

Arguments

tooltip

Frame object - the tooltip acquiring the cell.

Return value

cell

Frame object - the created cell.

:ReleaseCell(cell)

Release a cell that LibQTip is no longer using. The cell has already been hidden, unanchored and orphaned by LibQTip.

Arguments

cell

Frame object - the cell to release.

:GetCellPrototype()

Return the prototype and metatable used to create new cells.

Return values

cellPrototype

table - the prototype on which cell are based.

cellMetatable

table - the metatable used to create new cell.

Cell interface

This interface describes the minimal set of methods that must be implemented by a custom Cell in order to be used by LibQTip.

:SetupCell(tooltip, value, justification, font[, leftPadding][, rightPadding][, maxWidth][, minWidth], ...)

Setup the cell with the given arguments.

Arguments

tooltip

Frame object - the tooltip the cell belongs to.

value

mixed - the non-nil value to be displayed in the cell.

justification

"LEFT", "CENTER" or "RIGHT" - the justification of the cell.

font

Font object - the font used to display the value.

leftPadding (optional)

number or nil - creates padding on the left side of the cell's value equal to the supplied number. Defaults to 0.

rightPadding (optional)

number or nil - creates padding on the right side of the cell's value equal to the supplied number. Defaults to 0.

maxWidth (optional)

number or nil - specify the maximum width (in pixels) of the cell. If the cell's value is textual and exceeds this width, it will wrap to a new line. If specified, must not be less than the value of minWidth.

minWidth (optional)

number or nil - specify the minimum width (in pixels) of the cell. Must not exceed the value of maxWidth, if it is specified.

...

mixed - any additional arguments passed to :SetCell

Return values

width

number - the minimal width of the content.

height

number - the minimal height of the content.

:GetPosition()

Returns the cell's position within the containing tooltip.

Return value

lineIndex

number - the line index of cell.

columnIndex

number or nil - the column index of cell.