Difference between revisions of "Structured Text"

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Hyperlink (Arma 3): ampersand)
 
(42 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
{{SideTOC}}
 
== Description ==
 
== Description ==
  
Rich text is able to include images and formatting.
+
Structured Text is just another RV Engine [[typeName | type]] TEXT. It is a rich text, which is able to include images and formatting. It can be created using XML like syntax, as seen in [[parseText]]. However using XML like syntax alone is not going to magically turn given string into structured text, it should be converted to TEXT first (see related commands bellow). Introduced with Armed Assault, does not refer to Cold War Crisis or Resistance.
  
It can be created using XML like syntax, as seen in [[parseText]].
+
'''Related commands:''' [[text]], [[parseText]], [[composeText]], [[formatText]], [[setAttributes]], [[ctrlSetStructuredText]], [[hint]], [[hintC]]
  
Introduced with Armed Assault, does not refer to Cold War Crisis or Resistance.
+
== Markups ==
  
'''Related commands:''' [[parseText]], [[composeText]], [[ctrlSetStructuredText]], [[hintC_structuredText]]
+
=== Syntax ===
 +
All attribute values should be encapsulated in double <tt>"..."</tt> or single <tt>'...'</tt> quotes. The following will log an ''.rpt'' error <tt>Unknown attribute .0</tt> and only number 2 would be taken into account:
 +
<t size=2.0>Large text</t>
 +
While both of the following are correct:
 +
<t size="2.0">Large text</t>
 +
<t size='2.0'>Large text</t>
  
===Code Examples:===
+
=== Text ===
 +
Texts could be created with the following markup:
 +
<t>Hello World!</t>
 +
Or could also be inserted via the [[composeText]] / [[formatText]] and [[text]] commands.
  
<nowiki>_separator1 = parseText "<br />------------------------<br />";</nowiki>
+
==== Non-breaking space ====
+
A non-breaking space, commonly known as '''&amp;nbsp;''' shows as '''?''' in structured text control. Use '''&amp;#160;''' as an alternative.
_image = "\ca\ui\textures\aus_flag.paa";
+
  <t>FIVE&amp;#160;&amp;#160;&amp;#160;&amp;#160;&amp;#160;SPACES</t>
   
 
_txt = composeText [image _image,"Heading Text",_separator1,"Content"];
 
 
hint _txt;
 
 
 
== Operators ==
 
  
 
=== Line break ===
 
=== Line break ===
Line breaks can also be inserted via the [[composeText]] and [[lineBreak]] commands
+
Line breaks could be created with either of the following markups:
<nowiki><br /></nowiki>
+
<nowiki><br/></nowiki>
 +
<nowiki><br></br></nowiki>
 +
Or could also be inserted via the [[composeText]] / [[formatText]] and [[lineBreak]] commands.
  
 
=== Image ===
 
=== Image ===
Images can also be inserted via the [[composeText]] and [[image]] commands
+
Images could be created with either of the following markups:
  <img image='red.paa' />
+
<nowiki><img image="\a3\Data_f\Flags\flag_Altis_co.paa"/></nowiki>
 +
<nowiki><img image="\a3\Data_f\Flags\flag_Altis_co.paa"></img></nowiki>
 +
Or could also be inserted via the [[composeText]] / [[formatText]] and [[image]] commands.
 +
 
 +
=== Hyperlink (Arma 3)===
 +
Clickable links, similar to HTML hyperlinks, could be created with the following markup:
 +
  <nowiki><a href="http://arma3.com">Arma 3</a></nowiki>
 +
By default the links are not underlined or have a different color to stand out. These attributes should be added separately.<br/>
 +
Note: ''&'' should be escaped by ''&amp;amp;''.
 +
<nowiki><a href="https://arma3.com/?foo&bar">Example URL A</a>//Won't work
 +
<a href="https://arma3.com/?foo&amp;amp;bar">Example URL B</a>//Will work</nowiki>
  
=== Color ===
+
== Attributes ==
In format [http://en.wikipedia.org/wiki/RGB RGB] or [http://en.wikipedia.org/wiki/ARGB ARGB]
+
The following inline attributes are supported:
<t color='#ff0000'>Red text</t>
+
* <tt>size</tt>
<t color='#99ffffff'>Transparent white text</t>
+
* <tt>color</tt>
 +
* <tt>font</tt>
 +
* <tt>align</tt>
 +
* <tt>valign</tt>
 +
* <tt>underline</tt>
 +
* <tt>shadow</tt>
 +
* <tt>shadowColor</tt>
 +
* <tt>shadowOffset</tt>
 +
* <tt>colorLink</tt>
 +
* <tt>href</tt>
 +
* <tt>image</tt>
  
 
=== Size ===
 
=== Size ===
Default is 1.
+
The structured text <tt>size</tt> attribute is a multiplier for the value of control config property <tt>size</tt>. Default is 1, meaning that the height of letters will be equal to the value set in config. Setting this to 2 will make letters 2 times the size, 0.5 will make them half the size, etc. If the control is defined as follows:
  <t size='2'> Large text</t>
+
 
 +
<syntaxhighlight lang="cpp">class MyStructuredText : RscStructuredText
 +
{
 +
...
 +
text = "Hello!";
 +
size = 0.04;
 +
...
 +
};</syntaxhighlight>
 +
 
 +
Then the structured text:
 +
  _control [[ctrlSetStructuredText]] [[parseText]] "<t size='2'>Hello!</t>";
 +
Will result in a total text size of 0.04 * 2 = 0.08. Unfortunately, there is no script command to set or get the value of config <tt>size</tt> property dynamically.
 +
 
 +
=== Color ===
 +
The <tt>color</tt> attribute is similar to HTML hex color and could either have format [http://en.wikipedia.org/wiki/RGB #RRGGBB] or [http://en.wikipedia.org/wiki/ARGB #AARRGGBB].
 +
<t color="#ff0000">Red text</t>
 +
<t color="#99ffffff">Semi-transparent white text</t>
  
 
=== Font ===
 
=== Font ===
Font are defined in ''CfgFontFamilies''
+
The value for the <tt>font</tt> attribute could be found in <tt>CfgFontFamilies</tt> config. Some of the Arma 3 fonts:
  <t font='Zeppelin33'>Bold Text</t>
+
* <tt>EtelkaMonospacePro</tt>
 +
* <tt>EtelkaMonospaceProBold</tt>
 +
* <tt>EtelkaNarrowMediumPro</tt>
 +
* <tt>LCD14</tt>
 +
* <tt>LucidaConsoleB</tt>
 +
* <tt>PuristaBold</tt>
 +
* <tt>PuristaLight</tt>
 +
* <tt>PuristaMedium</tt>
 +
* <tt>PuristaSemibold</tt>
 +
* <tt>RobotoCondensed</tt>
 +
* <tt>RobotoCondensedBold</tt>
 +
* <tt>RobotoCondensedLight</tt>
 +
* <tt>TahomaB</tt>
 +
  <t font="PuristaBold">Bold Text</t>
 +
<t font="LCD14">Wicked looking text</t>
 +
 
 +
=== Horizontal Alignment ===
 +
The <tt>align</tt> attribute controls horizontal text alignment and could be one of the following:
 +
* <tt>left</tt>
 +
* <tt>center</tt>
 +
* <tt>right</tt>
 +
<t align="right">Text displayed to the right</t>
  
=== Align ===
+
=== Vertical Alignment ===
Parameter can be 'left', 'center', 'right'
+
The <tt>valign</tt> attribute controls vertical text alignment and could be one of the following:
  <t align='center'>Centered Text</t>
+
* <tt>top</tt>
 +
* <tt>middle</tt>
 +
* <tt>bottom</tt>
 +
  <t valign="bottom">Text displayed at the bottom</t>
  
 
=== Underline ===
 
=== Underline ===
  <t underline='true'>Underlined Text</t>
+
The <tt>underline</tt> attribute underlines each individual word in text. The normal spaces are not underlined.
 +
  <t underline="1">Underlined Text</t>
 +
{{Informative | If you would like to have have a continuous underline between words, use non-breaking spaces. This could be achieved in several ways:
 +
* Insertion from keyboard: [https://en.wikipedia.org/wiki/Non-breaking_space#Keyboard_entry_methods Alt+255]
 +
* Scripted method:
 +
<code>[[hint]] [[parseText]] [[format]] ["<t underline<nowiki>=</nowiki>'1'>%1</t>", "Underlined Text" [[splitString]] " " [[joinString]] [[toString]] [160]]</code>
 +
* Using HTML code:
 +
<code>[[hint]] [[parseText]] "<t underline<nowiki>=</nowiki>'1'>Underlined&amp;#160;Text</t>";</code>}}
  
 
=== Shadow ===
 
=== Shadow ===
Parameter can be '0' (no shadow), '1' (classic shadow, can be colored), '2' outline (always black)
+
The <tt>shadow</tt> attribute controls the appearance of shadow/outline around text and could be one of the following:
  <t shadow='1'>Text with shadow</t>
+
* <tt>0</tt> - normal text
  <t shadow='1' shadowColor='#ff0000'>Text with red Shadow</t>
+
* <tt>1</tt> - classic shadow (text ghosting below and to the right)
  <t shadow='2'>Text with outline</t>
+
* <tt>2</tt> - outline (slight, always black, outline around characters)
 +
<t shadow="0">Text with no shadow</t>
 +
<t shadow="1">Text with default black shadow</t>
 +
<t shadow="2">Text with default black outline</t>
 +
 
 +
=== Shadow Color ===
 +
The <tt>shadowColor</tt> attribute controls the color of the shadow (not the outline, which is always black for some reason)
 +
  <t shadow="1" shadowColor="#ff0000">Text with red shadow</t>
 +
 
 +
=== Shadow Offset ===
 +
The <tt>shadowOffset</tt> attribute controls how far is the shadow offset from the text source (has no effect on the outline)
 +
  <t shadow="1" shadowColor="#ff0000" shadowOffset="0.5">Text with red shadow, which is offset by half character size</t>
 +
 
 +
=== Link Color ===
 +
Will change the color of the text if the text is a link, otherwise the text color is unaffected.
 +
<t colorLink="#0000ff"><a href="http://www.arma3.com/">Blue text</a></t>
 +
  <a colorLink="#0000ff" href="http://www.arma3.com/">Blue text too</a>
 +
<t colorLink="#0000ff">Normal text color</t>
 +
 
 +
=== Hyperlink Reference ===
 +
The <tt>href</tt> attribute is essential part of the <tt><nowiki><a></nowiki></tt> tag and should contain URL of the destination (See [[Structured_Text#Hyperlink_.28Arma_3.29 | Hyperlink]]).
 +
 
 +
=== Image Reference ===
 +
The <tt>image</tt> attribute is essential part of the <tt><nowiki><img></nowiki></tt> tag and should contain filepath to the image (See [[Structured_Text#Image | Image]]).
 +
 
 +
== SQF Code Examples: ==
 +
<tt>align</tt> <tt>valign</tt> demo:
 +
<code>[[hint]] [[parseText]] "<t size='3'><t size='1' valign='top' align='right'>Top Right</t> <t size='1' valign='middle' align='center'>Middle Center</t> <t size='1' valign='bottom' align='left'>Bottom Left</t></t>";</code>
 +
{{Informative | Sometimes an extra space is required when outputting to [[hint]]. In the above example spaces between <tt><nowiki><t></nowiki></tt>s inside another <tt><nowiki><t></nowiki></tt> wrapper ensure that the hint will be 3 lines tall}}
  
=== Hyperlink ===
+
Create clickable image:
Since ["Arma 3","Arma3",125,126163,"Development"]
+
<code>_ctrl = [[findDisplay]] 46 [[createDisplay]] "RscDisplayEmpty" [[ctrlCreate]] ["RscStructuredText", -1];
<nowiki><a href='http://google.com'>Google</a></nowiki>
+
_ctrl [[ctrlSetPosition]] [0,0,1,1];
<nowiki><a color='#0000FF' href='http://arma3.com'>Arma 3</a></nowiki>
+
_ctrl [[ctrlCommit]] 0;
<nowiki><a underline='true' color='#0000FF' href='http://killzonekid.com'>KK's&amp;#160;blog</a></nowiki>
+
_ctrl [[ctrlSetStructuredText]] [[parseText]] "<nowiki><a color='#00FF00' size='5' href='http://arma3.com'><img image='\A3\weapons_f\ammoBoxes\data\ui\map_AmmoBox_F_CA.paa'/></a></nowiki>";</code>
[[Category: Data Types]]
 
  
===Notes:===
+
The use of [[composeText]]:  
All operator types values should be encapsulated with '', for example, the following will log an .rpt error "Unknown attribute .0" and only 2 would be taken into account:
+
<code>_separator = [[parseText]] "<nowiki><br/>------------------------<br/></nowiki>";
<t size=2.0> Large text</t>
+
_image = "\a3\Data_f\Flags\flag_Altis_co.paa";
While the following is correct:
+
_txt1 = [[text]] "left";
<t size='2.0'> Large text</t>
+
_txt1 [[setAttributes]] ["align", "left"];
 +
_txt2 = [[text]] "right";
 +
_txt2 [[setAttributes]] ["align", "right"];
 +
_structuredText = [[composeText]] <nowiki>[</nowiki>[[image]] _image, [[lineBreak]], [[lineBreak]], [[text]] "Heading Text", _separator, _txt1, _txt2];
 +
[[hint]] _structuredText;</code>

Latest revision as of 09:30, 16 February 2019

Description

Structured Text is just another RV Engine type TEXT. It is a rich text, which is able to include images and formatting. It can be created using XML like syntax, as seen in parseText. However using XML like syntax alone is not going to magically turn given string into structured text, it should be converted to TEXT first (see related commands bellow). Introduced with Armed Assault, does not refer to Cold War Crisis or Resistance.

Related commands: text, parseText, composeText, formatText, setAttributes, ctrlSetStructuredText, hint, hintC

Markups

Syntax

All attribute values should be encapsulated in double "..." or single '...' quotes. The following will log an .rpt error Unknown attribute .0 and only number 2 would be taken into account:

<t size=2.0>Large text</t>

While both of the following are correct:

<t size="2.0">Large text</t>
<t size='2.0'>Large text</t>

Text

Texts could be created with the following markup:

<t>Hello World!</t>

Or could also be inserted via the composeText / formatText and text commands.

Non-breaking space

A non-breaking space, commonly known as &nbsp; shows as ? in structured text control. Use &#160; as an alternative.

<t>FIVE&#160;&#160;&#160;&#160;&#160;SPACES</t>

Line break

Line breaks could be created with either of the following markups:

<br/>
<br></br>

Or could also be inserted via the composeText / formatText and lineBreak commands.

Image

Images could be created with either of the following markups:

<img image="\a3\Data_f\Flags\flag_Altis_co.paa"/>
<img image="\a3\Data_f\Flags\flag_Altis_co.paa"></img>

Or could also be inserted via the composeText / formatText and image commands.

Hyperlink (Arma 3)

Clickable links, similar to HTML hyperlinks, could be created with the following markup:

<a href="http://arma3.com">Arma 3</a>

By default the links are not underlined or have a different color to stand out. These attributes should be added separately.
Note: & should be escaped by &amp;.

<a href="https://arma3.com/?foo&bar">Example URL A</a>//Won't work
<a href="https://arma3.com/?foo&amp;bar">Example URL B</a>//Will work

Attributes

The following inline attributes are supported:

  • size
  • color
  • font
  • align
  • valign
  • underline
  • shadow
  • shadowColor
  • shadowOffset
  • colorLink
  • href
  • image

Size

The structured text size attribute is a multiplier for the value of control config property size. Default is 1, meaning that the height of letters will be equal to the value set in config. Setting this to 2 will make letters 2 times the size, 0.5 will make them half the size, etc. If the control is defined as follows:

class MyStructuredText : RscStructuredText 
{
	...
	text = "Hello!";
	size = 0.04;
	...
};

Then the structured text:

_control ctrlSetStructuredText parseText "<t size='2'>Hello!</t>";

Will result in a total text size of 0.04 * 2 = 0.08. Unfortunately, there is no script command to set or get the value of config size property dynamically.

Color

The color attribute is similar to HTML hex color and could either have format #RRGGBB or #AARRGGBB.

<t color="#ff0000">Red text</t>
<t color="#99ffffff">Semi-transparent white text</t>

Font

The value for the font attribute could be found in CfgFontFamilies config. Some of the Arma 3 fonts:

  • EtelkaMonospacePro
  • EtelkaMonospaceProBold
  • EtelkaNarrowMediumPro
  • LCD14
  • LucidaConsoleB
  • PuristaBold
  • PuristaLight
  • PuristaMedium
  • PuristaSemibold
  • RobotoCondensed
  • RobotoCondensedBold
  • RobotoCondensedLight
  • TahomaB
<t font="PuristaBold">Bold Text</t>
<t font="LCD14">Wicked looking text</t>

Horizontal Alignment

The align attribute controls horizontal text alignment and could be one of the following:

  • left
  • center
  • right
<t align="right">Text displayed to the right</t>

Vertical Alignment

The valign attribute controls vertical text alignment and could be one of the following:

  • top
  • middle
  • bottom
<t valign="bottom">Text displayed at the bottom</t>

Underline

The underline attribute underlines each individual word in text. The normal spaces are not underlined.

<t underline="1">Underlined Text</t>
If you would like to have have a continuous underline between words, use non-breaking spaces. This could be achieved in several ways:
  • Insertion from keyboard: Alt+255
  • Scripted method:

hint parseText format ["<t underline='1'>%1</t>", "Underlined Text" splitString " " joinString toString [160]]

  • Using HTML code:
hint parseText "<t underline='1'>Underlined&#160;Text</t>";

Shadow

The shadow attribute controls the appearance of shadow/outline around text and could be one of the following:

  • 0 - normal text
  • 1 - classic shadow (text ghosting below and to the right)
  • 2 - outline (slight, always black, outline around characters)
<t shadow="0">Text with no shadow</t>
<t shadow="1">Text with default black shadow</t>
<t shadow="2">Text with default black outline</t>

Shadow Color

The shadowColor attribute controls the color of the shadow (not the outline, which is always black for some reason)

<t shadow="1" shadowColor="#ff0000">Text with red shadow</t>

Shadow Offset

The shadowOffset attribute controls how far is the shadow offset from the text source (has no effect on the outline)

<t shadow="1" shadowColor="#ff0000" shadowOffset="0.5">Text with red shadow, which is offset by half character size</t>

Link Color

Will change the color of the text if the text is a link, otherwise the text color is unaffected.

<t colorLink="#0000ff"><a href="http://www.arma3.com/">Blue text</a></t>
<a colorLink="#0000ff" href="http://www.arma3.com/">Blue text too</a>
<t colorLink="#0000ff">Normal text color</t>

Hyperlink Reference

The href attribute is essential part of the <a> tag and should contain URL of the destination (See Hyperlink).

Image Reference

The image attribute is essential part of the <img> tag and should contain filepath to the image (See Image).

SQF Code Examples:

align valign demo: hint parseText "<t size='3'><t size='1' valign='top' align='right'>Top Right</t> <t size='1' valign='middle' align='center'>Middle Center</t> <t size='1' valign='bottom' align='left'>Bottom Left</t></t>";

Sometimes an extra space is required when outputting to hint. In the above example spaces between <t>s inside another <t> wrapper ensure that the hint will be 3 lines tall

Create clickable image: _ctrl = findDisplay 46 createDisplay "RscDisplayEmpty" ctrlCreate ["RscStructuredText", -1]; _ctrl ctrlSetPosition [0,0,1,1]; _ctrl ctrlCommit 0; _ctrl ctrlSetStructuredText parseText "<a color='#00FF00' size='5' href='http://arma3.com'><img image='\A3\weapons_f\ammoBoxes\data\ui\map_AmmoBox_F_CA.paa'/></a>";

The use of composeText: _separator = parseText "<br/>------------------------<br/>"; _image = "\a3\Data_f\Flags\flag_Altis_co.paa"; _txt1 = text "left"; _txt1 setAttributes ["align", "left"]; _txt2 = text "right"; _txt2 setAttributes ["align", "right"]; _structuredText = composeText [image _image, lineBreak, lineBreak, text "Heading Text", _separator, _txt1, _txt2]; hint _structuredText;