ezEngine  Milestone 7
ezConsole Class Reference

A Quake-style console is 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 (ezStreamWriterBase &Stream) const
 Writes the state of the console (history, bound keys) to the stream.
 
virtual void LoadState (ezStreamReaderBase &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.
 

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.
 

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
 

Private Member Functions

virtual bool ProcessInputCharacter (ezUInt32 uiChar)
 
virtual bool FilterInputCharacter (ezUInt32 uiChar)
 

Private Attributes

ezCommandProcessor m_CommandProcessor
 
ezDeque< ConsoleStringm_ConsoleStrings
 
ezUInt32 m_uiMaxConsoleStrings
 
ezInt32 m_iScrollPosition
 
ezInt32 m_iCurrentInputHistoryElement
 
bool m_bLogOutputEnabled
 
bool m_bDefaultInputHandlingInitialized
 
ezStaticArray< ezString, 16 > m_InputHistory
 
ezMap< ezString, ezStringm_BoundKeys
 

Detailed Description

A Quake-style console is 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

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.

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.

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.

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.

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.

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.

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: