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

@@ -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):
 """,
                     ),
                 ],

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
 

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)

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.
+
+

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)
+```
+

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);
+```

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: