Unigine::Console Class

Header:

#include <UnigineConsole.h>

List of functions:

List of Variables:

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.

NoticeThe 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:arg

To remove the added console command, use removeCommand() method.

Console Class

Members

int addCommand(const char * name, const char * desc, const Ptr<CommandCallback> & 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.
const Ptr<CommandCallback> & 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.

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.

void flush()

Forces to execute all queued console commands.

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.

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 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, incuding 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 setOutputCallback(const Ptr<OutputCallback> & func)

Sets 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 fuction
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()->setOutputCallback(MakeCallback(this,&AppWorldLogic::output_callback));
	
	return 1;
}

Arguments

const Ptr<OutputCallback> & func - The callback pointer. The callback arguments must be (const char *text,int level).

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 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 LEVEL_ERROR

Description

An error message.

int LEVEL_NORMAL

Description

An ordinary message.

int LEVEL_WARNING

Description

A warning.

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)