ConsoleConstructor
Engine/source/console/console.h
This is the backend for the ConsoleMethod()/ConsoleFunction() macros.
Entry Type Fields
One of these is set based on the type of entry we want inserted in the console.
console_autodoc
A function/method that returns a string.
A function/method that returns an int.
A function/method that returns a float.
A function/method that returns nothing.
A function/method that returns a bool.
bool
Indicates that this is a group marker.
bool
Indicates that this is a namespace marker.
bool
Is this a callback into script?
ConsoleConstructor Innards
The ConsoleConstructor class is used as the backend for the ConsoleFunction() and ConsoleMethod() macros.
The way it works takes advantage of several properties of C++.
The ConsoleFunction()/ConsoleMethod() macros wrap the declaration of a ConsoleConstructor.
// The definition of a ConsoleFunction using the macro ConsoleFunction(ExpandFilename, const char*, 2, 2, "(string filename)") { argc; char* ret = Con::getReturnBuffer( 1024 ); Con::expandScriptFilename(ret, 1024, argv[1]); return ret; } // Resulting code static const char* cExpandFilename(SimObject *, S32, const char **argv); static ConsoleConstructor gExpandFilenameobj(NULL,"ExpandFilename", cExpandFilename, "(string filename)", 2, 2); static const char* cExpandFilename(SimObject *, S32 argc, const char **argv) { argc; char* ret = Con::getReturnBuffer( 1024 ); Con::expandScriptFilename(ret, 1024, argv[1]); return ret; } // A similar thing happens when you do a ConsoleMethod.
As you can see, several global items are defined when you use the ConsoleFunction method. The macro constructs the name of these items from the parameters you passed it. Your implementation of the console function is is placed in a function with a name based on the actual name of the console funnction. In addition, a ConsoleConstructor is declared.
Because it is defined as a global, the constructor for the ConsoleConstructor is called before execution of main() is started. The constructor is called once for each global ConsoleConstructor variable, in the order in which they were defined (this property only holds true within file scope).
We have ConsoleConstructor create a linked list at constructor time, by storing a static pointer to the head of the list, and keeping a pointer to the next item in each instance of ConsoleConstructor. init() is a helper function in this process, automatically filling in commonly used fields and updating first and next as needed. In this way, a list of items to add to the console is assemble in memory, ready for use, before we start execution of the program proper.
In Con::init(), ConsoleConstructor::setup() is called to process this prepared list. Each item in the list is iterated over, and the appropriate Con namespace functions (usually Con::addCommand) are invoked to register the ConsoleFunctions and ConsoleMethods in the appropriate namespaces.
Basic Console Constructors
ConsoleConstructor(const char * className, const char * funcName, StringCallback sfunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
ConsoleConstructor(const char * className, const char * funcName, IntCallback ifunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
ConsoleConstructor(const char * className, const char * funcName, FloatCallback ffunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
ConsoleConstructor(const char * className, const char * funcName, VoidCallback vfunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
ConsoleConstructor(const char * className, const char * funcName, BoolCallback bfunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
Magic Console Constructors
These perform various pieces of "magic" related to consoleDoc functionality.
console_autodoc
ConsoleConstructor(const char * className, const char * groupName, const char * usage)
Indicates a group marker.
ConsoleConstructor(const char * className, const char * callbackName, const char * usage, ConsoleFunctionHeader * header)
Indicates a callback declared with the DECLARE_SCRIPT_CALLBACK macro and friends.
Public Attributes
const char *
Name of the class namespace to which to add the method.
The extended function header.
bool
Whether this is a TORQUE_TOOLS only function.
Detailed Description
This is the backend for the ConsoleMethod()/ConsoleFunction() macros.
See the group ConsoleConstructor Innards for specifics on how this works.
console_autodoc
Entry Type Fields
One of these is set based on the type of entry we want inserted in the console.
console_autodoc
StringCallback mSC
A function/method that returns a string.
IntCallback mIC
A function/method that returns an int.
FloatCallback mFC
A function/method that returns a float.
VoidCallback mVC
A function/method that returns nothing.
BoolCallback mBC
A function/method that returns a bool.
bool mGroup
Indicates that this is a group marker.
bool mNS
Indicates that this is a namespace marker.
bool mCallback
Is this a callback into script?
ConsoleConstructor Innards
The ConsoleConstructor class is used as the backend for the ConsoleFunction() and ConsoleMethod() macros.
The way it works takes advantage of several properties of C++.
The ConsoleFunction()/ConsoleMethod() macros wrap the declaration of a ConsoleConstructor.
// The definition of a ConsoleFunction using the macro ConsoleFunction(ExpandFilename, const char*, 2, 2, "(string filename)") { argc; char* ret = Con::getReturnBuffer( 1024 ); Con::expandScriptFilename(ret, 1024, argv[1]); return ret; } // Resulting code static const char* cExpandFilename(SimObject *, S32, const char **argv); static ConsoleConstructor gExpandFilenameobj(NULL,"ExpandFilename", cExpandFilename, "(string filename)", 2, 2); static const char* cExpandFilename(SimObject *, S32 argc, const char **argv) { argc; char* ret = Con::getReturnBuffer( 1024 ); Con::expandScriptFilename(ret, 1024, argv[1]); return ret; } // A similar thing happens when you do a ConsoleMethod.
As you can see, several global items are defined when you use the ConsoleFunction method. The macro constructs the name of these items from the parameters you passed it. Your implementation of the console function is is placed in a function with a name based on the actual name of the console funnction. In addition, a ConsoleConstructor is declared.
Because it is defined as a global, the constructor for the ConsoleConstructor is called before execution of main() is started. The constructor is called once for each global ConsoleConstructor variable, in the order in which they were defined (this property only holds true within file scope).
We have ConsoleConstructor create a linked list at constructor time, by storing a static pointer to the head of the list, and keeping a pointer to the next item in each instance of ConsoleConstructor. init() is a helper function in this process, automatically filling in commonly used fields and updating first and next as needed. In this way, a list of items to add to the console is assemble in memory, ready for use, before we start execution of the program proper.
In Con::init(), ConsoleConstructor::setup() is called to process this prepared list. Each item in the list is iterated over, and the appropriate Con namespace functions (usually Con::addCommand) are invoked to register the ConsoleFunctions and ConsoleMethods in the appropriate namespaces.
init(const char * cName, const char * fName, const char * usg, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
validate()
Validate there are no duplicate entries for this item.
setup()
ConsoleConstructor * mNext
ConsoleConstructor * mFirst
Basic Console Constructors
ConsoleConstructor(const char * className, const char * funcName, StringCallback sfunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
ConsoleConstructor(const char * className, const char * funcName, IntCallback ifunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
ConsoleConstructor(const char * className, const char * funcName, FloatCallback ffunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
ConsoleConstructor(const char * className, const char * funcName, VoidCallback vfunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
ConsoleConstructor(const char * className, const char * funcName, BoolCallback bfunc, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)
Magic Console Constructors
These perform various pieces of "magic" related to consoleDoc functionality.
console_autodoc
ConsoleConstructor(const char * className, const char * groupName, const char * usage)
Indicates a group marker.
(A doxygen illusion)
Con::markCommandGroup console_autodoc
ConsoleConstructor(const char * className, const char * callbackName, const char * usage, ConsoleFunctionHeader * header)
Indicates a callback declared with the DECLARE_SCRIPT_CALLBACK macro and friends.
Public Attributes
const char * mClassName
Name of the class namespace to which to add the method.
const char * mFuncName
Name of the function/method.
ConsoleFunctionHeader * mHeader
The extended function header.
S32 mMaxa
Maximum number of arguments accepted by the funtion. Zero for varargs.
S32 mMina
Minimum number of arguments expected by the function.
bool mToolOnly
Whether this is a TORQUE_TOOLS only function.
const char * mUsage
Usage string for documentation.