File indexing completed on 2025-03-16 08:11:26

 /*
     This source file is part of Konsole, a terminal emulator.
 
     SPDX-FileCopyrightText: 2007-2008 Robert Knight <robertknight@gmail.com>
 
     SPDX-License-Identifier: GPL-2.0-or-later
 
     This program 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, write to the Free Software
     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
     02110-1301  USA.
 */
 
 #ifndef KEYBOARDTRANSLATOR_H
 #define KEYBOARDTRANSLATOR_H
 
 // Qt
 #include <QHash>
 #include <QKeySequence>
 #include <QList>
 #include <QMetaType>
 #include <QVarLengthArray>
 
 // Konsole
 // #include "konsole_export.h"
 #define KONSOLEPRIVATE_EXPORT
 
 class QIODevice;
 class QTextStream;
 
 namespace Konsole
 {
 
 /**
  * A convertor which maps between key sequences pressed by the user and the
  * character strings which should be sent to the terminal and commands
  * which should be invoked when those character sequences are pressed.
  *
  * Konsole supports multiple keyboard translators, allowing the user to
  * specify the character sequences which are sent to the terminal
  * when particular key sequences are pressed.
  *
  * A key sequence is defined as a key code, associated keyboard modifiers
  * (Shift,Ctrl,Alt,Meta etc.) and state flags which indicate the state
  * which the terminal must be in for the key sequence to apply.
  */
 class KeyboardTranslator
 {
 public:
     /**
      * The meaning of a particular key sequence may depend upon the state which
      * the terminal emulation is in.  Therefore findEntry() may return a different
      * Entry depending upon the state flags supplied.
      *
      * This enum describes the states which may be associated with with a particular
      * entry in the keyboard translation entry.
      */
     enum State {
         /** Indicates that no special state is active */
         NoState = 0,
         /**
          * TODO More documentation
          */
         NewLineState = 1,
         /**
          * Indicates that the terminal is in 'Ansi' mode.
          * TODO: More documentation
          */
         AnsiState = 2,
         /**
          * TODO More documentation
          */
         CursorKeysState = 4,
         /**
          * Indicates that the alternate screen ( typically used by interactive programs
          * such as screen or vim ) is active
          */
         AlternateScreenState = 8,
         /** Indicates that any of the modifier keys is active. */
         AnyModifierState = 16,
         /** Indicates that the numpad is in application mode. */
         ApplicationKeypadState = 32
     };
     Q_DECLARE_FLAGS(States, State)
 
     /**
      * This enum describes commands which are associated with particular key sequences.
      */
     enum Command {
         /** Indicates that no command is associated with this command sequence */
         NoCommand = 0,
         /** TODO Document me */
         SendCommand = 1,
         /** Scroll the terminal display up one page */
         ScrollPageUpCommand = 2,
         /** Scroll the terminal display down one page */
         ScrollPageDownCommand = 4,
         /** Scroll the terminal display up one line */
         ScrollLineUpCommand = 8,
         /** Scroll the terminal display down one line */
         ScrollLineDownCommand = 16,
         /** Toggles scroll lock mode */
         ScrollLockCommand = 32,
         /** Scroll the terminal display up to the start of history */
         ScrollUpToTopCommand = 64,
         /** Scroll the terminal display down to the end of history */
         ScrollDownToBottomCommand = 128,
         /** Echos the operating system specific erase character. */
         EraseCommand = 256
     };
     Q_DECLARE_FLAGS(Commands, Command)
 
     /**
      * Represents an association between a key sequence pressed by the user
      * and the character sequence and commands associated with it for a particular
      * KeyboardTranslator.
      */
     class Entry
     {
     public:
         /**
          * Constructs a new entry for a keyboard translator.
          */
         Entry();
 
         /**
          * Returns true if this entry is null.
          * This is true for newly constructed entries which have no properties set.
          */
         bool isNull() const;
 
         /** Returns the commands associated with this entry */
         Command command() const;
         /** Sets the command associated with this entry. */
         void setCommand(Command command);
 
         /**
          * Returns the character sequence associated with this entry, optionally replacing
          * wildcard '*' characters with numbers to indicate the keyboard modifiers being pressed.
          *
          * TODO: The numbers used to replace '*' characters are taken from the Konsole/KDE 3 code.
          * Document them.
          *
          * @param expandWildCards Specifies whether wild cards (occurrences of the '*' character) in
          * the entry should be replaced with a number to indicate the modifier keys being pressed.
          *
          * @param modifiers The keyboard modifiers being pressed.
          */
         QByteArray text(bool expandWildCards = false, Qt::KeyboardModifiers modifiers = Qt::NoModifier) const;
 
         /** Sets the character sequence associated with this entry */
         void setText(const QByteArray &text);
 
         /**
          * Returns the character sequence associated with this entry,
          * with any non-printable characters replaced with escape sequences.
          *
          * eg. \\E for Escape, \\t for tab, \\n for new line.
          *
          * @param expandWildCards See text()
          * @param modifiers See text()
          */
         QByteArray escapedText(bool expandWildCards = false, Qt::KeyboardModifiers modifiers = Qt::NoModifier) const;
 
         /** Returns the character code ( from the Qt::Key enum ) associated with this entry */
         int keyCode() const;
         /** Sets the character code associated with this entry */
         void setKeyCode(int keyCode);
 
         /**
          * Returns a bitwise-OR of the enabled keyboard modifiers associated with this entry.
          * If a modifier is set in modifierMask() but not in modifiers(), this means that the entry
          * only matches when that modifier is NOT pressed.
          *
          * If a modifier is not set in modifierMask() then the entry matches whether the modifier
          * is pressed or not.
          */
         Qt::KeyboardModifiers modifiers() const;
 
         /** Returns the keyboard modifiers which are valid in this entry.  See modifiers() */
         Qt::KeyboardModifiers modifierMask() const;
 
         /** See modifiers() */
         void setModifiers(Qt::KeyboardModifiers modifiers);
         /** See modifierMask() and modifiers() */
         void setModifierMask(Qt::KeyboardModifiers modifiers);
 
         /**
          * Returns a bitwise-OR of the enabled state flags associated with this entry.
          * If flag is set in stateMask() but not in state(), this means that the entry only
          * matches when the terminal is NOT in that state.
          *
          * If a state is not set in stateMask() then the entry matches whether the terminal
          * is in that state or not.
          */
         States state() const;
 
         /** Returns the state flags which are valid in this entry.  See state() */
         States stateMask() const;
 
         /** See state() */
         void setState(States state);
         /** See stateMask() */
         void setStateMask(States mask);
 
         /**
          * Returns the key code and modifiers associated with this entry
          * as a QKeySequence
          */
         // QKeySequence keySequence() const;
 
         /**
          * Returns this entry's conditions ( ie. its key code, modifier and state criteria )
          * as a string.
          */
         QString conditionToString() const;
 
         /**
          * Returns this entry's result ( ie. its command or character sequence )
          * as a string.
          *
          * @param expandWildCards See text()
          * @param modifiers See text()
          */
         QString resultToString(bool expandWildCards = false, Qt::KeyboardModifiers modifiers = Qt::NoModifier) const;
 
         /**
          * Returns true if this entry matches the given key sequence, specified
          * as a combination of @p keyCode , @p modifiers and @p state.
          */
         bool matches(int keyCode, Qt::KeyboardModifiers modifiers, States flags) const;
 
         bool operator==(const Entry &rhs) const;
 
     private:
         void insertModifier(QString &item, int modifier) const;
         void insertState(QString &item, int state) const;
         QByteArray unescape(const QByteArray &text) const;
 
         int _keyCode;
         Qt::KeyboardModifiers _modifiers;
         Qt::KeyboardModifiers _modifierMask;
         States _state;
         States _stateMask;
 
         Command _command;
         QByteArray _text;
     };
 
     /** Constructs a new keyboard translator with the given @p name */
     KeyboardTranslator(const QString &name);
 
     // KeyboardTranslator(const KeyboardTranslator& other);
 
     /** Returns the name of this keyboard translator */
     QString name() const;
 
     /** Sets the name of this keyboard translator */
     void setName(const QString &name);
 
     /** Returns the descriptive name of this keyboard translator */
     QString description() const;
 
     /** Sets the descriptive name of this keyboard translator */
     void setDescription(const QString &description);
 
     /**
      * Looks for an entry in this keyboard translator which matches the given
      * key code, keyboard modifiers and state flags.
      *
      * Returns the matching entry if found or a null Entry otherwise ( ie.
      * entry.isNull() will return true )
      *
      * @param keyCode A key code from the Qt::Key enum
      * @param modifiers A combination of modifiers
      * @param state Optional flags which specify the current state of the terminal
      */
     Entry findEntry(int keyCode, Qt::KeyboardModifiers modifiers, States state = NoState) const;
 
     /**
      * Adds an entry to this keyboard translator's table.  Entries can be looked up according
      * to their key sequence using findEntry()
      */
     void addEntry(const Entry &entry);
 
     /**
      * Replaces an entry in the translator.  If the @p existing entry is null,
      * then this is equivalent to calling addEntry(@p replacement)
      */
     void replaceEntry(const Entry &existing, const Entry &replacement);
 
     /**
      * Removes an entry from the table.
      */
     void removeEntry(const Entry &entry);
 
     /** Returns a list of all entries in the translator. */
     QList<Entry> entries() const;
 
     /** The modifier code for the actual Ctrl key on this OS. */
     static const Qt::KeyboardModifier CTRL_MOD;
 
 private:
     QMultiHash<int, Entry> _entries; // entries in this keyboard translation,
                                      // entries are indexed according to
                                      // their keycode
     QString _name;
     QString _description;
 };
 Q_DECLARE_OPERATORS_FOR_FLAGS(KeyboardTranslator::States)
 Q_DECLARE_OPERATORS_FOR_FLAGS(KeyboardTranslator::Commands)
 
 /**
  * Parses the contents of a Keyboard Translator (.keytab) file and
  * returns the entries found in it.
  *
  * Usage example:
  *
  * @code
  *  QFile source( "/path/to/keytab" );
  *  source.open( QIODevice::ReadOnly );
  *
  *  KeyboardTranslator* translator = new KeyboardTranslator( "name-of-translator" );
  *
  *  KeyboardTranslatorReader reader(source);
  *  while ( reader.hasNextEntry() )
  *      translator->addEntry(reader.nextEntry());
  *
  *  source.close();
  *
  *  if ( !reader.parseError() )
  *  {
  *      // parsing succeeded, do something with the translator
  *  }
  *  else
  *  {
  *      // parsing failed
  *  }
  * @endcode
  */
 class KeyboardTranslatorReader
 {
 public:
     /** Constructs a new reader which parses the given @p source */
     KeyboardTranslatorReader(QIODevice *source);
 
     /**
      * Returns the description text.
      * TODO: More documentation
      */
     QString description() const;
 
     /** Returns true if there is another entry in the source stream */
     bool hasNextEntry() const;
     /** Returns the next entry found in the source stream */
     KeyboardTranslator::Entry nextEntry();
 
     /**
      * Returns true if an error occurred whilst parsing the input or
      * false if no error occurred.
      */
     bool parseError();
 
     /**
      * Parses a condition and result string for a translator entry
      * and produces a keyboard translator entry.
      *
      * The condition and result strings are in the same format as in
      */
     static KeyboardTranslator::Entry createEntry(const QString &condition, const QString &result);
 
 private:
     struct Token {
         enum Type { TitleKeyword, TitleText, KeyKeyword, KeySequence, Command, OutputText };
         Type type;
         QString text;
     };
     QList<Token> tokenize(const QString &);
     void readNext();
     bool decodeSequence(const QString &,
                         int &keyCode,
                         Qt::KeyboardModifiers &modifiers,
                         Qt::KeyboardModifiers &modifierMask,
                         KeyboardTranslator::States &state,
                         KeyboardTranslator::States &stateFlags);
 
     static bool parseAsModifier(const QString &item, Qt::KeyboardModifier &modifier);
     static bool parseAsStateFlag(const QString &item, KeyboardTranslator::State &state);
     static bool parseAsKeyCode(const QString &item, int &keyCode);
     static bool parseAsCommand(const QString &text, KeyboardTranslator::Command &command);
 
     QIODevice *_source;
     QString _description;
     KeyboardTranslator::Entry _nextEntry;
     bool _hasNext;
 };
 
 /** Writes a keyboard translation to disk. */
 class KeyboardTranslatorWriter
 {
 public:
     /**
      * Constructs a new writer which saves data into @p destination.
      * The caller is responsible for closing the device when writing is complete.
      */
     KeyboardTranslatorWriter(QIODevice *destination);
     ~KeyboardTranslatorWriter();
 
     /**
      * Writes the header for the keyboard translator.
      * @param description Description of the keyboard translator.
      */
     void writeHeader(const QString &description);
     /** Writes a translator entry. */
     void writeEntry(const KeyboardTranslator::Entry &entry);
 
 private:
     QIODevice *_destination;
     QTextStream *_writer;
 };
 
 /**
  * Manages the keyboard translations available for use by terminal sessions,
  * see KeyboardTranslator.
  */
 class KONSOLEPRIVATE_EXPORT KeyboardTranslatorManager
 {
 public:
     /**
      * Constructs a new KeyboardTranslatorManager and loads the list of
      * available keyboard translations.
      *
      * The keyboard translations themselves are not loaded until they are
      * first requested via a call to findTranslator()
      */
     KeyboardTranslatorManager();
     ~KeyboardTranslatorManager();
 
     KeyboardTranslatorManager(const KeyboardTranslatorManager &) = delete;
     KeyboardTranslatorManager &operator=(const KeyboardTranslatorManager &) = delete;
 
     /**
      * Adds a new translator.  If a translator with the same name
      * already exists, it will be replaced by the new translator.
      *
      * TODO: More documentation.
      */
     void addTranslator(KeyboardTranslator *translator);
 
     /**
      * Deletes a translator.  Returns true on successful deletion or false otherwise.
      *
      * TODO: More documentation
      */
     bool deleteTranslator(const QString &name);
 
     /** Returns the default translator for Konsole. */
     const KeyboardTranslator *defaultTranslator();
 
     /**
      * Returns the keyboard translator with the given name or 0 if no translator
      * with that name exists.
      *
      * The first time that a translator with a particular name is requested,
      * the on-disk .keyboard file is loaded and parsed.
      */
     const KeyboardTranslator *findTranslator(const QString &name);
     /**
      * Returns a list of the names of available keyboard translators.
      *
      * The first time this is called, a search for available
      * translators is started.
      */
     QList<QString> allTranslators();
 
     /** Returns the global KeyboardTranslatorManager instance. */
     static KeyboardTranslatorManager *instance();
 
 private:
     static const QByteArray defaultTranslatorText;
 
     void findTranslators(); // locate the available translators
     KeyboardTranslator *loadTranslator(const QString &name); // loads the translator
                                                              // with the given name
     KeyboardTranslator *loadTranslator(QIODevice *device, const QString &name);
 
     bool saveTranslator(const KeyboardTranslator *translator);
     QString findTranslatorPath(const QString &name);
 
     QHash<QString, KeyboardTranslator *> _translators; // maps translator-name -> KeyboardTranslator
                                                        // instance
     bool _haveLoadedAll;
 };
 
 inline int KeyboardTranslator::Entry::keyCode() const
 {
     return _keyCode;
 }
 inline void KeyboardTranslator::Entry::setKeyCode(int keyCode)
 {
     _keyCode = keyCode;
 }
 
 inline void KeyboardTranslator::Entry::setModifiers(Qt::KeyboardModifiers modifier)
 {
     _modifiers = modifier;
 }
 inline Qt::KeyboardModifiers KeyboardTranslator::Entry::modifiers() const
 {
     return _modifiers;
 }
 
 inline void KeyboardTranslator::Entry::setModifierMask(Qt::KeyboardModifiers mask)
 {
     _modifierMask = mask;
 }
 inline Qt::KeyboardModifiers KeyboardTranslator::Entry::modifierMask() const
 {
     return _modifierMask;
 }
 
 inline bool KeyboardTranslator::Entry::isNull() const
 {
     return (*this == Entry());
 }
 
 inline void KeyboardTranslator::Entry::setCommand(Command command)
 {
     _command = command;
 }
 inline KeyboardTranslator::Command KeyboardTranslator::Entry::command() const
 {
     return _command;
 }
 
 inline void KeyboardTranslator::Entry::setText(const QByteArray &text)
 {
     _text = unescape(text);
 }
 inline int oneOrZero(int value)
 {
     return value ? 1 : 0;
 }
 inline QByteArray KeyboardTranslator::Entry::text(bool expandWildCards, Qt::KeyboardModifiers modifiers) const
 {
     QByteArray expandedText = _text;
 
     if (expandWildCards) {
         int modifierValue = 1;
         modifierValue += oneOrZero(modifiers & Qt::ShiftModifier);
         modifierValue += oneOrZero(modifiers & Qt::AltModifier) << 1;
         modifierValue += oneOrZero(modifiers & KeyboardTranslator::CTRL_MOD) << 2;
 
         for (int i = 0; i < _text.length(); i++) {
             if (expandedText[i] == '*')
                 expandedText[i] = '0' + modifierValue;
         }
     }
 
     return expandedText;
 }
 
 inline void KeyboardTranslator::Entry::setState(States state)
 {
     _state = state;
 }
 inline KeyboardTranslator::States KeyboardTranslator::Entry::state() const
 {
     return _state;
 }
 
 inline void KeyboardTranslator::Entry::setStateMask(States stateMask)
 {
     _stateMask = stateMask;
 }
 inline KeyboardTranslator::States KeyboardTranslator::Entry::stateMask() const
 {
     return _stateMask;
 }
 }
 
 Q_DECLARE_METATYPE(Konsole::KeyboardTranslator::Entry)
 Q_DECLARE_METATYPE(const Konsole::KeyboardTranslator *)
 
 #endif // KEYBOARDTRANSLATOR_H