UIScene

The UIScene tag at the top of the XML files defines certain global parameters about the entire GUI window being defined in the file.

A scene doesn't have anything to render by default, but rather contains items that will get rendered. So a file that defines a UIScene and nothing else will not appear as anything in the game.

Some of the attributes for UIScene overlap with those of UIObject, even though UIScene does not inherit from UIObject, so this attributes will be repeated here.

The following attriibutes are supported by the UIScene tag:

OnCreate
This callback gets executed when the scene is loaded from the XML file. This is not necessarily a one time thing, as it is possible for scenes to get unloaded from memory and then reloaded from the file the next time they are needed. Additional detail about this will be included later in this article.

priority
This determines where scenes fall in the render order, in terms of which scenes should cover up other scenes.
The valid arguments to this attribute in order of highest priority to lowest are:
SCENE_TOOLTIP - Appears on top of any other GUI
SCENE_GLOBAL - Used for messageboxes generally.
SCENE_FE_FULLSCREEN - Pre-game full screen GUIs
SCENE_INGAME_FULLSCREEN - Full screen GUIs within the game.
SCENE_INGAME_SYSTEM - Escape menu and options screens.
SCENE_SCRIPT - GUIs brought up by script
SCENE_NWN1_DIALOG - The NWN1 style dialog box
SCENE_INGAME_MENU - The popup player menu
SCENE_INGAME - Most of the windows in-game
SCENE_INGAME_TARGET - The target box

OnDestroy
This callback gets executed when the scene is unloaded from memory.

OnAdd
This callback gets executed any time the scene is made visible.

OnRemove
This callback gets executed any time the scene is closed. Note that scenes can be closed and yet remain in memory. This in fact the default behavior. See idleexpiretime below for more information.

OnBackout
This callback gets executed when the user hits their Esc key and this scene is going to be closed as a result. If the backoutkey attribute is not true, then this callback will do nothing.

OnUpdate
This is the callback to execute every frame.

OnUnhandledMouseClick
This callback gets executed if a user clicks on the scene, but none of the contents of the scene did anything with the user's click.

updaterate
The time between updates, in seconds. If no value is specified, the scene will get an update every frame.

draggable
This determines if the entire scene is draggable. This is different from dragging a single UI Object within a scene as it moves the entire window. The default setting is false.

dragregion_x
dragregion_y
dragregion_width
dragregion_height
These 4 attributes are used to define the space on the scene that can be used to drag the scene. The numbers are in pixels. If a drag region is defined using these 4 attributes, the user can only drag the scene by clicking and dragging in the defined location. If no drag region is defined, the user can drag the scene by clicking anywhere on the scene where the click will not be used by a child object of the scene.

dragresizable
Determines if this scene can be resized by dragging the edges of it. This is used in the chat window for resizing, for example. The default setting is false.

dragresizeborder
This attribute defines the size, in pixels, of the border of the scene that can be clicked on in order to resize the window.

capturemouseclicks
If set to false, then mouse clicks should pass right through the background of this scene. Useful for semi-transparent overlays and other situations where it is expected that the user be able to click through the UI Object. The default setting is true.

capturemousevents
This is pretty much a redundant attribute. It does the exact same thing as capturemouseclicks.

fullscreen
This attribute can be true or false. By default it is false. It controls what happens to this scene when the resolution of the game changes. Scenes that have this attribute set to 'true' will not have their origins moved but their dimenions will be adjusted to the new resolution. Scenes that have this attribute set to 'false' will not be resized when the resolution changes but their origin will change to stay roughly in the same part of the screen that the window appeared in before.

width
Width of the scene in pixels. The argument 'SCREEN_WIDTH' can also be used to make this scene always match the width of the full screen.

height
Height of the scene in pixels. The argument 'SCREEN_HEIGHT' can also be used to make this scene always match the height of the full screen.

x
The x origin for the window. The following string arguments are also valid: ALIGN_CENTER, ALIGN_LEFT, ALIGN_RIGHT. Defaults to 0.

y
The y origin for the window. The following string arguments are also valid: ALIGN_CENTER, ALIGN_TOP, ALIGN_BOTTOM. Defaults to 0.

expiretime
This is the amount of time in seconds a scene should be up before it is automatically removed from view and unloaded from memory. If 0 or not set, then the scene will never be automatically removed from view.

idleexpiretime
This is the amount of time in seconds a scene should not be visible before it should be unloaded from memory. This can be used to unload scenes that were shown once that will not be needed again anytime soon. The next time the scene is requested, it will be loaded from disk. This makes it possible to sometimes do quick testing of GUI changes by setting a short idleexpiretime, closing the window, then reopening it to see what it looks like with the new changes on disk.

autolayout
This attribute is only of interest in message-box style GUI screens. If enabled, the engine will attempt to automatically position the text, the 'okay', and the 'cancel' button in a classic message box layout. If left false, then the engine will not attempt to arrange any of the contents of the messagebox when the message box is requested. It is false by default.

modal
If set to true, then this UI scene will block access to the game or any underlying GUI screens until the window is closed. It is false by default. Note that scripts that bring up GUIs can override this parameter based on the parameters passed in to the script function.

fadein
The time in seconds this scene should take to fade in completely when opened.

fadeout
The time in seconds this scene should take to fade out completely when closed.

minwidth
This attribute is defunct and no longer does anything.

minheight
This attribute is defunct and no longer does anything.

scriptloadable
In order for a server script to have any control over this GUI at all, this attribute must exist in the UIScene tag and must be set to true. It is false by default. If false, than all script functions that attempt to manipulate a user's GUI will fail.

backoutkey
If this attribute is set true, then use of the backout key ('Esc' key by default) will cause this window to close. The backout key follows a defined set of logic for determining what to do when it is used. First it closes any open 'windows' in the reverse order that they were opened (Most recent window opened is closed first). If there are no windows to close, it clears the player's target. If the player has nothing targetted, it brings up the in-game options screen.