1
1
mirror of https://github.com/wez/wezterm.git synced 2024-12-14 07:13:18 +03:00
wezterm/docs/config/lua/MuxPane.md
Wez Furlong 2e9fe87e34 lua: expand mux api
Allow iterating all windows at the mux layer.
windows allow iterating tabs.
Tabs allow iterating panes.

Versions of iteration that report additional information (like index,
active and positioning) are also added.

Panes can now reference their containing tab and window objects.
Tabs can now reference their containing window object.

refs: https://github.com/wez/wezterm/issues/1598 (sort of)
refs: https://github.com/wez/wezterm/issues/225
2022-06-27 13:19:03 -07:00

139 lines
3.1 KiB
Markdown

# MuxPane
*Since: 20220624-141144-bd1b7c5d*
`MuxPane` represents a pane that is managed by the multiplexer.
It has the following methods:
## `pane:pane_id()`
Returns the pane id
## `pane:split{}`
Splits `pane` and spawns a program into the split, returning the
`MuxPane` object associated with it:
```lua
local new_pane = pane:split{}
```
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
pane:split{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
pane:split{cwd="/tmp"}
```
### set_environment_variables
Sets additional environment variables in the environment for
this command invocation.
```lua
pane:split{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
pane:split{domain={DomainName="my.name"}}
```
Or you may use the default domain:
```lua
pane:split{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
pane:split{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
pane:split{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
pane:split{direction="Top", size=0.333}
pane:split{direction="Top", size=0.5}
```
## `pane:send_paste(text)`
Sends text to the pane as though it was pasted. If bracketed paste mode is
enabled then the text will be sent as a bracketed paste. Otherwise, it will
be sent as-is.
## `pane:send_text(text)`
Sends text to the pane as-is.
## `pane:window()`
*Since: nightly builds only*
Returns the [MuxWindow](MuxWindow.md) that contains the tab that contains this pane.
## `pane:tab()`
*Since: nightly builds only*
Returns the [MuxTab](MuxTab.md) that contains this pane.