Represents a single GUI screen. More...

#include <screen.hpp>

Inheritance diagram for GUIEngine::Screen:

[legend]

Public Member Functions
std::function< Screen *()>	getNewScreenPointer () const
	Save the function before GUIEngine::clearScreenCache, call it after to get the new screen instance pointer.

void	setScreenPointerFunction (const std::function< Screen *()> &f)

	Screen (bool pause_race=true)
	Creates a dummy incomplete object; only use to override behaviour in sub-class.

	Screen (const char *filename, bool pause_race=true)
	Creates a screen populated by the widgets described in a STK GUI file.

bool	operator== (const char *filename) const

void	loadFromFile ()
	loads this Screen from the file passed to the constructor

bool	isLoaded () const

void	addWidgets ()
	Adds the IrrLicht widgets corresponding to this screen to the IGUIEnvironment.

void	calculateLayout ()
	Called after all widgets have been added.

void	manualAddWidget (Widget *w)
	Can be used for custom purposes for which the load-screen-from-XML code won't make it.

void	manualRemoveWidget (Widget *w)
	Can be used for custom purposes for which the load-screen-from-XML code won't make it.

void	setUpdateInBackground (bool value)
	When set to true it updates the screen even if modal dialog is opened.

bool	getUpdateInBackground ()

const std::string &	getName () const

virtual void	unload ()
	Next time this menu needs to be shown, don't use cached values, re-calculate everything.

bool	needs3D ()
	Will be called to determine if the 3D scene must be rendered when at this screen.

void	setNeeds3D (bool needs3D)
	Invoke this method for screens that use a 3D scene as background.

virtual void	loadedFromFile ()=0
	Callback invoked when loading this menu.

virtual void	unloaded ()
	Callback invoked when this screen is being unloaded.

virtual void	beforeAddingWidget ()
	Optional callback invoked very early, before widgets have been added (contrast with init(), which is invoked afer widgets were added)

virtual void	init ()
	Callback invoked when entering this menu (after the widgets have been added).

void	push ()
	Displays this screen bu pushing it onto the stack of screen in the state manager.

virtual void	tearDown ()
	Callback invoked before leaving this menu.

virtual bool	onEscapePressed ()
	Called when escape is pressed.

virtual void	eventCallback (Widget *widget, const std::string &name, const int playerID)=0
	will be called everytime something happens.

virtual void	onUpdate (float dt)
	optional callback you can override to be notified at every frame.

virtual void	onDraw (float dt)
	optional callback you can override to be notified at every frame.

virtual MusicInformation *	getMusic () const

virtual MusicInformation *	getInGameMenuMusic () const

virtual int	getWidth ()

virtual int	getHeight ()

virtual bool	isResizable () const

virtual EventPropagation	filterActions (PlayerAction action, int deviceID, const unsigned int value, Input::InputType type, int playerId)
	Override this if you need to be notified of player actions in subclasses.

virtual void	onDisabledItemClicked (const std::string &item)
	Callback you can use if you want to know when the user pressed on a disabled ribbon item.

virtual void	filterInput (Input::InputType type, int deviceID, int btnID, int axisDir, int value)
	Override this if you need to be notified of raw input in subclasses.

virtual void	onDialogClose ()
	Callback that gets called when a dialog is closed.

virtual void	onFocusChanged (Widget previous, Widget focus, int playerID)
	Callback called when focus changes.

Public Member Functions inherited from GUIEngine::AbstractTopLevelContainer
virtual int	getWidth ()=0

virtual int	getHeight ()=0

Widget *	getWidget (const char *name)
	This function returns a widget by name if that widget is found.

Widget *	getWidget (const int id)
	This function returns a widget by irrlicht ID if that widget is found.

template<typename T >
T *	getWidget (const char *name)
	This function searches and returns a widget by name, cast as specified type, if that widget is found and the type is correct.

Widget *	getFirstWidget (PtrVector< Widget > *within_vector=NULL)
	This function returns the first widget found in within_vector.

Widget *	getLastWidget (PtrVector< Widget > *within_vector=NULL)
	This function returns the last widget found in within_vector.

void	elementsWereDeleted (PtrVector< Widget > *within_vector=NULL)
	This function is called when screen is removed.

bool	isMyChild (Widget *widget) const
	This function checks if a widget is a child of the container.

virtual bool	enableScreenPadding () const

Static Public Member Functions
static void	parseScreenFileDiv (irr::io::IXMLReader xml, PtrVector< Widget > &append_to, irr::gui::IGUIElement parent=NULL)
	Loads a GUI screen from its XML file.

Static Public Member Functions inherited from GUIEngine::AbstractTopLevelContainer
static Widget *	getWidget (const char name, PtrVector< Widget > within_vector)
	This function returns a widget by name if that widget is found in within_vector.

static Widget *	getWidget (const int id, PtrVector< Widget > *within_vector)
	This function returns a widget by irrlicht ID if that widget is found.

Protected Attributes
bool	m_resizable
	True if this screen is resizable.

Protected Attributes inherited from GUIEngine::AbstractTopLevelContainer
PtrVector< Widget, HOLD >	m_widgets
	the widgets in this screen

Widget *	m_first_widget
	AbstractTopLevelContainer is generally able to determine its first widget just fine, but in highly complex screens (e.g.

Widget *	m_last_widget
	AbstractTopLevelContainer is generally able to determine its last widget just fine, but in highly complex screens (e.g.

Private Attributes
bool	m_pause_race
	True if the race (if it is running) should be paused when this screen is shown.

bool	m_loaded

bool	m_render_3d
	Will be called to determine if the 3D scene must be rendered when at this screen.

bool	m_update_in_background
	When set to true it updates the screen even if modal dialog is opened.

unsigned int	m_magic_number
	to catch errors as early as possible, for debugging purposes only

unsigned	m_width

unsigned	m_height

std::string	m_filename

std::function< Screen *()>	m_screen_func
	For runtime screen reloading without template.

Friends
class	Skin

Additional Inherited Members
Protected Member Functions inherited from GUIEngine::AbstractTopLevelContainer
void	addWidgetsRecursively (PtrVector< Widget > &widgets, Widget *parent=NULL)
	This function adds a list of widgets recursively, effectively creating the hierarchy of widgets.

Detailed Description

Represents a single GUI screen.

Mainly responsible of its children widgets; Screen lays them out, asks them to add themselves, asks them to remove themselves, etc.

Also initiates the read of GUI files, even though most of that work is done in "screen_loader.cpp"

Constructor & Destructor Documentation

◆ Screen()

Screen::Screen	(	const char *	file,
		bool	pause_race = `true`
	)

Creates a screen populated by the widgets described in a STK GUI file.

Parameters

filename Name of the XML file describing the screen. This is NOT a path. The passed file name will be searched for in the STK data/gui directory.

Member Function Documentation

◆ beforeAddingWidget()

virtual void GUIEngine::Screen::beforeAddingWidget ( )

inlinevirtual

Optional callback invoked very early, before widgets have been added (contrast with init(), which is invoked afer widgets were added)

Reimplemented in AddonsScreen, ArenasScreen, EasterEggScreen, EditGPScreen, EditTrackScreen, GhostReplaySelection, GPInfoScreen, GrandPrixEditorScreen, HighScoreSelection, KartSelectionScreen, MainMenuScreen, CreateServerScreen, NetworkKartSelectionScreen, NetworkingLobby, BaseOnlineProfileAchievements, OnlineProfileBase, OnlineProfileFriends, OnlineScreen, OnlineUserSearch, ServerSelection, TracksScreen, OptionsScreenDevice, BaseUserScreen, SoccerSetupScreen, TrackInfoScreen, and TracksAndGPScreen.

◆ calculateLayout()

void Screen::calculateLayout ( )

Called after all widgets have been added.

namely expands layouts into absolute positions.

◆ eventCallback()

virtual void GUIEngine::Screen::eventCallback	(	Widget *	widget,
		const std::string &	name,
		const int	playerID
	)

pure virtual

will be called everytime something happens.

Events are generally a widget state change. In this case, a pointer to the said widget is passed along its name, so you get its new state and/or act. There are two special events, passed with a NULL widget, and which bear the names "init" and "tearDown", called respectively when a screen is being made visible and when it's being left, allowing for setup/clean-up.

Implemented in GPInfoScreen, TrackInfoScreen, OptionsScreenInput, AddonsScreen, ArenasScreen, CreditsScreen, CutSceneGeneral, EasterEggScreen, EditGPScreen, EditTrackScreen, FeatureUnlockedCutScene, GhostReplaySelection, GrandPrixCutscene, GrandPrixEditorScreen, HelpScreen1, HelpScreen2, HelpScreen3, HelpScreen4, HelpScreen5, HelpScreen6, HelpScreen7, HighScoreSelection, KartSelectionScreen, MainMenuScreen, CreateServerScreen, NetworkingLobby, OnlineLanScreen, BaseOnlineProfileAchievements, OnlineProfileBase, OnlineProfileFriends, OnlineProfileServers, OnlineProfileSettings, OnlineScreen, OnlineUserSearch, RegisterScreen, ServerSelection, TracksScreen, OptionsScreenAudio, OptionsScreenDevice, OptionsScreenGeneral, OptionsScreenLanguage, OptionsScreenUI, OptionsScreenVideo, BaseUserScreen, TabbedUserScreen, RaceResultGUI, RaceSetupScreen, SoccerSetupScreen, and TracksAndGPScreen.

◆ filterActions()

virtual EventPropagation GUIEngine::Screen::filterActions	(	PlayerAction	action,
		int	deviceID,
		const unsigned int	value,
		Input::InputType	type,
		int	playerId
	)

inlinevirtual

Override this if you need to be notified of player actions in subclasses.

Reimplemented in BaseUserScreen, RaceResultGUI, and SoccerSetupScreen.

◆ filterInput()

virtual void GUIEngine::Screen::filterInput	(	Input::InputType	type,
		int	deviceID,
		int	btnID,
		int	axisDir,
		int	value
	)

inlinevirtual

Override this if you need to be notified of raw input in subclasses.

Reimplemented in OptionsScreenInput.

◆ getHeight()

virtual int GUIEngine::Screen::getHeight ( )

inlinevirtual

Implements GUIEngine::AbstractTopLevelContainer.

◆ getInGameMenuMusic()

virtual MusicInformation * GUIEngine::Screen::getInGameMenuMusic ( ) const

inlinevirtual

Returns: which music to play at this screen, if accessed in "in-game-menu" mode

Reimplemented in FeatureUnlockedCutScene, GrandPrixLose, and GrandPrixWin.

◆ getMusic()

virtual MusicInformation * GUIEngine::Screen::getMusic ( ) const

inlinevirtual

Returns: which music to play at this screen

Reimplemented in CreditsScreen.

◆ getName()

const std::string & GUIEngine::Screen::getName ( ) const

inline

Returns: the name of this menu (which is the name of the file)

◆ getWidth()

virtual int GUIEngine::Screen::getWidth ( )

inlinevirtual

Implements GUIEngine::AbstractTopLevelContainer.

◆ init()

void Screen::init ( )

virtual

Callback invoked when entering this menu (after the widgets have been added).

Initialisation before the object is displayed.

Note: The same instance of your object may be entered/left more than once, so make sure that one instance of your object can be used several times if the same screen is visited several times.

If necessary this function will pause the race if it is running (i.e. world exists). While only some of the screen can be shown during the race (via the in-game menu you can get the options screen and the help screens only). This is used by the RaceResultGUI to leave the race running (for the end animation) while the results are being shown.

Reimplemented in OptionsScreenInput, AddonsScreen, ArenasScreen, CreditsScreen, CutSceneGeneral, EasterEggScreen, EditGPScreen, EditTrackScreen, FeatureUnlockedCutScene, GhostReplaySelection, GPInfoScreen, GrandPrixEditorScreen, GrandPrixLose, GrandPrixWin, HelpScreen1, HelpScreen2, HelpScreen3, HelpScreen4, HelpScreen5, HelpScreen6, HelpScreen7, HighScoreSelection, KartSelectionScreen, MainMenuScreen, CreateServerScreen, NetworkKartSelectionScreen, NetworkingLobby, OnlineLanScreen, BaseOnlineProfileAchievements, OnlineProfileBase, OnlineProfileFriends, OnlineProfileServers, OnlineProfileSettings, OnlineScreen, OnlineUserSearch, RegisterScreen, ServerSelection, TracksScreen, OptionsScreenAudio, OptionsScreenDevice, OptionsScreenGeneral, OptionsScreenLanguage, OptionsScreenUI, OptionsScreenVideo, BaseUserScreen, TabbedUserScreen, RaceResultGUI, RaceSetupScreen, SoccerSetupScreen, TrackInfoScreen, and TracksAndGPScreen.

◆ isLoaded()

bool GUIEngine::Screen::isLoaded ( ) const

inline

Returns: whether this screen is currently loaded

◆ loadedFromFile()

virtual void GUIEngine::Screen::loadedFromFile ( )

pure virtual

Callback invoked when loading this menu.

Precondition: Children widgets of this menu have been created by the time this callback is invoked.

Note: This method is not called everytime the screen is shown. Screen::init is. Use this method for persistent setup code (namely, that deals with setting up children widget objects and needs not be done everytime we visit the screen).; A Screen object instance may be unloaded then loaded back. This method might thus be called more than once in the lifetime of a Screen object, however there will always be an 'unload' event in-between calls to this method.

Implemented in OptionsScreenInput, AddonsScreen, ArenasScreen, CreditsScreen, CutSceneGeneral, EasterEggScreen, EditGPScreen, EditTrackScreen, FeatureUnlockedCutScene, GhostReplaySelection, GPInfoScreen, GrandPrixEditorScreen, GrandPrixLose, GrandPrixWin, HelpScreen1, HelpScreen2, HelpScreen3, HelpScreen4, HelpScreen5, HelpScreen6, HelpScreen7, HighScoreSelection, KartSelectionScreen, MainMenuScreen, CreateServerScreen, NetworkingLobby, OnlineLanScreen, BaseOnlineProfileAchievements, OnlineProfileBase, OnlineProfileFriends, OnlineProfileServers, OnlineProfileSettings, OnlineScreen, OnlineUserSearch, RegisterScreen, ServerSelection, TracksScreen, OptionsScreenAudio, OptionsScreenDevice, OptionsScreenGeneral, OptionsScreenLanguage, OptionsScreenUI, OptionsScreenVideo, BaseUserScreen, RaceResultGUI, RaceSetupScreen, SoccerSetupScreen, TrackInfoScreen, and TracksAndGPScreen.

◆ onDialogClose()

virtual void GUIEngine::Screen::onDialogClose ( )

inlinevirtual

Callback that gets called when a dialog is closed.

Can be used to set focus for instance.

Reimplemented in RegisterScreen.

◆ onDisabledItemClicked()

virtual void GUIEngine::Screen::onDisabledItemClicked ( const std::string & item )

inlinevirtual

Callback you can use if you want to know when the user pressed on a disabled ribbon item.

(the main use I see for this is to give feedback)

Reimplemented in MainMenuScreen.

◆ onDraw()

virtual void GUIEngine::Screen::onDraw ( float dt )

inlinevirtual

optional callback you can override to be notified at every frame.

Reimplemented in CreditsScreen, and RaceResultGUI.

◆ onEscapePressed()

virtual bool GUIEngine::Screen::onEscapePressed ( )

inlinevirtual

Called when escape is pressed.

Returns: true if the screen should be closed, false if you handled the press another way

Reimplemented in CutSceneGeneral, EditGPScreen, FeatureUnlockedCutScene, GhostReplaySelection, GrandPrixCutscene, KartSelectionScreen, MainMenuScreen, NetworkKartSelectionScreen, NetworkingLobby, OnlineLanScreen, OnlineProfileBase, OnlineProfileServers, OnlineScreen, RegisterScreen, TracksScreen, OptionsScreenDevice, OptionsScreenVideo, RaceResultGUI, and SoccerSetupScreen.

◆ onFocusChanged()

virtual void GUIEngine::Screen::onFocusChanged	(	Widget *	previous,
		Widget *	focus,
		int	playerID
	)

inlinevirtual

Callback called when focus changes.

Reimplemented in RegisterScreen.

◆ onUpdate()

virtual void GUIEngine::Screen::onUpdate ( float dt )

inlinevirtual

optional callback you can override to be notified at every frame.

Reimplemented in MainMenuScreen, CreateServerScreen, NetworkingLobby, BaseOnlineProfileAchievements, OnlineProfileFriends, OnlineScreen, OptionsScreenUI, SoccerSetupScreen, OptionsScreenInput, AddonsScreen, CutSceneGeneral, FeatureUnlockedCutScene, GPInfoScreen, GrandPrixLose, GrandPrixWin, KartSelectionScreen, NetworkKartSelectionScreen, OnlineUserSearch, RegisterScreen, ServerSelection, TracksScreen, BaseUserScreen, and RaceResultGUI.

◆ setNeeds3D()

void GUIEngine::Screen::setNeeds3D ( bool needs3D )

inline

Invoke this method for screens that use a 3D scene as background.

(if this method is not invoked with 'true' as parameter, the menu background will be rendered instead).

Note: To create the 3D background, use the facilities provided by the irrLicht scene manager, this class will not set up any 3D scene.

◆ tearDown()

void Screen::tearDown ( )

virtual

Callback invoked before leaving this menu.

Prepares removal of this screen.

Note: The same instance of your object may be entered/left more than once, so make sure that one instance of your object can be used several times if the same screen is visited several times.

If necessary this will unpause the race (so this means that if you have several consecutive screens while the race is running the race will be unpaused and paused when switching from one screen to the next.

Reimplemented in AddonsScreen, CutSceneGeneral, FeatureUnlockedCutScene, GhostReplaySelection, GrandPrixCutscene, HighScoreSelection, KartSelectionScreen, MainMenuScreen, CreateServerScreen, NetworkingLobby, OnlineUserSearch, ServerSelection, TracksScreen, OptionsScreenAudio, OptionsScreenGeneral, OptionsScreenLanguage, OptionsScreenUI, OptionsScreenVideo, BaseUserScreen, RaceResultGUI, SoccerSetupScreen, and TrackInfoScreen.

◆ unload()

void Screen::unload ( )

virtual

Next time this menu needs to be shown, don't use cached values, re-calculate everything.

(useful e.g. on reschange, when sizes have changed and must be re-calculated)

Reimplemented in RaceResultGUI.

◆ unloaded()

virtual void GUIEngine::Screen::unloaded ( )

inlinevirtual

Callback invoked when this screen is being unloaded.

Override this method in children classes if you need to be notified of this.

Note: A Screen object instance may be unloaded then loaded back at will.; An unloaded Screen object does not have its children widgets anymore, it only retains its members (most importantly the path to its GUI file) so that it can be loaded back later.

Reimplemented in OptionsScreenInput, AddonsScreen, GhostReplaySelection, GPInfoScreen, HighScoreSelection, KartSelectionScreen, NetworkingLobby, ServerSelection, TracksScreen, OptionsScreenAudio, OptionsScreenDevice, OptionsScreenGeneral, OptionsScreenLanguage, OptionsScreenUI, OptionsScreenVideo, BaseUserScreen, and TrackInfoScreen.

Member Data Documentation

◆ m_pause_race

bool GUIEngine::Screen::m_pause_race

private

True if the race (if it is running) should be paused when this screen is shown.

The RaceResultGUI uses this to leave the race running while it is being shown.

The documentation for this class was generated from the following files:

guiengine/screen.hpp
guiengine/screen.cpp
guiengine/screen_loader.cpp

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Screen()

Member Function Documentation

◆ beforeAddingWidget()

◆ calculateLayout()

◆ eventCallback()

◆ filterActions()

◆ filterInput()

◆ getHeight()

◆ getInGameMenuMusic()

◆ getMusic()

◆ getName()

◆ getWidth()

◆ init()

◆ isLoaded()

◆ loadedFromFile()

◆ onDialogClose()

◆ onDisabledItemClicked()

◆ onDraw()

◆ onEscapePressed()

◆ onFocusChanged()

◆ onUpdate()

◆ setNeeds3D()

◆ tearDown()

◆ unload()

◆ unloaded()

Member Data Documentation

◆ m_pause_race