SGBinding.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 __SGBINDING_HXX
  11 #define __SGBINDING_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 #include <simgear/props/condition.hxx>
  22
  23 #include "commands.hxx"
  24
  25 /**
  26  * An input binding of some sort.
  27  *
  28  * <p>This class represents a binding that can be assigned to a
  29  * keyboard key, a joystick button or axis, or even a panel
  30  * instrument.</p>
  31  */
  32 class SGBinding : public SGConditional
  33 {
  34 public:
  35
  36   /**
  37    * Default constructor.
  38    */
  39   SGBinding ();
  40
  41     /**
  42      * Convenience constructor.
  43      *
  44      * @param commandName TODO
  45      */
  46     SGBinding(const std::string& commandName);
  47
  48   /**
  49    * Convenience constructor.
  50    *
  51    * @param node The binding will be built from this node.
  52    * @param root Property root used while building binding.
  53    */
  54   SGBinding( const SGPropertyNode *node,
  55              SGPropertyNode *root );
  56
  57
  58   /**
  59    * Destructor.
  60    */
  61   virtual ~SGBinding ();
  62
  63
  64   /**
  65    * clear internal state of the binding back to empty. This is useful
  66    * if you don't want the 'remove on delete' behaviour of the
  67    * destructor.
  68    */
  69   void clear();
  70
  71
  72   /**
  73    * Get the command name.
  74    *
  75    * @return The string name of the command for this binding.
  76    */
  77   const std::string &getCommandName () const { return _command_name; }
  78
  79
  80   /**
  81    * Get the command itself.
  82    *
  83    * @return The command associated with this binding, or 0 if none
  84    * is present.
  85    */
  86   SGCommandMgr::Command* getCommand () const { return _command; }
  87
  88
  89   /**
  90    * Get the argument that will be passed to the command.
  91    *
  92    * @return A property node that will be passed to the command as its
  93    * argument, or 0 if none was supplied.
  94    */
  95   const SGPropertyNode * getArg () { return _arg; }
  96
  97
  98   /**
  99    * Read a binding from a property node.
 100    *
 101    * @param node The property node containing the binding.
 102    * @param root The property root node used while building the binding from
 103    *             \a node.
 104    */
 105   void read (const SGPropertyNode * node, SGPropertyNode* root);
 106
 107
 108   /**
 109    * Fire a binding.
 110    */
 111   void fire () const;
 112
 113
 114   /**
 115    * Fire a binding with a scaled movement (rather than absolute position).
 116    */
 117   void fire (double offset, double max) const;
 118
 119
 120   /**
 121    * Fire a binding with a setting (i.e. joystick axis).
 122    *
 123    * A double 'setting' property will be added to the arguments.
 124    *
 125    * @param setting The input setting, usually between -1.0 and 1.0.
 126    */
 127   void fire (double setting) const;
 128
 129   /**
 130    * Fire a binding with a number of additional parameters
 131    *
 132    * The children of params will be merged with the fixed arguments.
 133    */
 134   void fire (SGPropertyNode* params) const;
 135
 136 private:
 137   void innerFire() const;
 138                                 // just to be safe.
 139   SGBinding (const SGBinding &binding);
 140
 141   std::string _command_name;
 142   mutable SGCommandMgr::Command* _command;
 143   mutable SGPropertyNode_ptr _arg;
 144   mutable SGPropertyNode_ptr _setting;
 145 };
 146
 147 typedef SGSharedPtr<SGBinding> SGBinding_ptr;
 148
 149 typedef std::vector<SGBinding_ptr > SGBindingList;
 150 typedef std::map<unsigned,SGBindingList> SGBindingMap;
 151
 152 /**
 153  * fire every binding in a list, in sequence
 154
 155  */
 156 void fireBindingList(const SGBindingList& aBindings, SGPropertyNode* params = NULL);
 157
 158 /**
 159  * fire every binding in a list with a setting value
 160
 161  */
 162 void fireBindingListWithOffset(const SGBindingList& aBindings, double offset, double max);
 163
 164 /**
 165  * read multiple bindings from property-list format
 166  */
 167 SGBindingList readBindingList(const simgear::PropertyList& aNodes, SGPropertyNode* aRoot);
 168
 169 /**
 170  * call clear() on every binding in a list
 171  */
 172 void clearBindingList(const SGBindingList& aBindings);
 173
 174 #endif