<doc>
  <legacy_id>1067</legacy_id>
  <name>HTMLText</name>
  <type>property</type>
  <syntax>
    <example>set the HTMLText of [<i>chunk</i> of] <i>field</i> to <i>htmlString</i></example>
    <example>get the [effective] HTMLText of [<i>chunk</i> of] <i>field</i></example>
  </syntax>
  <library></library>
  <objects>
    <field/>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Text and Data Processing</category>
  </classification>
  <references>
    <function tag="numToChar">numToChar Function</function>
    <keyword tag="URL">URL Keyword</keyword>
    <function tag="charToNum">charToNum Function</function>
    <function tag="colorNames">colorNames Function</function>
    <property tag="foregroundColor">foregroundColor Property</property>
    <function tag="format">format Function</function>
    <property tag="unicodeText">unicodeText Property</property>
    <property tag="mimeText">mimeText Property</property>
    <property tag="textSize">textSize Property</property>
    <property tag="RTFText">RTFText Property</property>
    <property tag="textFont">textFont Property</property>
    <property tag="dragData">dragData Property</property>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
    <changed version="2.0"></changed>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
    <ios/>
    <android/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
    <mobile/>
  </classes>
  <security>
  </security>
  <summary>Specifies the contents of a <keyword tag="field">field</keyword>, with its text <glossary tag="format">formatting</glossary> represented as <glossary tag="HTML">HTML</glossary> tags and special characters represented as <glossary tag="HTML">HTML</glossary> entities.</summary>
  <examples>
    <example>set the HTMLText of field "White Paper" to "&lt;b&gt;&lt;i&gt;Click here!&lt;/i&gt;&lt;/b&gt;"</example>
    <example>set the HTMLText of field "Dest" to the HTMLText of field "Source"</example>
    <example>write the HTMLText of field "Story" to file myWebFile</example>
    <example>put the effective htmlText of field "description"</example>
  </examples>
  <description>
  <overview>Use the <b>HTMLText</b> <glossary tag="property">property</glossary> to display text from a web page in a <keyword tag="field">field</keyword>, or copy or export a <glossary tag="field">field's</glossary> contents with the text <glossary tag="format">formatting</glossary> intact.</overview>
  <value><p>The <b>HTMLText</b> of a <keyword tag="field">field</keyword> or <glossary tag="chunk">chunk</glossary> is a <keyword tag="string">string</keyword>.</p><p>If the <b>effective</b> keyword is specified the <b>htmlText</b> property retuns the html of the field with explicit formatting. For example if the <b>textFont</b> of the stack is set this is not included in the <b>htmlText</b> but is inlcuded in the effective <b>htmlText</b>.</p></value>
   <comments><p>The <b>HTMLText</b> <glossary tag="property">property</glossary> is a representation of the styled text of the <keyword tag="field">field</keyword>. LiveCode uses a subset of <glossary tag="HTML">HTML</glossary> tags that includes font, size, style, and text color information.</p><p/><p>Setting the <b>HTMLText</b> of a <keyword tag="field">field</keyword> (or a <glossary tag="chunk">chunk</glossary> of a <keyword tag="field">field</keyword>) sets both the text contents and the style attributes corresponding to the tags listed below. (Other tags are ignored.)</p><p/><p>Getting the <b>HTMLText</b> <glossary tag="property">property</glossary> reports a <keyword tag="string">string</keyword> consisting of the text of the <keyword tag="field">field</keyword> (or <glossary tag="chunk">chunk</glossary> of a <keyword tag="field">field</keyword>), with any font, size, style, or color <property tag="properties">properties</property> embedded in the text in the form of the tags listed below.</p><p/><p><code/><b>Note:</b><code/> The <property tag="HTMLText">HTMLText</property> of a <keyword tag="field">field</keyword> or <glossary tag="chunk">chunk</glossary> includes formatting information for the text, but does not include information about the text <property tag="properties">properties</property> of the <keyword tag="field">field</keyword> itself. If you use the <property tag="HTMLText">HTMLText</property> <glossary tag="property">property</glossary> to transfer text between <glossary tag="field">fields</glossary>, you must make sure that the destination <glossary tag="field">field's</glossary> <property tag="textFont">textFont</property> and other text <property tag="properties">properties</property> match the settings of the source field, if you want the text in both <glossary tag="field">fields</glossary> to look identical.</p><p/><p>The tags translate as follows:</p><p/><p><code><b>&lt;p&gt; &lt;/p&gt;</b></code></p><p>Encloses a line of text. (Blank lines are also enclosed in<code> &lt;p&gt; &lt;/p&gt;</code>.)</p><p/><p><code><b>&lt;sub&gt; &lt;/sub&gt;</b></code></p><p>Encloses text whose <b>textShift</b> is a positive <keyword tag="integer">integer</keyword>. (The<code> &lt;sub&gt; </code>tag is not nested for additional levels of subscription: it appears once for a run of subscripted text, regardless of the value of the <property tag="textShift">textShift</property>.)</p><p/><p><code><b>&lt;sup&gt; &lt;/sup&gt;</b></code></p><p>Encloses text whose <b>textShift</b> is a <glossary tag="negative">negative</glossary> <keyword tag="integer">integer</keyword>. (The<code> &lt;sup&gt; </code>tag is not nested for additional levels of superscription: it appears once for a run of superscripted text, regardless of the value of the <property tag="textShift">textShift</property>.)</p><p/><p><code><b>&lt;i&gt; &lt;/i&gt;</b></code></p><p>Encloses text whose <b>textStyle</b> is "italic".</p><p/><p><code><b>&lt;b&gt; &lt;/b&gt;</b></code></p><p>Encloses text whose <b>textStyle</b> is "bold".</p><p/><p><code><b>&lt;strike&gt; &lt;/strike&gt;</b></code></p><p>Encloses text whose <b>textStyle</b> is "strikeout".</p><p/><p><code><b>&lt;u&gt; &lt;/u&gt;</b></code></p><p>Encloses text whose <b>textStyle</b> is "underline".</p><p/><p><code><b>&lt;box&gt; &lt;/box&gt;</b></code></p><p>Encloses text whose <b>textStyle</b> is "box".</p><p/><p><code><b>&lt;threedbox&gt; &lt;/threedbox&gt;</b></code></p><p>Encloses text whose <b>textStyle</b> is "threeDBox".</p><p/><p><code><b>&lt;font&gt; &lt;/font&gt;</b></code></p><p>Encloses text whose <b>textFont</b>, <property tag="textSize">textSize</property>, <property tag="foregroundColor">foregroundColor</property>, or <property tag="backgroundColor">backgroundColor</property> is different from the <glossary tag="field">field's</glossary> <keyword tag="default">default</keyword>. These five <property tag="properties">properties</property> are represented as attributes of the<code> &lt;font&gt; </code>tag.</p><p>        * <code>face="<i>fontName</i>" </code>appears in the<code> &lt;font&gt; </code>tag if the <b>textFont</b> is not the <keyword tag="default">default</keyword>.</p><p>        * s<code>ize="<i>pointSize</i>" </code>appears if the <b>textSize</b> is not the <keyword tag="default">default</keyword>.</p><p>In standard HTML, the <i>size</i> attribute normally takes a value between 1 and 7, representing a relative text size, with 3 being the normal text size for the web page. To accommodate this convention, when setting the <b>HTMLText</b> of a <keyword tag="field">field</keyword>, if the <i>pointSize</i> is between 1 and 7, the <property tag="textSize">textSize</property> of the text is set to a standard value:</p><p><code><b><i>pointSize</i>            textSize</b></code></p><p>        1               8 point</p><p>        2               10 point</p><p>        3               12 point</p><p>        4               14 point</p><p>        5               17 point</p><p>        6               20 point</p><p>        7               25 point</p><p>        * <code>lang="<i>languageName</i>"</code> appears if the <b>textFont</b> includes a language specification.</p><p>        * <code>color="<i>colorSpec</i>" </code>appears if the <b>foregroundColor</b> is not the <keyword tag="default">default</keyword>.</p><p>        * <code>bgcolor="<i>colorSpec</i>" </code>appears if the <b>backgroundColor</b> is not the <keyword tag="default">default</keyword>.</p><p>When getting the <b>htmlText</b> of a <keyword tag="field">field</keyword>, a color is represented as an <glossary tag="HTML">HTML</glossary>-style color consisting of a hash mark (#) followed by three 2-digit <glossary tag="hexadecimal">hexadecimal</glossary> numbers, one for each of red, green, and blue.</p><p/><p><code><b>&lt;a&gt; &lt;/a&gt;</b></code></p><p>Encloses text whose <b>textStyle</b> is "link" or whose <property tag="linkText">linkText</property> <glossary tag="property">property</glossary> is not empty. If the <property tag="textStyle">textStyle</property> of the text contains "link", the <property tag="linkText">linkText</property> is included as the value of the "href" attribute. Otherwise, it is included as the value of the "name" attribute.</p><p/><p><code><b>&lt;img src="imageSpecifier"&gt;</b></code></p><p>Replaces a character whose <b>imageSource</b> <glossary tag="property">property</glossary> is not empty. The value of the <property tag="imageSource">imageSource</property> <glossary tag="property">property</glossary> is included as the value of the "src" attribute.</p><p/><p>When you set the <b>HTMLText</b> of a <keyword tag="field">field</keyword>, all tags other than those above are ignored, except heading tags (<code>&lt;h1&gt;</code>--<code>&lt;h6&gt;</code>), which change the size of the text in the heading element:</p><p><code><b>tag           textSize</b></code></p><p><code>&lt;h1&gt;</code>               34 point</p><p><code>&lt;h2&gt;</code>               24 point</p><p><code>&lt;h3&gt;</code>               18 point</p><p><code>&lt;h4&gt;</code>               14 point</p><p><code>&lt;h5&gt;</code>               12 point</p><p><code>&lt;h6&gt;</code>               10 point</p><p/><p>You can use LiveCode color references for the "color" and "bgcolor" attributes. LiveCode translates these into standard HTML-style color specifications.</p><p/><p>If a chunk of text includes more than one of the above styles, LiveCode encloses the text in the tags corresponding to each style, from the inside out. For example, if the word "Flail" in a field is underlined and bold, its corresponding <b>HTMLText</b> is "<code>&lt;u&gt;&lt;b&gt;Flail&lt;/b&gt;&lt;/u&gt;</code>".</p><p/><p>Special characters (whose ASCII value is greater than 127) are <glossary tag="encode">encoded</glossary> as <glossary tag="HTML">HTML</glossary> entities. LiveCode recognizes the following named entities:</p><p/><p>       Á       &amp;Aacute;</p><p>       Á       &amp;aacute;</p><p>                 Acirc;</p><p>                 acirc;</p><p>                 acute;</p><p>                 AElig;</p><p>                 aelig;</p><p>                 Agrave;</p><p>                 agrave;</p><p>                 Aring;</p><p>                 aring;</p><p>                 Atilde;</p><p>                 atilde;</p><p>                 Auml;</p><p>                 auml;</p><p>                 brvbar;</p><p>                 Ccedil;</p><p>                 ccedil;</p><p>                 cedil;</p><p>                 cent;</p><p>                 copy;</p><p>                 curren;</p><p>       °      deg;</p><p>                 divide;</p><p>       é    Eacute;</p><p>       é    eacute;</p><p>                 Ecirc;</p><p>                 ecirc;</p><p>                 Egrave;</p><p>                 egrave;</p><p>                 ETH;</p><p>                 eth;</p><p>                 Euml;</p><p>                 euml;</p><p>                 frac12;</p><p>                 frac14;</p><p>                 frac34;</p><p>                 gt;</p><p>                 Iacute;</p><p>                 iacute;</p><p>                 Icirc;</p><p>                 icirc;</p><p>                 iexcl;</p><p>                 Igrave;</p><p>                 igrave;</p><p>                 iquest;</p><p>                 Iuml;</p><p>                 iuml;</p><p>                 laquo;</p><p>                 lt;</p><p>                 macr;</p><p>                 micro;</p><p>                 middot;</p><p>                 nbsp;</p><p>                 not;</p><p>                 Ntilde;</p><p>                 ntilde;</p><p>                 Oacute;</p><p>                 oacute;</p><p>                 Ocirc;</p><p>                 ocirc;</p><p>                 Ograve;</p><p>                 ograve;</p><p>                 ordf;</p><p>                 ordm;</p><p>                 Oslash;</p><p>                 oslash;</p><p>                 Otilde;</p><p>                 otilde;</p><p>                 Ouml;</p><p>                 ouml;</p><p>                 para;</p><p>                 plusmn;</p><p>                 pound;</p><p>                 raquo;</p><p>                 reg;</p><p>                 sect;</p><p>                 shy;</p><p>                 sup1;</p><p>                 sup2;</p><p>                 sup3;</p><p>                 szlig;</p><p>                 THORN;</p><p>                 thorn;</p><p>                 times;</p><p>                 Uacute;</p><p>                 uacute;</p><p>                 Ucirc;</p><p>                 ucirc;</p><p>                 Ugrave;</p><p>                 ugrave;</p><p>                 uml;</p><p>                 Uuml;</p><p>                 uuml;</p><p>                 Yacute;</p><p>                 yacute;</p><p>                 yen;</p><p>                 yuml;</p><p/><p>Unicode characters whose numeric value is greater than 255 are encoded as "bignum" entities, with a leading ampersand and trailing semicolon. For example, the Japanese character whose numeric value is 12387 is encoded as "#12387;".</p><p/><p><b>Important!</b><code/> The <b>HTMLText</b> <glossary tag="property">property</glossary> uses a tag <glossary tag="control structure">structure</glossary> that is HTML-like, but is not completely standard <glossary tag="HTML">HTML</glossary>, in order to accommodate the full <glossary tag="range">range</glossary> of text styling available in LiveCode. Specifically:</p><p/><p>* The link, box and threedbox tags, as well as the bgColor attribute of the font tag, have been added to accommodate styles that don't exist in standard HTML.</p><p/><p>* The size attribute of the font tag can encode the font's point size, in addition to the standard 7 HTML sizes.</p><p/><p>* The <b>HTMLText</b> reports entities whose <glossary tag="ASCII">ASCII value</glossary> is between 129 and 159. These correspond to characters in the <function tag="openStacks">Windows</function> <glossary tag="character set">character set</glossary> (code page 1252) that are not legal <glossary tag="HTML">HTML</glossary> entities.</p><p/><p><b>Changes:</b></p><p>The lang attribute, and the ability to encode Unicode characters, was added in version 2.0.</p><p/><p>The use of the a tag to enclose text whose <b>textStyle</b> <glossary tag="property">property</glossary> is "link" was introduced in version 1.1.1. In previous versions, link and /link enclosed text whose <b>textStyle</b> was "link" and whose <property tag="linkText">linkText</property> <glossary tag="property">property</glossary> was empty.</p><p/><p>In versions before 1.1, tags were capitalized. (Tags are not case-sensitive, so when you set the <b>HTMLText</b> <glossary tag="property">property</glossary>, you can use either uppercase or lowercase.)</p><p/><p>The a tag was introduced in version 1.1. In previous versions, the GROUP tag was used instead.</p><p/><p>In version 1.1, the behavior of the p tag changed. In previous versions, the P tag was interpreted as a line-break character. In version 1.1, p and /p enclose each line.</p><p/><p>The translation between the <b>linkText</b> <glossary tag="property">property</glossary> and the a tag, and between the <property tag="imageSource">imageSource</property> <glossary tag="property">property</glossary> and the img tag, was introduced in version 1.1. In previous versions, these two <property tag="properties">properties</property> were not available in the <b>HTMLText</b>.</p>
    
    <p>Paragraphs with a non-empty <b>listStyle</b> present themselves in <b>htmlText</b> wrapped with &lt;LI&gt; tags. Sequences of such paragraphs with the same <b>listStyle</b> are bracketed by &lt;UL&gt; or &lt;OL&gt; tags. These tags take a <i>type</i> attribute, matching the (legacy) HTML attribute of the same name:</p>
    <p> disc - disc</p> 
    <p> circle - circle</p> 
    <p> square - square</p> 
    <p> l - decimal</p> 
    <p> a - lower latin</p> 
    <p> A - upper latin</p> 
    <p> i - lower roman</p> 
    <p> I - upper roman</p>     
    </comments> 
  </description>
</doc>