<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/config/mouse.md - fork/wezterm @ termwiz-0.23.3</title>
<meta name="description" content="docs/config/mouse.md in fork/wezterm at termwiz-0.23.3.">
<meta property="og:title" content="docs/config/mouse.md - fork/wezterm @ termwiz-0.23.3">
<meta property="og:description" content="docs/config/mouse.md in fork/wezterm at termwiz-0.23.3.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="termwiz-0.23.3" data-tip="4bf28e253c0167102f07bfc7e7199c13eed98012">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/wezterm</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/wezterm</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Wez Furlong</span><span class="commit-message" data-commit="84f7fb9f3b0deb192d45ee36257e5f329584b1fc">docs: add tags to a number of pages</span><span class="snapshot-sha sha" data-commit="84f7fb9f3b0deb192d45ee36257e5f329584b1fc">84f7fb9f3</span><time datetime="2023-04-08T07:48:40-07:00" title="2023-04-08 07:48:40 -0700">2023-04-08</time></p>
<header class="topbar"><details class="switcher"><summary>termwiz-0.23.3</summary><div class="menu"><strong>branches</strong><a href="/fork/wezterm/ref/main/">main</a><strong>tags</strong><a href="/fork/wezterm/ref/termiz-0.23.1/">termiz-0.23.1</a><a href="/fork/wezterm/ref/termiz-0.23.2/">termiz-0.23.2</a><a href="/fork/wezterm/ref/termiz-0.23.3/">termiz-0.23.3</a><a href="/fork/wezterm/ref/termwiz-0.23.0/">termwiz-0.23.0</a><a href="/fork/wezterm/ref/termwiz-0.23.1/">termwiz-0.23.1</a><a href="/fork/wezterm/ref/termwiz-0.23.2/">termwiz-0.23.2</a><a class="current" href="/fork/wezterm/ref/termwiz-0.23.3/">termwiz-0.23.3</a><a href="/fork/wezterm/ref/vtparse-0.7.0/">vtparse-0.7.0</a><a class="all" href="/fork/wezterm/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/wezterm/">wezterm</a> / <a href="/fork/wezterm/ref/termwiz-0.23.3/tree/docs/">docs</a> / <a href="/fork/wezterm/ref/termwiz-0.23.3/tree/docs/config/">config</a> / <span class="cur">mouse.md</span></nav>
<span class="view-stats"><span>9.4 KiB</span><span>229 lines</span></span><span class="actions"><a class="raw" href="/fork/wezterm/raw/8cd52632e6f790042f42fef4cd26d1165f9bfcc7/docs/config/mouse.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><hr />
<p>tags:</p>
<ul>
<li>mouse</li>
</ul>
<hr />
<p>Mouse bindings are configurable, and there are a number of default assignments
described below.</p>
<p>The assignments are based around a triggering mouse event which may be combined
with a set of modifier keys to produce an action.</p>
<p>By default applications running in the terminal don't respond to the mouse.
However, applications can emit escape sequences to request mouse event tracking.
When mouse event tracking is enabled, mouse events are NOT matched against
the mouse assignments and are instead passed through to the application.</p>
<p>You can bypass the mouse reporting capture by holding down the <code>SHIFT</code> key;
that will prevent the event from being passed to the application and allow matching
it against your assignments as though the <code>SHIFT</code> key were not pressed.</p>
<p>The <a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/lua/config/bypass_mouse_reporting_modifiers.md">bypass_mouse_reporting_modifiers</a>
option allows you to specify an alternative set of modifiers to use for
bypassing mouse reporting capture.</p>
<h2>Default Mouse Assignments</h2>
<p><em>Note: you can run <code>wezterm show-keys</code> to show the effective key and mouse assignments</em>.</p>
<p>In the table below, <code>Triple Left Down</code> means that the left mouse button is
being triple clicked and that the event matches the downstroke of the third
quick consecutive press.  <code>Triple Left Up</code> matches the subsequent release event
of that triple click, so for a triple click both
<code>SelectTextAtMouseCursor="Line"</code> and <code>CompleteSelection</code> will be triggered in
that order.</p>
<p>NOTE: In the action column, <code>act</code> is an alias to <code>wezterm.action</code> (to avoid repetition):</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>act</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v></pre>
<table><thead><tr><th>Event</th><th>Modifiers</th><th>Action</th></tr></thead><tbody>
<tr><td>Triple Left Down</td><td><code>NONE</code></td><td><code>act.SelectTextAtMouseCursor("Line")</code></td></tr>
<tr><td>Double Left Down</td><td><code>NONE</code></td><td><code>act.SelectTextAtMouseCursor("Word")</code></td></tr>
<tr><td>Single Left Down</td><td><code>NONE</code></td><td><code>act.SelectTextAtMouseCursor("Cell")</code></td></tr>
<tr><td>Single Left Down</td><td><code>SHIFT</code></td><td><code>act.ExtendSelectionToMouseCursor("Cell")</code></td></tr>
<tr><td>Single Left Down</td><td><code>ALT</code></td><td><code>act.SelectTextAtMouseCursor("Block")</code>  {{since('20220624-141144-bd1b7c5d', inline=True)}}</td></tr>
<tr><td>Single Left Up</td><td><code>SHIFT</code></td><td><code>act.CompleteSelectionOrOpenLinkAtMouseCursor("ClipboardAndPrimarySelection")</code></td></tr>
<tr><td>Single Left Up</td><td><code>NONE</code></td><td><code>act.CompleteSelectionOrOpenLinkAtMouseCursor("ClipboardAndPrimarySelection")</code></td></tr>
<tr><td>Single Left Up</td><td><code>ALT</code></td><td><code>act.CompleteSelection("ClipboardAndPrimarySelection")</code>  {{since('20220624-141144-bd1b7c5d', inline=True)}}</td></tr>
<tr><td>Double Left Up</td><td><code>NONE</code></td><td><code>act.CompleteSelection("ClipboardAndPrimarySelection")</code></td></tr>
<tr><td>Triple Left Up</td><td><code>NONE</code></td><td><code>act.CompleteSelection("ClipboardAndPrimarySelection")</code></td></tr>
<tr><td>Single Left Drag</td><td><code>NONE</code></td><td><code>act.ExtendSelectionToMouseCursor("Cell")</code></td></tr>
<tr><td>Single Left Drag</td><td><code>ALT</code></td><td><code>act.ExtendSelectionToMouseCursor("Block")</code> {{since('20220624-141144-bd1b7c5d', inline=True)}}</td></tr>
<tr><td>Single Left Down</td><td><code>ALT+SHIFT</code></td><td><code>act.ExtendSelectionToMouseCursor("Block")</code>  {{since('20220624-141144-bd1b7c5d', inline=True)}}</td></tr>
<tr><td>Single Left Up</td><td><code>ALT+SHIFT</code></td><td><code>act.CompleteSelection("ClipboardAndPrimarySelection")</code>  {{since('20220624-141144-bd1b7c5d', inline=True)}}</td></tr>
<tr><td>Double Left Drag</td><td><code>NONE</code></td><td><code>act.ExtendSelectionToMouseCursor("Word")</code></td></tr>
<tr><td>Triple Left Drag</td><td><code>NONE</code></td><td><code>act.ExtendSelectionToMouseCursor("Line")</code></td></tr>
<tr><td>Single Middle Down</td><td><code>NONE</code></td><td><code>act.PasteFrom("PrimarySelection")</code></td></tr>
<tr><td>Single Left Drag</td><td><code>SUPER</code></td><td><code>act.StartWindowDrag</code> (<em>since 20210314-114017-04b7cedd</em>)</td></tr>
<tr><td>Single Left Drag</td><td><code>CTRL+SHIFT</code></td><td><code>act.StartWindowDrag</code> (<em>since 20210314-114017-04b7cedd</em>)</td></tr>
</tbody></table>
<p>If you don't want the default assignments to be registered, you can
disable all of them with this configuration; if you chose to do this,
you must explicitly register every binding.</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>disable_default_mouse_bindings</a-v> = <a-co>true</a-co></pre>
<h2>Configuring Mouse Assignments</h2>
<p>{{since('20200607-144723-74889cd4')}}</p>
<p>You can define mouse actions using the <code>mouse_bindings</code> configuration section:</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>wezterm</a-v> = <a-f>require</a-f> <a-s>&#39;wezterm&#39;</a-s>
<a-k>local</a-k> <a-v>act</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v>
<a-k>local</a-k> <a-v>config</a-v> = <a-cr>{}</a-cr>

<a-v>config</a-v><a-p>.</a-p><a-v>mouse_bindings</a-v> = <a-cr>{</a-cr>
  <a-c>-- Right click sends &quot;woot&quot; to the terminal</a-c>
  <a-cr>{</a-cr>
    <a-v>event</a-v> = <a-cr>{</a-cr> <a-v>Down</a-v> = <a-cr>{</a-cr> <a-v>streak</a-v> = <a-n>1</a-n><a-p>,</a-p> <a-v>button</a-v> = <a-s>&#39;Right&#39;</a-s> <a-cr>}</a-cr> <a-cr>}</a-cr><a-p>,</a-p>
    <a-v>mods</a-v> = <a-s>&#39;NONE&#39;</a-s><a-p>,</a-p>
    <a-v>action</a-v> = <a-v>act</a-v><a-p>.</a-p><a-f>SendString</a-f> <a-s>&#39;woot&#39;</a-s><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>

  <a-c>-- Change the default click behavior so that it only selects</a-c>
  <a-c>-- text and doesn&#39;t open hyperlinks</a-c>
  <a-cr>{</a-cr>
    <a-v>event</a-v> = <a-cr>{</a-cr> <a-v>Up</a-v> = <a-cr>{</a-cr> <a-v>streak</a-v> = <a-n>1</a-n><a-p>,</a-p> <a-v>button</a-v> = <a-s>&#39;Left&#39;</a-s> <a-cr>}</a-cr> <a-cr>}</a-cr><a-p>,</a-p>
    <a-v>mods</a-v> = <a-s>&#39;NONE&#39;</a-s><a-p>,</a-p>
    <a-v>action</a-v> = <a-v>act</a-v><a-p>.</a-p><a-f>CompleteSelection</a-f> <a-s>&#39;ClipboardAndPrimarySelection&#39;</a-s><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>

  <a-c>-- and make CTRL-Click open hyperlinks</a-c>
  <a-cr>{</a-cr>
    <a-v>event</a-v> = <a-cr>{</a-cr> <a-v>Up</a-v> = <a-cr>{</a-cr> <a-v>streak</a-v> = <a-n>1</a-n><a-p>,</a-p> <a-v>button</a-v> = <a-s>&#39;Left&#39;</a-s> <a-cr>}</a-cr> <a-cr>}</a-cr><a-p>,</a-p>
    <a-v>mods</a-v> = <a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p>
    <a-v>action</a-v> = <a-v>act</a-v><a-p>.</a-p><a-v>OpenLinkAtMouseCursor</a-v><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
  <a-c>-- NOTE that binding only the &#39;Up&#39; event can give unexpected behaviors.</a-c>
  <a-c>-- Read more below on the gotcha of binding an &#39;Up&#39; event only.</a-c>
<a-cr>}</a-cr>

<a-k>return</a-k> <a-v>config</a-v></pre>
<p>Each entry in the mouse binding table can have the following fields:</p>
<ul>
<li><code>event</code> - the mouse event on which to trigger. Described in detail below.</li>
<li><code>mods</code> - the keyboard modifier keys that must be active in order to match the event.
<code>mods</code> have the same definition and meaning as for key assignments and are described
in more detail in <a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/keys.md#configuring-key-assignments">Configuring Key Assignments</a>.</li>
<li><code>action</code> - the action to take when this mouse binding is matched</li>
<li><code>mouse_reporting</code> - an optional boolean that defaults to <code>false</code>. This mouse binding
entry will only be considered if the current pane's mouse reporting state matches.
In general, you should avoid defining assignments that have
<code>mouse_reporting=true</code> as it will prevent the application running in the
pane from receiving that mouse event.  You can, of course, define these and
still send your mouse event to the pane by holding down the configured
<a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/lua/config/bypass_mouse_reporting_modifiers.md">mouse reporting bypass modifier
key</a>. {{since('20220807-113146-c2fee766', inline=True)}}</li>
<li><code>alt_screen</code> - an optional field that defaults to <code>'Any'</code>, but that can also
be set to either <code>true</code> or <code>false</code>. This mouse binding entry will only be
considered if the current pane's alt screen state matches this field.  Most
of the default mouse assignments are defined as <code>alt_screen='Any'</code>, a notable
exception being that mouse wheel scrolling only applies when
<code>alt_screen=false</code>, as the mouse wheel is typically mapped to arrow keys by
the terminal in alt screen mode. {{since('20220807-113146-c2fee766', inline=True)}}.</li>
</ul>
<p>The <code>action</code> and <code>mods</code> portions are described in more detail in the key assignment
information below.</p>
<p>The <code>event</code> portion has three components:</p>
<ul>
<li>Whether it is a <code>Down</code>, <code>Up</code> or <code>Drag</code> event</li>
<li>The number of consecutive clicks within the click threshold (the <em>click streak</em>)</li>
<li>The mouse button; <code>Left</code>, <code>Right</code>, or <code>Middle</code>.</li>
</ul>
<p>A double click is a <code>down-up-down</code> sequence where either the second button down
is held for long enough or is released and no subsequent down event occurs
within the click threshold.  When recognized, it emits a <code>Down</code> event with
<code>streak=2</code>.  If the mouse is moved while the button is held, a <code>Drag</code> event
with <code>streak=2</code> is generated.  When the mouse button is released an <code>Up</code> event
with <code>streak=2</code> is generated.</p>
<p>The mouse event recognizer supports an arbitrary click streak, so if
you wanted quadruple-click bindings you can specify <code>streak=4</code>.</p>
<table><thead><tr><th>Event</th><th>Lua Representation</th></tr></thead><tbody>
<tr><td>Triple Left Down</td><td><code>event={Down={streak=3, button="Left"}}</code></td></tr>
<tr><td>Double Left Up</td><td><code>event={Up={streak=2, button="Left"}}</code></td></tr>
<tr><td>Single Left Drag</td><td><code>event={Drag={streak=1, button="Left"}}</code></td></tr>
</tbody></table>
<p>{{since('20220807-113146-c2fee766')}}</p>
<p>You can handle vertical wheel scroll events using the example shown below. The
<code>streak</code> and amount associated with either <code>WheelUp</code> or <code>WheelDown</code> are set to
<code>1</code> for the sake of simplicity of matching the event; you may use
<a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/lua/window/current_event.md"><code>window:current_event</code></a>, if to access the actual
delta scroll value while handling the event.</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>wezterm</a-v> = <a-f>require</a-f> <a-s>&#39;wezterm&#39;</a-s>
<a-k>local</a-k> <a-v>act</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v>
<a-k>local</a-k> <a-v>config</a-v> = <a-cr>{}</a-cr>

<a-v>config</a-v><a-p>.</a-p><a-v>mouse_bindings</a-v> = <a-cr>{</a-cr>
  <a-c>-- Scrolling up while holding CTRL increases the font size</a-c>
  <a-cr>{</a-cr>
    <a-v>event</a-v> = <a-cr>{</a-cr> <a-v>Down</a-v> = <a-cr>{</a-cr> <a-v>streak</a-v> = <a-n>1</a-n><a-p>,</a-p> <a-v>button</a-v> = <a-cr>{</a-cr> <a-v>WheelUp</a-v> = <a-n>1</a-n> <a-cr>}</a-cr> <a-cr>}</a-cr> <a-cr>}</a-cr><a-p>,</a-p>
    <a-v>mods</a-v> = <a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p>
    <a-v>action</a-v> = <a-v>act</a-v><a-p>.</a-p><a-v>IncreaseFontSize</a-v><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>

  <a-c>-- Scrolling down while holding CTRL decreases the font size</a-c>
  <a-cr>{</a-cr>
    <a-v>event</a-v> = <a-cr>{</a-cr> <a-v>Down</a-v> = <a-cr>{</a-cr> <a-v>streak</a-v> = <a-n>1</a-n><a-p>,</a-p> <a-v>button</a-v> = <a-cr>{</a-cr> <a-v>WheelDown</a-v> = <a-n>1</a-n> <a-cr>}</a-cr> <a-cr>}</a-cr> <a-cr>}</a-cr><a-p>,</a-p>
    <a-v>mods</a-v> = <a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p>
    <a-v>action</a-v> = <a-v>act</a-v><a-p>.</a-p><a-v>DecreaseFontSize</a-v><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr>

<a-k>return</a-k> <a-v>config</a-v></pre>
<h1>Gotcha on binding an 'Up' event only</h1>
<p>If you only have a mouse bind on the 'Up' event and not on the 'Down' event,
the 'Down' event will still be sent to the running program.
If that program is tracking mouse inputs (like tmux or vim with mouse support),
you may experience <em>unintuitive behavior</em> as the program receives the 'Down'
event, but not the 'Up' event (which is bound to something in your config).</p>
<p>To avoid this, it is recommended to disable the 'Down' event (to ensure it won't
be sent to the running program), for example:</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>wezterm</a-v> = <a-f>require</a-f> <a-s>&#39;wezterm&#39;</a-s>
<a-k>local</a-k> <a-v>act</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v>
<a-k>local</a-k> <a-v>config</a-v> = <a-cr>{}</a-cr>

<a-v>config</a-v><a-p>.</a-p><a-v>mouse_bindings</a-v> = <a-cr>{</a-cr>
  <a-c>-- Bind &#39;Up&#39; event of CTRL-Click to open hyperlinks</a-c>
  <a-cr>{</a-cr>
    <a-v>event</a-v> = <a-cr>{</a-cr> <a-v>Up</a-v> = <a-cr>{</a-cr> <a-v>streak</a-v> = <a-n>1</a-n><a-p>,</a-p> <a-v>button</a-v> = <a-s>&#39;Left&#39;</a-s> <a-cr>}</a-cr> <a-cr>}</a-cr><a-p>,</a-p>
    <a-v>mods</a-v> = <a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p>
    <a-v>action</a-v> = <a-v>act</a-v><a-p>.</a-p><a-v>OpenLinkAtMouseCursor</a-v><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
  <a-c>-- Disable the &#39;Down&#39; event of CTRL-Click to avoid weird program behaviors</a-c>
  <a-cr>{</a-cr>
    <a-v>event</a-v> = <a-cr>{</a-cr> <a-v>Down</a-v> = <a-cr>{</a-cr> <a-v>streak</a-v> = <a-n>1</a-n><a-p>,</a-p> <a-v>button</a-v> = <a-s>&#39;Left&#39;</a-s> <a-cr>}</a-cr> <a-cr>}</a-cr><a-p>,</a-p>
    <a-v>mods</a-v> = <a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p>
    <a-v>action</a-v> = <a-v>act</a-v><a-p>.</a-p><a-v>Nop</a-v><a-p>,</a-p>
  <a-cr>}</a-cr><a-p>,</a-p>
<a-cr>}</a-cr>
<a-k>return</a-k> <a-v>config</a-v></pre>
<h1>Available Actions</h1>
<p>See the <a href="lua/keyassignment/index.md"><code>KeyAssignment</code> reference</a> for information
on available actions.</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"><a-pr>tags</a-pr><a-p>:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">  <a-p>-</a-p> <a-s>mouse</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">Mouse bindings are configurable, and there are a number of default assignments</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">described below.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">The assignments are based around a triggering mouse event which may be combined</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">with a set of modifier keys to produce an action.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">By default applications running in the terminal don&#39;t respond to the mouse.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">However, applications can emit escape sequences to request mouse event tracking.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">When mouse event tracking is enabled, mouse events are NOT matched against</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">the mouse assignments and are instead passed through to the application.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">You can bypass the mouse reporting capture by holding down the `SHIFT` key;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">that will prevent the event from being passed to the application and allow matching</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">it against your assignments as though the `SHIFT` key were not pressed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">The [bypass_mouse_reporting_modifiers](lua/config/bypass_mouse_reporting_modifiers.md)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">option allows you to specify an alternative set of modifiers to use for</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">bypassing mouse reporting capture.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>##</a-p> <a-tt>Default Mouse Assignments</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">*Note: you can run `wezterm show-keys` to show the effective key and mouse assignments*.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">In the table below, `Triple Left Down` means that the left mouse button is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">being triple clicked and that the event matches the downstroke of the third</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">quick consecutive press.  `Triple Left Up` matches the subsequent release event</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">of that triple click, so for a triple click both</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">`SelectTextAtMouseCursor=&quot;Line&quot;` and `CompleteSelection` will be triggered in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">that order.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">NOTE: In the action column, `act` is an alias to `wezterm.action` (to avoid repetition):</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>local </a-p><a-v>act</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>| Event | Modifiers | Action |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>| --------- | --- | ------ |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>| Triple Left Down | `NONE`   | `act.SelectTextAtMouseCursor(&quot;Line&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>| Double Left Down | `NONE`   | `act.SelectTextAtMouseCursor(&quot;Word&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>| Single Left Down | `NONE`   | `act.SelectTextAtMouseCursor(&quot;Cell&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>| Single Left Down | `SHIFT`   | `act.ExtendSelectionToMouseCursor(&quot;Cell&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>| Single Left Down | `ALT`   | `act.SelectTextAtMouseCursor(&quot;Block&quot;)`  {{since(&#39;20220624-141144-bd1b7c5d&#39;, inline=True)}} |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>| Single Left Up | `SHIFT`   | `act.CompleteSelectionOrOpenLinkAtMouseCursor(&quot;ClipboardAndPrimarySelection&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>| Single Left Up | `NONE`   | `act.CompleteSelectionOrOpenLinkAtMouseCursor(&quot;ClipboardAndPrimarySelection&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>| Single Left Up | `ALT`   | `act.CompleteSelection(&quot;ClipboardAndPrimarySelection&quot;)`  {{since(&#39;20220624-141144-bd1b7c5d&#39;, inline=True)}} |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"><a-p>| Double Left Up | `NONE`   | `act.CompleteSelection(&quot;ClipboardAndPrimarySelection&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>| Triple Left Up | `NONE`   | `act.CompleteSelection(&quot;ClipboardAndPrimarySelection&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"><a-p>| Single Left Drag | `NONE`   | `act.ExtendSelectionToMouseCursor(&quot;Cell&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>| Single Left Drag | `ALT`   | `act.ExtendSelectionToMouseCursor(&quot;Block&quot;)` {{since(&#39;20220624-141144-bd1b7c5d&#39;, inline=True)}} |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>| Single Left Down | `ALT+SHIFT`   | `act.ExtendSelectionToMouseCursor(&quot;Block&quot;)`  {{since(&#39;20220624-141144-bd1b7c5d&#39;, inline=True)}} |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>| Single Left Up | `ALT+SHIFT`   | `act.CompleteSelection(&quot;ClipboardAndPrimarySelection&quot;)`  {{since(&#39;20220624-141144-bd1b7c5d&#39;, inline=True)}} |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"><a-p>| Double Left Drag | `NONE`   | `act.ExtendSelectionToMouseCursor(&quot;Word&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>| Triple Left Drag | `NONE`   | `act.ExtendSelectionToMouseCursor(&quot;Line&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"><a-p>| Single Middle Down | `NONE`   | `act.PasteFrom(&quot;PrimarySelection&quot;)`  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>| Single Left Drag | `SUPER` | `act.StartWindowDrag` (*since 20210314-114017-04b7cedd*) |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>| Single Left Drag | `CTRL+SHIFT` | `act.StartWindowDrag` (*since 20210314-114017-04b7cedd*) |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>If you don&#39;t want the default assignments to be registered, you can</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>disable all of them with this configuration; if you chose to do this,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>you must explicitly register every binding.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>config.</a-p><a-v>disable_default_mouse_bindings</a-v><a-p> = </a-p><a-co>true</a-co></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"><a-p>## </a-p><a-tt>Configuring Mouse Assignments</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-p>{{since(&#39;20200607-144723-74889cd4&#39;)}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>You can define mouse actions using the `mouse_bindings` configuration section:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"><a-p>local </a-p><a-v>wezterm</a-v><a-p> = </a-p><a-f>require</a-f><a-p> </a-p><a-s>&#39;wezterm&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-p>local </a-p><a-v>act</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"><a-p>local </a-p><a-v>config</a-v><a-p> = </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"><a-p>config.</a-p><a-v>mouse_bindings</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>  </a-p><a-c>-- Right click sends &quot;woot&quot; to the terminal</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"><a-p>    </a-p><a-v>event</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Down</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>streak</a-v><a-p> = </a-p><a-n>1</a-n><a-p>, </a-p><a-v>button</a-v><a-p> = </a-p><a-s>&#39;Right&#39;</a-s><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"><a-p>    </a-p><a-v>mods</a-v><a-p> = </a-p><a-s>&#39;NONE&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>    </a-p><a-v>action</a-v><a-p> = </a-p><a-v>act</a-v><a-p>.</a-p><a-f>SendString</a-f><a-p> </a-p><a-s>&#39;woot&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"><a-p>  </a-p><a-c>-- Change the default click behavior so that it only selects</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"><a-p>  </a-p><a-c>-- text and doesn&#39;t open hyperlinks</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"><a-p>    </a-p><a-v>event</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Up</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>streak</a-v><a-p> = </a-p><a-n>1</a-n><a-p>, </a-p><a-v>button</a-v><a-p> = </a-p><a-s>&#39;Left&#39;</a-s><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"><a-p>    </a-p><a-v>mods</a-v><a-p> = </a-p><a-s>&#39;NONE&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>    </a-p><a-v>action</a-v><a-p> = </a-p><a-v>act</a-v><a-p>.</a-p><a-f>CompleteSelection</a-f><a-p> </a-p><a-s>&#39;ClipboardAndPrimarySelection&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"><a-p>  </a-p><a-c>-- and make CTRL-Click open hyperlinks</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"><a-p>    </a-p><a-v>event</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Up</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>streak</a-v><a-p> = </a-p><a-n>1</a-n><a-p>, </a-p><a-v>button</a-v><a-p> = </a-p><a-s>&#39;Left&#39;</a-s><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"><a-p>    </a-p><a-v>mods</a-v><a-p> = </a-p><a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"><a-p>    </a-p><a-v>action</a-v><a-p> = </a-p><a-v>act</a-v><a-p>.</a-p><a-v>OpenLinkAtMouseCursor</a-v><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"><a-p>  </a-p><a-c>-- NOTE that binding only the &#39;Up&#39; event can give unexpected behaviors.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"><a-p>  </a-p><a-c>-- Read more below on the gotcha of binding an &#39;Up&#39; event only.</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"><a-p>return </a-p><a-v>config</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"><a-p>Each entry in the mouse binding table can have the following fields:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"><a-p>* `event` - the mouse event on which to trigger. Described in detail below.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"><a-p>* `mods` - the keyboard modifier keys that must be active in order to match the event.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"><a-p>  `mods` have the same definition and meaning as for key assignments and are described</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"><a-p>  in more detail in [Configuring Key Assignments](keys.md#configuring-key-assignments).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"><a-p>* `action` - the action to take when this mouse binding is matched</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"><a-p>* `mouse_reporting` - an optional boolean that defaults to `false`. This mouse binding</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"><a-p>   entry will only be considered if the current pane&#39;s mouse reporting state matches.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"><a-p>   In general, you should avoid defining assignments that have</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"><a-p>   `mouse_reporting=true` as it will prevent the application running in the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"><a-p>   pane from receiving that mouse event.  You can, of course, define these and</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"><a-p>   still send your mouse event to the pane by holding down the configured</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"><a-p>   [mouse reporting bypass modifier</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"><a-p>   key](lua/config/bypass_mouse_reporting_modifiers.md). {{since(&#39;20220807-113146-c2fee766&#39;, inline=True)}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"><a-p>* `alt_screen` - an optional field that defaults to `&#39;Any&#39;`, but that can also</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"><a-p>  be set to either `true` or `false`. This mouse binding entry will only be</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>  considered if the current pane&#39;s alt screen state matches this field.  Most</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"><a-p>  of the default mouse assignments are defined as `alt_screen=&#39;Any&#39;`, a notable</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"><a-p>  exception being that mouse wheel scrolling only applies when</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"><a-p>  `alt_screen=false`, as the mouse wheel is typically mapped to arrow keys by</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"><a-p>  the terminal in alt screen mode. {{since(&#39;20220807-113146-c2fee766&#39;, inline=True)}}.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"><a-p>The `action` and `mods` portions are described in more detail in the key assignment</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"><a-p>information below.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"><a-p>The `event` portion has three components:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"><a-p>* Whether it is a `Down`, `Up` or `Drag` event</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"><a-p>* The number of consecutive clicks within the click threshold (the *click streak*)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"><a-p>* The mouse button; `Left`, `Right`, or `Middle`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text"><a-p>A double click is a `down-up-down` sequence where either the second button down</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"><a-p>is held for long enough or is released and no subsequent down event occurs</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"><a-p>within the click threshold.  When recognized, it emits a `Down` event with</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"><a-p>`streak=2`.  If the mouse is moved while the button is held, a `Drag` event</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"><a-p>with `streak=2` is generated.  When the mouse button is released an `Up` event</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"><a-p>with `streak=2` is generated.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"><a-p>The mouse event recognizer supports an arbitrary click streak, so if</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"><a-p>you wanted quadruple-click bindings you can specify `streak=4`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"><a-p>| Event             | Lua Representation  |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text"><a-p>| ----------------- | ------------------- |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"><a-p>| Triple Left Down  | `event={Down={streak=3, button=&quot;Left&quot;}}` |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text"><a-p>| Double Left Up  | `event={Up={streak=2, button=&quot;Left&quot;}}` |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"><a-p>| Single Left Drag  | `event={Drag={streak=1, button=&quot;Left&quot;}}` |</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"><a-p>{{since(&#39;20220807-113146-c2fee766&#39;)}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"><a-p>You can handle vertical wheel scroll events using the example shown below. The</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"><a-p>`streak` and amount associated with either `WheelUp` or `WheelDown` are set to</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"><a-p>`1` for the sake of simplicity of matching the event; you may use</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text"><a-p>[`window:current_event`](lua/window/current_event.md), if to access the actual</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"><a-p>delta scroll value while handling the event.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"><a-p>local </a-p><a-v>wezterm</a-v><a-p> = </a-p><a-f>require</a-f><a-p> </a-p><a-s>&#39;wezterm&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text"><a-p>local </a-p><a-v>act</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"><a-p>local </a-p><a-v>config</a-v><a-p> = </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text"><a-p>config.</a-p><a-v>mouse_bindings</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"><a-p>  </a-p><a-c>-- Scrolling up while holding CTRL increases the font size</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text"><a-p>    </a-p><a-v>event</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Down</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>streak</a-v><a-p> = </a-p><a-n>1</a-n><a-p>, </a-p><a-v>button</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>WheelUp</a-v><a-p> = </a-p><a-n>1</a-n><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text"><a-p>    </a-p><a-v>mods</a-v><a-p> = </a-p><a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"><a-p>    </a-p><a-v>action</a-v><a-p> = </a-p><a-v>act</a-v><a-p>.</a-p><a-v>IncreaseFontSize</a-v><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text"><a-p>  </a-p><a-c>-- Scrolling down while holding CTRL decreases the font size</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"><a-p>    </a-p><a-v>event</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Down</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>streak</a-v><a-p> = </a-p><a-n>1</a-n><a-p>, </a-p><a-v>button</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>WheelDown</a-v><a-p> = </a-p><a-n>1</a-n><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text"><a-p>    </a-p><a-v>mods</a-v><a-p> = </a-p><a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"><a-p>    </a-p><a-v>action</a-v><a-p> = </a-p><a-v>act</a-v><a-p>.</a-p><a-v>DecreaseFontSize</a-v><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text"><a-p>return </a-p><a-v>config</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text"><a-p># </a-p><a-tt>Gotcha on binding an &#39;Up&#39; event only</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text"><a-p>If you only have a mouse bind on the &#39;Up&#39; event and not on the &#39;Down&#39; event,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text"><a-p>the &#39;Down&#39; event will still be sent to the running program.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text"><a-p>If that program is tracking mouse inputs (like tmux or vim with mouse support),</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text"><a-p>you may experience _unintuitive behavior_ as the program receives the &#39;Down&#39;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text"><a-p>event, but not the &#39;Up&#39; event (which is bound to something in your config).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text"><a-p>To avoid this, it is recommended to disable the &#39;Down&#39; event (to ensure it won&#39;t</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text"><a-p>be sent to the running program), for example:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text"><a-p>local </a-p><a-v>wezterm</a-v><a-p> = </a-p><a-f>require</a-f><a-p> </a-p><a-s>&#39;wezterm&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"><a-p>local </a-p><a-v>act</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>action</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text"><a-p>local </a-p><a-v>config</a-v><a-p> = </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text"><a-p>config.</a-p><a-v>mouse_bindings</a-v><a-p> = </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text"><a-p>  </a-p><a-c>-- Bind &#39;Up&#39; event of CTRL-Click to open hyperlinks</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text"><a-p>    </a-p><a-v>event</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Up</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>streak</a-v><a-p> = </a-p><a-n>1</a-n><a-p>, </a-p><a-v>button</a-v><a-p> = </a-p><a-s>&#39;Left&#39;</a-s><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text"><a-p>    </a-p><a-v>mods</a-v><a-p> = </a-p><a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text"><a-p>    </a-p><a-v>action</a-v><a-p> = </a-p><a-v>act</a-v><a-p>.</a-p><a-v>OpenLinkAtMouseCursor</a-v><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text"><a-p>  </a-p><a-c>-- Disable the &#39;Down&#39; event of CTRL-Click to avoid weird program behaviors</a-c></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text"><a-p>  </a-p><a-cr>{</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text"><a-p>    </a-p><a-v>event</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>Down</a-v><a-p> = </a-p><a-cr>{</a-cr><a-p> </a-p><a-v>streak</a-v><a-p> = </a-p><a-n>1</a-n><a-p>, </a-p><a-v>button</a-v><a-p> = </a-p><a-s>&#39;Left&#39;</a-s><a-p> </a-p><a-cr>}</a-cr><a-p> </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text"><a-p>    </a-p><a-v>mods</a-v><a-p> = </a-p><a-s>&#39;CTRL&#39;</a-s><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text"><a-p>    </a-p><a-v>action</a-v><a-p> = </a-p><a-v>act</a-v><a-p>.</a-p><a-v>Nop</a-v><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text"><a-p>  </a-p><a-cr>}</a-cr><a-p>,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text"><a-p>}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text"><a-p>return </a-p><a-v>config</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L224" href="#L224">224</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L225" href="#L225">225</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L226" href="#L226">226</a><span class="code-text"><a-p># </a-p><a-tt>Available Actions</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L227" href="#L227">227</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text">See the [`KeyAssignment` reference](lua/keyassignment/index.md) for information</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L229" href="#L229">229</a><span class="code-text">on available actions.</span></span></pre></div></div>
</main>
</body>
</html>
