From 229df874b7624f49137ee7d66b10bfbc82b68dc8 Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Tue, 9 Mar 2021 21:50:48 -0800 Subject: [PATCH] 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. --- ci/generate-docs.py | 9 +++ docs/config/lua/wezterm/on.md | 39 +---------- docs/config/lua/window-events/index.md | 9 +++ docs/config/lua/window-events/open-uri.md | 39 +++++++++++ .../window-events/window-config-reloaded.md | 35 ++++++++++ .../lua/window-events/window-resized.md | 68 +++++++++++++++++++ .../config/lua/window/set_config_overrides.md | 6 ++ 7 files changed, 168 insertions(+), 37 deletions(-) create mode 100644 docs/config/lua/window-events/index.md create mode 100644 docs/config/lua/window-events/open-uri.md create mode 100644 docs/config/lua/window-events/window-config-reloaded.md create mode 100644 docs/config/lua/window-events/window-resized.md diff --git a/ci/generate-docs.py b/ci/generate-docs.py index 195e3fa8a..ff0cd0937 100644 --- a/ci/generate-docs.py +++ b/ci/generate-docs.py @@ -250,6 +250,15 @@ TermWindow running in the wezterm process. ## 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): """, ), ], diff --git a/docs/config/lua/wezterm/on.md b/docs/config/lua/wezterm/on.md index 6be440f06..b44b32119 100644 --- a/docs/config/lua/wezterm/on.md +++ b/docs/config/lua/wezterm/on.md @@ -24,43 +24,8 @@ reloading the configuration will clear any existing event handlers. ## Predefined Events -### `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. +See [Window Events](../window-events/index.md) for a list of pre-defined +events. ## Custom Events diff --git a/docs/config/lua/window-events/index.md b/docs/config/lua/window-events/index.md new file mode 100644 index 000000000..50f0f76fa --- /dev/null +++ b/docs/config/lua/window-events/index.md @@ -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) diff --git a/docs/config/lua/window-events/open-uri.md b/docs/config/lua/window-events/open-uri.md new file mode 100644 index 000000000..6577f1586 --- /dev/null +++ b/docs/config/lua/window-events/open-uri.md @@ -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. + + diff --git a/docs/config/lua/window-events/window-config-reloaded.md b/docs/config/lua/window-events/window-config-reloaded.md new file mode 100644 index 000000000..0670ccea3 --- /dev/null +++ b/docs/config/lua/window-events/window-config-reloaded.md @@ -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) +``` + diff --git a/docs/config/lua/window-events/window-resized.md b/docs/config/lua/window-events/window-resized.md new file mode 100644 index 000000000..ad24c53b9 --- /dev/null +++ b/docs/config/lua/window-events/window-resized.md @@ -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); +``` diff --git a/docs/config/lua/window/set_config_overrides.md b/docs/config/lua/window/set_config_overrides.md index b19a2ce92..1288a43e1 100644 --- a/docs/config/lua/window/set_config_overrides.md +++ b/docs/config/lua/window/set_config_overrides.md @@ -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 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 ligatures in the current window: