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