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 <boost/shared_ptr.hpp>
  23
  24 #include <vector>
  25
  26
  27 namespace lyx {
  28
  29 /// Defines key maps and actions for key sequences
  30 class KeyMap {
  31 public:
  32         enum ItemType {
  33                 System,         //< loaded from a bind file
  34                 UserBind,       //< \bind loaded from user.bind
  35                 UserUnbind,     //< \unbind loaded from user.bind, with corresponding
  36                                 //<    entry in system bind file
  37                 UserExtraUnbind //< \unbind loaded from user.bind, without
  38                                 //<    corresponding entry in system bind file.
  39         };
  40         /**
  41          * Bind/Unbind a key sequence to an action.
  42          * @return 0 on success, or position in string seq where error
  43          * occurs.
  44          * See KeySequence::parse for the syntax of the seq string
  45          */
  46         size_t bind(std::string const & seq, FuncRequest const & func);
  47         size_t unbind(std::string const & seq, FuncRequest const & func);
  48
  49         /**
  50          * Define/Undefine an action for a key sequence.
  51          * @param r internal recursion level
  52          */
  53         void bind(KeySequence * seq, FuncRequest const & func,
  54                     unsigned int r = 0);
  55         void unbind(KeySequence * seq, FuncRequest const & func,
  56                     unsigned int r = 0);
  57
  58
  59         /// returns the function bound to this key sequence, or
  60         /// FuncRequest::unknown if no binding exists for it.
  61         /// @param r an internal recursion counter
  62         // FIXME Surely there's a better way to do that?
  63         FuncRequest getBinding(KeySequence const & seq, unsigned int r = 0);
  64
  65         /// clear all bindings
  66         void clear();
  67
  68         /** Parse a bind file. If a valid unbind_map is given, put \unbind
  69          * bindings to a separate KeyMap. This is used in the Shortcut preference
  70          * dialog where main and user bind files are loaded separately so \unbind
  71          * in user.bind can not nullify \bind in the master bind file.
  72          *
  73          * @param bind_file bind file
  74          * @param unbind_map pointer to a KeyMap that holds \unbind bindings
  75          */
  76         bool read(std::string const & bind_file, KeyMap * unbind_map = 0);
  77
  78         /** write to a bind file.
  79          * @param append append to the bind_file instead of overwrite it
  80          * @param unbind use \unbind instead of \bind, indicating this KeyMap
  81          *        actually record unbind maps.
  82          */
  83         void write(std::string const & bind_file, bool append, bool unbind = false) const;
  84
  85         /**
  86          * print all available keysyms
  87          * @param forgui true if the string should use translations and
  88          *   special characters.
  89          */
  90         docstring const print(bool forgui) const;
  91
  92         /**
  93          * Look up a key press in the keymap.
  94          * @param key the keysym
  95          * @param mod the modifiers
  96          * @param seq the current key sequence so far
  97          * @return the action / LFUN_COMMAND_PREFIX / LFUN_UNKNOWN_ACTION
  98          */
  99         FuncRequest const &
 100                 lookup(KeySymbol const & key, KeyModifier mod, KeySequence * seq) const;
 101
 102         ///
 103         typedef std::vector<KeySequence> Bindings;
 104
 105         /// Given an action, find all keybindings.
 106         Bindings findBindings(FuncRequest const & func) const;
 107
 108         /// Given an action, print the keybindings.
 109         docstring printBindings(FuncRequest const & func,
 110                                 KeySequence::outputFormat format) const;
 111
 112         struct Binding {
 113                 Binding(FuncRequest const & r, KeySequence const & s, ItemType t)
 114                         : request(r), sequence(s), tag(t) {}
 115                 FuncRequest request;
 116                 KeySequence sequence;
 117                 KeyMap::ItemType tag;
 118         };
 119         typedef std::vector<Binding> BindingList;
 120         /**
 121          * Return all lfun and their associated bindings.
 122          * @param unbound list unbound (func without any keybinding) as well
 123          * @param tag an optional tag to indicate the source of the bindinglist
 124          */
 125         BindingList listBindings(bool unbound, ItemType tag = System) const;
 126
 127         /**
 128          *  Given an action, find the first 1-key binding (if it exists).
 129          *  The KeySymbol pointer is 0 is no key is found.
 130          *  [only used by the Qt/Mac frontend]
 131          */
 132         std::pair<KeySymbol, KeyModifier>
 133                 find1keybinding(FuncRequest const & func) const;
 134
 135         /**
 136          * Returns a string of the given keysym, with modifiers.
 137          * @param key the key as a keysym
 138          * @param mod the modifiers
 139          */
 140         static std::string const printKeySym(KeySymbol const & key,
 141                                              KeyModifier mod);
 142
 143 private:
 144         ///
 145         typedef std::pair<KeyModifier, KeyModifier> ModifierPair;
 146
 147         ///
 148         struct Key {
 149                 /// Keysym
 150                 KeySymbol code;
 151                 /// Modifier masks
 152                 ModifierPair mod;
 153                 /// Keymap for prefix keys
 154                 boost::shared_ptr<KeyMap> prefixes;
 155                 /// Action for !prefix keys
 156                 FuncRequest func;
 157         };
 158
 159         /**
 160          * Given an action, find all keybindings
 161          * @param func the action
 162          * @param prefix a sequence to prepend the results
 163          */
 164         Bindings findBindings(FuncRequest const & func,
 165                               KeySequence const & prefix) const;
 166
 167         void listBindings(BindingList & list, KeySequence const & prefix,
 168                           ItemType tag) const;
 169
 170         /// is the table empty ?
 171         bool empty() const { return table.empty(); }
 172         ///
 173         typedef std::vector<Key> Table;
 174         ///
 175         Table table;
 176 };
 177
 178 /// Implementation is in LyX.cpp
 179 extern KeyMap & theTopLevelKeymap();
 180
 181
 182 } // namespace lyx
 183
 184 #endif // KEYMAP_H