Unigine::Console Class
| Header: | #include <UnigineConsole.h> |
Controls console-related parameters.
Adding Console Command with Several Arguments#
The Console class can be used to create custom user console commands with a different number of arguments. This section provides an example of how to create a custom console command with several arguments.
Prior Knowledge
It is supposed that you have already created an empty C++ project by using UNIGINE SDK Browser.
In the example below, we perform the following actions:
- Define and implement AppWorldLogic instance methods for console commands.
- Get the console instance (which has a singleton implementation) and add a new command.
1. Adding Instance Methods
In this example, we define three methods in the AppWorldLogic.h header file: one as a callback for a console command and another two methods for actions depending on the number of arguments:
Source code (C++)
// AppWorldLogic.h
/* ... */
class AppWorldLogic : public Unigine::WorldLogic {
public:
AppWorldLogic();
/* ... */
private:
// choose the method
void choose_command(int argc, char **argv);
// perform an action if there are no arguments
void action_no_args();
// perform another action if an argument was passed
void action_one_arg(const char *s);
};
/* ... */- choose_command() selects the appropriate method.
- action_no_args() is called if there are no console arguments.
- action_one_arg() is called if an argument was passed.
In the AppWorldLogic.cpp file implement recently defined methods:
Source code (C++)
// AppWorldLogic.cpp
// check the number of arguments and call the corresponding method
void AppWorldLogic::choose_command(int argc, char **argv) {
for (int i = 0; i < argc; i++) {
Unigine::Log::message("arg[%d]: %s\n", i, argv[i]);
}
// note: the first element of argv is the name of console command
if (argc == 1) {
action_no_args();
}
else if (argc == 2) {
action_one_arg(argv[1]);
}
// for more arguments:
//else if (...) {
// // etc
//}
}
// write the message into console, if there are no arguments
void AppWorldLogic::action_no_args() {
Unigine::Log::message("first action! no arguments!\n");
}
// write the message into console, if an argument was passed
void AppWorldLogic::action_one_arg(const char *s) {
Unigine::Log::message("second action! the argument is:%s \n", s);
}Arguments argc and argv are used to get the arguments count and arguments vector.
Notice
The first element of argv always keeps the name of a console command. Thus, argc is always >= 1. To get the first passed argument, you should use argv[1].
2. Adding Custom Console Command
Add custom command to the AppWorldLogic.cpp file by using addCommand() function. By adding this code into AppWorldLogic::init() function, the engine adds a new console command on AppWorldLogic class instance initialization.
Source code (C++)
// AppWorldLogic.cpp
#include "UnigineConsole.h"
#include "UnigineCallback.h"
/* ... */
int AppWorldLogic::init() {
// get the existing singleton Console instance and add a command
Unigine::Console::get()->addCommand(
"console_action",
"Performs custom console action",
Unigine::MakeCallback(this, &AppWorldLogic::choose_command)
);
return 1;
}
/* ... */3. Running Sample
After building the project, run it and open the console. Write recently created command to see the result:
Output
#if you write "console_action"
arg[0]: console_action
first action! no arguments!
#if you write "console_action arg"
arg[0]: console action
arg[1]: arg
second action! the argument is:argTo remove the added console command, use removeCommand() method.
See Also#
- C++ API sample located in the folder <UnigineSDK>/source/samples/Api/Systems/Console
- C# API sample located in the folder <UnigineSDK>/source/csharp/samples/Api/Systems/Console
Console Class
Members
Console * get( )
Returns a pointer to the existing Console instance.Return value
A pointer to the Console instance.void setActivity( int activity )
Opens or closes the console. By default the console is closed.Arguments
- int activity - 1 to make the console active (opened); otherwise, 0.
int getActivity( )
Returns a value indicating if the console is opened or closed.Return value
Returns 1 if the console is active (opened); otherwise, 0.void setBackgroundColor( const Math::vec4 & color )
Sets a background color for the console.Arguments
- const Math::vec4 & color - Four-component vector specifying the color in the RGBA format.
int isCommand( const char * name )
Returns a value indicating if a command with a given name exists.Arguments
- const char * name - The command name.
Return value
Returns 1 if the command with a given name exists; otherwise, 0.const char * getCommandDescription( const char * name )
Returns the description of the console command by its name. If the name isn't specified, an empty string will be returned.Arguments
- const char * name - The command name.
Return value
The command description if it exists; otherwise, an empty string.const char * getCommandName( int num )
Returns the name of the console command by its number in the array of the existing commands.Arguments
- int num - The command number.
Return value
The command name if it is found in the array of the existing commands; otherwise, an empty string.void setErrorColor( const Math::vec4 & color )
Sets a color for error messages in the console.Arguments
- const Math::vec4 & color - Four-component vector specifying the color in the RGBA format.
void setFloat( const char * name, float value )
Sets a float value for a given variable.Arguments
- const char * name - The variable name.
- float value - Float value of the variable.
float getFloat( const char * name )
Returns a float value of a given variable.Arguments
- const char * name - The variable name.
Return value
Float value of the variable.float getFloatMax( const char * name )
Returns a maximum float value for a given variable.Arguments
- const char * name - Variable name.
Return value
Maximum float value of the variable.float getFloatMin( const char * name )
Returns a minimum float value for a given variable.Arguments
- const char * name - Variable name.
Return value
Minimum float value of the variable.int isFloat( const char * name )
Checks if the value set for the given console variable is of the float type.Arguments
- const char * name - The variable name.
Return value
1 if the variable value is float; otherwise, 0.void setInt( const char * name, int value )
Sets an integer value for a given variable.Arguments
- const char * name - Name of the variable.
- int value - Integer value of the variable.
int getInt( const char * name )
Returns an integer value of a given variable.Arguments
- const char * name - Name of the variable.
Return value
Integer value of the variable.int getIntMax( const char * name )
Returns a maximum integer value for a given variable.Arguments
- const char * name - Variable name.
Return value
Maximum integer value of the variable.int getIntMin( const char * name )
Returns a minimum integer value for a given variable.Arguments
- const char * name - Variable name.
Return value
Minimum integer value of the variable.int isInt( const char * name )
Checks if the value of the given console variable is of the integer type.Arguments
- const char * name - The variable name.
Return value
1 if the variable value is int; otherwise, 0.void setLock( int lock )
Disables or enables the console. By default the console is enabled.Arguments
- int lock - Positive integer to disable the console; otherwise, 0.
int getLock( )
Checks if the console is disabled.Return value
1 if the console is disabled; otherwise, 0.void setMessageColor( const Math::vec4 & color )
Sets a color for ordinary messages in the console.Arguments
- const Math::vec4 & color - Four-component vector specifying the color in the RGBA format.
int getNumCommands( )
Returns the number of all available console commands, including the custom ones.Return value
The number of available console commands.int getNumVariables( )
Returns the number of all available console variables.Return value
The number of available console variables.void * addOutputCallback( Unigine::CallbackBase2 <const char *, int> * func )
Adds a callback function that will be executed when a text is output to the console. The function is useful when you implement a custom console, for example. The callback function must receive 2 arguments:- const char *text - a text that is output to the console,
- int level - one of the LEVEL_* variables that indicate the type of the output text. The value can be important for setting a color for console messages, for example.
Source code (C++)
// the callback function
void AppWorldLogic::output_callback(const char *text, int level)
{
switch (level):
case Console::LEVEL_NORMAL:
// logic for ordinary messages
case Console::LEVEL_WARNING:
// logic for warnings
case Console::LEVEL_ERROR:
// logic for error messages
}
int AppWorldLogic::init()
{
// set the callback
Console::get()->addOutputCallback(MakeCallback(this,&AppWorldLogic::output_callback));
return 1;
}Arguments
- Unigine::CallbackBase2 <const char *, int> * func - The callback pointer. The callback arguments must be: (const char *text, int level).
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool removeOutputCallback( void * id )
Removes the specified callback from the list of output callbacks.Arguments
- void * id - Callback ID obtained when adding it.
Return value
True if the callback with the given ID was removed successfully; otherwise false.void clearOutputCallbacks( )
Clears all added output callbacks.void setPrompt( const char * str )
Updates the console prompt. The default prompt is Unigine~#.Arguments
- const char * str - New console prompt.
void setString( const char * name, const char * value )
Sets a string value for a given variable.Arguments
- const char * name - The variable name.
- const char * value - String value of the variable.
const char * getString( const char * name )
Returns the string value of a given variable.Arguments
- const char * name - The variable name.
Return value
String value of the variable.int isString( const char * name )
Checks if the value of the given console variable is of the string type.Arguments
- const char * name - The variable name.
Return value
1 if the variable value is string; otherwise, 0.void setTextColor( const Math::vec4 & color )
Sets a common font color for the console.Arguments
- const Math::vec4 & color - Four-component vector specifying the color in the RGBA format.
int isVariable( const char * name )
Returns a value indicating if a variable with a given name exists.Arguments
- const char * name - The variable name.
Return value
1 if the variable exists; otherwise, 0.const char * getVariableDescription( const char * name )
Returns the description of the console variable by its name. If the name isn't specified, an empty string will be returned.Arguments
- const char * name - The variable name.
Return value
The variable description if it exists; otherwise, an empty string.const char * getVariableName( int num )
Returns the name of the console variable by its number in the array of the existing variables.Arguments
- int num - The variable number.
Return value
The variable name if it is found in the array of the existing variables; otherwise, an empty string.void setVec2( const char * name, const Math::vec2 & value )
Sets a two component vector for the console variable.Arguments
- const char * name - Name of the variable.
- const Math::vec2 & value - Value of the variable.
Math::vec2 getVec2( const char * name )
Returns the two component vector console variable.Arguments
- const char * name - Name of the variable.
Return value
Value of the variable.int isVec2( const char * name )
Returns a value indicating if the console variable is a two component vector.Arguments
- const char * name - Name of the variable.
Return value
1 if the variable is a two component vector; otherwise, 0.void setVec3( const char * name, const Math::vec3 & value )
Sets a three component vector for the console variable.Arguments
- const char * name - Name of the variable.
- const Math::vec3 & value - Value of the variable.
Math::vec3 getVec3( const char * name )
Returns the three component vector console variable.Arguments
- const char * name - Name of the variable.
Return value
Value of the variable.int isVec3( const char * name )
Returns a value indicating if the console variable is a three component vector.Arguments
- const char * name - Name of the variable.
Return value
1 if the variable is a three component vector; otherwise, 0.void setVec4( const char * name, const Math::vec4 & value )
Sets a four component vector for the console variable.Arguments
- const char * name - Name of the variable.
- const Math::vec4 & value - Value of the variable.
Math::vec4 getVec4( const char * name )
Returns the four component vector console variable.Arguments
- const char * name - Name of the variable.
Return value
Value of the variable.int isVec4( const char * name )
Returns a value indicating if the console variable is a four component vector.Arguments
- const char * name
Return value
1 if the variable is a three component vector; otherwise, 0.void setWarningColor( const Math::vec4 & color )
Sets a color for warning messages in the console.Arguments
- const Math::vec4 & color - Four-component vector specifying the color in the RGBA format.
int addCommand( const char * name, const char * desc, Unigine::CallbackBase2 <int, const char *> * callback )
Adds a custom console command bound to a given callback function.Arguments
- const char * name - Name of the new console command.
- const char * desc - Short description to be displayed in the console.
- Unigine::CallbackBase2 <int, const char *> * callback - The callback pointer. The callback arguments must be (int argc, char** argv,...).
Return value
1 if the custom command is added successfully; otherwise, 0.void flush( )
Forces to execute all queued console commands.int removeCommand( const char * name )
Removes a custom console command.Arguments
- const char * name - Name of the custom console command.
Return value
1 if the custom command has been removed successfully; otherwise, 0.void run( const char * command )
Runs the specified console command.Arguments
- const char * command - A console command with arguments.
Last update:
2020-01-14
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)