simgear/misc/commands.hxx

   1 /**
   2  * \file commands.hxx
   3  * Interface definition for encapsulated commands.
   4  * Started Spring 2001 by David Megginson, david@megginson.com
   5  * This code is released into the Public Domain.
   6  *
   7  * $Id$
   8  */
   9
  10 #ifndef __COMMANDS_HXX
  11 #define __COMMANDS_HXX
  12
  13
  14 #include <simgear/compiler.h>
  15
  16 #include STL_STRING
  17 #include <map>
  18 #include <vector>
  19
  20 #include "props.hxx"
  21
  22 SG_USING_STD(string);
  23 SG_USING_STD(map);
  24 SG_USING_STD(vector);
  25
  26
  27 /**
  28  * Manage commands.
  29  *
  30  * <p>This class allows the application to register and unregister
  31  * commands, and provides shortcuts for executing them.  Commands
  32  * are simple functions that take a const pointer to an SGPropertyNode
  33  * as an argument and return a bool value indicating success or failure.
  34  * The property node may be ignored, or it may contain values that
  35  * the command uses as parameters.</p>
  36  *
  37  * <p>There are convenience methods for invoking a command function
  38  * with no arguments or with a single, primitive argument.</p>
  39  *
  40  * @author David Megginson, david@megginson.com
  41  */
  42 class SGCommandMgr
  43 {
  44 public:
  45
  46   /**
  47    * Type for a command function.
  48    */
  49   typedef bool (*command_t) (const SGPropertyNode * arg);
  50
  51
  52   /**
  53    * Default constructor.
  54    */
  55   SGCommandMgr ();
  56
  57
  58   /**
  59    * Destructor.
  60    */
  61   virtual ~SGCommandMgr ();
  62
  63
  64   /**
  65    * Register a new command with the manager.
  66    *
  67    * @param name The command name.  Any existing command with
  68    * the same name will silently be overwritten.
  69    * @param command A pointer to a one-arg function returning
  70    * a bool result.  The argument is always a const pointer to
  71    * an SGPropertyNode (which may contain multiple values).
  72    */
  73   virtual void addCommand (const string &name, command_t command);
  74
  75
  76   /**
  77    * Look up an existing command.
  78    *
  79    * @param name The command name.
  80    * @return A pointer to the command, or 0 if there is no registered
  81    * command with the name specified.
  82    */
  83   virtual command_t getCommand (const string &name) const;
  84
  85
  86   /**
  87    * Get a list of all existing command names.
  88    *
  89    * @return A (possibly empty) vector of the names of all registered
  90    * commands.
  91    */
  92   virtual vector<string> getCommandNames () const;
  93
  94
  95   /**
  96    * Execute a command.
  97    *
  98    * This is the primary method for invoking a command; the others
  99    * are convenience methods that invoke this one indirectly.
 100    *
 101    * @param name The name of the command.
 102    * @param arg A const pointer to an SGPropertyNode.  The node
 103    * may have a value and/or children, etc., so that it is possible
 104    * to pass an arbitrarily complex data structure to a command.
 105    * @return true if the command is present and executes successfully,
 106    * false otherwise.
 107    */
 108   virtual bool execute (const string &name, const SGPropertyNode * arg) const;
 109
 110
 111   /**
 112    * Execute a command with no argument.
 113    *
 114    * The command function will receive a pointer to a property node
 115    * with no value and no children.
 116    *
 117    * @param name The name of the command.
 118    * @return true if the command is present and executes successfully,
 119    * false otherwise.
 120    */
 121   virtual bool execute (const string &name) const;
 122
 123
 124   /**
 125    * Execute a command with a single bool argument.
 126    *
 127    * The command function will receive a pointer to a property node
 128    * with a bool value and no children.
 129    *
 130    * @param name The name of the command.
 131    * @param arg The bool argument to the command.
 132    * @return true if the command is present and executes successfully,
 133    * false otherwise.
 134    */
 135   virtual bool execute (const string &name, bool arg) const;
 136
 137
 138   /**
 139    * Execute a command with a single int argument.
 140    *
 141    * The command function will receive a pointer to a property node
 142    * with a int value and no children.
 143    *
 144    * @param name The name of the command.
 145    * @param arg The int argument to the command.
 146    * @return true if the command is present and executes successfully,
 147    * false otherwise.
 148    */
 149   virtual bool execute (const string &name, int arg) const;
 150
 151
 152   /**
 153    * Execute a command with a single long argument.
 154    *
 155    * The command function will receive a pointer to a property node
 156    * with a long value and no children.
 157    *
 158    * @param name The name of the command.
 159    * @param arg The long argument to the command.
 160    * @return true if the command is present and executes successfully,
 161    * false otherwise.
 162    */
 163   virtual bool execute (const string &name, long arg) const;
 164
 165
 166   /**
 167    * Execute a command with a single float argument.
 168    *
 169    * The command function will receive a pointer to a property node
 170    * with a float value and no children.
 171    *
 172    * @param name The name of the command.
 173    * @param arg The float argument to the command.
 174    * @return true if the command is present and executes successfully,
 175    * false otherwise.
 176    */
 177   virtual bool execute (const string &name, float arg) const;
 178
 179
 180   /**
 181    * Execute a command with a single double argument.
 182    *
 183    * The command function will receive a pointer to a property node
 184    * with a double value and no children.
 185    *
 186    * @param name The name of the command.
 187    * @param arg The double argument to the command.
 188    * @return true if the command is present and executes successfully,
 189    * false otherwise.
 190    */
 191   virtual bool execute (const string &name, double arg) const;
 192
 193
 194   /**
 195    * Execute a command with a single string argument.
 196    *
 197    * The command function will receive a pointer to a property node
 198    * with a string value and no children.
 199    *
 200    * @param name The name of the command.
 201    * @param arg The string argument to the command.
 202    * @return true if the command is present and executes successfully,
 203    * false otherwise.
 204    */
 205   virtual bool execute (const string &name, string arg) const;
 206
 207
 208 private:
 209
 210   typedef map<string,command_t> command_map;
 211   command_map _commands;
 212
 213 };
 214
 215 #endif __COMMANDS_HXX
 216
 217 // end of commands.hxx