WoW:UIOBJECT SimpleHTML: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
(→‎Well-formed HTML: split code)
m (Move page script moved page UIOBJECT SimpleHTML to UIOBJECT SimpleHTML without leaving a redirect)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{widget}}
{{widget|tocright=0}}
'''SimpleHTML''' widgets allow display of simple HTML markup as well as standard escape sequences. The two may be combined; if HTML is not valid (not well-formed XHTML), it will be displayed literaly.
'''SimpleHTML''' widgets allow display of simple HTML markup as well as standard escape sequences. See also [[XML/SimpleHTML]].


==Supported HTML==
== Summary ==
The following HTML tags are supported:
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.  
; h1, h2, h3, p
: <code> &lt;(h1|h2|h3|p) [align="(left|center|right)"]&gt;...&lt;/(h1|h2|h3|p)&gt;</code>
: Text containers; following optional attributes are supported:
:*align - (left, center, right) controls positioning of the text element,
; img
:<code>&lt;img src="IMAGE_SOURCE" [align="(left|center|right)"] [width="NUM"] [height="NUM"] /&gt;</code>
: Image, only outside of text containers; following attributes are supported:
:*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
: <code>&lt;a href="LINK"&gt;TEXT&lt;/a></code>
: anchor (link only), only displayed inside text containers; following attributes are required:
:*href - (string) link to pass OnHyperLink* widget handlers
;br
: <code> &lt;br /&gt;</code>
: line break, no attributes.


===Well-formed HTML===
SimpleHTML appears to have all the methods of [[#FontInstance|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.
SimpleHTML will only display text as HTML if it is well-formed; the following conditions and quirks apply:
* Tag names are case insensitive, img and iMg achieve the same result.
* All tags must be closed; closing tags must match the case of the opening tag; some tags are self-closing (br, img).
* Attribute values must be quoted; both double and single quotes are supported.
* Quotes, less/greater than signs, and amperstands must be entity-escaped (<code>&amp;quot;</code> <code>&amp;lt;</code> <code>&amp;gt;</code> <code>&amp;amp;</code>). 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 <code>&lt;html>&lt;body>  &lt;/body>&lt;/html></code> tags.


==Standard escape sequences==
== Supported HTML ==
* h1, h2, h3, p - text containers
: <code><nowiki><(h1|h2|h3|p) [align="(left|center|right)"]>...</(h1|h2|h3|p)></nowiki></code>
:* align - (left, center, right) controls positioning of the text element,
 
* img - image, only outside of text containers
: <code><nowiki><img src="IMAGE_SOURCE" [align="(left|center|right)"] [width="NUM"] [height="NUM"] /></nowiki></code>
:* 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
: <code><nowiki><a href="LINK">TEXT</a></nowiki></code>
:* href - (string) link to pass OnHyperLink* widget handlers
 
* br - line break
: <code><nowiki><br /></nowiki></code>
:: no attributes
 
=== HTML Notes ===
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: <code>'&amp;quot;' '&amp;lt;' '&amp;gt;' '&amp;amp;'</code>. 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 <code><nowiki><html><body> </body></html></nowiki></code> tags.
 
== Standard escape sequences ==
SimpleHTML also supports the usual [[UI Escape Sequences]], which can be used to change font color, or as an alternative syntax to specify hyperlinks.
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==
== Setting element styles ==
It is possible to set different fonts for the text-container elements (h1, h2, h3, and p), using [[API_FontInstance_SetFont|SetFont]]:
It is possible to set different fonts for the text-container elements, like h1, h2, h3, and p, using [[API_FontInstance_SetFont|SetFont]]:
  SimpleHTML:SetFont('h1', GameFontHighlightLarge);
  SimpleHTML:SetFont('h1', GameFontHighlightLarge);


You can also define font properties for these elements in your XML files, eg:
You can also define font properties for these elements in your XML files, like:
&lt;SimpleHTML ...>
<pre>
   &lt;FontStringHeader1 inherits="GameFontHighlightLarge"/>
<SimpleHTML ...>
  &lt;/SimpleHTML>
   <FontStringHeader1 inherits="GameFontHighlightLarge"/>
</SimpleHTML>
</pre>
 
See [[XML/SimpleHTML]] for XML details.
 
== Creation using pure Lua ==
Create the SimpleHTML object
  local simpleHTML = CreateFrame('SimpleHTML');
 
Assign the HTML code to be displayed.
<nowiki>simpleHTML:SetText('<html><body><h1>Heading1</h1><p>A paragraph</p></body></html>');</nowiki>
 
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 ==
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.
 
[[Image:SimpleHTMLExample.png|The finished product]]


==Example==
<pre>
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>
[[Image:SimpleHTMLExample.png|thumb|right|The finished product]]
<h1>SimpleHTML Demo: Ambush</h1>
<!-- Mediawiki would insist on taking this literally, so we replaced < with &lt; to force it to display it as code  -->
<img src="Interface\Icons\Ability_Ambush" width="32" height="32" align="right"/>
&lt;html><body>
<p align="center">|cffee4400'You think this hurts? Just wait.'|r</p>
&lt;h1>SimpleHTML Demo: Ambush&lt;/h1>
<br/><br/>
&lt;img src="Interface\Icons\Ability_Ambush" width="32" height="32" align="right"/>
<p>Among every ability a rogue has at his disposal,<br/>
&lt;p align="center">|cffee4400'You think this hurts? Just wait.'|r&lt;/p>
Ambush is without a doubt the hardest hitting Rogue ability.</p>
&lt;br/>&lt;br/>
</body></html>
&lt;p>Among every ability a rogue has at his disposal,&lt;br/>
</pre>
Ambush is without a doubt the hardest hitting Rogue ability.&lt;/p>
&lt;/body>&lt;/html>

Latest revision as of 04:49, 15 August 2023

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: '&quot;' '&lt;' '&gt;' '&amp;'. 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.

The finished product

<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>