Widget: SimpleHTML
← Widget API < SimpleHTML
SimpleHTML widgets allow display of simple HTML markup as well as standard escape sequences. See also XML/SimpleHTML.
Summary[edit]
HTML markup and the standard escape sequences may be combined in the same text. If HTML is not valid, not well-formed XHTML, it will be displayed literally.
SimpleHTML appears to have all the methods of FontInstance, and can be used in the same way to set the default font, but they all have an optional first parameter for which element's font to set, like "h1", "h2", "p", etc... The font instance methods are not reflected in the SimpleHTML frame until you SetText on the frame. It also appears that you can only supply the block elements and not the inline elements, like Hyperlinks cannot be colored a different color. Other than that, see UIOBJECT FontInstance for documentation of these methods.
Supported HTML[edit]
- h1, h2, h3, p - text containers
<(h1|h2|h3|p) [align="(left|center|right)"]>...</(h1|h2|h3|p)>- align - (left, center, right) controls positioning of the text element,
- img - image, only outside of text containers
<img src="IMAGE_SOURCE" [align="(left|center|right)"] [width="NUM"] [height="NUM"] />- align - (left, center, right) controls positioning of the image
- width - (number) width of image in pixels
- height - (number) height of image in pixels
- src - (string) image source, for example Interface\Icons\Ability_Ambush
- a - anchor (link only), only displayed inside text containers
<a href="LINK">TEXT</a>- href - (string) link to pass OnHyperLink* widget handlers
- br - line break
<br />- no attributes
HTML Notes[edit]
The following conditions and quirks apply:
- SimpleHTML will only display text as HTML if it is well-formed
- Tag names are case insensitive, img and iMg achieve the same result
- All tags must be closed. Some tags are self-closing, like br, img.
- Closing tags must match the case of the opening tag.
- Attribute values must be quoted. Both double and single quotes are supported.
- Quotes, less/greater than signs, and ampersands must be entity-escaped, like:
'"' '<' '>' '&'. No other entity-escapes are supported. - Unrecognized tags are ignored entirely, even if they contain known tags inside.
- Unrecognized attributes are ignored.
- Document content must be enclosed in
<html><body> </body></html>tags.
Standard escape sequences[edit]
SimpleHTML also supports the usual UI Escape Sequences, which can be used to change font color, or as an alternative syntax to specify hyperlinks.
Setting element styles[edit]
It is possible to set different fonts for the text-container elements, like h1, h2, h3, and p, using SetFont:
SimpleHTML:SetFont('h1', GameFontHighlightLarge);
You can also define font properties for these elements in your XML files, like:
<SimpleHTML ...>
<FontStringHeader1 inherits="GameFontHighlightLarge"/>
</SimpleHTML>
See XML/SimpleHTML for XML details.
Creation using pure Lua[edit]
Create the SimpleHTML object
local simpleHTML = CreateFrame('SimpleHTML');
Assign the HTML code to be displayed.
simpleHTML:SetText('<html><body><h1>Heading1</h1><p>A paragraph</p></body></html>');
For the SimpleHTML object to actual render HTML or plain text, a font must be set.
simpleHTML:SetFont('Fonts\\FRIZQT__.TTF', 11);
The literal number 11 specifies the size of the font.
Examples[edit]
The following is an example of a combination of HTML markup and UI Escape Sequences, as well as custom element styles. The code below was passed to 'SimpleHTML:SetText()' to generate the image on the right.
<html><body>
<h1>SimpleHTML Demo: Ambush</h1>
<img src="Interface\Icons\Ability_Ambush" width="32" height="32" align="right"/>
<p align="center">|cffee4400'You think this hurts? Just wait.'|r</p>
<br/><br/>
<p>Among every ability a rogue has at his disposal,<br/>
Ambush is without a doubt the hardest hitting Rogue ability.</p>
</body></html>