= !ConsoleCommand =
[[TracNav(TracNav/TOC_Development)]]
[[TOC]]

== Description ==
A !ConsoleCommand is a function which can be called by the [wiki:Shell]. !ConsoleCommand inherits from [wiki:Executor] and adds some additional features used to [wiki:KeyBinder bind commands to keys] and to allow easy use in the Shell ([wiki:ArgumentCompleter 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 [wiki:CommandExecutor]. If you want to execute the same command over and over, see [wiki:CommandEvaluation] for more performance.

ConsoleCommands are stored in a map in the Identifier of the implementing class. Shortcuts are stored in [wiki: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 [wiki:OrxonoxClass]. For any other combination see [wiki:ConsoleCommand#AdvancedCreation the chapter below].

=== Call ===
Now you can call the function by typing the ''functionname'' into the [wiki: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 [wiki: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 [wiki: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 [wiki:ConsoleCommand#AccessLevels the chapter below])
 * '''argumentCompleter('''''param number (0-4)''''', '''''completer''''')''': Sets the [wiki:ArgumentCompleter] for a given parameter (see [wiki:ConsoleCommand#ArgumentCompletion the chapter below])

 * '''keybindMode('''''mode''''')''': When the command gets called if [wiki:KeyBinder 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 [wiki: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[[br]][[br]]
  * '''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 [wiki: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[[br]][[br]]
  * '''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 [wiki:ArgumentCompleter] and [wiki:ArgumentCompletionFunctions] for more information about how to add a new function for argument completion.

== Illustration ==
[[Image(ConsoleCommand.png)]]