User Interface Documentation

Last Updated: January 11, 2000

Hierarchy

The user interface is basically made of four components - the event system, the signal system, Widgets and the Window Manager.

I’ll go over the events and signals, and leave the rest up to a reference manual.

Event System

The event system for the user interface is identical to that of the game. Sending and posting events hasn’t changed at all.

Signals

Signals are a fairly new concept, and all classes in the UI are derived from USignal. Signals don’t have a destination, but rather, Listeners connect with USignal object (and thus UI objects) to wait for an event to be signaled. That signal event is then translated to another event which is sent to the listener.

Consider this case:

Event EV_Run ( "ev_run", … );

class runner : public Listener

{

public:

CLASS_PROTOTYPE ( runner );

void OnRun ( Event * );

void MakeRunningButton ();

}

CLASS_DECLARATION ( Listener, runner, NULL )

{

{ &EV_Run, OnRun },

{ NULL, NULL }

};

void runner::MakeRunningButton ()

{

UIButton *button = new UIButton;

button->InitFrame ( NULL );

button->Connect ( this, W_ButtonPressed, EV_Run );

}

UIButton is a widget that calls SendSignal ( W_ButtonPressed ) whenever it is pressed. This connection in the bolded line says that when the button sends the signal W_ButtonPressed, the event EV_Run will be sent on to this (being the runner class).

Signals are useful for when you want to know when another window is being sized, moved, activated, destroyed, et cetera. That will all be documented below.

UIWindowManager

::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

get/setFirstResponder () - This lets a widget capture the mouse and keyboard input regardless of activation.

ActivateControl () - Activates a widget for getting input

DeactivateCurrentControl () - Makes no widget get input

DeactivateCurrentSmart () - Takes activation away from the current widget and tries to give it to the next logical candidate a la Win32.

ActiveControl () - Should be named getActiveControl () - gets the active control

setCursor () - Sets the cursor to a shader/material

showCursor () - Shows/hides the mouse cursor

RegisterShader () - Registers a permanent shader and returns a pointer to it for when the renderer restarts

IsDead () - Lets you know if the window manager is in the process of dying (being destructed)

Remarks

There is exactly one window manager object and its name is uWinMan. It is automatically created by the game and is a transparent widget that covers the entire screen. Its job is to tell widgets when to draw, handle mouse and keyboard input, handle activation, and handle clipping for the renderer.

UIWidget

::USignal::Listener::Class

Signals

W_Destroyed - Signals a window’s destruction

W_SizeChanged - Signals that a window’s size has changed

W_FrameChanged - Signals that a window has moved

W_OriginChanged - Signals that a widget’s origin has changed

W_Activated - Signals that a widget has been activated

W_Deactivated - Signals that a widget has been deactivated

Mouse Events

The following mouse events have this format:

<float: x, float: y, int: buttons>

Where "buttons" is a bitmask where button x’s down status is 1 << (x-1)

W_MouseEntered - Mouse has just come into the control

W_MouseExited - Mouse is now pointing at a different control

W_MouseMoved - The mouse has moved within the control

W_Left/Right/CenterMouseDragged - The mouse is being held down and moved

W_Left/Right/CenterMouseDown/Up - Pretty obvious.

Events

W_RealignWidget - An convenience event set up so it can respond to a parent’s W_SizeChanged

EV_Widget_Hide ( "hide" ) - Hides the widget

EV_Layout_Size ( "size" ) <float:x> <float:y> <float:width> <float:height> - Set the rectangle of the widget

EV_Layout_Rect ( "rect" ) - See EV_Layout_Size

EV_Layout_Name ( "name" ) <string> - Sets the name of the widget

EV_Layout_Title ( "title" ) <string> - Sets the title of the widget

EV_Layout_Font ( "font" ) <string> - Sets the font of the widget

EV_Layout_BGColor ("bgcolor") <float:red><float:green><float:blue><float:alpha> - Set the background color of the widget

EV_Layout_FGColor ("fgcolor") <float:red><float:green><float:blue><float:alpha> - Set the foreground color of the widget

EV_Layout_Borderstyle ( "borderstyle" ) <string> - Sets the border style of the widget (NONE, 3D_BORDER, INDENT_BORDER)

EV_Layout_Shader ( "shader" ) <string> - Sets the background shader of the widget

EV_Layout_TileShader ( "tileshader" ) <string> - Sets the background shader of the widget and draw it tiled

EV_Layout_HoverShader ( "hovershader" ) <string> - Set the background shader when the mouse is over the widget

EV_Layout_FadeIn ("fadein") <float:time> - Se the amount of time (seconds) for a widget to fade in over

EV_Layout_StopSound ( "stopsound" ) <string> - Set the sound to be played when the widget stops moving

EV_Layout_ClickSound ( "clicksound") <string> - Set the sound to be played when the widget is clicked

EV_Layout_Stretch ( "stretch" ) <string> - Set the widget to be stretched horizontally or vertically across the screen (horizontal vertical both)

EV_Layout_InitData ( "initdata" ) <string> - Set the linkcvar to be initialized to this value

EV_Layout_Direction ( "direction" ) <string:direction> [float:time] - Set the direction the widget will appear from on the screen (from_top, from_bottom, from_left, or from_right) Time is specified to determine how fast the widget will scroll in.

EV_Layout_Align ( "align" ) <string> - Set the side of the screen to align the widget (left right top bottom)

EV_Layout_StuffCommand ( "stuffcommand" ) <string> Set the command to be stuffed when the widget is clicked

EV_Layout_LinkCvar ( "linkcvar" ) <string>Set the cvar that will be updated when the widget is changed

Virtual function overrides

KeyEvent () - Non-alphanumeric keys get passed into here on a keypress

CharEvent () - Alphanumeric keys go through here.

Draw () - Function called to draw the widget

AlignPosition () – Used internally to updated the widget’s position on the screen based on its alignment

FrameInitialized () - Called after the widget’s initialized

UpdateData () - For updating widgets from the contents of cvars

UpdateUIElement () – Used internally to update attached cvars

Functions of note

InitFrame () - This is what creates the widget.

get/setParent - Changes or gets the parent control. Can be NULL.

getFirst/Prev/NextChild - Obvious.

getNext/Prev/LastSibling - Like calling the child functions on the parent.

Enable/Disable/isEnabled () - A disabled control cannot be activated, and this is a hint to be drawn in a way to indicate this

IsDying () - true if widget is being destroyed

FindResponder () - Tells you which control would be hit if the mouse were clicked on a position. Called from the window manager, tells you what control would be clicked, ignoring the set/getFirstResponder () stuff.

setFont () - Duh.

set/getShow () - Hides this control. Note that if you hide a control, all children calling getShow () on themselves will still return true, even though they’re hidden due to the propogation. Hidden controls and their children are not drawn or activated.

get/set*Color () - Obvious.

get/setSize () - Size of the widget

get/setFrame () - The window’s frame relative to its parent

get/setOrigin () - Should be depreciated. Useless.

get/setName () - Name of the widget, good for referencing through script.

get/setTitle () - The title that DrawTitle draws.

get/setDirection/Motion*/Align - This is all Scott’s, ask him about it.

setMaterial () - The shader for the background of the object.

setHoverMaterial () - The shader for when the mouse is over the object. Not used by base widget, should be removed or only placed in classes that need it.

getLocalPoint () - Translates a point from global space to local space.

getGlobalPoint () - Translates a point from local space to global space.

get/setBackgroundAlpha () - Sets the alpha for the background. If it’s 0, the background isn’t drawn

getTitleWidth/Height () - Width and height of the title string in the current font.

CanActivate/AllowActivate () - Lets a control get activated and queries if it can

IsActive () - Asks the window manager if the current control is active

Link* () - Links up the control to a cvar or command. Implementation depends on the widget

FindWidget () - Searches for a child widget by name

BringToFrontPropogated () - Brings the current control and all its parents to the front

IsThisOrChildActive () - Obvious. Returns the active widget or NULL if none apply.

MouseEventToClientPoint () - Helper function, takes an event object from a mouse event and returns it in local space.

getClientFrame () - A rect with 0, 0 as the upper left and getSize () size.

get/setAlwaysOnTop/Bottom - Makes the control always on top or bottom relative to its siblings. Setting both top and bottom to false makes it "normal"

SendSignal - Like USignal::SendSignal, but only sends it if the window manager isn’t dying.

Remarks

Widgets are the basic building block of the UI. Creating them automatically registers them with the window manager and you act on these objects to move them around and stuff. Child widgets sit inside their parents, and all widgets are drawn from top to bottom in the hierarchy, clipped by the window manager.

After a widget’s frame has been initialized, it deletes itself when its parent is deleted. When you delete a widget yourself, it is removed from the screen and all its children are deleted as well.

UIButton

::UIButtonBase::UIWidget::USignal::Listener::Class

Signals

W_Button_Pressed - Sent when the button is clicked

Events

Functions of note

Remarks

The class it’s derived from, UIButtonBase, it only used for this, so I haven’t bothered to document it.

This function can use the widgets linking to a cvar to toggle a cvar on press or execute a command.

UICheckBox

::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

isChecked () - Lets you know if the check box is checked or not.

Remarks

This can be linked to a cvar in order to toggle it.

UIConsole

::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

setConsoleHandler () - Sets a function to handle the user’s console input

AddText () - Adds text to the console

Remarks

This creates a simple console control with its own scroll bar. This is not a floating console, just the inside of one of those windows.

UIFakkLabel

::UILabel::UIWidget::USignal::Listener::Class

Signals

Events

EV_Layout_PlayerStat("playerstat") <integer> – Sets the player stat to be displayed when this label is rendered. Playerstats are sent over in the playerstate to keep track of things like health, ammo, etc… Playerstats are defined in bg_public.h.

EV_Layout_InventoryRenderModelIndex("invmodelrender") <integer> - Sets the index of an item model to be drawn in the label. The index corresponds to the set of itemindexes that are sent over in the playerstate. The client code looks this up for a corresponding model (which is specified by the Inventory System commands) and renders it in the label. In FAKK2 the indexes refer to items that are being held in specific hands so that the HUD can display what the active weapon in that hand is.

EV_Layout_ItemIndex("itemstat") <integer> - Sets the index of an item name to be drawn in the label. The index corresponds to the set of itemindexes that are sent over in the playerstate. The game code looks this up for a corresponding item name (which is specified by the Inventory System commands) and draws it in the label. In FAKK2 the indexes refer to items that are being held in specific hands so that the HUD can display what the active weapon in that hand is.

Functions of note

Remarks

This widget is used in the FAKK2 client executable. It is an extension to the UILabel class that is used to special case render items that are used in the HUD.

UIFloatingConsole

::UIFloatingWindow::UIWidget::USignal::Listener::Class

Signals

UIFloatingWindow::W_ClosePressed - Signaled when the close button is pressed

Events

Functions of note

setConsoleHandler () - Sets a function to handle the user’s console input

AddText () - Adds text to the console

setConsoleBackground () - Sets the background color and alpha for the console object

setConsoleColor () - Sets the foreground color of the console object

Remarks

This console is like a UIFloatingWindow, except that it does not automatically close. It also comes with a sizer and a status bar. The normal window foreground/background colors have no effect because this control sets its alpha to 0. Use setConsole* instead to set up the colors.

UIField

::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

Remarks

This is only set up to take user input and set cvars based on it. It’s a simple one line edit box.

This probably should be fixed to add in support for normal querying.

UIFloatingWindow

::UIWidget::USignal::Listener::Class

Signals

Events

UIFloatingWindow::W_ClosePressed - Sent to the window when the close button is pressed. Deletes the window by default.

UIFloatingWindow::W_MinimizedPressed - Sent to the window when the minimize button is pressed. Does a windowshade by default.

Functions of note

Create () - A more floating window-specific version of InitFrame (), doesn’t have stuff like font and border since they don’t really apply

IsMinimized () - Tells you if the window is minimized. To unminimize it, ProcessEvent ( W_MinimizePressed ) on it.

getChildSpace () - Gets the parent widget you should create child widgets in. This is so that you don’t need to worry about positioning your controls under the title bar and such.

Remarks

Should be fairly self explanatory.

UIFont

(base class)

Signals

Events

Functions of note

UIFont (name ), setFont ( name ) - Loads in the font specified by name for use in this font object

Print () - Prints out text, allows for newlines to print multiple lines of text

PrintJustified () - Prints out a single line of text justified within a rectangle but not clipped to it.

setColor () - Sets the color this font will be printed in

getWidth () - Gets the width of a string

getCharWidth () - Gets the width of a single char

getHeight () - Gets the fonts height

Remarks

UILabel

::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

Remarks

Very simple widget, just draws its title centered. It can also be bound to a cvar and draw that instead.

UILayout

::Listener::Class

Signals

Events

Functions of note

Load () - Loads a layout file (.urc) which creates a widget container and stuffs all the widgets into it.

Remarks

This does all the work for you, there’s nothing to really talk about. It runs through the file, uses RTTI to create all the widgets it needs, and send the EV_Layout events to configure the controls

UIList

::UIWidget::USignal::Listener::Class

Signals

Events

EV_Layout_AddListItem <string> - Adds <string> to the list

Functions of note

AddItem () - Adds a string to the list

Remarks

Displays a quake-type list. The current item is displayed on one line, with left and right buttons to scroll through the choices. If bound to a cvar, it sets it to the text of the current item. If bound to a command, it stuffs the selected item.

UIListIndex

::UIList::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

Remarks

Same as a UIList except that instead of the list item being set in the cvar, it’s the index number of the item.

UIListBox

::UIWidget::USignal::Listener::Class

Signals

EV_UIListBox_ItemSelected <integer> - When the selected item changes, this is signaled. <integer> is the newly selected item.

EV_UIListBox_ItemDoubleClicked <integer> - When an item is double clicked, this is signaled. <integer> is the clicked item.

Events

EV_Layout_AddListItem <string> - Adds <string> to the list

Functions of note

getCurrentItem () - Gets the current 0-based item index

getNumItems () - Duh

getItemText () - Gets the text for the zero-based item index

DeleteItem () - Deletes an item

DeleteAllItems () - Clears out the list box

Remarks

This is a fully scrolling Win32-type list box. When linked to cvars a selection change updates the cvar. When linked to a command, a double click carries it out.

UIMultiLineEdit

::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

getEndSelPoint () - Returns a UIPoint2D representing the end selection

setData () - Sets the text in the edit control

getData () - Gets the text in the edit control

Empty () - Empties out the edit control

Copy/Paste/DeleteSelection () - Pretty obvious

setChanged () - Sets the "the data has changed" flag.

IsChanged () - Tells you if the data has changed since the last setChanged ( false )

Remarks

This creates an edit box with a vertical scroll bar. *Changed are convenience functions for you to know if the user has typed something. The notepad widget uses this to know whether or not to confirm closing notepad.

UINotepad

::UIFloatingWindow::UIWidget::USignal::Listener::Class

Signals

Events

EV_Notepad_SaveAs - Menu event for Save As

EV_Notepad_Save - Menu event for Save

EV_Notepad_Find - Menu event for Find

EV_Notepad_Goto - Menu event for Goto

EV_Notepad_Cut/Copy/Paste - You get the idea.

W_Notepad_ChildSizeChanged - Sent when the size of notepad’s child window changes

Functions of note

Create () - Used to create the notepad window. Can fail (returns false) if it can’t load the file.

setFileName () - Used to change the file name (so that a file can be saved as a different file)

Remarks

The notepad has a pull down menu, a status bar with sizing bar, and a multiline edit control.

It is preferred that the helper function UI_LoadNotepadFile () be used to open a notepad window for you.

UIPopupMenu

::UIWidget::USignal::Listener::Class

Enums

uipopup_type

{

UIP_NONE - A dummy item, or the last one

UIP_EVENT - data points to an event object

UIP_SUBMENU - data points to a describe[] representing a submenu

UIP_CMD - data is a const char * with a command to stuff

UIP_CVAR - data is a const char * with a cvar/data pair

UIP_SEPARATOR - this item is a seperator

};

Types

uipopup_describe

{

const char *title - The displayed text in the menu, NULL if last item

uipopup_type type - The type of menu item (above)

void *data - The data (type-specific), can be NULL for types that don’t need it

};

Functions of note

Create () - To create a simple popup menu, call the first type of this function. The second type is reserved for pulldown menus and advanced usage.

YouAreASubMenu () - For use internally and by pulldown menus.

Dismiss () - Dismisses of this menu and the menus above it if this is a submenu

setAutoDismiss () - Sets whether or not the menu calls Dismiss () when an item is selected. Defaults to true.

setNext/PrevSelection () - Moves the current menu selection up or down one and wraps around

getSelectedDescribe () - Gets the describe pointer for the selected menu item, or NULL if there is no selected item

setSelection () - Sets the index of the currently selected menu item

Remarks

When making the menu, you make it with a uipopup_describe array. the last entry having a NULL title and data, and a type of UIP_NONE. Here’s an example from Notepad:

static uipopup_describe fileMenu [] =

{

{ "Save (Ctrl-S)", UIP_EVENT, &EV_Notepad_Save },

{ "Save As... (Ctrl-A)", UIP_EVENT, &EV_Notepad_SaveAs },

{ "", UIP_SEPARATOR, NULL },

{ "Close (Ctrl-W)", UIP_EVENT, &UIFloatingWindow::W_ClosePressed },

{ NULL, UIP_NONE, NULL }

};

UIPulldownMenu

::UIWidget::USignal::Listener::Class

Types

uipull_describe

{

const char *title - The displayed text in the pull down menu

uipopup_describe *desc - A uipopup_describe[] for the popup menu

};

Events

EV_Pulldown_ChildKilled - Sent when the child popupmenu is killed

Functions of note

Create () - Creates a pull down menu bar anywhere in a window

CreateAligned () - Creates a pull down menu bar aligned to the top of the parent

Realign () - Call this when the parent is resized to realign the menu bar to the top

Remarks

This is the class for a standard pulldown menu bar a la notepad’s. This control doesn’t automatically realign itself (FIXME) when the parent is sized, so make sure to call Realign () when that happens.

UISlider

::UIWidget::USignal::Listener::Class

Signals

Events

EV_AutoIncrement - Used to auto increment the slider

EV_AutoDecrement - Used to auto decrement the slider

EV_Layout_Range ( "setrange" ) <float: min> <float: max> - Sets the range of the slider between min and max, inclusive

EV_Layout_Range ( "slidertype" ) <string: float|integer> - Sets the type of the slider to either float precision or integer precision

EV_Layout_SliderStep ( "stepsize" ) <float: stepsize> - Sets the step size of the slider when using the arrow buttons

Functions of note

setType () - Sets the slider type, either SLIDER_FLOAT or SLIDER_INTEGER

setRange () - Sets the range of the slider

setStep () - Sets the step size of the slider

Remarks

FIXME

There is no way to query the value of the slider

Sliders must be bound to cvars to be useful in any way

UIWindowSizer

::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

UIWindowSizer ( UIWidget * ) - Constructs a window sizer and binds it to the widget in the argument

get/setDraggingWidget () - Gets and sets the widget that the window sizer sizes.

Remarks

The window sizer is meant to work hand-in-hand with the status bar, and I haven’t tried it standalone yet.

UIStatusBar

::UIWidget::USignal::Listener::Class

Signals

Events

Functions of note

UIStatusBar ( alignment_t, float height ),

AlignBar ( alignment_t, float height ) - Aligns the status bar to a side specified by the alignment_t and a specified height. The only valid alignment_t is WND_ALIGN_BOTTOM

DontAlignBar () - Doesn’t align the bar to a side

EnableSizeBox () - Specifies the widget to make the size box resize. If the widget is NULL, the size box is hidden

Remarks

Here’s the easiest way to put a size box in your app. The status bar automatically realigns itself and the size box when the parent is resized.

To set the status bar text, set the title with setTitle ()

UIVertScroll

::UIWidget::USignal::Listener::Class

Signals

W_Scrollbar_Positioned <integer: pos> - Signaled when the scrollbar’s position changes

Events

Functions of note

get/setNumItems () - Gets/Sets the number of items the bar is scrolling

get/setPageHeight () - Gets/sets how many items are on a page

get/setTopItem () - Gets/sets which item is the top one

setThumbColor () - Sets the color of the scrolling thumb

setSolidBorderColor () - Sets the color of the border around the scroll bar

InitFrameAlignRight () - Creates a scroll bar if it hasn’t been already and aligns it to the right of the parent. Call this whenever the parent resizes to realign it.

Remarks

This is a basic vertical scroll bar implementation. FIXME The bar doesn’t realign itself whenever the parent is resized, so call InitFrameAlignRight () to do that. Don’t worry, it won’t recreate the scroll bar, that only gets created once.

UIText

::UIWidget::USignal::Listener::Class

Console

::USignal::Listener::Class

These classes have been made obsolete and should be removed from the library post-haste.