ezEngine  Milestone 7
ezCVar Class Referenceabstract

CVars are global variables that are used for configuring the engine. More...

#include <CVar.h>

Inheritance diagram for ezCVar:

Classes

struct  CVarEvent
 The data that is broadcast whenever a cvar is changed. More...
 

Public Member Functions

virtual void SetToRestartValue ()=0
 Copies the 'Restart' value into the 'Current' value. More...
 
const char * GetName () const
 Returns the (display) name of the CVar.
 
virtual ezCVarType::Enum GetType () const =0
 Returns the type of the CVar.
 
const char * GetDescription () const
 Returns the description of the CVar.
 
ezBitflags< ezCVarFlagsGetFlags () const
 Returns all the CVar flags.
 
const char * GetPluginName () const
 Returns the name of the plugin which this CVar is declared in.
 

Static Public Member Functions

static void SetStorageFolder (const char *szFolder)
 Sets the path (folder) in which all CVar setting files should be stored. More...
 
static ezCVarFindCVarByName (const char *szName)
 Searches all CVars for one with the given name. Returns nullptr if no CVar could be found. The name is case-sensitive.
 
static void SaveCVars ()
 Stores all CVar values in files in the storage folder, that must have been set via 'SetStorageFolder'. More...
 
static void LoadCVars (bool bOnlyNewOnes=true, bool bSetAsCurrentValue=true)
 Loads the CVars from the settings files in the storage folder. More...
 

Public Attributes

ezEvent< const CVarEvent & > m_CVarEvents
 Code that needs to be execute whenever a cvar is changed can register itself here to be notified of such events.
 

Static Public Attributes

static ezEvent< const CVarEvent & > s_AllCVarEvents
 Broadcasts changes to ANY CVar. Thus code that needs to update when any one of them changes can use this to be notified.
 

Protected Member Functions

 ezCVar (const char *szName, ezBitflags< ezCVarFlags > Flags, const char *szDescription)
 
void RegisterCVarTelemetryChangeCB ()
 

Static Protected Member Functions

static void TelemetryMessage (void *pPassThrough)
 

Private Member Functions

 EZ_DECLARE_ENUMERABLE_CLASS (ezCVar)
 
 EZ_MAKE_SUBSYSTEM_STARTUP_FRIEND (Foundation, CVars)
 

Static Private Member Functions

static void AssignSubSystemPlugin (const char *szPluginName)
 
static void PluginEventHandler (const ezPlugin::PluginEvent &EventData)
 

Private Attributes

bool m_bHasNeverBeenLoaded
 
const char * m_szName
 
const char * m_szDescription
 
const char * m_szPluginName
 
ezBitflags< ezCVarFlagsm_Flags
 

Static Private Attributes

static ezString s_StorageFolder
 

Additional Inherited Members

- Protected Attributes inherited from ezEnumerable< ezCVar >
ezEnumerablem_pNextInstance
 

Detailed Description

CVars are global variables that are used for configuring the engine.

The state of a CVar can be automatically stored when the application is shut down, and during reloading of plugins. It will be restored again when the application starts again. This makes it possible to use them to tweak code that is work in progress or to change global settings. CVars are enumerable, which is why it is easy to present them in a console or a GUI at runtime, to allow modifying them while the application is running. It is very easy and convenient to temporarily add a CVar while some code is in development, to be able to try out different approaches. However, one should throw out all unnecessary variables after such work is finished. CVars are stored in one settings file per plugin. That means plugins can easily contain additional CVars for their own use and their states are restored at plugin loading time, as well. For the storage of CVars to work, the 'StorageFolder' must have been set. Also at startup the application should explicitly load CVars via 'LoadCVars', once the filesystem is set up and the storage folder is configured. The CVar system listens to events from the Plugin system, and it will automatically take care to serialize and deserialize CVar values whenever plugins are loaded or unloaded. CVars additionally allow to only change their visible value after a certain subsystem has been 'restarted', i.e. a user can change the CVar value at runtime, but when the 'current' value is read, it will not have changed. It will change however, once the application is restarted (such that code can initialize the engine with the correct values) or after the corresponding subsystem explicitly sets the CVar to the updated value. This is useful, e.g. for a screen resolution CVar, as changing this at runtime might be possible in a GUI, but the engine might not support that without a restart. Finally all CVars broadcast events when their value is changed, which can be used to listen to certain CVars and react properly when their value changes.

Member Function Documentation

void ezCVar::LoadCVars ( bool  bOnlyNewOnes = true,
bool  bSetAsCurrentValue = true 
)
static

Loads the CVars from the settings files in the storage folder.

This function has no effect, if the storage folder has not been set via 'SetStorageFolder' yet or it has been set to be empty. If bOnlyNewOnes is set, only CVars that have been never been loaded from file before are loaded. All other CVars will stay unchanged. If bSetAsCurrentValue is true, variables that are flagged as 'RequiresRestart', will be set to the restart value immediately ('SetToRestartValue' is called on them). Otherwise their 'Current' value will always stay unchanged and the value from disk will only be stored in the 'Restart' value. Independent on the parameter settings, all CVar changes during loading will always trigger change events.

void ezCVar::SaveCVars ( )
static

Stores all CVar values in files in the storage folder, that must have been set via 'SetStorageFolder'.

This function has no effect, if 'SetStorageFolder' has not been called, or the folder has been set to be empty. This function is also automatically called whenever plugin changes occur, or when the engine is shut down. So it might not be necessary to call this function manually at shutdown.

void ezCVar::SetStorageFolder ( const char *  szFolder)
static

Sets the path (folder) in which all CVar setting files should be stored.

The path is used by SaveCVars and LoadCVars. However those functions will create one settings file per plugin, so szFolder must not be a file name, but only a path to a folder.

After setting the storage folder, one should immediately load all CVars via LoadCVars.

virtual void ezCVar::SetToRestartValue ( )
pure virtual

Copies the 'Restart' value into the 'Current' value.

This change will not trigger a 'restart value changed' event, but it might trigger a 'current value changed' event. Code that uses a CVar that is flagged as 'RequiresRestart' for its initialization (and which is the reason, that that CVar is flagged as such) should always call this BEFORE it uses the CVar value.

Implemented in ezTypedCVar< Type, CVarType >.


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