docs: gui-startup, mux-startup and wezterm.mux

refs: #1949
refs: #674

.gitignore

@@ -16,9 +16,11 @@
 /docs/colorschemes/**/index.md
 /docs/config/lua/config/index.md
 /docs/config/lua/wezterm/index.md
+/docs/config/lua/wezterm.mux/index.md
 /docs/config/lua/pane/index.md
 /docs/config/lua/window/index.md
 /docs/config/lua/mux-events/index.md
+/docs/config/lua/gui-events/index.md
 /docs/config/lua/window-events/index.md
 /docs/config/lua/keyassignment/index.md
 /docs/mermaid.min.js

ci/generate-docs.py

@@ -172,6 +172,10 @@ TOC = [
                         "module: wezterm",
                         "config/lua/wezterm",
                     ),
+                    Gen(
+                        "module: wezterm.mux",
+                        "config/lua/wezterm.mux",
+                    ),
                     Gen(
                         "struct: Config",
                         "config/lua/config",
@@ -181,6 +185,9 @@ TOC = [
                         "config/lua/keyassignment",
                     ),
                     Page("object: LocalProcessInfo", "config/lua/LocalProcessInfo.md"),
+                    Page("object: MuxWindow", "config/lua/MuxWindow.md"),
+                    Page("object: MuxTab", "config/lua/MuxTab.md"),
+                    Page("object: MuxPane", "config/lua/MuxPane.md"),
                     Page("object: PaneInformation", "config/lua/PaneInformation.md"),
                     Page("object: TabInformation", "config/lua/TabInformation.md"),
                     Page("object: SshDomain", "config/lua/SshDomain.md"),
@@ -196,6 +203,10 @@ TOC = [
                         "config/lua/window",
                     ),
                     Page("object: WslDomain", "config/lua/WslDomain.md"),
+                    Gen(
+                        "events: Gui",
+                        "config/lua/gui-events",
+                    ),
                     Gen(
                         "events: Multiplexer",
                         "config/lua/mux-events",

docs/changelog.md

@@ -14,6 +14,7 @@ As features stabilize some brief notes about them will accumulate here.
 #### New
 * [background](config/lua/config/background.md) option for rich background compositing and parallax scrolling effects.
 * Added [docs for the cli](cli/general.md)
+* New [wezterm.mux](config/lua/wezterm.mux/index.md) module, [gui-startup](config/lua/gui-events/gui-startup.md) and [mux-startup](config/lua/mux-events/mux-startup.md) events for spawning programs into your preferred arrangement when wezterm starts. [#674](https://github.com/wez/wezterm/issues/674)
 * ssh client now supports `BindAddress`. Thanks to [@gpanders](https://github.com/gpanders)! [#1875](https://github.com/wez/wezterm/pull/1875)
 * [PaneInformation.domain_name](config/lua/PaneInformation.md) and [pane:get_domain_name()](config/lua/pane/get_domain_name.md) which return the name of the domain with which a pane is associated. [#1881](https://github.com/wez/wezterm/issues/1881)
 * You may now use `CTRL-n` and `CTRL-p` (in addition to the up/down arrow and vi motion keys) to change the selected row in the Launcher.  Thanks to [@Junnplus](https://github.com/Junnplus)! [#1880](https://github.com/wez/wezterm/pull/1880)

docs/config/lua/MuxPane.md

@@ -0,0 +1,13 @@
+# MuxPane
+
+*Since: nightly builds only*
+
+`MuxPane` represents a pane that is managed by the multiplexer.
+
+It has the following methods:
+
+## `pane:pane_id()`
+
+Returns the pane id
+
+

docs/config/lua/MuxTab.md

@@ -0,0 +1,14 @@
+# MuxTab
+
+*Since: nightly builds only*
+
+`MuxTab` represents a tab that is managed by the multiplexer.
+
+It has the following methods:
+
+## `tab:tab_id()`
+
+Returns the tab id
+
+
+

docs/config/lua/MuxWindow.md

@@ -0,0 +1,76 @@
+# MuxWindow
+
+*Since: nightly builds only*
+
+`MuxWindow` represents a window that is managed by the multiplexer.
+
+It has the following methods:
+
+## `window:window_id()`
+
+Returns the window id
+
+## `window:get_workspace()`
+
+Returns the name of the workspace to which the window belongs.
+
+## `window:set_workspace("something")`
+
+Changes the name of the workspace to which the window belongs.
+
+## `window:spawn_tab{}`
+
+Spawns a program into a new tab within this window, returning the
+[MuxTab](MuxTab.md), [MuxPane](MuxPane.md) and
+[MuxWindow](MuxWindow.md) objects associated with it:
+
+```lua
+local tab, pane, window = window:spawn_tab{}
+```
+
+When no arguments are passed, the default program is spawned.
+
+The following parameters are supported:
+
+### args
+
+Specifies the argument array for the command that should be spawned.
+If omitted the default program for the domain will be spawned.
+
+```lua
+window:spawn_tab{args={"top"}}
+```
+
+### cwd
+
+Specify the current working directory that should be used for
+the program.
+
+If unspecified, follows the rules from [default_cwd](config/default_cwd.md)
+
+```lua
+window:spawn_tab{cwd="/tmp"}
+```
+
+### set_environment_variables
+
+Sets additional environment variables in the environment for
+this command invocation.
+
+```lua
+window:spawn_tab{set_environment_variables={"FOO"="BAR"}}
+```
+
+### domain
+
+Specifies the multiplexer domain into which the program should
+be spawned.  The default value is assumed to be `"CurrentPaneDomain"`,
+which causes the domain from the currently active pane to be used.
+
+You may specify the name of one of the multiplexer domains
+defined in your configuration using the following:
+
+```lua
+window:spawn_tab{domain={DomainName="my.name"}}
+```
+

docs/config/lua/gui-events/gui-startup.md

@@ -0,0 +1,30 @@
+# `gui-startup`
+
+*Since: nightly builds only*
+
+The `gui-startup` event is emitted once when the GUI server is starting up
+when running the `wezterm start` subcommand.
+
+It is triggered before any default program is started.
+
+If no explicit program was passed to `wezterm start`, and if the
+`gui-startup` event causes any panes to be created then those will take
+precedence over the default program configuration and no additional default
+program will be spawned.
+
+This event is useful for starting a set of programs in a standard
+configuration to save you the effort of doing it manually each time:
+
+```lua
+local wezterm = require 'wezterm'
+local mux = wezterm.mux
+
+wezterm.on("gui-startup", function()
+  local tab, pane, window = mux.spawn_window{}
+  mux.split_pane(pane, {size=0.3})
+  mux.split_pane(pane, {size=0.5})
+end)
+
+return {}
+```
+

docs/config/lua/mux-events/mux-startup.md

@@ -0,0 +1,31 @@
+# `mux-startup`
+
+*Since: nightly builds only*
+
+The `mux-startup` event is emitted once when the mux server is starting up.
+It is triggered before any default program is started.
+
+If the `mux-startup` event causes any panes to be created then those will
+take precedence over the default program configuration and no additional
+default program will be spawned.
+
+This event is useful for starting a set of programs in a standard
+configuration to save you the effort of doing it manually each time:
+
+```lua
+local wezterm = require 'wezterm'
+local mux = wezterm.mux
+
+-- this is called by the mux server when it starts up.
+-- It makes a window split top/bottom
+wezterm.on("mux-startup", function()
+  local tab, pane, window = mux.spawn_window{}
+  mux.split_pane(pane, {direction="Top"})
+end)
+
+return {
+  unix_domains = {
+    {name="unix"}
+  },
+}
+```

docs/config/lua/wezterm.mux/active_workspace.md

@@ -0,0 +1,6 @@
+# `wezterm.mux.active_workspace()`
+
+*Since: nightly builds only*
+
+Returns the name of the active workspace.
+

docs/config/lua/wezterm.mux/get_pane.md

@@ -0,0 +1,11 @@
+# `wezterm.mux.get_pane(PANE_ID)`
+
+*Since: nightly builds only*
+
+Given a pane ID, verifies that the ID is a valid pane known to the mux
+and returns a [MuxPane](../MuxPane.md) object that can be used to
+operate on the pane.
+
+This is useful for situations where you have obtained a pane id from
+some other source and want to use the various `MuxPane` methods with it.
+

docs/config/lua/wezterm.mux/get_tab.md

@@ -0,0 +1,11 @@
+# `wezterm.mux.get_tab(WINDOW_ID)`
+
+*Since: nightly builds only*
+
+Given a tab ID, verifies that the ID is a valid tab known to the mux
+and returns a [MuxTab](../MuxTab.md) object that can be used to
+operate on the tab.
+
+This is useful for situations where you have obtained a tab id from
+some other source and want to use the various `MuxTab` methods with it.
+

docs/config/lua/wezterm.mux/get_window.md

@@ -0,0 +1,10 @@
+# `wezterm.mux.get_window(WINDOW_ID)`
+
+*Since: nightly builds only*
+
+Given a window ID, verifies that the ID is a valid window known to the mux
+and returns a [MuxWindow](../MuxWindow.md) object that can be used to
+operate on the window.
+
+This is useful for situations where you have obtained a window id from
+some other source and want to use the various `MuxWindow` methods with it.

docs/config/lua/wezterm.mux/index.markdown

@@ -0,0 +1,27 @@
+*Since: nightly builds only*
+
+The `wezterm.mux` module exposes functions that operate on the multiplexer layer.
+
+The multiplexer manages the set of running programs into panes, tabs, windows
+and workspaces.
+
+The multiplexer may not be connected to a GUI so certain operations that require
+a running Window management system are not present in the interface exposed
+by this module.
+
+You will typically use something like:
+
+```lua
+local wezterm = require 'wezterm'
+local mux = wezterm.mux
+```
+
+at the top of your configuration file to access it.
+
+## Important Note!
+
+*You should **avoid using, at the file scope in your config**, mux functions that cause new splits, tabs or windows to be created. The configuration file can be evaluated multiple times in various contexts. If you want to spawn new programs when wezterm starts up, look at the [gui-startup](../gui-events/gui-startup.md) and [mux-startup](../mux-events/mux-startup.md) events.*
+
+## Available functions, constants
+
+

docs/config/lua/wezterm.mux/spawn_window.md

@@ -0,0 +1,78 @@
+## `wezterm.mux.spawn_window{}`
+
+*Since: nightly builds only*
+
+Spawns a program into a new window, returning the [MuxTab](../MuxTab.md),
+[MuxPane](../MuxPane.md) and [MuxWindow](../MuxWindow.md) objects
+associated with it:
+
+```lua
+local tab, pane, window = wezterm.mux.spawn_window{}
+```
+
+When no arguments are passed, the default program is spawned.
+
+The following parameters are supported:
+
+### args
+
+Specifies the argument array for the command that should be spawned.
+If omitted the default program for the domain will be spawned.
+
+```lua
+wezterm.mux.spawn_window{args={"top"}}
+```
+
+### cwd
+
+Specify the current working directory that should be used for
+the program.
+
+If unspecified, follows the rules from [default_cwd](../config/default_cwd.md)
+
+```lua
+wezterm.mux.spawn_window{cwd="/tmp"}
+```
+
+### set_environment_variables
+
+Sets additional environment variables in the environment for
+this command invocation.
+
+```lua
+wezterm.mux.spawn_window{set_environment_variables={"FOO"="BAR"}}
+```
+
+### domain
+
+Specifies the multiplexer domain into which the program should
+be spawned.  The default value is assumed to be `"DefaultDomain"`,
+which causes the default domain to be used.
+
+You may specify the name of one of the multiplexer domains
+defined in your configuration using the following:
+
+```lua
+wezterm.mux.spawn_window{domain={DomainName="my.name"}}
+```
+
+### width and height
+
+Only valid when width and height are used together, allows specifying
+the number of column and row cells that the window should have.
+
+```lua
+wezterm.mux.spawn_window{width=60, height=30}
+```
+
+### workspace
+
+Specifies the name of the workspace that the newly created window
+will be associated with.  If omitted, the currently active workspace
+name will be used.
+
+```lua
+wezterm.mux.spawn_window{workspace={"coding"}}
+```
+
+

docs/config/lua/wezterm.mux/split_pane.md

@@ -0,0 +1,106 @@
+## `wezterm.mux.split_pane(pane, {})`
+
+*Since: nightly builds only*
+
+Splits `pane` and spawns a program into the split, returning the
+[MuxPane](../MuxPane.md)  object associated with it:
+
+```lua
+local new_pane = wezterm.mux.split_pane(pane)
+```
+
+When no arguments are passed, the pane is split in half left/right and the
+right half has the default program spawned into it.
+
+The following parameters are supported:
+
+### args
+
+Specifies the argument array for the command that should be spawned.
+If omitted the default program for the domain will be spawned.
+
+```lua
+wezterm.mux.split_pane(pane, {args={"top"})
+```
+
+### cwd
+
+Specify the current working directory that should be used for
+the program.
+
+If unspecified, follows the rules from [default_cwd](../config/default_cwd.md)
+
+```lua
+wezterm.mux.split_pane(pane, {cwd="/tmp"})
+```
+
+### set_environment_variables
+
+Sets additional environment variables in the environment for
+this command invocation.
+
+```lua
+wezterm.mux.split_pane(pane, {set_environment_variables={"FOO"="BAR"})
+```
+
+### domain
+
+Specifies the multiplexer domain into which the program should
+be spawned.  The default value is assumed to be `"CurrentPaneDomain"`,
+which causes the default domain to be used.
+
+You may specify the name of one of the multiplexer domains
+defined in your configuration using the following:
+
+```lua
+wezterm.mux.split_pane(pane, {domain={DomainName="my.name"})
+```
+
+Or you may use the default domain:
+
+```lua
+wezterm.mux.split_pane(pane, {domain="DefaultDomain"})
+```
+
+### direction
+
+Specifies where the new pane should be placed.  Possible values are:
+
+* `"Right"` - splits the pane left/right and places the new pane on the right.
+* `"Left"` - splits the pane left/right and places the new pane on the left.
+* `"Top"` - splits the pane top/bottom and places the new pane on the top.
+* `"Bottom"` - splits the pane top/bottom and places the new pane on the bottom.
+
+```lua
+wezterm.mux.split_pane(pane, {direction="Top"})
+```
+
+### top_level
+
+If `true`, rather than splitting `pane` in half, the tab that contains it
+is split and the new pane runs the full extent of the tab dimensions.
+
+```lua
+wezterm.mux.split_pane(pane, {direction="Bottom", top_level=true})
+```
+
+### size
+
+Controls the size of the new pane.
+
+Numeric values less than `1.0` are used to express a fraction of the
+available space; `0.5` means `50%` of the available space, for example.
+
+Numeric values greater or equal to `1` are used to specify the number of
+cells.
+
+The default value is `0.5`.
+
+This creates two additional splits within `pane`, creating three
+total splits that each occupy 1/3 of the available space:
+
+```lua
+wezterm.mux.split_pane(pane, {direction="Top", size=0.333})
+wezterm.mux.split_pane(pane, {direction="Top", size=0.5})
+```
+

lua-api-crates/mux/src/lib.rs

@@ -252,8 +252,6 @@ impl MuxWindow {
 struct SpawnTab {
     #[dynamic(default)]
     domain: SpawnTabDomain,
-    width: Option<usize>,
-    height: Option<usize>,
     #[dynamic(flatten)]
     cmd_builder: CommandBuilderFrag,
 }
@@ -270,14 +268,7 @@ impl SpawnTab {
             size = window
                 .get_by_idx(0)
                 .map(|tab| tab.get_size())
-                .unwrap_or_else(|| match (self.width, self.height) {
-                    (Some(cols), Some(rows)) => TerminalSize {
-                        rows,
-                        cols,
-                        ..Default::default()
-                    },
-                    _ => config::configuration().initial_size(0),
-                });
+                .unwrap_or_else(|| config::configuration().initial_size(0));
 
             pane = window
                 .get_active()