application startup event

[gwww]

Is your feature request related to a problem? Please describe.
I would like to run some Lua on a new window creation. For example SplitHorizontal.

Describe the solution you'd like
An event is generated that can invoke a wezterm.on function.

Describe alternatives you've considered
Could not think of any.

Additional context
I currently envision only doing this for the initial window that is created. I'm assuming a window ID of 0 would be able to test for that, but, the window ID documents don't say anything about how the IDs are created.

[wez]

There's some nuance/difficulty to implementing literally what you requested because of layering:

• The multiplexer layer (mux) which manages the domains and panes, and the mapping of windows, tabs and panes.
• The gui layer, which renders windows, tabs and panes

Windows can be created in the multiplexer model either to hold newly spawned panes/tabs, or when attaching to a domain that has a pre-existing set of windows, tabs and panes. Windows are always created after a pane; a window cannot exist without any panes inside it.

Gui windows are created in response to the multiplexer advising the gui that a window was added to the mux model.

From what you described, I think you're shooting for startup-time session management, and there isn't enough context associated with window creation to know whether it makes sense to do that.

For #256 what I had in mind was an event that fires when the GUI is started, but before the default_prog is invoked (when there are no windows). That would give an opportunity for your config logic to spawn a default set of windows/tabs. If it doesn't spawn anything, then default_prog would be spawned as usual.

We're currently missing a family of lua functions to operate on the Mux, Domain, and the mux Window, Tab and Pane objects (which are distinct from the Gui Window and Pane objects that are currently exposed). That API would be useful for the hypothetical wezterm cli eval subcommand that has been brought up in conversation and/or enhancement issues a couple of times, so it is doubly desirable to have.

[gwww]

Whew ;)

I installed Rust last night, cloned the repo and started looking into adding this. (Never really written rust before). I couldn't figure out the layers enough to determine where to drop the line of code to emit_event. Glad it wasn't just me not understanding... although I don't understand the layers yet, I now know it was not an "easy PR" for a beginner in this code base.

So, yes, what I was shooting for is startup callback to do splits and anything else I might want on launch. Generalizing for any new window, if it's easy, is a bonus.

[wez]

It's now possible to do this:

local wezterm = require 'wezterm'
local mux = wezterm.mux

-- This produces a window split horizontally into three equal parts
wezterm.on("gui-startup", function()
  wezterm.log_info("doing gui startup")
  local tab, pane, window = mux.spawn_window{}
  mux.split_pane(pane, {size=0.3})
  mux.split_pane(pane, {size=0.5})
end)

-- this is called by the mux server when it starts up.
-- It makes a window split top/bottom
wezterm.on("mux-startup", function()
  wezterm.log_info("doing mux startup")
  local tab, pane, window = mux.spawn_window{}
  mux.split_pane(pane, {direction="Top"})
end)

return {
  unix_domains = {
    {name="unix"}
  },
}

Docs still need to be written, but you may be able to infer some of the other functions from the code that sets up the wezterm.mux module which you can find over here: https://github.com/wez/wezterm/blob/main/lua-api-crates/mux/src/lib.rs

[wez]

Docs are now live at:

• https://wezfurlong.org/wezterm/config/lua/gui-events/gui-startup.html
• https://wezfurlong.org/wezterm/config/lua/mux-events/mux-startup.html
• https://wezfurlong.org/wezterm/config/lua/wezterm.mux/index.html

[wez]

This should be fixed now in main.

It typically takes about an hour before fixes are available as nightly builds for all platforms. Linux builds are the fastest to build and are often available within about 20 minutes. Windows and macOS builds take a bit longer.

Please take a few moments to try out the fix and let me know how that works out.

If you prefer to use packages provided by your distribution or package manager of choice and don't want to replace that with a nightly download, keep in mind that you can download portable packages (eg: a .dmg file on macOS, a .zip file on Windows and an .AppImage file on Linux) that can be run without permanently installing or replacing an existing package, and can then simply be deleted once you no longer need them.

If you are eager and can build from source then you may be able to try this out more quickly.

[gwww]

Once I figured out that mux.pane_split changed to pane:split all is good! Thank you!

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.