Structured Text: Difference between revisions
Lou Montana (talk | contribs) m (Text replacement - ";[ ]+ " to "; ") |
Lou Montana (talk | contribs) m (Text replacement - "{{Feature | Informative | " to "{{Feature|informative|") |
||
(14 intermediate revisions by 3 users not shown) | |||
Line 2: | Line 2: | ||
Structured Text is a [[Data Types|Data Type]] that has been introduced with {{arma1}}. It is a '''rich text''', which is able to include images and formatting. It can be created using XML-like syntax, as seen [[#Markup|below]]. However, using XML-like syntax alone is not going to turn a normal string into structured text, it should be converted to TEXT first. | Structured Text is a [[Data Types|Data Type]] that has been introduced with {{arma1}}. It is a '''rich text''', which is able to include images and formatting. It can be created using XML-like syntax, as seen [[#Markup|below]]. However, using XML-like syntax alone is not going to turn a normal string into structured text, it should be converted to TEXT first. | ||
{{Feature|important|This type is not meant to be used with remote execution. Executing | {{Feature|important| | ||
This type is not meant to be used with remote execution. Executing <sqf inline>[parseText "test"] remoteExec ["hint"];</sqf> will result in the following rpt message:<br> | |||
{{hl|Performance warning: SimpleSerialization::Write 'params' is using type of ',TEXT' which is not optimized by simple serialization, falling back to generic serialization, use generic type or ask for optimizations for these types}}<br> | |||
Parse the text on the receiving client instead. | |||
}} | |||
Line 15: | Line 18: | ||
=== Syntax === | === Syntax === | ||
All attribute values should be encapsulated in double | All attribute values should be encapsulated in double {{hl|"..."}} or single {{hl|'...'}} quotes. Both of the following are correct: | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t size="2.0">Large text</t> | <t size="2.0">Large text</t> | ||
Line 21: | Line 24: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
{{Feature|warning|The following will log an ''.rpt'' error | {{Feature|warning|The following will log an ''.rpt'' error {{hl|Unknown attribute .0}} and only number 2 would be taken into account: | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t size=2.0>Large text</t> | <t size=2.0>Large text</t> | ||
Line 35: | Line 38: | ||
Or could also be inserted via the [[composeText]] / [[formatText]] and [[text]] commands. | Or could also be inserted via the [[composeText]] / [[formatText]] and [[text]] commands. | ||
==== | ==== Special characters ==== | ||
To insert special characters, such as {{hl|<}}, {{hl|>}}, etc. you can use the {{Link|https://dev.w3.org/html5/html-author/charref|HTML representation}} of that character, e.g.: | |||
{| class="wikitable" | |||
|- | |||
< | ! Character !! HTML | ||
|- | |||
| < || {{hl|&lt;}} | |||
|- | |||
| > || {{hl|&gt;}} | |||
|- | |||
| non-breaking space || {{hl|&#160;}} | |||
|- | |||
| ... || ... | |||
|} | |||
{{Feature|important|Using a special character directly will result in it being displayed as "?" or, in the case of writing "<TEXT>", will result in an error in the [[RPT]]: {{hl|Wrong text element 'TEXT'}} | |||
}} | |||
=== Line break === | === Line break === | ||
Line 62: | Line 75: | ||
Or could also be inserted via the [[composeText]] / [[formatText]] and [[image]] commands. | Or could also be inserted via the [[composeText]] / [[formatText]] and [[image]] commands. | ||
{{ArgTitle|Hyperlink | {{ArgTitle|3|Hyperlink|{{GVI|arma3}}}} | ||
Clickable links, similar to HTML hyperlinks, could be created with the following markup: | Clickable links, similar to HTML hyperlinks, could be created with the following markup: | ||
Line 80: | Line 93: | ||
The following inline attributes are supported: | The following inline attributes are supported: | ||
{{Columns|4| | {{Columns|4| | ||
* | * {{hl|size}} | ||
* | * {{hl|color}} | ||
* | * {{hl|font}} | ||
* | * {{hl|align}} | ||
* | * {{hl|valign}} | ||
* | * {{hl|underline}} | ||
* | * {{hl|shadow}} | ||
* | * {{hl|shadowColor}} | ||
* | * {{hl|shadowOffset}} | ||
* | * {{hl|colorLink}} | ||
* | * {{hl|href}} | ||
* | * {{hl|image}} | ||
}} | }} | ||
=== Size === | === Size === | ||
The structured text | The structured text {{hl|size}} attribute is a multiplier for the value of control config property {{hl|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: | ||
<syntaxhighlight lang="cpp"> | <syntaxhighlight lang="cpp"> | ||
Line 109: | Line 122: | ||
Then the structured text: | Then the structured text: | ||
<sqf>_control ctrlSetStructuredText parseText "<t size='2'>Hello!</t>";</sqf> | |||
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 | 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 {{hl|size}} property dynamically. | ||
=== Color === | === Color === | ||
The | The {{hl|color}} attribute is similar to HTML hex color and could either have format {{Link|https://en.wikipedia.org/wiki/RGB|<nowiki>#RRGGBB</nowiki>}} or {{Link|https://en.wikipedia.org/wiki/ARGB|<nowiki>#AARRGGBB</nowiki>}}. | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t color='#ff0000'>Red text</t> | <t color='#ff0000'>Red text</t> | ||
Line 122: | Line 135: | ||
=== Font === | === Font === | ||
The value for the | The value for the {{hl|font}} attribute could be found in {{hl|CfgFontFamilies}} config. Some of the {{arma3}} fonts: | ||
{{Columns|4| | {{Columns|4| | ||
* | * {{hl|EtelkaMonospacePro}} | ||
* | * {{hl|EtelkaMonospaceProBold}} | ||
* | * {{hl|EtelkaNarrowMediumPro}} | ||
* | * {{hl|LCD14}} | ||
* | * {{hl|LucidaConsoleB}} | ||
* | * {{hl|PuristaBold}} | ||
* | * {{hl|PuristaLight}} | ||
* | * {{hl|PuristaMedium}} | ||
* | * {{hl|PuristaSemibold}} | ||
* | * {{hl|RobotoCondensed}} | ||
* | * {{hl|RobotoCondensedBold}} | ||
* | * {{hl|RobotoCondensedLight}} | ||
* | * {{hl|TahomaB}} | ||
}} | }} | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
Line 145: | Line 158: | ||
=== Horizontal Alignment === | === Horizontal Alignment === | ||
The | The {{hl|align}} attribute controls horizontal text alignment and could be one of the following: | ||
* | * {{hl|left}} | ||
* | * {{hl|center}} | ||
* | * {{hl|right}} | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t align='right'>Text displayed to the right</t> | <t align='right'>Text displayed to the right</t> | ||
Line 155: | Line 168: | ||
=== Vertical Alignment === | === Vertical Alignment === | ||
The | The {{hl|valign}} attribute controls vertical text alignment and could be one of the following: | ||
* | * {{hl|top}} | ||
* | * {{hl|middle}} | ||
* | * {{hl|bottom}} | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t valign='bottom'>Text displayed at the bottom</t> | <t valign='bottom'>Text displayed at the bottom</t> | ||
Line 165: | Line 178: | ||
=== Underline === | === Underline === | ||
The | The {{hl|underline}} attribute underlines each individual word in text. The normal spaces are not underlined. | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t underline='1'>Underlined Text</t> | <t underline='1'>Underlined Text</t> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
{{Feature | | {{Feature|informative| | ||
* Insertion from keyboard: {{ | If you would like to have a continuous underline between words, use non-breaking spaces. This could be achieved in several ways: | ||
* Insertion from keyboard: {{Link|https://en.wikipedia.org/wiki/Non-breaking_space#Keyboard_entry_methods|Alt+255}} | |||
* Scripted method: | * Scripted method: | ||
< | <sqf>hint parseText format ["<t underline='1'>%1</t>", "Underlined Text" splitString " " joinString toString [160]]</sqf> | ||
* Using HTML code: | * Using HTML code: | ||
< | <sqf>hint parseText "<t underline='1'>Underlined&#160;Text</t>";</sqf> | ||
}} | |||
=== Shadow === | === Shadow === | ||
The | The {{hl|shadow}} attribute controls the appearance of shadow/outline around text and could be one of the following: | ||
* | * {{hl|0}} - normal text | ||
* | * {{hl|1}} - classic shadow (text ghosting below and to the right) | ||
* | * {{hl|2}} - outline (slight, always black, outline around characters) | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t shadow='0'>Text with no shadow</t> | <t shadow='0'>Text with no shadow</t> | ||
Line 190: | Line 205: | ||
=== Shadow Color === | === Shadow Color === | ||
The | The {{hl|shadowColor}} attribute controls the color of the shadow (not the outline, which is always black for some reason) | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t shadow='1' shadowColor='#ff0000'>Text with red shadow</t> | <t shadow='1' shadowColor='#ff0000'>Text with red shadow</t> | ||
Line 197: | Line 212: | ||
=== Shadow Offset === | === Shadow Offset === | ||
The | The {{hl|shadowOffset}} attribute controls how far is the shadow offset from the text source (has no effect on the outline) | ||
<syntaxhighlight lang="html"> | <syntaxhighlight lang="html"> | ||
<t shadow='1' shadowColor='#ff0000' shadowOffset='0.5'>Text with red shadow, which is offset by half character size</t> | <t shadow='1' shadowColor='#ff0000' shadowOffset='0.5'>Text with red shadow, which is offset by half character size</t> | ||
Line 213: | Line 228: | ||
=== Hyperlink Reference === | === Hyperlink Reference === | ||
The | The {{hl|href}} attribute is essential part of the {{hl|<nowiki><a></nowiki>}} tag and should contain URL of the destination (See [[#Hyperlink | Hyperlink]]). | ||
=== Image Reference === | === Image Reference === | ||
The | The {{hl|image}} attribute is essential part of the {{hl|<nowiki><img></nowiki>}} tag and should contain filepath to the image (See [[Structured_Text#Image | Image]]). | ||
== SQF Code Examples == | == SQF Code Examples == | ||
{{hl|align}} {{hl|valign}} demo: | |||
< | <sqf>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>";</sqf> | ||
{{Feature | | {{Feature|informative|Sometimes an extra space is required when outputting to [[hint]]. In the above example spaces between {{hl|<nowiki><t></nowiki>}}s inside another {{hl|<nowiki><t></nowiki>}} wrapper ensure that the hint will be 3 lines tall}} | ||
Create clickable image: | Create clickable image: | ||
< | <sqf> | ||
_ctrl | _ctrl = findDisplay 46 createDisplay "RscDisplayEmpty" ctrlCreate ["RscStructuredText", -1]; | ||
_ctrl | _ctrl ctrlSetPosition [0,0,1,1]; | ||
_ctrl | _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>"; | |||
</sqf> | |||
The use of [[composeText]]: | The use of [[composeText]]: | ||
< | <sqf> | ||
_separator = parseText "<br />------------------------<br />"; | |||
_image = "\a3\Data_f\Flags\flag_Altis_co.paa"; | _image = "\a3\Data_f\Flags\flag_Altis_co.paa"; | ||
_txt1 = | _txt1 = text "left"; | ||
_txt1 | _txt1 setAttributes ["align", "left"]; | ||
_txt2 = | _txt2 = text "right"; | ||
_txt2 | _txt2 setAttributes ["align", "right"]; | ||
_structuredText = | _structuredText = composeText [image _image, lineBreak, lineBreak, text "Heading Text", _separator, _txt1, _txt2]; | ||
hint _structuredText; | |||
</sqf> | |||
[[Category:Data Types]] | [[Category:Data Types]] |
Latest revision as of 21:42, 16 May 2024
Structured Text is a Data Type that has been introduced with Armed Assault. It is a rich text, which is able to include images and formatting. It can be created using XML-like syntax, as seen below. However, using XML-like syntax alone is not going to turn a normal string into structured text, it should be converted to TEXT first.
Commands
- See Command Group: Structured Text for all related commands.
Markups
Syntax
All attribute values should be encapsulated in double "..." or single '...' quotes. 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.
Special characters
To insert special characters, such as <, >, etc. you can use the HTML representation of that character, e.g.:
Character | HTML |
---|---|
< | < |
> | > |
non-breaking space |   |
... | ... |
Line break
Line breaks could be created with either of the following markups:
<br/>
<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 image='\a3\Data_f\Flags\flag_Altis_co.paa'></img>
Or could also be inserted via the composeText / formatText and image commands.
Hyperlink
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 &.
<a href='https://arma3.com/?foo&bar'>Example URL A</a> <!-- will not work -->
<a href='https://arma3.com/?foo&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:
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>
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:
Create clickable image:
The use of composeText: