src/KeyMap.h

   1 // -*- C++ -*-
   2 /**
   3  * \file KeyMap.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Lars Gullik Bjønnes
   8  * \author Jean-Marc Lasgouttes
   9  * \author John Levon
  10  *
  11  * Full author contact details are available in file CREDITS.
  12  */
  13
  14 #ifndef KEYMAP_H
  15 #define KEYMAP_H
  16
  17 #include "FuncRequest.h"
  18 #include "KeySequence.h"
  19
  20 #include "support/strfwd.h"
  21
  22 #include <memory>
  23 #include <vector>
  24
  25
  26 namespace lyx {
  27
  28 namespace support {
  29         class FileName;
  30 }
  31
  32 /// Defines key maps and actions for key sequences
  33 class KeyMap {
  34 public:
  35         enum ItemType {
  36                 System,         //< loaded from a bind file
  37                 UserBind,       //< \bind loaded from user.bind
  38                 UserUnbind,     //< \unbind loaded from user.bind, with corresponding
  39                                 //<    entry in system bind file
  40                 UserExtraUnbind //< \unbind loaded from user.bind, without
  41                                 //<    corresponding entry in system bind file.
  42         };
  43         enum BindReadType {
  44                 MissingOK,      //< It's OK if this file is missing.
  45                 Fallback,       //< If missing, fallback to default "cua". This should only
  46                                 //< be used when attempting to read the user-secified bind file.
  47                 Default         //< Report error and return.
  48         };
  49         /**
  50          * Bind/Unbind a key sequence to an action.
  51          * @return 0 on success, or position in string seq where error
  52          * occurs.
  53          * See KeySequence::parse for the syntax of the seq string
  54          */
  55         size_t bind(std::string const & seq, FuncRequest const & func);
  56         size_t unbind(std::string const & seq, FuncRequest const & func);
  57
  58         /**
  59          * Define/Undefine an action for a key sequence.
  60          * @param r internal recursion level
  61          */
  62         void bind(KeySequence * seq, FuncRequest const & func,
  63                     unsigned int r = 0);
  64         void unbind(KeySequence * seq, FuncRequest const & func,
  65                     unsigned int r = 0);
  66
  67
  68         /// returns the function bound to this key sequence, or:
  69         /// * FuncRequest::unknown if no binding exists for it;
  70         /// * FuncRequest::prefix if this is the start of longer keysequences
  71         /// @param r an internal recursion counter
  72         // FIXME Surely there's a better way to do that?
  73         FuncRequest getBinding(KeySequence const & seq, unsigned int r = 0);
  74
  75         /// clear all bindings
  76         void clear();
  77
  78         /** Parse a bind file. If a valid unbind_map is given, put \unbind
  79          * bindings to a separate KeyMap. This is used in the Shortcut preference
  80          * dialog where main and user bind files are loaded separately so \unbind
  81          * in user.bind can not nullify \bind in the master bind file.
  82          *
  83          * @param bind_file bind file
  84          * @param unbind_map pointer to a KeyMap that holds \unbind bindings
  85          * @param rt how to respond if the file can't be found
  86          * @param i18n whether to search in localized folders
  87          */
  88         bool read(std::string const & bind_file, KeyMap * unbind_map = 0,
  89                         BindReadType rt = Default, bool i18n = true);
  90
  91         /** write to a bind file.
  92          * @param append append to the bind_file instead of overwrite it
  93          * @param unbind use \unbind instead of \bind, indicating this KeyMap
  94          *        actually record unbind maps.
  95          */
  96         void write(std::string const & bind_file, bool append, bool unbind = false) const;
  97
  98         /**
  99          * print all available keysyms
 100          * @param forgui true if the string should use translations and
 101          *   special characters.
 102          */
 103         docstring const print(bool forgui) const;
 104
 105         /**
 106          * Look up a key press in the keymap.
 107          * @param key the keysym
 108          * @param mod the modifiers
 109          * @param seq the current key sequence so far
 110          * @return the action / LFUN_COMMAND_PREFIX / LFUN_UNKNOWN_ACTION
 111          */
 112         FuncRequest const &
 113                 lookup(KeySymbol const & key, KeyModifier mod, KeySequence * seq) const;
 114
 115         ///
 116         typedef std::vector<KeySequence> Bindings;
 117
 118         /// Given an action, find all keybindings.
 119         Bindings findBindings(FuncRequest const & func) const;
 120
 121         /// Given an action, print the keybindings.
 122         docstring printBindings(FuncRequest const & func,
 123                                 KeySequence::outputFormat format,
 124                                 bool const untranslated = false) const;
 125
 126         struct Binding {
 127                 Binding(FuncRequest const & r, KeySequence const & s, ItemType t)
 128                         : request(r), sequence(s), tag(t) {}
 129                 FuncRequest request;
 130                 KeySequence sequence;
 131                 KeyMap::ItemType tag;
 132         };
 133         typedef std::vector<Binding> BindingList;
 134         /**
 135          * Return all lfun and their associated bindings.
 136          * @param unbound list unbound (func without any keybinding) as well
 137          * @param tag an optional tag to indicate the source of the bindinglist
 138          */
 139         BindingList listBindings(bool unbound, ItemType tag = System) const;
 140
 141         /**
 142          *  Given an action, find the first 1-key binding (if it exists).
 143          *  The KeySymbol pointer is 0 is no key is found.
 144          *  [only used by the Qt/Mac frontend]
 145          */
 146         std::pair<KeySymbol, KeyModifier>
 147                 find1keybinding(FuncRequest const & func) const;
 148
 149         /**
 150          * Returns a string of the given keysym, with modifiers.
 151          * @param key the key as a keysym
 152          * @param mod the modifiers
 153          */
 154         static std::string const printKeySym(KeySymbol const & key,
 155                                              KeyModifier mod);
 156
 157 private:
 158         ///
 159         typedef std::pair<KeyModifier, KeyModifier> ModifierPair;
 160
 161         ///
 162         struct Key {
 163                 /// Keysym
 164                 KeySymbol code;
 165                 /// Modifier masks
 166                 ModifierPair mod;
 167                 /// Keymap for prefix keys
 168                 std::shared_ptr<KeyMap> prefixes;
 169                 /// Action for !prefix keys
 170                 FuncRequest func;
 171         };
 172
 173         enum ReturnValues {
 174                 ReadOK,
 175                 ReadError,
 176                 FileError,
 177                 FormatMismatch
 178         };
 179         ///
 180         bool read(support::FileName const & bind_file, KeyMap * unbind_map = 0);
 181         ///
 182         ReturnValues readWithoutConv(support::FileName const & bind_file, KeyMap * unbind_map = 0);
 183
 184         /**
 185          * Given an action, find all keybindings
 186          * @param func the action
 187          * @param prefix a sequence to prepend the results
 188          */
 189         Bindings findBindings(FuncRequest const & func,
 190                               KeySequence const & prefix) const;
 191
 192         void listBindings(BindingList & list, KeySequence const & prefix,
 193                           ItemType tag) const;
 194
 195         /// is the table empty ?
 196         bool empty() const { return table.empty(); }
 197         ///
 198         typedef std::vector<Key> Table;
 199         ///
 200         Table table;
 201 };
 202
 203 /// Implementation is in LyX.cpp
 204 extern KeyMap & theTopLevelKeymap();
 205
 206
 207 } // namespace lyx
 208
 209 #endif // KEYMAP_H