1
1
mirror of https://github.com/wez/wezterm.git synced 2024-12-23 21:32:13 +03:00

docs: break out events into their own pages

Take the existing open-uri docs and move to their own page.
Add docs for the new window events.
This commit is contained in:
Wez Furlong 2021-03-09 21:50:48 -08:00
parent 354a12a0ff
commit 229df874b7
7 changed files with 168 additions and 37 deletions

View File

@ -250,6 +250,15 @@ TermWindow running in the wezterm process.
## Available methods ## Available methods
""",
),
Gen(
"events: Window",
"config/lua/window-events",
index="""
# Events emitted by the `Window` object
The following events can be handled using [wezterm.on](../wezterm/on.md):
""", """,
), ),
], ],

View File

@ -24,43 +24,8 @@ reloading the configuration will clear any existing event handlers.
## Predefined Events ## Predefined Events
### `open-uri` See [Window Events](../window-events/index.md) for a list of pre-defined
events.
The `open-uri` event is emitted when the `CompleteSelectionOrOpenLinkAtMouseCursor`
key/mouse assignment is triggered.
The default action is to open the active URI in your browser, but if you
register for this event you can co-opt the default behavior.
For example, if you prefer to launch your preferred MUA in a new window
in response to clicking on `mailto:` URLs, you could do something like:
```lua
local wezterm = require 'wezterm';
wezterm.on("open-uri", function(window, pane, uri)
local start, match_end = uri:find("mailto:")
if start == 1 then
local recipient = uri:sub(match_end+1)
window:perform_action(wezterm.action{SpawnCommandInNewWindow={
args={"mutt", recipient}
}}, pane);
-- prevent the default action from opening in a browser
return false
end
-- otherwise, by not specifying a return value, we allow later
-- handlers and ultimately the default action to caused the
-- URI to be opened in the browser
end)
```
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.
The third event parameter is the URI string.
## Custom Events ## Custom Events

View File

@ -0,0 +1,9 @@
# Events emitted by the `Window` object
The following events can be handled using [wezterm.on](../wezterm/on.md):
- [open-uri](open-uri.md)
- [window-config-reloaded](window-config-reloaded.md)
- [window-resized](window-resized.md)

View File

@ -0,0 +1,39 @@
# `open-uri`
The `open-uri` event is emitted when the `CompleteSelectionOrOpenLinkAtMouseCursor`
key/mouse assignment is triggered.
The default action is to open the active URI in your browser, but if you
register for this event you can co-opt the default behavior.
For example, if you prefer to launch your preferred MUA in a new window
in response to clicking on `mailto:` URLs, you could do something like:
```lua
local wezterm = require 'wezterm';
wezterm.on("open-uri", function(window, pane, uri)
local start, match_end = uri:find("mailto:")
if start == 1 then
local recipient = uri:sub(match_end+1)
window:perform_action(wezterm.action{SpawnCommandInNewWindow={
args={"mutt", recipient}
}}, pane);
-- prevent the default action from opening in a browser
return false
end
-- otherwise, by not specifying a return value, we allow later
-- handlers and ultimately the default action to caused the
-- URI to be opened in the browser
end)
```
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.
The third event parameter is the URI string.

View File

@ -0,0 +1,35 @@
# `window-config-reloaded`
*Since: nightly*
The `window-config-reloaded` event is emitted when the configuration for a
window has been reloaded. This can occur when the configuration file is
detected as changed (when
[automatically_reload_config](../config/automatically_reload_config.md) is
enabled), when the configuration is explicitly reloaded via the
[ReloadConfiguration](../keyassignment/ReloadConfiguration.md) key action, and
when [window:set_config_overrides](../window/set_config_overrides.md) is called
for the window.
This event is fire-and-forget from the perspective of wezterm; it fires the
event to advise of the config change, but has no other expectations.
If you call `window:set_config_overrides` from inside this event callback then
an additional `window-config-reloaded` event will be triggered. You should
take care to avoid creating a loop by only calling
`window:set_config_overrides` when the actual override values are changed.
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 active pane in that window.
```lua
local wezterm = require 'wezterm';
wezterm.on("window-config-reloaded", function(window, pane)
wezterm.log_info("the config was reloaded for this window!");
end)
```

View File

@ -0,0 +1,68 @@
# `window-resized`
*Since: nightly*
The `window-resized` event is emitted when the window is resized and when
transitioning between full-screen and regular windowed mode.
The event is triggered asynchronously with respect to the potentially-ongoing
live resize operation. `wezterm` will coalesce the stream of multiple events
generated by a live resize such that there can be a maximum of 1 event
executing and 1 event buffered.
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 active pane in that window.
This example demonstrates adjusting the window padding when going fullscreen
so that the terminal content fits in the middle third of the display.
Note how care is taken to avoid calling `window:set_config_overrides` unless
something has changed. Also note how both the `window-resized` and
[window-config-reloaded](window-config-reloaded.md) events are connected to the
same `recompute_padding` function; that causes the padding changes to take
effect both when toggling fullscreen and when editing the config file to adjust
the event handling code:
```lua
local wezterm = require 'wezterm';
function recompute_padding(window)
local window_dims = window:get_dimensions();
local overrides = window:get_config_overrides() or {}
if not window_dims.is_full_screen then
if not overrides.window_padding then
-- not changing anything
return;
end
overrides.window_padding = nil;
else
-- Use only the middle 33%
local third = math.floor(window_dims.pixel_width / 3)
local new_padding = {
left = third,
right = third,
top = 0,
bottom = 0
};
if overrides.window_padding and new_padding.left == overrides.window_padding.left then
-- padding is same, avoid triggering further changes
return
end
overrides.window_padding = new_padding
end
window:set_config_overrides(overrides)
end
wezterm.on("window-resized", function(window, pane)
recompute_padding(window)
end);
wezterm.on("window-config-reloaded", function(window)
recompute_padding(window)
end);
```

View File

@ -11,6 +11,12 @@ This can be used to override configuration on a per-window basis;
this is only useful for options that apply to the GUI window, such this is only useful for options that apply to the GUI window, such
as rendering the GUI. as rendering the GUI.
Each call to `window:set_config_overrides` will emit the
[window-config-reloaded](../window-events/window-config-reloaded.md) event for
the window. If you are calling this method from inside the handler
for `window-config-reloaded` you should take care to only call `window:set_config_overrides`
if the actual override values have changed to avoid a loop.
In this example, a key assignment (`CTRL-SHIFT-E`) is used to toggle the use of In this example, a key assignment (`CTRL-SHIFT-E`) is used to toggle the use of
ligatures in the current window: ligatures in the current window: