UI escape sequences

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

→ UI Tech. Details

Many UI elements that display text on the screen support special escape sequences starting with the | pipe character.

Escape Sequences

Coloring

|cAARRGGBBtext|r

• Each pair of digits represents a color value (plus the alpha value, however the alpha value is currently ignored and should always be FF) as a hexadecimal number. The |r escape sequence pops nested color sequences in-order.^[1]

/run print("this is \124cFFFF0000red and \124cFF00FF00this is green\124r back to red\124r back to white")

> this is red and this is green back to red back to white

Global Colors

|cncolorname:text|r

• Renders a text string with a named global color.

/run print("Normal Text \124cnPURE_GREEN_COLOR:Green Text \124cnPURE_RED_COLOR:Red Text\124r Green Text\124r Normal Text")

> Normal Text Green Text Red Text Green Text Normal Text

Textures

|Tpath:height[:width[:offsetX:offsetY[:textureWidth:textureHeight:leftTexel:rightTexel:topTexel:bottomTexel[:rVertexColor:gVertexColor:bVertexColor]]]]|t

Will insert a texture into a font string. Parameter width is optional (see below). The offsets are optional and will shift the texture from where it would normally be placed. TextHeight is based on size of the font used - this is used to automatically scale icons based on the size of the text.

• height == 0; width omitted: Width = Height = TextHeight (always square!)
• height > 0;  width omitted: Width = Height = height (always square!)
• height == 0; width == 0   : Width = Height = TextHeight (always square!)
• height > 0;  width == 0   : Width = TextHeight; Height = height (height is height!!!)
• height == 0; width > 0    : Width = width * TextHeight; Height = TextHeight (width is an aspect ratio and defines width!!!)
• height > 0;  width > 0    : Width = width; Height = height
• offsetX offsetY: Offset for the rendered image, in pixels
• textureWidth textureHeight: Size of the source image, in pixels
• leftTexel rightTexel topTexel bottomTexel: (x1 x2 y1 y2) Coordinates that identify the left/right/top/bottom edges, in pixels (see Texture:SetTexCoord() but non-normalized)
• rVertexColor gVertexColor bVertexColor: RGB color values in the range 0-255 that are used to tint the texture

Notes:

• When you need to display a square icon in the string (spell/item icon), use only |Tpath:0|t
• When you need to display a rectangular image in the string (Blizzard logo), use aspect ratio version: |Tpath:0:aspectRatio|t

Texture atlas

Main article: AtlasID

Atlases allow for easily getting part of a texture without having to use tex coords. 📝 Note there is a : after |A.

|A:atlas:height:width[:offsetX:offsetY[:rVertexColor:gVertexColor:bVertexColor]]|a

Examples

• Both slash / or escaped backslashes \\ are valid file separators.
• Parameters that are zeros can be omitted in between :characters.

Coloring
"|cFFFF0000This is red text|r this is normal color" WrapTextInColorCode("This is red text", "FFFF0000").." this is normal color"	This is red text this is normal color
Texture
Accepts a file path or FileDataID. "|T133784:16|t Coins" "|TInterface\\Icons\\INV_Misc_Coin_01:16|t Coins" CreateTextureMarkup("Interface/Icons/INV_Misc_Coin_01", 64, 64, 16, 16, 0, 1, 0, 1)	Coins[2]
"|TInterface\\Icons\\INV_Misc_Coin_01:16:16:0:0:64:64:4:60:4:60|t Coins (cropped)"	Coins (cropped)
Sets the vertex color of the texture to green (73:177:73). "|TInterface\\ChatFrame\\UI-ChatIcon-ArmoryChat:14:14:0:0:16:16:0:16:0:16:73:177:73|t Reckful"	Reckful[3]
Texture atlas
Accepts an Atlas name or ID.[4] "|A:4259:19:19|a Tank" "|A:groupfinder-icon-role-large-tank:19:19|a Tank" "|Tinterface\\lfgframe\\groupfinder:19:19:::2048:1024:1805:1834:393:422|t Tank" CreateAtlasMarkup("groupfinder-icon-role-large-tank", 16, 16)	Tank[5]

Utility functions:

• WrapTextInColorCode()
• CreateTextureMarkup()
• CreateAtlasMarkup()

Protected strings

Also known as Kstrings - they prevent strings from being parsed. For example addons/scripts only see the string |Kq1|k instead of the actual displayed name.

• q for the confidentiality of Battle.net account names in C_BattleNet.GetFriendAccountInfo().
• r for the name and comment in group finder listings in C_LFGList.GetSearchResultInfo() and C_LFGList.GetActiveEntryInfo().
• u prevents using the message history as a persistent data storage in C_Club.GetMessageInfo() and C_Club.GetMessagesInRange().
• v for the message in CHAT_MSG_COMMUNITIES_CHANNEL.

Grammar

Korean

text|1A;B; is for Korean postpositions.^[6] For example object particles - Eul 을 is used following a consonant, Reul 를 is used following a vowel.

print("라면|1을;를;") -- 라면을 ramyeoneul
print("나무|1을;를;") -- 나무를 namureul

French

|2 text is for French prepositions - de before a consonant and d' before a vowel. Having zero, one or multiple trailing spaces after |2 does not matter for the end result.

print("|2 fraise") -- de fraise
print("|2 avion")  -- d'avion

Russian

|3-id(text) is for the Russian declension of nouns (including proper names) which take different forms based on their usage in a sentence.^[7] See also DeclineName().

print("|3-1(Кролик)") -- Кролика
print("|3-2(Кролик)") -- Кролику
print("|3-3(Кролик)") -- Кролика
print("|3-4(Кролик)") -- Кроликом
print("|3-5(Кролик)") -- Кролике

Plural

number |4singular:plural; or number |4singular:plural1:plural2; for ruRU. This assigns the singular or plural form depending on the number.

print("1 |4car:cars;")      -- 1 car
print("2 |4car:cars;")      -- 2 cars
print("3 blue |4car:cars;") -- 3 blue cars

number |7singular:plural; behaves the same as |4 but appears to only with large numbers while on certain non-english locales.

print("1 |7Million:Millionen;") -- 1 Million
print("2 |7Million:Millionen;") -- 2 Millionen

A or an

|5 text is for indefinite articles, a is used before words starting with a consonant sound, an is used before words starting with a vowel sound. Optionally, a ^ modifier may be inserted to uppercase the article.

print("|5 banana")  -- a banana
print("|5 apple")   -- an apple
print("|5^ apple")  -- An apple

Lowercase

|6 TEXT appears to convert only the next word to lowercase. Multiple words can be converted if wrapped in parentheses.

print("|6 HELLO WORLD") -- hello WORLD
print("|6(HELLO WORLD)") -- hello world

Word Wrapping

|Wtext|w

Hints that word wrapping of text should be avoided where possible. If the text would require wrapping the client will prefer to wrap before the start of the sequence instead of breaking it up. If the text is still too large, the hint may be ignored and the text broken up regardless.

Other

|n: Newline, if the widget supports it. Similar behavior as \n and \r

||: Escapes the "|" character.

Any invalid escape sequences will be displayed as-is or is otherwise undefined behavior.

Patch changes

• Patch 9.0.1 (2020-10-13): The |r escape sequence pops nested color sequences in-order instead of resetting the text to the default color.
  
• Patch 5.4.1 (2013-10-29): Added the |W escape sequence (word wrapping).
  
• Patch 4.0.1 (2010-10-12): Added the |K escape sequence (Kstrings).
  

See also

• Hyperlinks