Special Screens

Taking a break from writing about the UI Elements for a moment, though there are still some of those that I will cover in future posts.

Most XML files are loaded as default UI Scene, which implies no special behaviors. There are, however, several XML files that will get special handling in code and most conform to specific rules in order to even be loaded. All of these scenes are distinguished by their identifying name in the INI file (Or the screen tag given to them when being loaded via script). The actual XML file name doesn't matter.

Note that when I list them below, if a name ends with a * mark, that means that only the text up to the * mark is required and that the name may be unique after that mark.

The following are special GUI screens that are loaded differently than most XML files:

SCREEN_FADE = The full screen 'fade' effect. It gets loaded like a normal XML file at first. After loaded, the first UIIcon object found (The one highest up in the file) becomes the engine's 'Fading' icon. The rest of the contents of the file will behave normally. In our default SCREEN_FADE, we include just the full screen icon. But there may be other things one would want to include on the fade, such as custom images, etc.

SCREEN_QUICKCHAT = The NWN1 style dialog box. First it is loaded like a normal XML file, then the following ui objects are searched for in order for the engine to use them:
npclistbox - Listbox of NPC spoken text
npctext - Text field for NPC spoken text (Contained by npclistbox generally)
replieslistbox - Listbox of Player Reply options
skipdialogbutton - Button for skipping through the NPC spoken nodes
speakername - Text field for containing the speaker's name
portrait - UIPortrait object
All but the speakername and portrait fields are necessary or the window will not be loaded.

SCREEN_CUTSCENE = The fill screen cutscene view with the black bars on the top and bottom. This window is loaded like any other, then the following objects are searched for by the engine:
topbar - UIFrame for the top black bar
bottombar - UIFrame for the bottom black bar
FULLSCREEN_IMAGE - UIIcon used for full screen images.
toplistbox - Listbox to contain the text shown on top
toplistboxtext - Textfield contained by toplistbox
bottomlistbox - Listbox to contain the text shown on the bottom. Spoken by NPCs
bottomlistboxtext - Text field contained by bottomlistbox
replieslistbox - Listbox to contain the replies available to a player.
skipdialogbutton - Fullscreen button for clicking through the dialog
Failure to locate any of the above objects will result in the screen not loading.

SCREEN_CONTEXTMENU = The rightclick menu system. Technically, this gets loaded like any other XML file. I'll make another post later about the syntax and format of the contextmenu.xml file.

SCREEN_MINIMAP = The in-game minimap GUI. I don't know a lot about how the Minimap works. If further documentation is requested for it, I can research it further later.

SCREEN_AREAMAP = The in-game area map that can be brought up. I don't know a lot about how the Area Map works. If further documentation is requested for it, I can research it further later.

SCREEN_MESSAGEBOX_SPLITSTACK* = Scene used for splitting stacks of items in inventory. The only gui element required is 'inputbox'.

SCREEN_MESSAGEBOX_SPLITSTACKSTORE* = Scene used for splitting stacks of items for stores. It's actually loaded identically to the SCREEN_MESSAGEBOX_SPLITSTACK and only requires the 'inputbox' object to exist. I'm not sure why it got made into a seperate entry.

SCREEN_MESSAGEBOX* = This is used for the generic message box popups. I'll probably have to write up more on them another time as they can be used effectively by scripts as well. The required elements for these are:
messagetext = Text field that contains the message.
okbutton = Button that will execute the OK callback
cancelbutton = Button that will execute the Cancel callback
messageboxlb = Listbox for containing the message text in case the text gets long.
MSGBOX_BACKGROUND = Frame used for the background, this one is optional.

SCREEN_STRINGINPUT_MESSAGEBOX* = Message boxes that prompt for user string input. They are identical to normal Message boxes, except that they also require a 'inputbox' text field.

SCREEN_MESSAGE* = Chat boxes, pretty much. Note that currently the engine only supports loading the hard coded ones in ingamegui.ini. I hope to change this to be a lot more flexible down the line. The required elements are:
messagelistbox - Listbox containing the scrollback text. If it is not found, the engine searches for messagelistbox2 instead. If neither is found, the screen is not loaded.
inputbox - Text field used for user input.
IMEREadingWindow - Used for IME support.
IMEReadingWindowBG - Used for IME support.
IMEComposeWindow - Used for IME support.
IMEComposeWindow - Used for IME support.
IMECandidateWindow - Used for IME support.
IMECandidateWindowBG - Used for IME support.
INPUT_CONTAINER - Used by the engine for easily hiding/unhiding the input related objects.

SCREEN_HOTBAR, SCREEN_HOTBAR_2, SCREEN_HOTBAR_V1, SCREEN_HOTBAR_V2 = All the hotbars built into the game. There are no required or special UI elements needed to load these.

If a Screen Tag doesn't match to any of the above screens, then a normal UI Scene gets created with all the default behaviors associated with it.