From 2b4d55804c2ba5c6764db6af3353373376694cef Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Tue, 11 May 2021 08:39:13 +0530
Subject: [PATCH] Document the mouse action mapping infrastructure

---
 docs/changelog.rst       |  5 +++-
 docs/index.rst           |  3 +++
 kitty/conf/definition.py | 20 +++++++--------
 kitty/config_data.py     | 53 ++++++++++++++++++++++++++++------------
 4 files changed, 54 insertions(+), 27 deletions(-)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 448382983..84b15ac2c 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -4,9 +4,12 @@ Changelog
 |kitty| is a feature-rich, cross-platform, *fast*, GPU based terminal.
 To update |kitty|, :doc:`follow the instructions <binary>`.
 
-0.20.4 [future]
+0.21.0 [future]
 ----------------------
 
+- Allow remapping all mouse button press/release events to perform arbitrary
+  actions. :ref:`See details <conf-kitty-mouse.mousemap>`.
+
 - Support infinite length ligatures (:iss:`3504`)
 
 - Unicode input kitten: Fix a regression in 0.20.0 that broke keyboard handling
diff --git a/docs/index.rst b/docs/index.rst
index 2522295e4..508b26851 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -272,6 +272,9 @@ Mouse features
 * You can select text with kitty even when a terminal program has grabbed
   the mouse by holding down the :kbd:`shift` key.
 
+All these actions can be customized in :file:`kitty.conf` as described
+:ref:`here <conf-kitty-mouse.mousemap>`.
+
 
 Font control
 -----------------
diff --git a/kitty/conf/definition.py b/kitty/conf/definition.py
index d13afe366..24de39192 100644
--- a/kitty/conf/definition.py
+++ b/kitty/conf/definition.py
@@ -255,27 +255,27 @@ def as_conf_file(all_options: Iterable[OptionOrAction]) -> List[str]:
     ans = ['# vim:fileencoding=utf-8:ft=conf:foldmethod=marker', '']
     a = ans.append
     current_group: Optional[Group] = None
-    num_open_folds = 0
+    group_folds = []
     all_options_ = list(all_options)
 
     def render_group(group: Group, is_shortcut: bool) -> None:
-        nonlocal num_open_folds
-        if is_shortcut or '.' not in group.name:
-            a('#: ' + group.short_text + ' {{''{')
-            num_open_folds += 1
+        a('#: ' + group.short_text + ' {{''{')
+        group_folds.append(group.name)
         a('')
         if group.start_text:
             a(render_block(group.start_text))
             a('')
 
     def handle_group_end(group: Group, new_group_name: str = '', new_group_is_shortcut: bool = False) -> None:
-        nonlocal num_open_folds
         if group.end_text:
             a(''), a(render_block(group.end_text))
         is_subgroup = new_group_name.startswith(group.name + '.')
-        if not is_subgroup and num_open_folds > 0:
+        while group_folds:
+            is_subgroup = new_group_name.startswith(group_folds[-1] + '.')
+            if is_subgroup:
+                break
             a('#: }}''}'), a('')
-            num_open_folds -= 1
+            del group_folds[-1]
 
     def handle_group(new_group: Group, is_shortcut: bool = False) -> None:
         nonlocal current_group
@@ -314,9 +314,9 @@ def as_conf_file(all_options: Iterable[OptionOrAction]) -> List[str]:
 
     if current_group:
         handle_group_end(current_group)
-        while num_open_folds > 0:
+        while group_folds:
             a('# }}''}')
-            num_open_folds -= 1
+            del group_folds[-1]
 
     map_groups = []
     start: Optional[int] = None
diff --git a/kitty/config_data.py b/kitty/config_data.py
index c45d9b4aa..8dc5ddab1 100644
--- a/kitty/config_data.py
+++ b/kitty/config_data.py
@@ -139,8 +139,27 @@ as color16 to color255.''')
     ],
     'advanced': [_('Advanced')],
     'os': [_('OS specific tweaks')],
-    'mousemap': [
+    'mouse.mousemap': [
         _('Mouse actions'),
+        _('''\
+Mouse buttons can be remapped to perform arbitrary actions. The syntax for
+doing so is:
+
+.. code-block:: none
+
+    mouse_map button-name event-type modes action
+
+Where ``button-name`` is one of ``left``, ``middle``, ``right`` or ``b1 ... b8``
+with added keyboard modifiers, for example: ``ctrl+shift+left`` refers to holding
+the :kbd:`ctrl+shift` keys while clicking with the left mouse button. The
+number ``b1 ... b8`` can be used to refer to upto eight buttons on a mouse.
+
+``event-type`` is one ``press``, ``release``, ``doublepress`` and ``triplepress``.
+``modes`` indicates whether the action is performed when the mouse is grabbed by the
+terminal application or not. It can have one or more or the values, ``grabbed,ungrabbed``.
+
+See the builtin actions below to get a sense of what is possible.
+'''),
     ],
     'shortcuts': [
         _('Keyboard shortcuts'),
@@ -637,6 +656,23 @@ The default shape of the mouse pointer when dragging across text.
 Valid values are: :code:`arrow`, :code:`beam` and :code:`hand`
 '''))
 
+g('mouse.mousemap')  # {{{
+
+m('click_url', 'ctrl+shift+left', 'release', 'grabbed,ungrabbed', 'mouse_click_url', _('Click the link under the mouse cursor'))
+m('paste_selection', 'middle', 'release', 'grabbed,ungrabbed', 'paste_selection', _('Paste from the primary selection'))
+m('extend_selection', 'right', 'press', 'grabbed,ungrabbed', 'mouse_selection extend', _('Extend the current selection'))
+for grabbed in (False, True):
+    modes = 'ungrabbed' + (',grabbed' if grabbed else '')
+    name_s = '_grabbed' if grabbed else ''
+    mods_p = 'shift+' if grabbed else ''
+    ts = _(' even when grabbed') if grabbed else ''
+    m('start_simple_selection' + name_s, mods_p + 'left', 'press', modes, 'mouse_selection normal', _('Start selecting text') + ts)
+    m('start_rectangle_selection' + name_s, mods_p + 'ctrl+alt+left', 'press', modes, 'mouse_selection rectangle',
+      _('Start selecting text in a rectangle') + ts)
+    m('select_word' + name_s, mods_p + 'left', 'doublepress', modes, 'mouse_selection word', _('Select a word') + ts)
+    m('select_line' + name_s, mods_p + 'left', 'triplepress', modes, 'mouse_selection line', _('Select a line') + ts)
+# }}}
+
 # }}}
 
 g('performance')  # {{{
@@ -1343,21 +1379,6 @@ automatically. Set it to :code:`x11` or :code:`wayland`
 to force the choice.'''))
 # }}}
 
-g('mousemap')  # {{{
-
-m('click_url', 'ctrl+shift+left', 'release', 'grabbed,ungrabbed', 'mouse_click_url', _('Click the link under the mouse cursor'))
-m('paste_selection', 'middle', 'release', 'grabbed,ungrabbed', 'paste_selection', _('Paste from the primary selection'))
-m('extend_selection', 'right', 'press', 'grabbed,ungrabbed', 'mouse_selection extend', _('Extend the current selection'))
-for grabbed in (False, True):
-    modes = 'ungrabbed' + (',grabbed' if grabbed else '')
-    name_s = '_grabbed' if grabbed else ''
-    mods_p = 'shift+' if grabbed else ''
-    m('start_simple_selection' + name_s, mods_p + 'left', 'press', modes, 'mouse_selection normal', _('Start selecting text'))
-    m('start_rectangle_selection' + name_s, mods_p + 'ctrl+alt+left', 'press', modes, 'mouse_selection rectangle',
-      _('Start selecting text in a rectangle'))
-    m('select_word' + name_s, mods_p + 'left', 'doublepress', modes, 'mouse_selection word', _('Select a word'))
-    m('select_line' + name_s, mods_p + 'left', 'triplepress', modes, 'mouse_selection line', _('Select a line'))
-# }}}
 
 g('shortcuts')  # {{{