A Quake-style console for in-game configuration of ezCVar and ezConsoleFunction. More...

#include <Console.h>

Classes
struct	ConsoleEvent
	The event data that is broadcast by the console. More...

struct	ConsoleString
	The data for one text entry in the console window. More...

Public Types
typedef ezDelegate< ezResult(const char , ezConsole )>	ezCommandProcessor
	The delegate type for an interpreter of all the commands that are typed into the console.

Public Member Functions
Configuration
void	SetMaxConsoleStrings (ezUInt32 uiMax)
	Adjusts how many strings the console will keep in memory at maximum.

ezUInt32	GetMaxConsoleStrings () const
	Returns how many strings the console will keep in memory at maximum.

virtual void	EnableLogOutput (bool bEnable)
	Enables or disables that the output from ezGlobalLog is displayed in the console. Enabled by default.

virtual void	SaveState (ezStreamWriter &Stream) const
	Writes the state of the console (history, bound keys) to the stream.

virtual void	LoadState (ezStreamReader &Stream)
	Reads the state of the console (history, bound keys) from the stream.

Command Processing
void	SetCommandInterpreter (ezCommandProcessor processor)
	Replaces the current command interpreter. This allows to attach a custom interpreter to the console. More...

void	ProcessCommand (const char *szCmd)
	Executes the given command using the current command interpreter. More...

void	BindKey (const char szKey, const char szCommand)
	Binds szCommand to szKey. Calling ExecuteBoundKey() with this key will then run that command. More...

void	UnbindKey (const char *szKey)
	Removes the key binding.

void	ExecuteBoundKey (const char *szKey)
	Executes the command that was bound to this key.

Input Handling
void	AddInputCharacter (ezUInt32 uiChar)
	Inserts one character at the caret position into the console input line. More...

void	ClearInputLine ()
	Clears the input line of the console.

const char *	GetInputLine () const
	Returns the current content of the input line.

ezInt32	GetCaretPosition () const
	Returns the position (in characters) of the caret.

void	MoveCaret (ezInt32 iMoveOffset)
	Moves the caret in the text. Its position will be clamped to the length of the current input line text.

void	DeleteNextCharacter ()
	Deletes the character following the caret position.

void	Scroll (ezInt32 iLines)
	Scrolls the contents of the console up or down. Will be clamped to the available range.

ezUInt32	GetScrollPosition () const
	Returns the current scroll position. This must be used during rendering to start with the proper line.

virtual void	AutoCompleteInputLine ()
	Tries to auto-complete the current input line. More...

virtual void	DoDefaultInputHandling (bool bConsoleOpen)
	This function implements input handling (via ezInputManager) for the console. More...

Console Content
void	AddConsoleString (const char *szText, const ezColor &color=ezColor(1, 1, 1), bool bShowOnScreen=false)
	Adds a string to the console. More...

const ezDeque< ConsoleString > &	GetConsoleStrings () const
	Returns all current console strings. Use GetScrollPosition() to know which one should be displayed as the first one.

void	ClearConsoleStrings ()
	Deletes all console strings, making the console empty.

const ezStaticArray< ezString, 16 > &	GetInputHistory () const
	Returns the current input history.

void	SearchInputHistory (ezInt32 iHistoryUp)
	Replaces the input line by the next (or previous) history item.

Public Attributes
Events
ezEvent< ConsoleEvent & >	m_Events
	The console event variable, to attach to.

Protected Member Functions
void	RemoveCharacter (ezUInt32 uiInputLinePosition)
	Deletes the character at the given position in the input line.

void	ClampCaretPosition ()
	Makes sure the caret position is clamped to the input line length.

void	AddToInputHistory (const char *szString)
	Adds an item to the input history.

void	LogHandler (const ezLoggingEventData &data)
	The function that is used to read ezGlobalLog messages.

Static Protected Member Functions
static void	FindPossibleCVars (const char *szVariable, ezDeque< ezString > &CommonStrings, ezDeque< ConsoleString > &ConsoleStrings)
	Iterates over all cvars and finds all that start with the string szVariable.

static void	FindPossibleFunctions (const char *szVariable, ezDeque< ezString > &CommonStrings, ezDeque< ConsoleString > &ConsoleStrings)
	Iterates over all console functions and finds all that start with the string szVariable.

static const ezString	FindCommonString (const ezDeque< ezString > &vStrings)
	Returns the prefix string that is common to all strings in the vStrings array.

Protected Attributes
ezInt32	m_iCaretPosition

ezStringBuilder	m_sInputLine

Helpers
ezMutex &	GetMutex () const
	Returns the internal mutex to prevent multi-threaded access.

static ezString	GetFullInfoAsString (ezCVar *pCVar)
	Returns a nice string containing all the important information about the cvar.

static const ezString	GetValueAsString (ezCVar *pCVar)
	Returns the value of the cvar as a string.

Detailed Description

A Quake-style console for in-game configuration of ezCVar and ezConsoleFunction.

The console displays the recent log activity and allows to modify cvars and call console functions. It supports auto-completion of known keywords. Additionally, 'keys' can be bound to arbitrary commands, such that useful commands can be executed easily. The default implementation uses ezConsoleInterpreter::Lua as the interpreter for commands typed into it. The interpreter can be replaced with custom implementations.

Member Function Documentation

◆ AddConsoleString()

void ezConsole::AddConsoleString	(	const char *	szText,
		const ezColor &	color = `ezColor(1, 1, 1)`,
		bool	bShowOnScreen = `false`
	)

Adds a string to the console.

bShowOnScreen is a hint for the renderer to also display this string on screen, even if the console is not visible.

◆ AddInputCharacter()

void ezConsole::AddInputCharacter ( ezUInt32 uiChar )

Inserts one character at the caret position into the console input line.

This function also calls ProcessInputCharacter and FilterInputCharacter. By default this already reacts on Tab, Enter and ESC and filters out all non ASCII characters.

◆ AutoCompleteInputLine()

void ezConsole::AutoCompleteInputLine ( )

virtual

Tries to auto-complete the current input line.

This will trigger ConsoleEvent::AutoCompleteRequest, which allows external code to suggest auto-complete options for the current word. The console will always use all CVars for auto-completion already.

◆ BindKey()

void ezConsole::BindKey	(	const char *	szKey,
		const char *	szCommand
	)

Binds szCommand to szKey. Calling ExecuteBoundKey() with this key will then run that command.

A key can be any arbitrary string. However, it might make sense to either use the standard ASCII characters A-Z and a-z, which allows to trigger actions by the press of any of those buttons. You can, however, also use names for input buttons, such as 'Key_Left', but then you also need to call ExecuteBoundKey() with those names. If you use such virtual key names, it makes also sense to listen to the auto-complete event and suggest those key names there.

◆ DoDefaultInputHandling()

void ezConsole::DoDefaultInputHandling ( bool bConsoleOpen )

virtual

This function implements input handling (via ezInputManager) for the console.

If the console is 'open' (ie. has full focus), it will handle more input for caret movement etc. However, in the 'closed' state, it will still execute bound keys and commands from the history. It is not required to call this function, you can implement input handling entirely outside the console.

If this function is used, it should be called once per frame and if the console is considered 'open', no further keyboard input should be processed, as that might lead to confusing behavior when the user types text into the console.

The state whether the console is considered open has to be managed by the application.

◆ ProcessCommand()

void ezConsole::ProcessCommand ( const char * szCmd )

Executes the given command using the current command interpreter.

This will also broadcast ConsoleEvent::BeforeProcessCommand and ConsoleEvent::ProcessCommandSuccess or ConsoleEvent::ProcessCommandFailure, depending on what the interpreter returned.

◆ SetCommandInterpreter()

void ezConsole::SetCommandInterpreter ( ezCommandProcessor processor )

inline

Replaces the current command interpreter. This allows to attach a custom interpreter to the console.

by default the Lua interpreter is used. Using a custom interpreter you can extend its functionality or allow for different syntax.

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

Code/Engine/GameEngine/Console/Console.h
Code/Engine/GameEngine/Console/Implementation/Autocomplete.cpp
Code/Engine/GameEngine/Console/Implementation/Commands.cpp
Code/Engine/GameEngine/Console/Implementation/Console.cpp
Code/Engine/GameEngine/Console/Implementation/Input.cpp

Classes

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Helpers