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.