1
1
mirror of https://github.com/wez/wezterm.git synced 2024-12-25 14:22:37 +03:00

docs: Improve clarity of wezterm.on wrt. callback params and example

Co-authored-by: Wez Furlong <wez@wezfurlong.org>
This commit is contained in:
Benoit de Chezelles 2022-06-25 16:24:15 +02:00 committed by Wez Furlong
parent ce89e33f01
commit 5638abaa98

View File

@ -13,6 +13,10 @@ an ordered list of callbacks is maintained for each event. When the event
is emitted, each of the registered callbacks is called in the order that
they were registered.
The callback will receive the following parameters:
- a [`window` object](../window/index.md) that represents the active gui window.
- a [`pane` object](../pane/index.md) that represents the active pane.
If a callback returns `false` it will prevent any callbacks that were registered
after it from being triggered for the current event. Some events have
a defined default action; returning `false` will prevent that default action
@ -36,55 +40,53 @@ has no special knowledge. It is recommended that you avoid event names
that are likely to be used future versions of wezterm in order to avoid
unexpected behavior if/when those names might be used in future.
The `wezterm.emit` function and the `EmitEvent` key assignment can be used
The [wezterm.emit](emit.md) function and the [EmitEvent](../keyassignment/EmitEvent.md) key assignment can be used to
emit events.
In this example, a key is assigned to capture the content of the active
---
In the following example, a key is assigned to capture the visible content of the active
pane, write it to a file and then open that file in the `vim` editor:
```lua
local wezterm = require 'wezterm';
local io = require 'io';
local os = require 'os';
local wezterm = require "wezterm"
local io = require "io"
local os = require "os"
local act = wezterm.action
wezterm.on("trigger-vim-with-scrollback", function(window, pane)
wezterm.on("trigger-vim-with-visible-text", function(window, pane)
-- Retrieve the current viewport's text.
-- Pass an optional number of lines (eg: 2000) to retrieve
-- that number of lines starting from the bottom of the viewport.
local scrollback = pane:get_lines_as_text();
--
-- Note: You could also pass an optional number of lines (eg: 2000) to
-- retrieve that number of lines starting from the bottom of the viewport.
local viewport_text = pane:get_lines_as_text()
-- Create a temporary file to pass to vim
local name = os.tmpname();
local f = io.open(name, "w+");
f:write(scrollback);
f:flush();
f:close();
local name = os.tmpname()
local f = io.open(name, "w+")
f:write(viewport_text)
f:flush()
f:close()
-- Open a new window running vim and tell it to open the file
window:perform_action(wezterm.action{SpawnCommandInNewWindow={
args={"vim", name}}
window:perform_action(act.SpawnCommandInNewWindow{
args={"vim", name}
}, pane)
-- wait "enough" time for vim to read the file before we remove it.
-- The window creation and process spawn are asynchronous
-- wrt. running this script and are not awaitable, so we just pick
-- a number. We don't strictly need to remove this file, but it
-- is nice to avoid cluttering up the temporary file directory
-- location.
wezterm.sleep_ms(1000);
os.remove(name);
-- Wait "enough" time for vim to read the file before we remove it.
-- The window creation and process spawn are asynchronous wrt. running
-- this script and are not awaitable, so we just pick a number.
--
-- Note: We don't strictly need to remove this file, but it is nice
-- to avoid cluttering up the temporary directory.
wezterm.sleep_ms(1000)
os.remove(name)
end)
return {
keys = {
{key="E", mods="CTRL",
action=wezterm.action{EmitEvent="trigger-vim-with-scrollback"}},
action=act.EmitEvent("trigger-vim-with-visible-text")},
}
}
```
The first event parameter is a [`window` object](../window/index.md) that
represents the gui window.
The second event parameter is a [`pane` object](../pane/index.md) that
represents the pane.