ConsoleCommand

TracNav(TracNav/TOC_Development)?

Description

A ConsoleCommand is a function which can be called by the Shell?. ConsoleCommand inherits from Executor and adds some additional features used to bind commands to keys and to allow easy use in the Shell (like argument completion).

At the moment, a ConsoleCommand must call a static function. The command is of static nature too and exists for the whole time. But this will change in the future.

A ConsoleCommand can also be called directly from the code by using CommandExecutor. If you want to execute the same command over and over, see CommandEvaluation for more performance.

ConsoleCommands are stored in a map in the Identifier of the implementing class. Shortcuts are stored in CommandExecutor.

Usage

Creation

Creating a ConsoleCommand is usually really easy. Just write the following lines:

*.cc file:

#include "core/command/ConsoleCommand.h"

SetConsoleCommand(ClassName, functionname, true);

Note: The last argument (true) means: create a shortcut for this command.

*.h file:

class ClassName
{
    public:
        static returntype functionname(param1, param2, ...);
};

Important: This works only for static memberfunctions of a class inheriting from OrxonoxClass. For any other combination see the chapter below.

Call

Now you can call the function by typing the functionname into the Shell?:

> functionname arg1 arg2 ...
or
> ClassName functionname arg1 arg2 ...

Note: The first variant works only if you enable the shortcut (true in SetConsoleCommand).

It's also possible to call the command directly from the code by using CommandExecutor:

CommandExecutor::execute("functionname arg1 arg2 ...");
or
CommandExecutor::execute("ClassName functionname arg1 arg2 ...");

Attributes

There are several attributes you can set, some of them are inherited from Executor, some are new.

Inherited:

• description(description): Sets the description of the Executor (what the function does)
• descriptionParam(param number (0-4), description): Sets the description of an argument (what the argument does)
• descriptionReturnvalue(description): Sets the description of the return value (what the return value does)

• defaultValues(value1, …): Sets default values
• defaultValue(param number (0-4), value): Sets the default value for a given parameter

New:

• accessLevel(level): Sets the access level (see the chapter below)
• argumentCompleter(param number (0-4), completer): Sets the ArgumentCompleter for a given parameter (see the chapter below)

• keybindMode(mode): When the command gets called if bound to a key (OnPress, OnRelease, OnHold)
• axisParamIndex(index):
• isAxisRelative(bool):

Chained attributes

You can specify all attributes from above in one single chained call, for example:

SetConsoleCommand(ClassName, functionname, true).description("Does something nice").defaultVal
    ues(10, "test", true, 1.234).argumentCompleter(0, autocompletion::completerfunction()).isA
    xisRelative(true);

Note: The attributes can be specified in any order.

Advanced Creation

There are several different macros so create a ConsoleCommand:

• Static classfunction, class derived from OrxonoxClass
  • SetConsoleCommand(classname, function, bCreateShortcut):
    • Simple command, with or without shortcut
  • SetConsoleCommandAlias(classname, function, name, bCreateShortcut):
    • Command with a different name than the functionname, with or without shortcut
  • SetConsoleCommandAliasMulti(classname, function, name, number, bCreateShortcut):
    • Several commands with different names calling the same function, number must be different for each command, with or without shortcut
      
      
  • SetConsoleCommandGeneric(fakevariable, classname, command, bCreateShortcut):
    • Custom command, you have to create ConsoleCommand manually with new, fakevariable must be a unique name

• Static classfunction, class not derived from OrxonoxClass
  • SetConsoleCommandShortcut(classname, function):
    • Simple command, only a shortcut
  • SetConsoleCommandShortcutAlias(classname, function, name):
    • Shortcut with a different name than the functionname
  • SetConsoleCommandShortcutAliasMulti(classname, function, name, number):
    • Several shortcuts with different names calling the same function, number must be different for each command

• C-style function
  • SetConsoleCommandShortcutExtern(function):
    • Simple command, only a shortcut
  • SetConsoleCommandShortcutExternAlias(function, name):
    • Shortcut with a different name than the functionname
  • SetConsoleCommandShortcutExternAliasMulti(function, name, number):
    • Several shortcuts with different names calling the same function, number must be different for each command
      
      
  • SetConsoleCommandShortcutGeneric(fakevariable, command):
    • Custom command, you have to create ConsoleCommand manually with new, fakevariable must be a unique name

Access Levels

-to come-

Argument Completion

See ArgumentCompleter and ArgumentCompletionFunctions for more information about how to add a new function for argument completion.

Illustration