include/core/keymapper.hpp

   1 #ifndef _keymapper__hpp__included__
   2 #define _keymapper__hpp__included__
   3
   4 #include <string>
   5 #include <sstream>
   6 #include <stdexcept>
   7 #include <list>
   8 #include <set>
   9 #include <map>
  10 #include <iostream>
  11 #include "misc.hpp"
  12
  13 /**
  14  * Takes in a raw command and returns the command that should be actually executed given the key polarity.
  15  *
  16  * parameter cmd: Raw command.
  17  * parameter polarity: Polarity (True => Being pressed, False => Being released).
  18  * returns: The fixed command, "" if no command should be executed.
  19  * throws std::bad_alloc: Not enough memory.
  20  */
  21 std::string fixup_command_polarity(std::string cmd, bool polarity) throw(std::bad_alloc);
  22
  23
  24
  25 /**
  26  * Modifier key.
  27  *
  28  * Each object of this class is a modifier key (e.g. left control) or group of modifier keys (e.g. control).
  29  */
  30 class modifier
  31 {
  32 public:
  33 /**
  34  * Create a new modifier.
  35  *
  36  * parameter name: Name of the modifier.
  37  * throws std::bad_alloc: Not enough memory.
  38  */
  39         modifier(const std::string& name) throw(std::bad_alloc);
  40 /**
  41  * Create a new linked modifier.
  42  *
  43  * If modifiers A and B are both linked to C, then:
  44  * - It is legal to specify A and/or B as modifier when modifier mask contains C.
  45  * - If modifier contains C, then both A and B activate it.
  46  *
  47  * The usual use for linked modifiers is when there are two closely related keys (e.g. left ctrl and right ctrl)
  48  * one wants to be able to be referred with single name.
  49  *
  50  * parameter name: Name of the modifier.
  51  * parameter linkgroup: The name of modifier this modifier is linked to (this modifier should be created).
  52  * throws std::bad_alloc: Not enough memory.
  53  */
  54         modifier(const std::string& name, const std::string& linkgroup) throw(std::bad_alloc);
  55 /**
  56  * Destructor
  57  */
  58         ~modifier() throw();
  59 /**
  60  * Look up a modifier.
  61  *
  62  * parameter name: The name of the modifier to look up.
  63  * returns: The looked up modifier.
  64  * throws std::bad_alloc: Not enough memory.
  65  * throws std::runtime_error: No such modifier is known.
  66  */
  67         static modifier& lookup(const std::string& name) throw(std::bad_alloc, std::runtime_error);
  68 /**
  69  * Get name of modifier.
  70  *
  71  * returns: The name of this modifier.
  72  * throws: std::bad_alloc: Not enough memory.
  73  */
  74         std::string name() const throw(std::bad_alloc);
  75 /**
  76  * Get name of linked modifier.
  77  *
  78  * returns: The name of linked modifier, "" if none.
  79  * throws: std::bad_alloc: Not enough memory.
  80  */
  81         std::string linked_name() const throw(std::bad_alloc);
  82 /**
  83  * Get set of all modifiers.
  84  */
  85         static std::set<std::string> get_set() throw(std::bad_alloc);
  86 private:
  87         modifier(const modifier&);
  88         modifier& operator=(const modifier&);
  89         std::string modname;
  90 };
  91
  92 /**
  93  * A set of modifier keys.
  94  */
  95 class modifier_set
  96 {
  97 public:
  98 /**
  99  * Add a modifier into the set.
 100  *
 101  * parameter mod: The modifier to add.
 102  * parameter really: If true, actually add the key. If false, do nothing.
 103  * throws std::bad_alloc: Not enough memory.
 104  */
 105         void add(const modifier& mod, bool really = true) throw(std::bad_alloc);
 106 /**
 107  * Remove a modifier from the set.
 108  *
 109  * parameter mod: The modifier to remove.
 110  * parameter really: If true, actually remove the key. If false, do nothing.
 111  * throws std::bad_alloc: Not enough memory.
 112  */
 113         void remove(const modifier& mod, bool really = true) throw(std::bad_alloc);
 114 /**
 115  * Construct modifier set from comma-separated string.
 116  *
 117  * parameter modifiers: The modifiers as string
 118  * returns: The constructed modifier set.
 119  * throws std::bad_alloc: Not enough memory.
 120  * throws std::runtime_error: Illegal modifier or wrong syntax.
 121  */
 122         static modifier_set construct(const std::string& modifiers) throw(std::bad_alloc, std::runtime_error);
 123 /**
 124  * Check modifier against its mask for validity.
 125  *
 126  * This method checks that:
 127  * - for each modifier in set, either that or its linkage group is in mask.
 128  * - Both modifier and its linkage group isn't in either set or mask.
 129  *
 130  * parameter set: The set to check.
 131  * parameter mask: The mask to check against.
 132  * returns: True if set is valid, false if not.
 133  * throws std::bad_alloc: Not enough memory.
 134  */
 135         static bool valid(const modifier_set& set, const modifier_set& mask) throw(std::bad_alloc);
 136 /**
 137  * Check if this modifier set triggers the action.
 138  *
 139  * Modifier set triggers another if for each modifier or linkage group in mask:
 140  * - Modifier appears in both set and trigger.
 141  * - At least one modifier with this linkage group appears in both set and trigger.
 142  * - Modifiers with this linkage group do not appear in either set nor trigger.
 143  *
 144  */
 145         static bool triggers(const modifier_set& set, const modifier_set& trigger, const modifier_set& mask)
 146                 throw(std::bad_alloc);
 147 /**
 148  * Equality check.
 149  *
 150  * parameter m: Another set.
 151  * returns: True if two sets are equal, false if not.
 152  */
 153         bool operator==(const modifier_set& m) const throw();
 154
 155 private:
 156         friend std::ostream& operator<<(std::ostream& os, const modifier_set& m);
 157         std::set<const modifier*> set;
 158 };
 159
 160 /**
 161  * Debugging print. Prints textual version of set into stream.
 162  *
 163  * parameter os: The stream to print to.
 164  * parameter m: The modifier set to print.
 165  * returns: reference to os.
 166  */
 167 std::ostream&  operator<<(std::ostream& os, const modifier_set& m);
 168
 169 /**
 170  * Key or key group.
 171  *
 172  * Each object of this type is either one key or group of keys.
 173  */
 174 class keygroup
 175 {
 176 public:
 177 /**
 178  * Key group type.
 179  */
 180         enum type
 181         {
 182 /**
 183  * Disabled.
 184  */
 185                 KT_DISABLED,
 186 /**
 187  * Singular button.
 188  */
 189                 KT_KEY,
 190 /**
 191  * Pressure-sensitive button
 192  */
 193                 KT_PRESSURE_PM,
 194                 KT_PRESSURE_MP,
 195                 KT_PRESSURE_0P,
 196                 KT_PRESSURE_0M,
 197                 KT_PRESSURE_P0,
 198                 KT_PRESSURE_M0,
 199 /**
 200  * Axis key pair.
 201  */
 202                 KT_AXIS_PAIR,
 203                 KT_AXIS_PAIR_INVERSE,
 204 /**
 205  * Hat.
 206  */
 207                 KT_HAT,
 208 /**
 209  * Mouse axis (this is not a real axis!).
 210  */
 211                 KT_MOUSE
 212         };
 213 /**
 214  * Create a new key group.
 215  *
 216  * parameter name: Name of the key group.
 217  * parameter t: Initial type of the key group.
 218  * throws std::bad_alloc: Not enough memory.
 219  */
 220         keygroup(const std::string& name, enum type t) throw(std::bad_alloc);
 221 /**
 222  * Destructor
 223  */
 224         ~keygroup() throw();
 225 /**
 226  * Lookup key group by name.
 227  *
 228  * Parameter name: The key group name.
 229  * Returns: The looked up key group, or NULL if not found.
 230  */
 231         static keygroup* lookup_by_name(const std::string& name) throw();
 232 /**
 233  * Get the set of axes.
 234  *
 235  * Returns: The axis set (all axes).
 236  * Throws std::bad_alloc: Not enough memory.
 237  */
 238         static std::set<std::string> get_axis_set() throw(std::bad_alloc);
 239 /**
 240  * Change type of key group.
 241  *
 242  * parameter t: New type for the key group.
 243  */
 244         void change_type(enum type t) throw();
 245 /**
 246  * Change calibration (Axis pairs and pressure buttons only).
 247  *
 248  * parameter left: The control value at extreme negative position.
 249  * parameter center: The control value at center position.
 250  * parameter right: The control value at extreme positive position.
 251  * parameter tolerance: How wide is the neutral zone (must be larger than 0 and smaller than 1).
 252  */
 253         void change_calibration(short left, short center, short right, double tolerance);
 254 /**
 255  * Change state of this key group.
 256  *
 257  * For KT_KEY, value is zero/nonzero.
 258  * For KT_PRESSURE_* and KT_AXIS_PAIR*, value is -32768...32767.
 259  * For KT_HAT, 1 is up, 2 is right, 4 is down, 8 is left (may be ORed).
 260  * For KT_MOUSE, value is -32768...32767.
 261  *
 262  * parameter pos: New position.
 263  * parameter modifiers: The modifier set that was pressed during the change.
 264  */
 265         void set_position(short pos, const modifier_set& modifiers) throw();
 266 /**
 267  * Look up individual key by name.
 268  *
 269  * parameter name: The name of the key to look up.
 270  * returns: First element is pointer to key group, second is key index within the group.
 271  * throws std::bad_alloc: Not enough memory.
 272  * throws std::runtime_error: No such key known.
 273  */
 274         static std::pair<keygroup*, unsigned> lookup(const std::string& name) throw(std::bad_alloc,
 275                 std::runtime_error);
 276 /**
 277  * Look up key group name.
 278  *
 279  * returns: The name of the key group.
 280  * throws std::bad_alloc: Not enough memory.
 281  */
 282         std::string name() throw(std::bad_alloc);
 283 /**
 284  * Get set of all keys (including subkeys).
 285  */
 286         static std::set<std::string> get_keys() throw(std::bad_alloc);
 287
 288 /**
 289  * Key group parameters.
 290  */
 291         struct parameters
 292         {
 293 /**
 294  * Type
 295  */
 296                 enum type ktype;
 297 /**
 298  * Last known raw value.
 299  */
 300                 short last_rawval;
 301 /**
 302  * Calibration left.
 303  */
 304                 short cal_left;
 305 /**
 306  * Calibration center.
 307  */
 308                 short cal_center;
 309 /**
 310  * Calibration right.
 311  */
 312                 short cal_right;
 313 /**
 314  * Calibration tolerance.
 315  */
 316                 double cal_tolerance;
 317         };
 318 /**
 319  * Get parameters.
 320  */
 321         struct parameters get_parameters();
 322 /**
 323  * Get all key parameters.
 324  */
 325         static std::map<std::string, struct parameters> get_all_parameters();
 326 /**
 327  * Set callback requests on/off
 328  */
 329         void request_hook_callback(bool state);
 330 private:
 331         unsigned state;
 332         enum type ktype;
 333         short last_rawval;
 334         short cal_left;
 335         short cal_center;
 336         short cal_right;
 337         double cal_tolerance;
 338         double compensate(short value);
 339         double compensate2(double value);
 340         void run_listeners(const modifier_set& modifiers, unsigned subkey, bool polarity, bool really, double x);
 341         std::string keyname;
 342         bool requests_hook;
 343 };
 344
 345 /**
 346  * This class handles internals of mapping events from keyboard buttons and pseudo-buttons.
 347  */
 348 class keymapper
 349 {
 350 public:
 351 /**
 352  * Binds a key, erroring out if binding would conflict with existing one.
 353  *
 354  * parameter mod: Modifier set to require to be pressed.
 355  * parameter modmask: Modifier set to take into account.
 356  * parameter keyname: Key to bind the action to.
 357  * parameter command: The command to bind.
 358  * throws std::bad_alloc: Not enough memory.
 359  * throws std::runtime_error: The binding would conflict with existing one or invalid modifier/key.
 360  */
 361         static void bind(std::string mod, std::string modmask, std::string keyname, std::string command)
 362                 throw(std::bad_alloc, std::runtime_error);
 363 /**
 364  * Unbinds a key, erroring out if binding does not exist..
 365  *
 366  * parameter mod: Modifier set to require to be pressed.
 367  * parameter modmask: Modifier set to take into account.
 368  * parameter keyname: Key to bind the action to.
 369  * throws std::bad_alloc: Not enough memory.
 370  * throws std::runtime_error: The binding does not exist.
 371  */
 372         static void unbind(std::string mod, std::string modmask, std::string keyname) throw(std::bad_alloc,
 373                 std::runtime_error);
 374 /**
 375  * Dump list of bindigns as message to console.
 376  *
 377  * throws std::bad_alloc: Not enough memory.
 378  */
 379         static void dumpbindings() throw(std::bad_alloc);
 380 /**
 381  * Get keys bound.
 382  */
 383         static std::set<std::string> get_bindings() throw(std::bad_alloc);
 384 /**
 385  * Get command for key.
 386  */
 387         static std::string get_command_for(const std::string& keyspec) throw(std::bad_alloc);
 388 /**
 389  * Bind command for key.
 390  */
 391         static void bind_for(const std::string& keyspec, const std::string& cmd) throw(std::bad_alloc,
 392                 std::runtime_error);
 393 };
 394
 395 #endif