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