UIOBJECT FontString

Main Menu
WoW API Widget API Widget scripts Lua API Events CVars XML schema Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs

FontString (inherits from LayeredRegion and FontInstance, created with Frame:CreateFontString) draws a block of text on the screen.

FontStrings are used widely through the UI, to display labels on controls, the names of units, keybindings on action buttons, health and mana values, and most other text data. You can change the text contents of it, set it to use a new FontObject, and set how it handles text that doesn't fit in its normal dimensions, such as how to wrap the text and whether to indent subsequent lines.

FontStrings must have a font assigned before they appear, either with SetFont() or SetFontObject(). FrameXML includes several fonts to choose from:

• FrameXML/SharedFontStyles.xml defines the traditional game fonts.
• FrameXML/FontStyles.xml defines additional fonts for certain use cases.

local f = CreateFrame("Frame")
local text = f:CreateFontString(nil, "ARTWORK", "GameFontNormal")
text:SetText("HelloWorld")

Or with a <FontString> element in an xml file

<FontString inherits="GameFontNormal" text="HelloWorld!">
	<!-- set anchors, font color, shadow and other properties here -->
</FontString>

Defined Methods

FontString:CalculateScreenAreaFromCharacterSpan(leftCharacterIndex, rightCharacterIndex)

FontString:CanNonSpaceWrap() - Get whether long strings without spaces are wrapped or truncated - New in 1.11.

FontString:CanWordWrap()

FontString:FindCharacterIndexAtCoordinate(x, y)

FontString:GetFieldSize()

FontString:GetLineHeight()

FontString:GetMaxLines()

FontString:GetNumLines() - Returns the number of lines

FontString:GetStringHeight() - Returns the height of the text in its current font, ignoring line wrapping

FontString:GetStringWidth() - Returns the length of the text, ignoring line wrapping

FontString:GetText() - Get the displayed text.

FontString:GetUnboundedStringWidth() - Returns the length of the text, ignoring line wrapping and truncation

FontString:GetWrappedWidth() - Returns the width of the longest line resulting from line wrapping

FontString:IsTruncated() - Returns whether the string is truncated because it lacked space

FontString:SetAlphaGradient(start, length) - Create or remove an alpha gradient over the text.

FontString:SetFixedColor()

FontString:SetFormattedText(formatstring[, ...]) - Set the formatted display text. - New in 2.3.

FontString:SetMaxLines()

FontString:SetNonSpaceWrap(wrapFlag) - Set whether long strings without spaces are wrapped or truncated.

FontString:SetText(text) - Set the displayed text.

FontString:SetTextHeight(pixelHeight) - Set the height of the text by scaling graphics (Note: Can distort text).

FontString:SetWordWrap(wrapFlag) - Set whether long strings of words are wrapped onto other lines.

Patch changes

• Patch 6.1.0 / API (2015-02-24): A bug circa 6.1 was attributed erroneous height calculations when "TOP" cand "CENTER" were the only anchored points.
  
• Patch 4.1.0 / API (2011-04-26): Methods added to calculate string length independently from Region:GetWidth().

  Previously, GetWidth() gave inconsistent results based on the order in which :Set() functions were used.^{[citation needed]} 
  

External links

• wowprogramming, Jim Whitehead