<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/config/lua/keyassignment/ActivateKeyTable.md - fork/wezterm @ termiz-0.23.2</title>
<meta name="description" content="docs/config/lua/keyassignment/ActivateKeyTable.md in fork/wezterm at termiz-0.23.2.">
<meta property="og:title" content="docs/config/lua/keyassignment/ActivateKeyTable.md - fork/wezterm @ termiz-0.23.2">
<meta property="og:description" content="docs/config/lua/keyassignment/ActivateKeyTable.md in fork/wezterm at termiz-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="termiz-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">Benoit de Chezelles</span><span class="commit-message" data-commit="cb593f6af5485e0de29ccc19ef27fc1416a85eef">docs: Try fix mkdocs rendering of lists</span><span class="snapshot-sha sha" data-commit="cb593f6af5485e0de29ccc19ef27fc1416a85eef">cb593f6af</span><time datetime="2025-02-07T18:43:44-07:00" title="2025-02-07 18:43:44 -0700">2025-02-07</time></p>
<header class="topbar"><details class="switcher"><summary>termiz-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 class="current" 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 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/termiz-0.23.2/tree/docs/">docs</a> / <a href="/fork/wezterm/ref/termiz-0.23.2/tree/docs/config/">config</a> / <a href="/fork/wezterm/ref/termiz-0.23.2/tree/docs/config/lua/">lua</a> / <a href="/fork/wezterm/ref/termiz-0.23.2/tree/docs/config/lua/keyassignment/">keyassignment</a> / <span class="cur">ActivateKeyTable.md</span></nav>
<span class="view-stats"><span>2.3 KiB</span><span>26 lines</span></span><span class="actions"><a class="raw" href="/fork/wezterm/raw/1bb8ffe50d5bf31c742121322f5fec608553ec73/docs/config/lua/keyassignment/ActivateKeyTable.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"><h1><code>ActivateKeyTable</code></h1>
<p>{{since('20220408-101518-b908e2dd')}}</p>
<p>Activates a named key table.</p>
<p>See <a href="/fork/wezterm/ref/termiz-0.23.2/blob/docs/config/key-tables.md">Key Tables</a> for a detailed example.</p>
<p>The following parameters are possible:</p>
<ul>
<li>
<p><code>name</code> - the name of the table to activate.  The name must match up to an entry in the <code>key_tables</code> configuration.</p>
</li>
<li>
<p><code>timeout_milliseconds</code> - an optional duration expressed in milliseconds. If specified, then the activation will automatically expire and pop itself from the key table stack once that duration elapses.  If omitted, this activation will not expire due to time.</p>
<ul>
<li>{{since('20220807-113146-c2fee766', inline=True)}}: the timer is reset each time you press a key that matches this key table activation, allowing for repeated key presses</li>
</ul>
</li>
<li>
<p><code>one_shot</code> - an optional boolean that controls whether the activation will pop itself after a single additional key press.  The default if left unspecified is <code>one_shot=true</code>. When set to <code>false</code>, pressing a key will not automatically pop the activation and you will need to use either a timeout or an explicit key assignment that triggers <a href="/fork/wezterm/ref/termiz-0.23.2/blob/docs/config/lua/keyassignment/PopKeyTable.md">PopKeyTable</a> to cancel the activation.</p>
</li>
<li>
<p><code>replace_current</code> - an optional boolean. Defaults to <code>false</code> if unspecified. If set to <code>true</code> then behave as though <a href="/fork/wezterm/ref/termiz-0.23.2/blob/docs/config/lua/keyassignment/PopKeyTable.md">PopKeyTable</a> was triggered before pushing this new activation on the stack.  This is most useful for key assignments in a table that was activated using <code>one_shot=false</code>.</p>
</li>
<li>
<p><code>until_unknown</code> - an optional boolean. Defaults to <code>false</code> if unspecified. If set to <code>true</code> then a key press that doesn't match any entries in the named key table will implicitly pop this entry from the stack. This can be used together with <code>timeout_milliseconds</code>. {{since('20220807-113146-c2fee766', inline=True)}}</p>
</li>
<li>
<p><code>prevent_fallback</code> - an optional boolean. Defaults to <code>false</code> if unspecified.
If set to <code>true</code> then a key press that doesn't match any entries in the named
key table will halt any further key table stack matching, allowing only key
assignments that are defined in the current key table activation to match.
Use with care: if you haven't defined an explicit
<a href="/fork/wezterm/ref/termiz-0.23.2/blob/docs/config/lua/keyassignment/PopKeyTable.md">PopKeyTable</a> assignment in the key table, you can lock
yourself out of the keyboard and will need to reload the configuration file
(eg: by re-saving it) to get back in. {{since('20221119-145034-49b9839f', inline=True)}}</p>
</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> <a-tt>`ActivateKeyTable`</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">{{since(&#39;20220408-101518-b908e2dd&#39;)}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">Activates a named key table.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">See [Key Tables](../../key-tables.md) for a detailed example.</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 following parameters are possible:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>* </a-p>`name` - the name of the table to activate.  The name must match up to an entry in the `key_tables` configuration.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p>* </a-p>`timeout_milliseconds` - an optional duration expressed in milliseconds. If specified, then the activation will automatically expire and pop itself from the key table stack once that duration elapses.  If omitted, this activation will not expire due to time.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-p>    * {{since(&#39;20220807-113146-c2fee766&#39;, inline=True)}}: the timer is reset each time you press a key that matches this key table activation, allowing for repeated key presses</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></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>* `one_shot` - an optional boolean that controls whether the activation will pop itself after a single additional key press.  The default if left unspecified is `one_shot=true`. When set to `false`, pressing a key will not automatically pop the activation and you will need to use either a timeout or an explicit key assignment that triggers [PopKeyTable](PopKeyTable.md) to cancel the activation.</a-p></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>* `replace_current` - an optional boolean. Defaults to `false` if unspecified. If set to `true` then behave as though [PopKeyTable](PopKeyTable.md) was triggered before pushing this new activation on the stack.  This is most useful for key assignments in a table that was activated using `one_shot=false`.</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"><a-p>* `until_unknown` - an optional boolean. Defaults to `false` if unspecified. If set to `true` then a key press that doesn&#39;t match any entries in the named key table will implicitly pop this entry from the stack. This can be used together with `timeout_milliseconds`. {{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="L19" href="#L19">19</a><span class="code-text"><a-p>* `prevent_fallback` - an optional boolean. Defaults to `false` if unspecified.</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>  If set to `true` then a key press that doesn&#39;t match any entries in the named</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"><a-p>  key table will halt any further key table stack matching, allowing only key</a-p></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>  assignments that are defined in the current key table activation to match.</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>  Use with care: if you haven&#39;t defined an explicit</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>  [PopKeyTable](PopKeyTable.md) assignment in the key table, you can lock</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>  yourself out of the keyboard and will need to reload the configuration file</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>  </a-p>(eg: by re-saving it) to get back in. {{since(&#39;20221119-145034-49b9839f&#39;, inline=True)}}</span></span></pre></div></div>
</main>
</body>
</html>
