<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/config/lua/config/debug_key_events.md - fork/wezterm @ termwiz-0.23.2</title>
<meta name="description" content="docs/config/lua/config/debug_key_events.md in fork/wezterm at termwiz-0.23.2.">
<meta property="og:title" content="docs/config/lua/config/debug_key_events.md - fork/wezterm @ termwiz-0.23.2">
<meta property="og:description" content="docs/config/lua/config/debug_key_events.md in fork/wezterm at termwiz-0.23.2.">
<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.2" data-tip="8b7ca454b5e0a65b69b1b736db54eae3c195384b">
<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.2</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 class="current" href="/fork/wezterm/ref/termwiz-0.23.2/">termwiz-0.23.2</a><a 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.2/tree/docs/">docs</a> / <a href="/fork/wezterm/ref/termwiz-0.23.2/tree/docs/config/">config</a> / <a href="/fork/wezterm/ref/termwiz-0.23.2/tree/docs/config/lua/">lua</a> / <a href="/fork/wezterm/ref/termwiz-0.23.2/tree/docs/config/lua/config/">config</a> / <span class="cur">debug_key_events.md</span></nav>
<span class="view-stats"><span>2.6 KiB</span><span>57 lines</span></span><span class="actions"><a class="raw" href="/fork/wezterm/raw/d8a334650e55d8b90b48601509d2c89afc38b59c/docs/config/lua/config/debug_key_events.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>keys</li>
<li>debug</li>
</ul>
<hr />
<h1><code>debug_key_events = false</code></h1>
<p>When set to true, each key event will be logged by the GUI layer as an INFO
level log message on the stderr stream from wezterm.  <strong>You will typically need
to launch <code>wezterm</code> directly from another terminal to see this logging</strong>.</p>
<p>This can be helpful in figuring out how keys are being decoded on your system,
or for discovering the system-dependent "raw" key code values.</p>
<pre class="language-lua"><a-v>config</a-v><a-p>.</a-p><a-v>debug_key_events</a-v> = <a-co>true</a-co></pre>
<p>Produces logs like the following when typing <code>ls</code>: (artificially wrapped
to make these docs more readable):</p>
<pre> 2021-02-20T17:04:28.149Z INFO  wezterm_gui::gui::termwindow   &gt; key_event 
   KeyEvent { key: Char('l'), modifiers: NONE, raw_key: None,
   raw_modifiers: NONE, raw_code: Some(46), repeat_count: 1, key_is_down: true }
 2021-02-20T17:04:28.605Z INFO  wezterm_gui::gui::termwindow   &gt; key_event
   KeyEvent { key: Char('s'), modifiers: NONE, raw_key: None, raw_modifiers: NONE,
   raw_code: Some(39), repeat_count: 1, key_is_down: true }
</pre>
<p>The key event has a number of fields:</p>
<ul>
<li><code>key</code> is the decoded key after keymapping and composition effects.  For
example <code>Char('l')</code> occurs when typing the <code>l</code> key and <code>Char('L')</code> occurs
when doing the same but with <code>SHIFT</code> held down.  It could also be one
of the keycode identifiers listed in
<a href="/fork/wezterm/ref/termwiz-0.23.2/blob/docs/config/keys.md#configuring-key-assignments">the Configuring Key Assignments</a>
section.</li>
<li><code>modifiers</code> indicates which modifiers are active after keymapping and composition
effects.  For example, typing <code>l</code> with <code>SHIFT</code> held down produces
<code>key: Char('L'), modifiers: NONE</code> because the <code>SHIFT</code> key composed to produce
the uppercase <code>L</code>.</li>
<li><code>raw_key</code> represents the key press prior to any keymapping/composition events.
If <code>raw_key</code> would be the same as <code>key</code> then <code>raw_key</code> will be printed as <code>NONE</code>.</li>
<li><code>raw_modifiers</code> represents the state of the modifier keys prior to any keymapping
or composition effects.  For example, typeing <code>l</code> with <code>SHIFT</code> held down produces
<code>raw_modifiers: SHIFT</code>.</li>
<li><code>raw_code</code> is the hardware-and-or-windowing-system-dependent raw keycode value
associated with the key press.  This generally represents the physical location
of the key independent of keymapping.</li>
<li><code>repeat_count</code> is usually <code>1</code> but on some systems may be larger number to
indicate that the key is being held down and that the system is synthesizing
multiple key-presses based on the system key repeat settings.</li>
<li><code>key_is_down</code> indicates whether the key is being pressed or released. This
will always be true when debug logging, as logging and key press handling is
only triggered on key press events in wezterm.</li>
</ul>
</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>keys</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> <a-s>debug</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"><a-p>#</a-p> <a-tt>`debug_key_events = false`</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">When set to true, each key event will be logged by the GUI layer as an INFO</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">level log message on the stderr stream from wezterm.  **You will typically need</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">to launch `wezterm` directly from another terminal to see this logging**.</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">This can be helpful in figuring out how keys are being decoded on your system,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">or for discovering the system-dependent &quot;raw&quot; key code values.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</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="L16" href="#L16">16</a><span class="code-text"><a-p>config.</a-p><a-v>debug_key_events</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="L17" href="#L17">17</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>Produces logs like the following when typing `ls`: (artificially wrapped</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"><a-p>to make these docs more readable):</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p> 2021-02-20T17:04:28.149Z INFO  wezterm_gui::gui::termwindow   &gt; key_event </a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p>   KeyEvent { key: Char(&#39;l&#39;), modifiers: NONE, raw_key: None,</a-p></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>   raw_modifiers: NONE, raw_code: Some(46), repeat_count: 1, key_is_down: true }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p> 2021-02-20T17:04:28.605Z INFO  wezterm_gui::gui::termwindow   &gt; key_event</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>   KeyEvent { key: Char(&#39;s&#39;), modifiers: NONE, raw_key: None, raw_modifiers: NONE,</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>   raw_code: Some(39), repeat_count: 1, key_is_down: true }</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>The key event has a number of fields:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-p>* `key` is the decoded key after keymapping and composition effects.  For</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>  example `Char(&#39;l&#39;)` occurs when typing the `l` key and `Char(&#39;L&#39;)` occurs</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"><a-p>  when doing the same but with `SHIFT` held down.  It could also be one</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>  of the keycode identifiers listed in</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>  [the 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="L38" href="#L38">38</a><span class="code-text"><a-p>  section.</a-p></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>* `modifiers` indicates which modifiers are active after keymapping and composition</a-p></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>  effects.  For example, typing `l` with `SHIFT` held down produces</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"><a-p>  `key: Char(&#39;L&#39;), modifiers: NONE` because the `SHIFT` key composed to produce</a-p></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>  the uppercase `L`.</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>* `raw_key` represents the key press prior to any keymapping/composition events.</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>  If `raw_key` would be the same as `key` then `raw_key` will be printed as `NONE`.</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>* `raw_modifiers` represents the state of the modifier keys prior to any keymapping</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>  or composition effects.  For example, typeing `l` with `SHIFT` held down produces</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>  `raw_modifiers: SHIFT`.</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>* `raw_code` is the hardware-and-or-windowing-system-dependent raw keycode value</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>  associated with the key press.  This generally represents the physical location</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>  of the key independent of keymapping.</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>* `repeat_count` is usually `1` but on some systems may be larger number to</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>  indicate that the key is being held down and that the system is synthesizing</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>  multiple key-presses based on the system key repeat settings.</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>* `key_is_down` indicates whether the key is being pressed or released. This</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>  will always be true when debug logging, as logging and key press handling is</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>  </a-p>only triggered on key press events in wezterm.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></span></span></pre></div></div>
</main>
</body>
</html>
