CKeyMap.h

/*
 * synergy -- mouse and keyboard sharing utility
 * Copyright (C) 2012 Bolton Software Ltd.
 * Copyright (C) 2005 Chris Schoeneman
 * 
 * This package is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * found in the file COPYING that should have accompanied this file.
 * 
 * This package is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef CKEYMAP_H
#define CKEYMAP_H

#include "KeyTypes.h"
#include "CString.h"
#include "CStringUtil.h"
#include "stdmap.h"
#include "stdset.h"
#include "stdvector.h"


class CKeyMap {
public:
    CKeyMap();
    ~CKeyMap();


    struct KeyItem {
    public:
        KeyID           m_id;           
        SInt32          m_group;        
        KeyButton       m_button;       
        KeyModifierMask m_required;     
        KeyModifierMask m_sensitive;    
        KeyModifierMask m_generates;    
        bool            m_dead;         
        bool            m_lock;         
        UInt32          m_client;       

    public:
        bool            operator==(const KeyItem&) const;
    };


    typedef std::vector<KeyItem> KeyItemList;

    class Keystroke {
    public:
        enum EType {
            kButton,                    
            kGroup                      
        };

        Keystroke(KeyButton, bool press, bool repeat, UInt32 clientData);
        Keystroke(SInt32 group, bool absolute, bool restore);

    public:
        struct CButton {
        public:
            KeyButton   m_button;       
            bool        m_press;        
            bool        m_repeat;       
            UInt32      m_client;       
        };
        struct CGroup {
        public:
            SInt32      m_group;        
            bool        m_absolute;     
            bool        m_restore;      
        };
        union CData {
        public:
            CButton     m_button;
            CGroup      m_group;
        };

        EType           m_type;
        CData           m_data;
    };

    typedef std::vector<Keystroke> Keystrokes;

    typedef std::multimap<KeyModifierMask, KeyItem> ModifierToKeys;

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

    typedef void (*ForeachKeyCallback)(KeyID, SInt32 group,
                            KeyItem&, void* userData);



    virtual void        swap(CKeyMap&);


    void                addKeyEntry(const KeyItem& item);


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


    bool                addKeyCombinationEntry(KeyID id, SInt32 group,
                            const KeyID* keys, UInt32 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, SInt32 group,
                            ModifierToKeys& activeModifiers,
                            KeyModifierMask& currentState,
                            KeyModifierMask desiredMask,
                            bool isAutoRepeat) const;


    SInt32              getNumGroups() const;


    SInt32              getEffectiveGroup(SInt32 group, SInt32 offset) const;


    const KeyItemList*  findCompatibleKey(KeyID id, SInt32 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 CString      formatKey(KeyID key, KeyModifierMask);


    static bool         parseKey(const CString&, KeyID&);


    static bool         parseModifiers(CString&, KeyModifierMask&);


private:
    enum EKeystroke {
        kKeystrokePress,        
        kKeystrokeRelease,      
        kKeystrokeRepeat,       
        kKeystrokeClick,        
        kKeystrokeModify,       
        kKeystrokeUnmodify      
    };
        
    // A list of ways to synthesize a KeyID
    typedef std::vector<KeyItemList> KeyEntryList;

    // computes the number of groups
    SInt32              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, SInt32 group,
                            ModifierToKeys& activeModifiers,
                            KeyModifierMask& currentState,
                            KeyModifierMask desiredMask,
                            bool isAutoRepeat) 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, SInt32 group,
                            ModifierToKeys& activeModifiers,
                            KeyModifierMask& currentState,
                            KeyModifierMask desiredMask,
                            bool isAutoRepeat) const;

    // maps a modifier key
    const KeyItem*      mapModifierKey(Keystrokes& keys,
                            KeyID id, SInt32 group,
                            ModifierToKeys& activeModifiers,
                            KeyModifierMask& currentState,
                            KeyModifierMask desiredMask,
                            bool isAutoRepeat) const;

    // returns the index into \p entryList of the KeyItemList requiring
    // the fewest modifier changes between \p currentState and
    // \p desiredState.
    SInt32              findBestKey(const KeyEntryList& entryList,
                            KeyModifierMask currentState,
                            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, SInt32 group,
                            SInt32 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,
                            SInt32& group,
                            ModifierToKeys& activeModifiers,
                            KeyModifierMask& currentState,
                            KeyModifierMask desiredState,
                            KeyModifierMask overrideModifiers,
                            bool isAutoRepeat,
                            Keystrokes& keystrokes) 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,
                            SInt32 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, SInt32 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 SInt32       getNumModifiers(KeyModifierMask state);

    // Initialize key name/id maps
    static void         initKeyNameMaps();

    // not implemented
    CKeyMap(const CKeyMap&);
    CKeyMap&            operator=(const CKeyMap&);

private:
    // Ways to synthesize a KeyID over multiple keyboard groups
    typedef std::vector<KeyEntryList> KeyGroupTable;

    // Table of KeyID to ways to synthesize that KeyID
    typedef std::map<KeyID, KeyGroupTable> KeyIDMap;

    // List of KeyItems that generate a particular modifier
    typedef std::vector<const KeyItem*> ModifierKeyItemList;

    // Map a modifier to the KeyItems that synthesize that modifier
    typedef std::vector<ModifierKeyItemList> ModifierToKeyTable;

    // A set of keys
    typedef std::set<KeyID> KeySet;

    // A set of buttons
    typedef std::set<KeyButton> KeyButtonSet;

    // Key maps for parsing/formatting
    typedef std::map<CString, KeyID,
                            CStringUtil::CaselessCmp> CNameToKeyMap;
    typedef std::map<CString, KeyModifierMask,
                            CStringUtil::CaselessCmp> CNameToModifierMap;
    typedef std::map<KeyID, CString> CKeyToNameMap;
    typedef std::map<KeyModifierMask, CString> CModifierToNameMap;

    // KeyID info
    KeyIDMap            m_keyIDMap;
    SInt32              m_numGroups;
    ModifierToKeyTable  m_modifierKeys;

    // composition info
    bool                m_composeAcrossGroups;

    // half-duplex info
    KeyButtonSet        m_halfDuplex;           // half-duplex set by synergy
    KeySet              m_halfDuplexMods;       // half-duplex set by user

    // dummy KeyItem for changing modifiers
    KeyItem             m_modifierKeyItem;

    // parsing/formatting tables
    static CNameToKeyMap*       s_nameToKeyMap;
    static CNameToModifierMap*  s_nameToModifierMap;
    static CKeyToNameMap*       s_keyToNameMap;
    static CModifierToNameMap*  s_modifierToNameMap;
};

#endif