ezEngine  Release 25.03
Protected Member Functions | Protected Attributes | List of all members
ezQuakeConsole Class Referencefinal

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

#include <QuakeConsole.h>

Inheritance diagram for ezQuakeConsole:
Inheritance graph
[legend]

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 &inout_stream) const
 Writes the state of the console (history, bound keys) to the stream.
 
virtual void LoadState (ezStreamReader &inout_stream)
 Reads the state of the console (history, bound keys) from the stream.
 
Command Processing
virtual void ExecuteCommand (ezStringView sInput) override
 Executes the given command using the current command interpreter.
 
void BindKey (ezStringView sKey, ezStringView sCommand)
 Binds szCommand to szKey. Calling ExecuteBoundKey() with this key will then run that command. More...
 
void UnbindKey (ezStringView sKey)
 Removes the key binding.
 
void ExecuteBoundKey (ezStringView sKey)
 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.
 
ezStringView 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 DoDefaultInputHandling (bool bConsoleOpen)
 This function implements input handling (via ezInputManager) for the console. More...
 
Console Content
virtual void AddConsoleString (ezStringView sText, ezConsoleString::Type type=ezConsoleString::Type::Default) override
 Adds a string to the console.
 
const ezDeque< ezConsoleString > & 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.
 
- Public Member Functions inherited from ezConsole
const ezEvent< const ezConsoleEvent & > & Events () const
 Grants access to subscribe and unsubscribe from console events.
 
ezMutex & GetMutex () const
 Returns the mutex that's used to prevent multi-threaded access.
 
void SetCommandInterpreter (const ezSharedPtr< ezCommandInterpreter > &pInterpreter)
 Replaces the current command interpreter. More...
 
const ezSharedPtr< ezCommandInterpreter > & GetCommandInterpreter () const
 Returns the currently used command interpreter.
 
virtual bool AutoComplete (ezStringBuilder &ref_sText)
 Auto-completes the given text. More...
 
void AddToInputHistory (ezStringView sText)
 Adds an item to the input history.
 
const ezStaticArray< ezString, 16 > & GetInputHistory () const
 Returns the current input history. More...
 
void RetrieveInputHistory (ezInt32 iHistoryUp, ezStringBuilder &ref_sResult)
 Replaces the input line by the next (or previous) history item.
 
ezResult SaveInputHistory (ezStringView sFile)
 Writes the current input history to a text file.
 
void LoadInputHistory (ezStringView sFile)
 Reads the text file and appends all lines to the input history.
 

Static Public Member Functions

Helpers
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.
 
- Static Public Member Functions inherited from ezConsole
static void SetMainConsole (ezConsole *pConsole)
 
static ezConsole * GetMainConsole ()
 

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 LogHandler (const ezLoggingEventData &data)
 The function that is used to read ezGlobalLog messages.
 
virtual bool ProcessInputCharacter (ezUInt32 uiChar)
 
virtual bool FilterInputCharacter (ezUInt32 uiChar)
 
virtual void InputStringChanged ()
 

Protected Attributes

ezInt32 m_iCaretPosition
 
ezStringBuilder m_sInputLine
 
ezDeque< ezConsoleString > m_ConsoleStrings
 
bool m_bUseFilteredStrings = false
 
ezDeque< ezConsoleString > m_FilteredConsoleStrings
 
ezUInt32 m_uiMaxConsoleStrings
 
ezInt32 m_iScrollPosition
 
bool m_bLogOutputEnabled
 
bool m_bDefaultInputHandlingInitialized
 
ezMap< ezString, ezString > m_BoundKeys
 
- Protected Attributes inherited from ezConsole
ezEvent< const ezConsoleEvent & > m_Events
 The console event variable, to attach to.
 
ezMutex m_Mutex
 
ezSharedPtr< ezCommandInterpreter > m_pCommandInterpreter
 
ezInt32 m_iCurrentInputHistoryElement = -1
 
ezStaticArray< ezString, 16 > m_InputHistory
 

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

◆ AddInputCharacter()

void ezQuakeConsole::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.

◆ BindKey()

void ezQuakeConsole::BindKey ( ezStringView  sKey,
ezStringView  sCommand 
)

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 ezQuakeConsole::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.

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