{"name":"Structured Text","title":"Structured Text","type":"topic","url":"https://community.bistudio.com/wiki/Structured_Text","revid":364507,"updated":"2024-05-16T20:42:02Z","aliases":["Text"],"markdown":"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.\n\n> [!IMPORTANT]\n> This type is not meant to be used with remote execution. Executing `[parseText \"test\"] remoteExec [\"hint\"];` will result in the following rpt message:\n>\n> `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`\n>\n> Parse the text on the receiving client instead.\n\n### Commands\n\n- See Command Group: Structured Text for all related commands.\n\n### Markups\n\n#### Syntax\n\nAll attribute values should be encapsulated in double `\"...\"` or single `'...'` quotes. Both of the following are correct:\n\n```html\nLarge text\nLarge text\n```\n\n> [!WARNING]\n> The following will log an *.rpt* error `Unknown attribute .0` and only number 2 would be taken into account:\n>\n> ```html\n> Large text\n> ```\n\n#### Text\n\nTexts could be created with the following markup:\n\n```html\nHello World!\n```\n\nOr could also be inserted via the composeText / formatText and text commands.\n\n##### Special characters\n\nTo insert special characters, such as `<`, `>`, etc. you can use the [HTML representation](https://dev.w3.org/html5/html-author/charref) of that character, e.g.:\n\n| Character | HTML |\n|---|---|\n| < | `<` |\n| > | `>` |\n| non-breaking space | |\n| ... | ... |\n\n> [!IMPORTANT]\n> Using a special character directly will result in it being displayed as \"?\" or, in the case of writing \"\", will result in an error in the RPT: `Wrong text element 'TEXT'`\n\n#### Line break\n\nLine breaks could be created with either of the following markups:\n\n```html\n
\n
\n

\n```\n\nOr could also be inserted via the composeText / formatText and lineBreak commands.\n\n#### Image\n\nImages could be created with either of the following markups:\n\n```html\n\n\n\n```\n\nOr could also be inserted via the composeText / formatText and image commands.\n\n#### Hyperlink (Arma 3)\n\nClickable links, similar to HTML hyperlinks, could be created with the following markup:\n\n```html\nArma 3\n```\n\nBy default the links are not underlined or have a different color to stand out. These attributes should be added separately.\n\nNote: *&* should be escaped by *&*.\n\n```html\nExample URL A \nExample URL B \n```\n\n### Attributes\n\nThe following inline attributes are supported:\n- `size`\n- `color`\n- `font`\n- `align`\n- `valign`\n- `underline`\n- `shadow`\n- `shadowColor`\n- `shadowOffset`\n- `colorLink`\n- `href`\n- `image`\n\n#### Size\n\nThe 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:\n\n```cpp\nclass MyStructuredText : RscStructuredText \n{\n ...\n text = \"Hello!\";\n size = 0.04;\n ...\n};\n```\n\nThen the structured text:\n\n```sqf\n_control ctrlSetStructuredText parseText \"Hello!\";\n```\n\nWill 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.\n\n#### Color\n\nThe `color` attribute is similar to HTML hex color and could either have format [#RRGGBB](https://en.wikipedia.org/wiki/RGB) or [#AARRGGBB](https://en.wikipedia.org/wiki/ARGB).\n\n```html\nRed text\nSemi-transparent white text\n```\n\n#### Font\n\nThe value for the `font` attribute could be found in `CfgFontFamilies` config. Some of the Arma 3 fonts:\n- `EtelkaMonospacePro`\n- `EtelkaMonospaceProBold`\n- `EtelkaNarrowMediumPro`\n- `LCD14`\n- `LucidaConsoleB`\n- `PuristaBold`\n- `PuristaLight`\n- `PuristaMedium`\n- `PuristaSemibold`\n- `RobotoCondensed`\n- `RobotoCondensedBold`\n- `RobotoCondensedLight`\n- `TahomaB`\n\n```html\nBold Text\nWicked looking text\n```\n\n#### Horizontal Alignment\n\nThe `align` attribute controls horizontal text alignment and could be one of the following:\n- `left`\n- `center`\n- `right`\n\n```html\nText displayed to the right\n```\n\n#### Vertical Alignment\n\nThe `valign` attribute controls vertical text alignment and could be one of the following:\n- `top`\n- `middle`\n- `bottom`\n\n```html\nText displayed at the bottom\n```\n\n#### Underline\n\nThe `underline` attribute underlines each individual word in text. The normal spaces are not underlined.\n\n```html\nUnderlined Text\n```\n\n> [!NOTE]\n> If you would like to have a continuous underline between words, use non-breaking spaces. This could be achieved in several ways:\n> - Insertion from keyboard: [Alt+255](https://en.wikipedia.org/wiki/Non-breaking_space#Keyboard_entry_methods)\n> - Scripted method:\n>\n> ```sqf\n> hint parseText format [\"%1\", \"Underlined Text\" splitString \" \" joinString toString [160]]\n> ```\n>\n> - Using HTML code:\n>\n> ```sqf\n> hint parseText \"Underlined Text\";\n> ```\n\n#### Shadow\n\nThe `shadow` attribute controls the appearance of shadow/outline around text and could be one of the following:\n- `0` - normal text\n- `1` - classic shadow (text ghosting below and to the right)\n- `2` - outline (slight, always black, outline around characters)\n\n```html\nText with no shadow\nText with default black shadow\nText with default black outline\n```\n\n#### Shadow Color\n\nThe `shadowColor` attribute controls the color of the shadow (not the outline, which is always black for some reason)\n\n```html\nText with red shadow\n```\n\n#### Shadow Offset\n\nThe `shadowOffset` attribute controls how far is the shadow offset from the text source (has no effect on the outline)\n\n```html\nText with red shadow, which is offset by half character size\n```\n\n#### Link Color\n\nWill change the color of the text if the text is a link, otherwise the text color is unaffected.\n\n```html\nBlue text\nBlue text too\nNormal text color\n```\n\n#### Hyperlink Reference\n\nThe `href` attribute is essential part of the `` tag and should contain URL of the destination (See Hyperlink).\n\n#### Image Reference\n\nThe `image` attribute is essential part of the `` tag and should contain filepath to the image (See Image).\n\n### SQF Code Examples\n\n`align` `valign` demo:\n\n```sqf\nhint parseText \"Top Right Middle Center Bottom Left\";\n```\n\n> [!NOTE]\n> Sometimes an extra space is required when outputting to hint. In the above example spaces between ``s inside another `` wrapper ensure that the hint will be 3 lines tall\n\nCreate clickable image:\n\n```sqf\n_ctrl = findDisplay 46 createDisplay \"RscDisplayEmpty\" ctrlCreate [\"RscStructuredText\", -1];\n_ctrl ctrlSetPosition [0,0,1,1];\n_ctrl ctrlCommit 0;\n_ctrl ctrlSetStructuredText parseText \"\";\n```\n\nThe use of composeText:\n\n```sqf\n_separator = parseText \"
------------------------
\";\n_image = \"\\a3\\Data_f\\Flags\\flag_Altis_co.paa\";\n_txt1 = text \"left\";\n_txt1 setAttributes [\"align\", \"left\"];\n_txt2 = text \"right\";\n_txt2 setAttributes [\"align\", \"right\"];\n_structuredText = composeText [image _image, lineBreak, lineBreak, text \"Heading Text\", _separator, _txt1, _txt2];\nhint _structuredText;\n```","sections":[{"heading":null,"level":1,"markdown":"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.\n\n> [!IMPORTANT]\n> This type is not meant to be used with remote execution. Executing `[parseText \"test\"] remoteExec [\"hint\"];` will result in the following rpt message:\n>\n> `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`\n>\n> Parse the text on the receiving client instead."},{"heading":"Commands","level":3,"markdown":"- See Command Group: Structured Text for all related commands."},{"heading":"Markups","level":3,"markdown":""},{"heading":"Syntax","level":4,"markdown":"All attribute values should be encapsulated in double `\"...\"` or single `'...'` quotes. Both of the following are correct:\n\n```html\nLarge text\nLarge text\n```\n\n> [!WARNING]\n> The following will log an *.rpt* error `Unknown attribute .0` and only number 2 would be taken into account:\n>\n> ```html\n> Large text\n> ```"},{"heading":"Text","level":4,"markdown":"Texts could be created with the following markup:\n\n```html\nHello World!\n```\n\nOr could also be inserted via the composeText / formatText and text commands."},{"heading":"Special characters","level":5,"markdown":"To insert special characters, such as `<`, `>`, etc. you can use the [HTML representation](https://dev.w3.org/html5/html-author/charref) of that character, e.g.:\n\n| Character | HTML |\n|---|---|\n| < | `<` |\n| > | `>` |\n| non-breaking space | |\n| ... | ... |\n\n> [!IMPORTANT]\n> Using a special character directly will result in it being displayed as \"?\" or, in the case of writing \"\", will result in an error in the RPT: `Wrong text element 'TEXT'`"},{"heading":"Line break","level":4,"markdown":"Line breaks could be created with either of the following markups:\n\n```html\n
\n
\n

\n```\n\nOr could also be inserted via the composeText / formatText and lineBreak commands."},{"heading":"Image","level":4,"markdown":"Images could be created with either of the following markups:\n\n```html\n\n\n\n```\n\nOr could also be inserted via the composeText / formatText and image commands."},{"heading":"Hyperlink (Arma 3)","level":4,"markdown":"Clickable links, similar to HTML hyperlinks, could be created with the following markup:\n\n```html\nArma 3\n```\n\nBy default the links are not underlined or have a different color to stand out. These attributes should be added separately.\n\nNote: *&* should be escaped by *&*.\n\n```html\nExample URL A \nExample URL B \n```"},{"heading":"Attributes","level":3,"markdown":"The following inline attributes are supported:\n- `size`\n- `color`\n- `font`\n- `align`\n- `valign`\n- `underline`\n- `shadow`\n- `shadowColor`\n- `shadowOffset`\n- `colorLink`\n- `href`\n- `image`"},{"heading":"Size","level":4,"markdown":"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:\n\n```cpp\nclass MyStructuredText : RscStructuredText \n{\n ...\n text = \"Hello!\";\n size = 0.04;\n ...\n};\n```\n\nThen the structured text:\n\n```sqf\n_control ctrlSetStructuredText parseText \"Hello!\";\n```\n\nWill 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."},{"heading":"Color","level":4,"markdown":"The `color` attribute is similar to HTML hex color and could either have format [#RRGGBB](https://en.wikipedia.org/wiki/RGB) or [#AARRGGBB](https://en.wikipedia.org/wiki/ARGB).\n\n```html\nRed text\nSemi-transparent white text\n```"},{"heading":"Font","level":4,"markdown":"The value for the `font` attribute could be found in `CfgFontFamilies` config. Some of the Arma 3 fonts:\n- `EtelkaMonospacePro`\n- `EtelkaMonospaceProBold`\n- `EtelkaNarrowMediumPro`\n- `LCD14`\n- `LucidaConsoleB`\n- `PuristaBold`\n- `PuristaLight`\n- `PuristaMedium`\n- `PuristaSemibold`\n- `RobotoCondensed`\n- `RobotoCondensedBold`\n- `RobotoCondensedLight`\n- `TahomaB`\n\n```html\nBold Text\nWicked looking text\n```"},{"heading":"Horizontal Alignment","level":4,"markdown":"The `align` attribute controls horizontal text alignment and could be one of the following:\n- `left`\n- `center`\n- `right`\n\n```html\nText displayed to the right\n```"},{"heading":"Vertical Alignment","level":4,"markdown":"The `valign` attribute controls vertical text alignment and could be one of the following:\n- `top`\n- `middle`\n- `bottom`\n\n```html\nText displayed at the bottom\n```"},{"heading":"Underline","level":4,"markdown":"The `underline` attribute underlines each individual word in text. The normal spaces are not underlined.\n\n```html\nUnderlined Text\n```\n\n> [!NOTE]\n> If you would like to have a continuous underline between words, use non-breaking spaces. This could be achieved in several ways:\n> - Insertion from keyboard: [Alt+255](https://en.wikipedia.org/wiki/Non-breaking_space#Keyboard_entry_methods)\n> - Scripted method:\n>\n> ```sqf\n> hint parseText format [\"%1\", \"Underlined Text\" splitString \" \" joinString toString [160]]\n> ```\n>\n> - Using HTML code:\n>\n> ```sqf\n> hint parseText \"Underlined Text\";\n> ```"},{"heading":"Shadow","level":4,"markdown":"The `shadow` attribute controls the appearance of shadow/outline around text and could be one of the following:\n- `0` - normal text\n- `1` - classic shadow (text ghosting below and to the right)\n- `2` - outline (slight, always black, outline around characters)\n\n```html\nText with no shadow\nText with default black shadow\nText with default black outline\n```"},{"heading":"Shadow Color","level":4,"markdown":"The `shadowColor` attribute controls the color of the shadow (not the outline, which is always black for some reason)\n\n```html\nText with red shadow\n```"},{"heading":"Shadow Offset","level":4,"markdown":"The `shadowOffset` attribute controls how far is the shadow offset from the text source (has no effect on the outline)\n\n```html\nText with red shadow, which is offset by half character size\n```"},{"heading":"Link Color","level":4,"markdown":"Will change the color of the text if the text is a link, otherwise the text color is unaffected.\n\n```html\nBlue text\nBlue text too\nNormal text color\n```"},{"heading":"Hyperlink Reference","level":4,"markdown":"The `href` attribute is essential part of the `` tag and should contain URL of the destination (See Hyperlink)."},{"heading":"Image Reference","level":4,"markdown":"The `image` attribute is essential part of the `` tag and should contain filepath to the image (See Image)."},{"heading":"SQF Code Examples","level":3,"markdown":"`align` `valign` demo:\n\n```sqf\nhint parseText \"Top Right Middle Center Bottom Left\";\n```\n\n> [!NOTE]\n> Sometimes an extra space is required when outputting to hint. In the above example spaces between ``s inside another `` wrapper ensure that the hint will be 3 lines tall\n\nCreate clickable image:\n\n```sqf\n_ctrl = findDisplay 46 createDisplay \"RscDisplayEmpty\" ctrlCreate [\"RscStructuredText\", -1];\n_ctrl ctrlSetPosition [0,0,1,1];\n_ctrl ctrlCommit 0;\n_ctrl ctrlSetStructuredText parseText \"\";\n```\n\nThe use of composeText:\n\n```sqf\n_separator = parseText \"
------------------------
\";\n_image = \"\\a3\\Data_f\\Flags\\flag_Altis_co.paa\";\n_txt1 = text \"left\";\n_txt1 setAttributes [\"align\", \"left\"];\n_txt2 = text \"right\";\n_txt2 setAttributes [\"align\", \"right\"];\n_structuredText = composeText [image _image, lineBreak, lineBreak, text \"Heading Text\", _separator, _txt1, _txt2];\nhint _structuredText;\n```"}],"categories":["Data Types"],"groups":["Data Types"]}