simgear/structure/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 <string>
  17 #include <map>
  18 #include <vector>
  19
  20 #include <OpenThreads/Mutex>
  21
  22 #include <simgear/props/props.hxx>
  23
  24 using std::string;
  25 using std::map;
  26 using std::vector;
  27
  28
  29 /**
  30  * Manage commands.
  31  *
  32  * <p>This class allows the application to register and unregister
  33  * commands, and provides shortcuts for executing them.  Commands are
  34  * simple functions that take a const pointer to an SGPropertyNode:
  35  * the function may use the nodes children as parameters.</p>
  36  *
  37  * @author David Megginson, david@megginson.com
  38  */
  39 class SGCommandMgr
  40 {
  41 public:
  42
  43   /**
  44    * Type for a command function.
  45    */
  46   typedef bool (*command_t) (const SGPropertyNode * arg);
  47
  48
  49   /**
  50    * Destructor.
  51    */
  52   virtual ~SGCommandMgr ();
  53
  54   /**
  55    * Implement the classical singleton.
  56    */
  57   static SGCommandMgr* instance();
  58
  59   /**
  60    * Register a new command with the manager.
  61    *
  62    * @param name The command name.  Any existing command with
  63    * the same name will silently be overwritten.
  64    * @param command A pointer to a one-arg function returning
  65    * a bool result.  The argument is always a const pointer to
  66    * an SGPropertyNode (which may contain multiple values).
  67    */
  68   virtual void addCommand (const string &name, command_t command);
  69
  70
  71   /**
  72    * Look up an existing command.
  73    *
  74    * @param name The command name.
  75    * @return A pointer to the command, or 0 if there is no registered
  76    * command with the name specified.
  77    */
  78   virtual command_t getCommand (const string &name) const;
  79
  80
  81   /**
  82    * Get a list of all existing command names.
  83    *
  84    * @return A (possibly empty) vector of the names of all registered
  85    * commands.
  86    */
  87   virtual vector<string> getCommandNames () const;
  88
  89
  90   /**
  91    * Execute a command.
  92    *
  93    * @param name The name of the command.
  94    * @param arg A const pointer to an SGPropertyNode.  The node
  95    * may have a value and/or children, etc., so that it is possible
  96    * to pass an arbitrarily complex data structure to a command.
  97    * @return true if the command is present and executes successfully,
  98    * false otherwise.
  99    */
 100   virtual bool execute (const string &name, const SGPropertyNode * arg) const;
 101
 102 protected:
 103   /**
 104    * Default constructor.
 105    */
 106   SGCommandMgr ();
 107
 108
 109 private:
 110
 111   typedef map<string,command_t> command_map;
 112   command_map _commands;
 113
 114   static OpenThreads::Mutex _instanceMutex;
 115
 116 };
 117
 118 #endif // __COMMANDS_HXX
 119
 120 // end of commands.hxx