[Modding] UI.Metrics and more UIElement methods + allowing pcall (and/or xpcall)
Hello
This is a feature request for the Modding API.
I'm currently making a Mod library (not a mod itself) which will help other Warzone Mod Makers to easily add colorful Text to their UI without having to mess with HorizontalLayoutGroups and Labels. It's realized by using the AddStringToUI function provided by the library, for example:
AddStringToUI(rootParent, "Hello!<red>This Text is red<blue>This Text is blue", 500);
- The rootParent (can also be a HorizontalLayoutGroup, VerticalLayoutGroup, EmptyObject or even a Button) is the parent to which the generated elements should be inheriting from.
- The string is an html inspired string with colortags and such ( hexadecimal color codes are also possible) from which the UI elements will be generated from
- The 500 is the max length of the line before a new line will automatically inserted
For more information check out https://github.com/Laurinchen/TextWriterLib
The current problem is that the data for sizing and such has been taken from the Warzone website and only from the Warzone website, this means that UI elements created by this library will most likely only be correctly displayed on the Website. This is an obvious cross-compatibility issue, which cannot be easily fixed by the library itself in Warzones Modding API current state. I'm therefore suggesting following (client only) UI APIs:
- UI.Metrics.GetTextWidth(text): Takes a string as the argument and returns the width of text in pixels as a number. Depends on the client type (website, standaloneclient, ...) and the current font used. Suggested Resources:
- UI.Metrics.HorizontalGapSize: Constant number, the gap Size between 2 Elements in a HorizontalLayoutGroup. Will depend on the the client type (website, standaloneclient, ...) the game is being played on
- UI.Metrics.VerticalGapSize: Constant number, the gap size between 2 Elements in a VerticalLayoutGroup. Will depend on the the client type the game is being played on
- UI.Metrics.ExtraSpacePerChildLevel: Constant number. Every child of a parent gets moved left further (left: CSS-property) depending how deep down it is the ancestor tree. This constant reflects that
Definition of a [UIElement]:
Everything that can have a size, which can for example be set via [UIElement].SetPreferredWidth, for example a HorizontalLayoutGroup or Label.
API suggestions:
- [UIElement].GetCurrentWidth(): Returns a number of how much width the element currently uses in pixels
- [UIElement].GetAvailableWidth(): Returns a number of the max width the element can expand into in pixels
- [UIElement].GetAvailableWidthLeft(): Returns a number of how much space there's left it still can expand into in pixels. Basically GetAvailableWidth() - GetCurrentWidth()
- [UIElement].GetCurrentHeight(): Returns a number of how much height the element currently uses in pixels
- [UIElement].GetAvailableHeight(): Returns a number of the max height the element can expand into in pixels
- [UIElement].GetAvailableHeightLeft(): Returns a number of how much space there's left it still can expand into in pixels. Basically GetAvailableHeight() - GetCurrentHeight()
- [UIElement].GetAncestorCount(): Returns the ancestor count of the UI Element. For example, the method called on a Label directly inheriting from rootParent should return 1.
- If any of the above cannot be calculated for whatever reason, it should return -1
Definition of dialogRootParent:
the rootParent passed to the callback of ClientGame.CreateDialog(callback).
- GetDialogHeight(dialogRootParent): Returns the height of the created menu created by calling ClientGame.CreateDialog(...)
- GetDialogWidth(dialogRootParent): Returns the width of the created menu created by calling ClientGame.CreateDialog(...)
- Above could also be parameters of the callback passed to ClientGame.CreateDialog(callback)
Aditionally, I think, following function(s) should be enabled:
- pcall
- xpcall
Reasoning: pcall (and xpcall) are core parts of the exception system of Lua and allow for simple error recovery. This is generally useful for general modding and programming, but it is also useful for this library: If the parsing fails, it could instead
- return an error
or
- add the error to the UI to inform the user of what happened
This is especially useful if
- a mod developer wants to let players have access to the functionality of this library, for example for a custom group chat with color support
- the text parameter is highly dynamically generated and the mod author didn't do formal verification of his code
Another reason is that http://lua-users.org/wiki/SandBoxes calls pcall and xpcall safe, so there shouldn't be much to worry about except if
- Fizzer changed pcall (and xpcall) in an important way
- Fizzer knows about security vulnerabilities with pcall (and xpcall)
- Fizzer changed the underlying exception system in such a way that pcall (and xpcall) don't work as expected anymore
I hope to gain Feedback by Fizzer and other Mod makers about these ideas. Thank you for reading
Tracking Issue of this Uservoice thread: https://github.com/Laurinchen/TextWriterLib/issues/1
-
Kaninchen commented
Edit: I now have implemented custom error handling, so while I technically don't need pcall and xpcall anymore, other mod makers may still need