KeyMap.h

Go to the documentation of this file.

/*
 * Deskflow -- mouse and keyboard sharing utility
 * SPDX-FileCopyrightText: (C) 2012 - 2016 Symless Ltd.
 * SPDX-FileCopyrightText: (C) 2005 Chris Schoeneman
 * SPDX-License-Identifier: GPL-2.0-only WITH LicenseRef-OpenSSL-Exception
 */
 
#pragma once
 
#include "base/String.h"
#include "deskflow/KeyTypes.h"
 
#include <map>
#include <set>
#include <vector>
 
namespace deskflow {


class KeyMap
{
public:
  // Class used for testing
  friend class KeyMapTests;
 
  KeyMap();
  virtual ~KeyMap() = default;


  struct KeyItem
  {
  public:
    KeyID m_id{};                  
    int32_t m_group{};             
    KeyButton m_button{};          
    KeyModifierMask m_required{};  
    KeyModifierMask m_sensitive{}; 
    KeyModifierMask m_generates{}; 
    bool m_dead{};                 
    bool m_lock{};                 
    uint32_t m_client{};           
 
  public:
    bool operator==(const KeyItem &) const;
  };


  using KeyItemList = std::vector<KeyItem>;

  class Keystroke
  {
  public:
    enum EType
    {
      kButton, 
      kGroup   
    };
 
    Keystroke(KeyButton, bool press, bool repeat, uint32_t clientData);
    Keystroke(int32_t group, bool absolute, bool restore);
 
  public:
    struct Button
    {
    public:
      KeyButton m_button{}; 
      bool m_press{};       
      bool m_repeat{};      
      uint32_t m_client{};  
    };
    struct Group
    {
    public:
      int32_t m_group{}; 
      bool m_absolute{}; 
      bool m_restore{};  
    };
    union Data
    {
    public:
      Button m_button;
      Group m_group;
    };
 
    EType m_type{};
    Data m_data{};
  };

  using Keystrokes = std::vector<Keystroke>;

  using ModifierToKeys = std::multimap<KeyModifierMask, KeyItem>;

  using ButtonToKeyMap = std::map<KeyButton, const KeyItem *>;

  using ForeachKeyCallback = void (*)(KeyID, int32_t group, KeyItem &, void *userData);



  virtual void swap(KeyMap &) noexcept;


  void addKeyEntry(const KeyItem &item);


  void addKeyAliasEntry(
      KeyID targetID, int32_t group, KeyModifierMask targetRequired, KeyModifierMask targetSensitive, KeyID sourceID,
      KeyModifierMask sourceRequired, KeyModifierMask sourceSensitive
  );


  bool addKeyCombinationEntry(KeyID id, int32_t group, const KeyID *keys, uint32_t numKeys);


  void allowGroupSwitchDuringCompose();


  void addHalfDuplexButton(KeyButton button);


  void clearHalfDuplexModifiers();


  virtual void addHalfDuplexModifier(KeyID key);


  virtual void finish();


  virtual void foreachKey(ForeachKeyCallback cb, void *userData);




  virtual const KeyItem *mapKey(
      Keystrokes &keys, KeyID id, int32_t group, ModifierToKeys &activeModifiers, KeyModifierMask &currentState,
      KeyModifierMask desiredMask, bool isAutoRepeat, const std::string &lang
  ) const;
 
  void setLanguageData(std::vector<std::string> layouts);


  int32_t getNumGroups() const;


  int32_t getEffectiveGroup(int32_t group, int32_t offset) const;


  const KeyItemList *
  findCompatibleKey(KeyID id, int32_t group, KeyModifierMask required, KeyModifierMask sensitive) const;


  virtual bool isHalfDuplex(KeyID key, KeyButton button) const;


  bool isCommand(KeyModifierMask mask) const;
 
  // Get the modifiers that indicate a command
  KeyModifierMask getCommandModifiers() const;


  static void collectButtons(const ModifierToKeys &modifiers, ButtonToKeyMap &keys);


  static void initModifierKey(KeyItem &item);


  static bool isDeadKey(KeyID key);


  static KeyID getDeadKey(KeyID key);


  static std::string formatKey(KeyID key, KeyModifierMask);


  static bool parseKey(const std::string &, KeyID &);


  static bool parseModifiers(std::string &, KeyModifierMask &);

 
private:
  enum EKeystroke
  {
    kKeystrokePress,   
    kKeystrokeRelease, 
    kKeystrokeRepeat,  
    kKeystrokeClick,   
    kKeystrokeModify,  
    kKeystrokeUnmodify 
  };
 
  // A list of ways to synthesize a KeyID
  using KeyEntryList = std::vector<KeyItemList>;
 
  // computes the number of groups
  int32_t findNumGroups() const;
 
  // computes the map of modifiers to the keys that generate the modifiers
  void setModifierKeys();
 
  // maps a command key.  a command key is a keyboard shortcut and we're
  // trying to synthesize a button press with an exact sets of modifiers,
  // not trying to synthesize a character.  so we just need to find the
  // right button and synthesize the requested modifiers without regard
  // to what character they would synthesize.  we disallow multikey
  // entries since they don't make sense as hotkeys.
  const KeyItem *mapCommandKey(
      Keystrokes &keys, KeyID id, int32_t group, ModifierToKeys &activeModifiers, KeyModifierMask &currentState,
      KeyModifierMask desiredMask, bool isAutoRepeat, const std::string &lang
  ) const;
 
  // maps a character key.  a character key is trying to synthesize a
  // particular KeyID and isn't entirely concerned with the modifiers
  // used to do it.
  const KeyItem *mapCharacterKey(
      Keystrokes &keys, KeyID id, int32_t group, ModifierToKeys &activeModifiers, KeyModifierMask &currentState,
      KeyModifierMask desiredMask, bool isAutoRepeat, const std::string &lang
  ) const;
 
  // maps a modifier key
  const KeyItem *mapModifierKey(
      Keystrokes &keys, KeyID id, int32_t group, ModifierToKeys &activeModifiers, KeyModifierMask &currentState,
      KeyModifierMask desiredMask, bool isAutoRepeat, const std::string &lang
  ) const;
 
  // returns the index into \p entryList of the KeyItemList requiring
  // the fewest modifier changes between \p currentState and
  // \p desiredState.
  int32_t findBestKey(const KeyEntryList &entryList, KeyModifierMask desiredState) const;
 
  // gets the \c KeyItem used to synthesize the modifier who's bit is
  // given by \p modifierBit in group \p group and does not synthesize
  // the key \p button.
  const KeyItem *keyForModifier(KeyButton button, int32_t group, int32_t modifierBit) const;
 
  // fills \p keystrokes with the keys to synthesize the key in
  // \p keyItem taking the modifiers into account.  returns \c true
  // iff successful and sets \p currentState to the
  // resulting modifier state.
  bool keysForKeyItem(
      const KeyItem &keyItem, int32_t &group, ModifierToKeys &activeModifiers, KeyModifierMask &currentState,
      KeyModifierMask desiredState, KeyModifierMask overrideModifiers, bool isAutoRepeat, Keystrokes &keystrokes,
      const std::string &lang
  ) const;
 
  // fills \p keystrokes with the keys to synthesize the modifiers
  // in \p desiredModifiers from the active modifiers listed in
  // \p activeModifiers not including the key in \p keyItem.
  // returns \c true iff successful.
  bool keysToRestoreModifiers(
      const KeyItem &keyItem, int32_t group, ModifierToKeys &activeModifiers, KeyModifierMask &currentState,
      const ModifierToKeys &desiredModifiers, Keystrokes &keystrokes
  ) const;
 
  // fills \p keystrokes and \p undo with the keys to change the
  // current modifier state in \p currentState to match the state in
  // \p requiredState for each modifier indicated in \p sensitiveMask.
  // returns \c true iff successful and sets \p currentState to the
  // resulting modifier state.
  bool keysForModifierState(
      KeyButton button, int32_t group, ModifierToKeys &activeModifiers, KeyModifierMask &currentState,
      KeyModifierMask requiredState, KeyModifierMask sensitiveMask, KeyModifierMask notRequiredMask,
      Keystrokes &keystrokes
  ) const;
 
  // Adds keystrokes to synthesize key \p keyItem in mode \p type to
  // \p keystrokes and to undo the synthesis to \p undo.
  void addKeystrokes(
      EKeystroke type, const KeyItem &keyItem, ModifierToKeys &activeModifiers, KeyModifierMask &currentState,
      Keystrokes &keystrokes
  ) const;
 
  // Returns the number of modifiers indicated in \p state.
  static int32_t getNumModifiers(KeyModifierMask state);
 
  // Initialize key name/id maps
  static void initKeyNameMaps();
 
  // Ways to synthesize a KeyID over multiple keyboard groups
  using KeyGroupTable = std::vector<KeyEntryList>;
 
  void addGroupToKeystroke(Keystrokes &keys, int32_t &group, const std::string &lang) const;
 
  int32_t getLanguageGroupID(int32_t group, const std::string &lang) const;
  const KeyItemList *
  getKeyItemList(const KeyGroupTable &keyGroupTable, int32_t group, KeyModifierMask desiredMask) const;
 
  // not implemented
  KeyMap(const KeyMap &);
  KeyMap &operator=(const KeyMap &);
 
private:
  // Table of KeyID to ways to synthesize that KeyID
  using KeyIDMap = std::map<KeyID, KeyGroupTable>;
 
  // List of KeyItems that generate a particular modifier
  using ModifierKeyItemList = std::vector<const KeyItem *>;
 
  // Map a modifier to the KeyItems that synthesize that modifier
  using ModifierToKeyTable = std::vector<ModifierKeyItemList>;
 
  // A set of keys
  using KeySet = std::set<KeyID>;
 
  // A set of buttons
  using KeyButtonSet = std::set<KeyButton>;
 
  // Key maps for parsing/formatting
  using NameToKeyMap = std::map<std::string, KeyID, deskflow::string::CaselessCmp>;
  using NameToModifierMap = std::map<std::string, KeyModifierMask, deskflow::string::CaselessCmp>;
  using KeyToNameMap = std::map<KeyID, std::string>;
  using ModifierToNameMap = std::map<KeyModifierMask, std::string>;
 
  // KeyID info
  KeyIDMap m_keyIDMap;
  int32_t m_numGroups;
  ModifierToKeyTable m_modifierKeys;
 
  // composition info
  bool m_composeAcrossGroups;
 
  // half-duplex info
  KeyButtonSet m_halfDuplex; // half-duplex set by deskflow
  KeySet m_halfDuplexMods;   // half-duplex set by user
 
  // dummy KeyItem for changing modifiers
  KeyItem m_modifierKeyItem;
 
  // Language sync data
  std::vector<std::string> m_keyboardLayouts;
 
  // parsing/formatting tables
  static NameToKeyMap *s_nameToKeyMap;
  static NameToModifierMap *s_nameToModifierMap;
  static KeyToNameMap *s_keyToNameMap;
  static ModifierToNameMap *s_modifierToNameMap;
};
 
} // namespace deskflow