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