Finished WindowEvents and documented all events.

lua/types/events/window.lua

@@ -1,17 +1,113 @@
 ---@meta
 
---TODO: finish
+-- The `"augment-command-palette"` event is emitted when
+-- the `Command Palette` is shown.
+--
+-- Its purpose is to enable you to add additional entries
+-- to the list of commands shown in the palette.
+--
+-- This hook is synchronous; calling asynchronous functions will not succeed.
+--
+-- The return value is a `AugmentCommandPaletteReturn` table
+---@see AugmentCommandPaletteReturn
+---@alias AugmentCommandPalette "augment-command-palette"
+
+-- The `"bell"` event is emitted when the `ASCII BEL` sequence
+-- is emitted to a pane in the window.
+--
+-- Defining an event handler doesn't alter wezterm's handling of the bell;
+-- the event supplements it and allows you
+-- to take additional action over the configured behavior.
+---@see Event.Bell
+---@alias Bell "bell"
+
+-- The `"format-tab-title"` event is emitted when the text for a tab title
+-- needs to be recomputed.
+--
+-- This event is a bit special in that it is synchronous and must return
+-- as quickly as possible in order to avoid blocking the GUI thread.
+--
+-- The most notable consequence of this is that some functions that are asynchronous
+-- (e.g. `wezterm.run_child_process()`) are not possible to call
+-- from inside the event handler and will generate a
+-- `format-tab-title: runtime error: attempt to yield from outside a coroutine` error
+---@alias FormatTabTitle "format-tab-title"
+
+-- The `"format-window-title"` event is emitted when the text for the window title
+-- needs to be recomputed.
+--
+-- This event is a bit special in that it is synchronous and must return
+-- as quickly as possible in order to avoid blocking the GUI thread.
+--
+-- The most notable consequence of this is that some functions that are asynchronous
+-- (e.g. `wezterm.run_child_process()`) are not possible to call
+-- from inside the event handler and will generate a
+-- `format-window-title: runtime error: attempt to yield from outside a coroutine` error
+---@alias FormatWindowTitle "format-window-title"
+
+-- The `"new-tab-button-click"` event is emitted when the user clicks on the
+-- `"new tab"` button in the tab bar.
+--
+-- This is the `+` button that is drawn to the right of the last tab
+---@alias NewTabButtonClick "new-tab-button-click"
+
+-- 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
+---@alias OpenUri "open-uri"
+
+-- ## WARNING
+--
+-- This event is considered to be deprecated and you should migrate to using `"update-status"`,
+-- which behaves the same way, but doesn't overly focus on the right status area.
+--
+-- ---
+--
+-- The `"update-right-status"` event is emitted periodically
+-- (based on the interval specified by the status_update_interval configuration value)
+---@deprecated
+---@alias UpdateRightStatus "update-right-status"
+
+-- The `"update-status"` event is emitted periodically
+-- (based on the interval specified by the status_update_interval configuration value)
+---@alias UpdateStatus "update-status"
+
+-- The `"user-var-changed"` event is emitted when a _user var escape sequence_
+-- is used to set a user var
+---@alias UserVarChanged "user-var-changed"
+
+-- 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 `Config.automatically_reload_config` is enabled),
+-- when the configuration is explicitly reloaded via the `ReloadConfiguration` key action,
+-- and when `Window:set_config_overrides()` is called for the window
+---@alias WindowConfigReloaded "window-config-reloaded"
+
+-- The `"window-focus-changed"` event is emitted when the focus state for a window is changed
+---@alias WindowFocusChanged "window-focus-changed"
+-- 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.
+---@alias WindowResized "window-resized"
 
 ---@alias WindowEvent
----|"augment-command-palette"
----|"bell"
----|"format-tab-title"
----|"format-window-title"
----|"new-tab-button-click"
----|"open-uri"
----|"update-right-status"
----|"update-status"
----|"user-var-changed"
----|"window-config-reloaded"
----|"window-focus-changed"
----|"window-resized"
+---|AugmentCommandPalette
+---|Bell
+---|FormatTabTitle
+---|FormatWindowTitle
+---|NewTabButtonClick
+---|OpenUri
+---|UpdateRightStatus -- DEPRECATED
+---|UpdateStatus
+---|UserVarChanged
+---|WindowConfigReloaded
+---|WindowFocusChanged
+---|WindowResized

lua/types/init.lua

@@ -701,51 +701,188 @@
 ---@see Wezterm.NerdFont for a list of icon names
 ---@field icon? Wezterm.NerdFont
 
+-- - The first event parameter is a `Window` object that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents the pane in which
+--   the bell was rung, which may not be active pane;
+--   it could be in an unfocused pane or tab
 ---@alias CallbackWindowPane fun(window: Window, pane: Pane)
+
 ---@alias AugmentCallbackWindowPane fun(window: Window, pane: Pane): AugmentCommandPaletteReturn
 
 -- This event is emitted when the Command Palette is shown.
+--
 -- Its purpose is to enable you to add additional entries to the list of commands shown in the palette.
+--
 -- This hook is synchronous; calling asynchronous functions will not succeed
----@alias EventAugmentCommandPalette fun(event: "augment-command-palette", callback: AugmentCallbackWindowPane): AugmentCommandPaletteReturn): nil
-
--- The bell event is emitted when the ASCII BEL sequence is emitted to a pane in the window.
--- Defining an event handler doesn"t alter wezterm's handling of the bell;
--- the event supplements it and allows you to take additional action over the configured behavior
----@alias EventBell fun(event: "augment-command-palette", callback: CallbackWindowPane)
-
--- TODO: Description
----@alias EventFormatTabTitle fun(event: "format-tab-title", callback: fun(tab: MuxTab, tabs: MuxTab[], panes: Pane[], config: Config, hover: bool, max_width: number): string)
+---@alias Event.AugmentCommandPalette fun(event: AugmentCommandPalette, callback: AugmentCallbackWindowPane): AugmentCommandPaletteReturn): nil
 
--- TODO: Description
----@alias EventFormatWindowTitle fun(event: "format-window-title", callback: fun(window: Window, pane: Pane, tabs: MuxTab[], panes: Pane[], config: Config))
+-- - The first event parameter is a `Window` object that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents
+--   the pane in which the bell was rung, which may not be active pane;
+--   it could be in an unfocused pane or tab
+---@alias Event.Bell fun(event: Bell, callback: CallbackWindowPane)
 
--- TODO: Description
----@alias EventNewTabButtonClick fun(event: "new-tab-button-click", callback: fun(window: Window, pane: Pane, button: "Left"|"Middle"|"Right", default_action: KeyAssignment): nil)
+-- The parameters to the event are:
+--
+-- - `tab`: The `TabInformation` for the active tab
+-- - `tabs`: An array containing `TabInformation` objects
+--         for each of the tabs in the window
+-- - `panes`: An array containing `PaneInformation` objects
+--          for each of the panes in the active tab
+-- - `config`: The effective configuration for the window
+-- - `hover`: `true` if the current tab is in the hover state
+-- - `max_width`: The maximum number of cells available
+--              to draw this tab when using the retro tab bar style
+--
+-- The return value of the event can be:
+--
+-- - A string, holding the text to use for the tab title
+-- - A `FormatItem` object as used in the `wezterm.format()` function.
+--   This allows formatting style and color information
+--   for individual elements within the tab
+--
+-- If the event encounters an error, or returns something that is not one of the types mentioned above,
+-- then the default tab title text will be computed and used instead.
+--
+-- When the tab bar is computed, this event is called twice for each tab;
+-- on the first pass, `hover` will be false and `max_width` will be set to `tab_max_width`.
+-- WezTerm will then compute the tab widths that will fit in the tab bar,
+-- and then call the event again for the set of tabs,
+-- this time with appropriate hover and max_width values.
+--
+-- Only the first `"format-tab-title"` event will be executed;
+-- it doesn't make sense to define multiple instances of the event
+-- with `multiple wezterm.on("format-tab-title", ...)` calls
+---@alias Event.FormatTabTitle fun(event: FormatTabTitle, callback: fun(tab: MuxTab, tabs: MuxTab[], panes: Pane[], config: Config, hover: bool, max_width: number): string|FormatItem)
 
--- TODO: Description
----@alias EventOpenUri fun(event: "open-uri", callback: fun(window: Window, pane: Pane, uri: string): nil)
+-- The parameters to the event are:
+--
+-- - `tab`: The `TabInformation` object for the active tab
+-- - `pane`: The `PaneInformation` object for the active pane
+-- - `tabs`: An array containing TabInformation objects
+--         for each of the tabs in the window
+-- - `panes`: An array containing `PaneInformation` objects
+--          for each of the panes in the active tab
+-- - `config`: The effective configuration for the window
+--
+-- The return value of the event should be a `string`,
+-- and if it is then it will be used as the title text in the window title bar.
+--
+-- If the event encounters an error, or returns something that is not a `string`,
+-- then the default window title text will be computed and used instead.
+--
+-- Only the first `"format-window-title"` event will be executed;
+-- it doesn't make sense to define multiple instances of the event
+-- with multiple `wezterm.on("format-window-title", ...)` calls
+---@alias Event.FormatWindowTitle fun(event: FormatWindowTitle, callback: fun(window: Window, pane: Pane, tabs: MuxTab[], panes: Pane[], config: Config): string)
 
--- TODO: Description
----@alias EventUpdateRightStatus fun(event: "update-right-status", callback: CallbackWindowPane)
+-- - The first event parameter is a `Window` object that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents the active pane in the window
+---@alias Event.NewTabButtonClick fun(event: NewTabButtonClick, callback: fun(window: Window, pane: Pane, button: "Left"|"Middle"|"Right", default_action: KeyAssignment))
 
--- TODO: Description
----@alias EventUpdateStatus fun(event: "update-status", callback: CallbackWindowPane)
+-- - The first event parameter is a `Window` object that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents the pane
+-- - The third event parameter is the URI string
+---@alias Event.OpenUri fun(event: OpenUri, callback: fun(window: Window, pane: Pane, uri: string))
 
--- TODO: Description
----@alias EventUserVarChanged fun(event: "user-var-changed", callback: fun(window: Window, pane: Pane, name: string, value: string): nil)
+-- ## WARNING
+--
+-- This event is considered to be deprecated and you should migrate to using `"update-status"`,
+-- which behaves the same way, but doesn't overly focus on the right status area.
+--
+-- ---
+--
+-- - The first event parameter is a `Window` object that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents the active pane in that window
+--
+-- There is no defined return value for the event,
+-- but its purpose is to allow you the chance to carry out some activity
+-- and then ultimately call `Window:set_right_status()'
+--
+-- WezTerm will ensure that only a single instance of this event is outstanding;
+-- if the hook takes longer than the `status_update_interval` to complete,
+-- `wezterm` won't schedule another call until `status_update_interval milliseconds`
+-- have elapsed since the last call completed
+---@deprecated
+---@alias Event.UpdateRightStatus fun(event: UpdateRightStatus, callback: CallbackWindowPane)
+
+-- - The first event parameter is a `Window` object that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents the active pane in that window
+--
+-- There is no defined return value for the event, but its purpose is
+-- to allow you the chance to carry out some activity and then ultimately call either
+-- `Window:set_right_status()` or `Window:set_left_status()`.
+--
+-- WezTerm will ensure that only a single instance of this event is outstanding;
+-- if the hook takes longer than the `status_update_interval` to complete,
+-- `wezterm` won't schedule another call until `status_update_interval milliseconds`
+-- have elapsed since the last call completed
+---@alias Event.UpdateStatus fun(event: UpdateStatus, callback: CallbackWindowPane)
+
+-- You can use something like the following from your shell
+-- to set the user var named foo to the value bar:
+--
+-- ```sh
+-- printf "\033]1337;SetUserVar=%s=%s\007" foo `echo -n bar | base64`
+-- ```
+--
+-- Then, if you have this in your config:
+--
+-- ```lua
+-- local wezterm = require 'wezterm'
+--
+-- wezterm.on('user-var-changed', function(window, pane, name, value)
+--   wezterm.log_info('var', name, value)
+-- end)
+--
+-- return {}
+-- ```
+--
+-- your event handler will be called with `name = 'foo'` and `value = 'bar'`.
+--
+-- See `Pane:get_user_vars()`
+---@alias Event.UserVarChanged fun(event: UserVarChanged, callback: fun(window: Window, pane: Pane, name: string, value: string))
 
--- TODO: Description
----@alias EventWindowConfigReloaded fun(event: "window-config-reloaded", callback: CallbackWindowPane)
+-- 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 that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents the active pane in that window
+---@alias Event.WindowConfigReloaded fun(event: WindowConfigReloaded, callback: CallbackWindowPane)
 
--- TODO: Description
----@alias EventWindowFocusChanged fun(event: "window-focus-changed", callback: CallbackWindowPane)
+-- 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.
+--
+-- - The first event parameter is a `Window` object that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents the active pane in that window
+---@alias Event.WindowFocusChanged fun(event: WindowFocusChanged, callback: CallbackWindowPane)
 
--- TODO: Description
----@alias EventWindowResized fun(event: "window-resized", callback: CallbackWindowPane)
+-- - The first event parameter is a `Window` object that represents the GUI window
+-- - The second event parameter is a `Pane` object that represents the active pane in that window
+---@alias Event.WindowResized fun(event: WindowResized, callback: CallbackWindowPane)
 
 -- A custom declared function
----@alias EventCustom fun(event: string, callback: fun(...: any): nil)
+---@alias Event.Custom fun(event: string, callback: fun(...: any))
+
+---@alias Events
+---|Event.AugmentCommandPalette
+---|Event.Bell
+---|Event.Custom
+---|Event.FormatTabTitle
+---|Event.FormatWindowTitle
+---|Event.NewTabButtonClick
+---|Event.OpenUri
+---|Event.UpdateRightStatus -- DEPRECATED
+---|Event.UpdateStatus
+---|Event.UserVarChanged
+---|Event.WindowConfigReloaded
+---|Event.WindowFocusChanged
+---|Event.WindowResized
 
 ---@alias CursorShape
 ---|"BlinkingBlock"

lua/types/wezterm/init.lua

@@ -54,7 +54,7 @@
 ---@field log_info fun(msg: string, ...: any): nil Logs the provided message string through wezterm's logging layer at 'INFO' level. If you started wezterm from a terminal that text will print to the stdout of that terminal. If running as a daemon for the multiplexer server then it will be logged to the daemon output path.
 ---@field log_warn fun(msg: string, ...: any): nil Logs the provided message string through wezterm's logging layer at 'WARN' level. If you started wezterm from a terminal that text will print to the stdout of that terminal. If running as a daemon for the multiplexer server then it will be logged to the daemon output path.
 ---@field open_with fun(path_or_url: string, application: string?) This function opens the specified path_or_url with either the specified application or uses the default application if application was not passed in.
----@field on EventAugmentCommandPalette|EventBell|EventFormatTabTitle|EventFormatWindowTitle|EventNewTabButtonClick|EventOpenUri|EventUpdateRightStatus|EventUpdateStatus|EventUserVarChanged|EventWindowConfigReloaded|EventWindowFocusChanged|EventWindowResized|EventCustom
+---@field on Events
 ---@field pad_left fun(string: string, min_width: integer): string Returns a copy of string that is at least min_width columns (as measured by wezterm.column_width)
 ---@field pad_right fun(string: string, min_width: integer): string Returns a copy of string that is at least min_width columns (as measured by wezterm.column_width).
 ---@field permute_any_or_no_mods any #TODO