Changes between Initial Version and Version 1 of ~archive/Shell

Timestamp:

Nov 27, 2007, 10:46:06 PM (16 years ago)

Author:

landauf

Comment:

—

~archive/Shell

@@ +1 @@
+= SHELL =
+The Shell is an extension to [source:/trunk/src/defs/debug.h debug.h], that allows
+the output to be redirected to an opengl shell ontop of an application (orxonox). It is bidirectional to enable the user to
+send commands to the application.
+
+== Structure ==
+
+http://www.orxonox.net/additionals/Shell.png
+
+ * __Application__:
+   * The Shell is communicating with the application (namely orxonox) through debug.h. E.g. all output can be redirected to the Shell's Buffer.
+   * Commands can be executed, and the result is sent back to the application via Shell's Commands.
+ * __Shell Input__:
+   * Gets input from the user keyboard.
+   * Command completion: on <TAB> the shell tries to complete either Classes, Objects or Commands
+   * The input is structured as follows:
+     * <Class> [Object] <functionCall> [argument1,[argument2,... ]] [[br]]
+      -- <> MUST BE [[br]]
+      -- [] optional, depending on the circumstances [[br]]
+      -- [Object] must be defined, if there exist more than one instance of a certain Class.
+ * __Display__:
+   * Renders the Text to the screen (with a nice little background). This is not a Class itself, it is inside the Shell/Shell's Input.
+ * __Shell Command__:
+   * An entered Shell Command will be checked for integrity, quality attributes:
+     1. Does an instance of the class exist?
+     2. More than one -> object required!
+     3. Does the function Exist
+     4. Are any parameters supplied?
+     5. Execute command
+
+
+== Usage ==
+Create a new Command: nothing easier than this, here an example:
+Use the makro function SHELL_COMMENAD(argumen1, argument2, argument3)->describe(argument4);
+{{{
+#!cpp
+SHELL_COMMAND(clear, Shell, clearShell)
+   ->describe("Clears the shell's Buffer")
+   ->setAlias("clear");
+}}}
+ * Argument 1: the name of the command in the shell (this is what you will enter in the shell), without "" (e.g. clear)
+ * Argument 2: the name of the class that executes the command, without "" (e.g. Shell)
+ * Argument 3: the name of the function (without any arguments) to execute on this command (e.g. clearShell)
+ * Argument 4: (optional) add a little description: a nice little text for the help screen.
+ * Argument 5: (optional) adds an Alias to this command, that can be used insted of ex. 'Shell clear'
+
+To use the command: In the Shell type: "Shell clear" or "clear" [[br]]
+This will execute the function Shell->clearShell(), which will clear the shell buffer.
+As you may have noticed, the Names are !!NOT!! concatenated with any "", this is because the above mentioned method uses a MACRO to register the Command. Further, it is important to note, that {{{SHELL_COMMAND(...)}}} is not an object function, it is actually called within the class.
+
+
+Background Knowledge: the macro unrolled:
+{{{
+#!cpp
+#define SHELL_COMMAND(command, class, function) \
+        ShellCommandBase* shell_command_##class##_##command = \
+         ShellCommand<class>::registerCommand(#command, #class, &class::function)
+
+/* MEANING:
+   ShellCommandBase* someUniqueVarName = 
+         ShellCommand<ClassName>::registerCommand("commandNameInShell", "ClassName", &ClassName::FunctionToCall);
+*/
+}}}
+This can also be called with arguments, for default values (##FIXME##)
+
+
+== Dependencies ==
+  * [wiki:TextEngine Text] -> [wiki:Element2D Element2D] ->BaseObject
+  * EvenentListener (for input)
+  * ClassList (List)
+
+== Responsible ==
+  bensch (see source for email)