id Tech 4 Classes (neo/ui)

Descriptions of files in the neo/ui folder.

  • The name of each section refers to the C++ files (.h and .cpp) with the same name. For example, BindWindow indicates the files BindWindow.h and BindWindow.cpp.
  • Some sections will show a file extension to mark a single file with no companion, such as ListGUILocal.h.
  • A "+ description" note means that the file contains a detailed description of one or several classes.
  • A class name between parentheses signifies that it is inherited: SubClass (BaseClass).
  • Some hypotheses are shared in this page. They are probable, but unconfirmed.

All elements in a gui are subwindows; each of them may or may not be interactive. Here are all types of subwindows:

  • windowDef
  • editDef
  • choiceDef
  • sliderDef
  • markerDef
  • bindDef
  • listDef
  • fieldDef
  • renderDef
  • gameSSDDef
  • gameBearShootDef
  • gameBustOutDef

windowDef objects are the most common; the others are special cases.

Each of these types is associated to a class in this folder. The class that defines "windowDef" subwindows is defined in Window.h, the one for "editDef" in EditWindow.h, the one for "choiceDef" in ChoiceWindow.h, etc.

=BindWindow

Class: idBindWindow (idWindow)

Supports bindDef subwindows, which assign a key to a game command. The Pause menu has a number of these, and is likely the only gui in the game that makes use of them.

  • HandleEvent() takes care of key assignment. It is called when the user clicks the option to change the key, and again when the new key is assigned.

=ChoiceWindow

Class: idChoiceWindow (idWindow)

Suports choiceDef subwindows, visible in the Pause menu > Options > Game Options.

When the user clicks on a choiceDef, it will cycle through all available options (often just Yes and No).

=DeviceContext

idDeviceContext seems to manage the appearance of guis: it has methods for formatting and displaying rectangles and text, as well as drawing the mouse cursor.

  • DrawCursor() draws the gui's cursor (not the regular default cursor, which appears when the console is opened)
  • DrawText() displays text fields; without it, no text would be visible in any gui

=EditWindow

Class: idEditWindow (idWindow)

Supports editDef subwindows (editable text fields), visible in the Pause menu > Options > Game Options > Player Name.

  • idEditWindow::GainFocus() is called (more than once, in fact) when the user clicks on an editDef to change its text

=FieldWindow

idFieldWindow (idWindow) powers fieldDef subwindows which, according to idDevNet, are not used in Doom 3 and probably aren't functional.

=GameBearShootWindow

Classes:

  • BSEntity (one of the only classes in the codebase whose name doesn't begin with "id")
  • idGameBearShootWindow

This class is related to the Shoot the Bear arcade minigame in Doom 3.

=GameBustOutWindow

Classes:

  • BOEntity
  • BOBrick
  • idGameBustOutWindow

Doubtless an other arcade game I haven't seen.

=GuiScript

A struct called guiCommandDef_t is defined here; an instance of this struct associates a gui function to a C++ function, via a function pointer: handler. See the notes on idGuiScript::Parse().

All gui commands are "declared" in an array of guiCommandDef_t objects, commandList[]. Also declared here are the (global) functions associated with them: Script_Set(), Script_SetFocus(), etc.

Note: Commands that affect the level and its script are dealt with in Entity.cpp (idEntity::HandleGuiCommands()).

Classes:

  • idGuiScript
  • idGuiScriptList

idGuiScript

This class interprets (and possibly executes) gui commands. An individual idGuiScript object is constructed for each command.

  • idGuiScript::Parse() (used on all commands in a gui file after it is loaded) checks whether a command is valid, i.e. if it is present in commandList. This method also links a function pointer (handler) to the corresponding C++ function
  • idGuiScript::Execute() calls the function pointed to by handler

idGuiScriptList

Maintains a list of idGuiScript objects (perhaps for all commands in one file?).

=ListGUI

Class: idListGUI

An interface class, inherited by idListGUILocal (in ListGUILocal.h).

=ListGUILocal.h

Class: idListGUILocal (idList<idStr>, idListGUI)

idListGUILocal manages the elements inside a listDef (see the ListWindow section).

  • idListGUILocal::Add() checks if an element with the specified index (the id argument) exists in the list. If so, the element takes the new value (the s argument); otherwise, a new element is added with the value
  • idListGUILocal::Push() simply appends an element to the list

=ListWindow

Class: idListWindow (idWindow)

listDef subwindows are lists of selectable values.

  • idListWindow::SetCurrentSel() is called when the user clicks one of the options. The value of the sel parameter will be the option's index (0, 1, 2, etc.)

=MarkerWindow

Like fieldDef subwindows, markerDef subwindows are not used in Doom 3 and probably aren't functional.

Class: idMarkerWindow (idWindow)

=Rectangle

Classes:

  • idRectangle
  • idRegion

idRectangle

A theoretical rectangle; this class displays nothing on the screen. idRectangle is likely just a mathematical base used by other classes to draw shapes.

idRegion

This class only maintain a list of idRectangle objects.

Few operations can be performed on these objects; apparently, idRegion is mainly used to:

  • manage a list of rectangles that are somehow related
  • verify if one of these rectangles contains a given 2D point (see the Contains() method)

=RegExp

Strangely, these files have nothing to do with regular expressions; it seems that "RegExp" means Register Expression.

Classes:

  • idRegister
  • idRegisterList

idRegister

I believe an instance of this class holds a single property of a windowDef: rect, bordercolor, text, etc.

  • The name member (idStr) is the name of the property
  • The type member (short) specifies the type of data, referencing one of the constants of the REGTYPE enum

idRegisterList

This class contains a list of idRegister objects (perhaps all the ones belonging to a specific windowDef?).

=RenderWindow

Class: idRenderWindow (idWindow)

renderDef subwindows display 3D objects. As far as I know, only one is used, in the main menu (for the planet in the background).

=SliderWindow

Class: idSliderWindow (idWindow)

sliderDef subwindows are used for gradual settings: volume, mouse sensitivity, etc.

Hypothesis: these subwindows might also be used for scrollbars for other graphical elements. (idListWindow and idEditWindow both own an idSliderWindow object.)

=SimpleWindow

idSimpleWindow is a lighter version of idWindow (which represents windowDefs in guis).

idSimpleWindow instances are only created in idWindow::Parse(). If an idWindow is simple (see idWindow::IsSimple() to know what that means), it is converted into an idSimpleWindow, no doubt to save resources.

  • The only constructor takes an idWindow as an argument
  • idSimpleWindow::GetParent() returns this windowDef's parent (also a windowDef)

The drawWin_t struct is just an idWindow and an idSimpleWindow. It is often used as an argument for idWinVar-related functions.

=UserInterface.h

Graphic user interfaces, or GUIs.

Classes:

  • idUserInterface (abstract, see idUserInterfaceLocal)
  • idUserInterfaceManager

=UserInterfaceLocal.h

Class: idUserInterfaceLocal (idUserInterface)

  • idUserInterfaceLocal::HandleNamedEvent() dispatches a named event in the gui's Desktop windowDef, which will propagate the event to its children

    Note: Once a named event is declared in a .gui file (with onNamedEvent), it is usable in the C++ code.

=Window

Window.cpp defines all available properties for a windowDef in an array called RegisterVars.

It's also here that idWindow objects are created (idWindow == windowDef in a gui). The other files (EditWindow.h, ChoiceWindow.h...) each manage their own subwindow type.

Classes:

  • rvNamedEvent
  • idWindow

idWindow

windowDef objects in GUIs.

  • idWindow::GetWinVarByName() returns the value of a gui variable
  • idWindow::MouseEnter() represents the mouse entering the rectangular zone of a windowDef. This function is only called once in idWindow::RouteMouseCoords()
  • idWindow::Parse() identifies the type of a subwindow: windowDef, editDef, etc.
  • idWindow::Redraw() updates and redraws windowDefs, and (in the case of the Desktop windowDef) also redraws the mouse
  • idWindow::RouteMouseCoords() observes the mouse's position, and calls MouseEnter() and MouseExit() when it enters or leaves a windowDef's area
  • idWindow::RunScript() is called for every gui event (OnActivate, OnEnter, OnAction...). It only takes one argument: the type of event. Types are defined in an enum:

    enum {
        ON_MOUSEENTER = 0,
        ON_MOUSEEXIT,
        ON_ACTION,
        ON_ACTIVATE,
        ON_DEACTIVATE,
        ON_ESC,
        ON_FRAME,
        ON_TRIGGER,
        ON_ACTIONRELEASE,
        ON_ENTER,
        ON_ENTERRELEASE,
        SCRIPT_COUNT
    };

    Note: This function is called every frame with the ON_FRAME event.

  • idWindow::StateChanged() updates the windowDef's appearance and calls the StateChanged() method of all its idWindow and idSimpleWindow children
  • idWindow::Interactive() checks if the windowDef or any of its children have an OnAction property, which means they will perform actions when clicked

    Hypothesis: OnAction is the only property checked; this is probably why moving the mouse over a windowDef (onMouseEnter) does not trigger a call to idEntity::HandleGuiCommands().

  • idWindow::IsSimple() returns false if the windowDef has children, events or other special properties; static, background windowDefs will generally qualify as "simple"

=Winvar

These files manages gui-related variables. Some of these are defined in the C++, others in the guis themselves.

Examples of gui variables in hud.gui (the main gui for the player's heads-up display) are: player_health, player_ammo and player_armor. These particular variables are set in various methods of idPlayer.

Main classes:

  • idWinVar
  • idMultiWinVar (idList< idWinVar * >)

Subclasses of idWinVar:

  • idWinBackground (idWinStr)
  • idWinBool
  • idWinFloat
  • idWinInt
  • idWinRectangle
  • idWinStr
  • idWinVec2
  • idWinVec3
  • idWinVec4

idWinVar

  • idWinVar::GetName() returns the name of a gui variable
  • idWinVar::SetName() sets its name

idWinStr

  • idStr::c_str() returns the value of this variable as a const char*

idWinRectangle

  • operator const idRectangle&() converts the data of the variable into an idRectangle