diff --git a/nwn-2-gui-scripting.md b/nwn-2-gui-scripting.md index 6ba1619..a9e2c45 100644 --- a/nwn-2-gui-scripting.md +++ b/nwn-2-gui-scripting.md @@ -1,8 +1,6 @@ -GUI Scripting - # Resources - [oeiprogrammer](https://oeiprogrammer.blogspot.fr) @@ -13,11 +11,11 @@ GUI Scripting The GUI are written in a non standard form of XML. - The first line must be something like `` -- Attributes values can be delimited by `'`, `"` or can end with a space - + This does not work: `OnLeftClick=UIObject_Misc_ExecuteServerScript("gui_myscript","Hello World")` because OnLeftClick value has no delimiter and will end after `Hello` +- Attributes values can be delimited by `'`, `"` or if not delemited ends with a space + + Example: this does not work: `OnLeftClick=UIObject_Misc_ExecuteServerScript("gui_myscript","Hello World")` because OnLeftClick value has no delimiter and will end after `Hello` - Auto-closing tags are accepted `` -- If you repeat an attribute twice, the GUI will not load -- The `UIScene` element is never closed +- If you repeat an attribute twice inside the same XML tag, the GUI will not load +- The `UIScene` tag must never be closed # Rules @@ -32,22 +30,24 @@ The XML file name must not exceed 32 characters (TODO: with or without extension ## Variables -The GUI file can store client-side variables that can be either local (only accessible through the current UI) or global (all UI share the same variables). They are identified by an integer index, and always store a string value. +The GUI file can store client-side variables that can be either local (limited to the current UI) or global (shared across all UIs of a player). They are identified by an integer index, and always store a string value. Examples: `local:0`, `local:1337`, `global:42`, ... +## Events +Events are special attributes that can trigger [callbacks](#callbacks) when specific actions are executed by the player (ex: clicking a button) or the client's engine (ex: when a frame is rendered). -## Functions +## Callbacks -Functions are special attribute values that execute specific actions either on the client-side (setting local gui variables, changing gui appearance) or on the server-side (executing scripts). +Callbacks are special attribute values for event attributes, that can execute specific actions either on the client-side (setting local gui variables, changing gui appearance) or on the server-side (executing scripts). It is better to put functions inside double quotes: `OnEvent="Callback('arg0','spaced arg',42)"`. This way it is compatible with XML standards and the function arguments values can contain spaces. Otherwise the UI won't load because the space will be treated as the end delimiter for the attribute value. -_TODO_: callback parameter parsing & delimitation (ie what happens if `UIObject_Misc_ExecuteServerScript("A,B","C",D,'E,F','G',H)`) +> _TODO_: callback parameter parsing & delimitation (ie what happens if `UIObject_Misc_ExecuteServerScript("A,B","C",D,'E,F','G',H)`) -You can use multiple functions on a single event by appending 0, 1, ... to the event name, ie `OnEvent0="DoThis()" OnEvent1="ThenDoThat()"`. Note: if you don't number events correctly, the GUI will not load. +You can execute multiple callbacks on a single event by appending 0, 1, ... to the event name: `OnEvent0="DoThis()" OnEvent1="ThenDoThat()"`. **If event numbers are not ordered correctly, the GUI will not load**. -The most useful callback is certainly `UIObject_Misc_ExecuteServerScript` that allows you to execute nwscript for any event from any UI element: `OnEvent="UIObject_Misc_ExecuteServerScript('gui_yourscript','AnyArgumentList',local:25)"` +The most useful callback is certainly `UIObject_Misc_ExecuteServerScript` that allows you to execute a server-side nwscript for any event from any UI element: `OnEvent="UIObject_Misc_ExecuteServerScript('gui_yourscript','AnyArgumentList',local:25)"`. Note: If a player is able to customize any GUI, he can execute arbitrary code on the server, and can be problematic for online servers. @@ -58,7 +58,7 @@ The most useful callback is certainly `UIObject_Misc_ExecuteServerScript` that a + Executing console commands `DebugMode 1` and `Guidebug` + Running [Skywing's client extension](https://neverwintervault.org/project/nwn2/other/nwn2-client-extension) and executing the in-chat command `/guidebug`. - When an attribute appears twice on the same element, the UI fails to load. -- Often NWN2 GUI files start with ``. This can safely be replaced by ``. +- Often NWN2 GUI files start with ``. This can be replaced by `` which generally fix syntaxic coloring. - Any standard-compliant XML parser will fail at parsing NWN2 UI files. You can find a custom XML parser implementation for nwn2 [here](https://github.com/CromFr/NWN2GuiViewer/blob/master/source/nwnxml.d). Warning: written in the D language.