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