This is a library to easily add colorful Text to your UI of your Warzone Mod.
This Library is in Alpha. It does most likely only display correctly on the Website, not on the Standalone Client or Mobile Client (especially in portrait mode).
You can discuss the library on The Warzone Modmaker Discord.
Feel free to make pull requests and open Issues
The main functions you will be using is AddStringToUI.
It has following signature:
AddStringToUI(
HorizontalLayoutGroup | VerticalLayoutGroup | EmptyUIObject | RootParent UIGroup,
string Text,
number MaxWidth = 30,
integer AncestorCount = 1
) -> table<HorizontalLayoutGroup: HorizontalLayoutGroup, Children: Label[]>;UIGroup
This is the UI container which the elements will be added to.
This must be either an element created by UI.CreateHorizontalLayoutGroup(parent), UI.CreateVerticalLayoutGroup(parent), UI.CreateEmpty(parent) or can be the rootParent itself
Note that this library may not work as expected on other UI containers besides VerticalLayoutGroup and rootParent.
A string with color tags.
For example "Hello, <red>this Text will be displayed as red, <#0000ff>and this Text as blue!"
A tag is denoted with a less than <, the tag content and a greater than >.
There are 4 kinds of tag contents
/wbrUsing <red>, <blue> or other color names built into Warzone (like <cinnamon>) will look up its Hexcode in the Colors table.
If a color name is not recognized, the color will be the default Warzone Text color.
Example: "Hello <green>World" will make "World" be displayed in a green color (#00ff05).
If the tag content starts with a hashtag, it will parse the next 6 hexadecimal numbers (0-9, a-f) as a color code.
More information here
Example:"This is <#ff0000>colorful" will make "colorful" be displayed in a red color (#ff0000)
Note that this library makes no attempt to check if the Hex color code is valid. Your mod will crash if you input an invalid Hex color code!
/Using </> will make following Text be displayed in the default Warzone color (white-ish).
Technically, you can use any non-recognized color name or just an empty <>,
but using </> is considered following the convention
Example: "<red>This is red</>This is default" Will make "This is red" be displayed in a red color but "This is default" in the default Warzone Text color.
wbrThis is per se not a color tag, but is instead used to indicate that a long word can be broken at this location (where <wbr> is).
Note that the library will prefer to insert newlines on spaces instead.
wbr means wordbreak. More Information here
Example: "ThisIs<wbr>AVeryLongWord"
If the given MaxWidth is too short to display the whole string, it may display
"ThisIs" on the first line and
"AVeryLongWord" on the second line
<If you want to write a literal < you can do this by typing two < in a row.
For example "This is a greater than: <<" will display as "This is a greater than: <"
Newlines can be freely added. It is denoted as a \n
Example: "<blue>This will be displayed on line 1 \nAnd this on line 2"
The blue color from the first line will continue on the second line.
(Default 30)
MaxWidth denotes how many pixels a line can take up. This includes gap size (internal), padding (internal) etc.
If not set, it will default to the preferred width of the UIGroup. If this is -1 (fit content) or
MaxWidth is smaller than 30, it will default to 30.
The default is not enough to properly display Texts, but it is enough to display most characters so the Lib won't infinitly loop.
(Default 1)
How many ancestors UIGroup has (including rootParent)
For example:
rootParent rootparent
↳VerticalLayoutGroup a
↳VerticalLayoutGroup b
↳VerticalLayoutGroup UIGroupIn this case, UIGroup has, not counting itself, 3 ancestors (rootParent, a and b).
Therefore, a 3 should be passed.
If you directly pass rootParent as UIGroup to AddStringToUI, then you should pass a 1 (default).
If you first create a container class for the generated text, which inherits from rootParent, then you should pass a 2,
etc.
If fine control over some or all created UI elements is wanted, you can use the return table of this function.
It returns an array of CreatedUIElements, which are basically the generated lines containing the parent HorizontalLayoutGroup and its children (colored Labels).
The "table convention" is as follows:
---@class CreatedUIElements
---@field HorizontalLayoutGroup HorizontalLayoutGroup
---@field Children Label[]The array is ordered after creation.
Next to hexcodes you can use predefines colors, listed in Colors.lua
You can access internal functions and tables via KaninchenTextWriterLibInternals["NAME"] where NAME is replaced by the function/table/enum name.
Refer to the documentation of the functions.
For Example local width = KaninchenTextWriterLibInternals["GetTextWidth"]("Hello World!");
This is to prevent namespace pollution
This library is available under the MIT-License, just as almost every other Warzone Mod.
Please give credit to this library in the mod description.
You can open issues or make pull requests to every file including README.md but excluding CharWidth.lua and LICENSE
Please give Feedback about this library to "Kaninchen" on Warzone, "@laurinchen2" on Discord
or in its channel on The Warzone Modmaker Discord