WoW:UIOBJECT SimpleHTML: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
(added synopsis of available tags)
(→‎Well-formed HTML: split code)
Line 3: Line 3:


==Supported HTML==
==Supported HTML==
Unknown tags are ignored completely (must still be well-formed), unknown attributes for known tags are ignored gracefully. All HTML must be inside <tt>&lt;html&gt;&lt;body&gt;</tt> tags to be displayed (and html and body tags must be terminated for HTML to be parsed). SimpleHTML accepts both double and single quotes for specifying parameter values, double quotes are used in examples below.
The following HTML tags are supported:
 
; h1, h2, h3, p
===Overview===
: <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:
&lt;(h1|h2|h3|p) [align=(left|center|right)] /&gt;
 
&lt;img src=IMAGE_SOURCE [align=(left|center|right)] [width=NUM] [height=NUM] /&gt;
 
&lt;a href=LINK /&gt;
 
&lt;br /&gt;
 
===Supported tags===
; h1, h2, h3, p : Text containers; following optional attributes
:*align - (left, center, right) controls positioning of the text element,
:*align - (left, center, right) controls positioning of the text element,
; img : Image, only outside of text containers; following attributes are supported:
; 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.
:*align - (left, center, right) controls positioning of the image.
:*width - (number) width of image in pixels.
:*width - (number) width of image in pixels.
:*height - (number) height of image in pixels.
:*height - (number) height of image in pixels.
:*src - (string) image source, for example Interface\Icons\Ability_Ambush
:*src - (string) image source, for example Interface\Icons\Ability_Ambush
; a : anchor (link only), only displayed inside text containers; following attributes
; 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
:*href - (string) link to pass OnHyperLink* widget handlers
;br : line break, no attributes.
;br  
 
: <code> &lt;br /&gt;</code>
: line break, no attributes.


===Example===
===Well-formed HTML===
<!-- Mediawiki would insist on taking this literally, so we replaced < with &lt; to force it to display it as code  -->
SimpleHTML will only display text as HTML if it is well-formed; the following conditions and quirks apply:
&lt;html>&lt;body>
* Tag names are case insensitive, img and iMg achieve the same result.
  &lt;h1>SimpleHTML Demo: Ambush&lt;/h1>
* All tags must be closed; closing tags must match the case of the opening tag; some tags are self-closing (br, img).
  &lt;img src="Interface\Icons\Ability_Ambush" width="32" height="32" align="right"/>
* Attribute values must be quoted; both double and single quotes are supported.
  &lt;p align="center">'You think this hurts? Just wait.'&lt;/p>&lt;br/>&lt;br/>
* 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.
  &lt;p>Among every ability a rogue has at his disposal,&lt;br/>Ambush is without a doubt the hardest hitting Rogue ability.&lt;/p>
* Unrecognized tags are ignored entirely, even if they contain known tags inside; unrecognized attributes are ignored.
  &lt;/body>&lt;/html>
* Document content must be enclosed in <code>&lt;html>&lt;body>  &lt;/body>&lt;/html></code> tags.


==Standard escape sequences==
==Standard escape sequences==
Line 41: Line 36:


==Setting element styles==
==Setting element styles==
It is possible to set different fonts for the text-container elements  (h1, h2, h3, and p), using:
It is possible to set different fonts for the text-container elements  (h1, h2, h3, and p), using [[API_FontInstance_SetFont|SetFont]]:
  SimpleHTML:SetFont('element', font); -- SimpleHTML:SetFont('h1', GameFontHighlightLarge);
  SimpleHTML:SetFont('h1', GameFontHighlightLarge);
(see the [[API_FontInstance_SetFont|SetFont documenation]] for more details)


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

Revision as of 18:39, 3 March 2008

Widget API < SimpleHTML

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.

Supported HTML

The following HTML tags are supported:

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

Well-formed HTML

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

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

It is possible to set different fonts for the text-container elements (h1, h2, h3, and p), using SetFont:

SimpleHTML:SetFont('h1', GameFontHighlightLarge);

You can also define font properties for these elements in your XML files, eg:

<SimpleHTML ...>
 <FontStringHeader1 inherits="GameFontHighlightLarge"/>
</SimpleHTML>

Example

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>