add window:active_tab(), window:active_pane(), tab:active_pane()

docs/changelog.md

@@ -40,6 +40,12 @@ As features stabilize some brief notes about them will accumulate here.
   obtain that same information and amend/extend it.
 * [display_pixel_geometry](config/lua/config/display_pixel_geometry.md) to specify subpixel antialiasing geometry. ?3422
 * In progress: integrated title and tab bar. Thanks to @yuraiz for getting things moving! #2722
+* Lua: [gui_window:active_tab()](config/lua/window/active_tab.md),
+  [gui_window:active_pane()](config/lua/window/active_pane.md) (surprise! this was already there, just undocumented!),
+  [mux_window:active_tab()](config/lua/mux-window/active_tab.md),
+  [mux_window:active_pane()](config/lua/mux-window/active_pane.md),
+  [tab:active_pane()](config/lua/MuxTab/active_pane.md) methods for conveniently getting at the active tab/pane
+  from a window/tab.
 
 #### Fixed
 * mux: Stale remote window mapping could prevent spawning new tabs in remote domain. #2759

docs/config/lua/MuxTab/active_pane.md

@@ -0,0 +1,18 @@
+# `tab:active_pane()`
+
+{{since('nightly')}}
+
+A convenience accessor for returning the active pane in the tab.
+
+In earlier versions of wezterm, you could obtain this via:
+
+```lua
+function active_pane(tab)
+  for _, item in ipairs(tab:panes_with_info()) do
+    if item.is_active then
+      return item.pane
+    end
+  end
+end
+```
+

docs/config/lua/mux-window/active_pane.md

@@ -0,0 +1,30 @@
+# `window:active_pane()`
+
+{{since('nightly')}}
+
+A convenience accessor for returning the active pane in the active tab of the window.
+
+In earlier versions of wezterm, you could obtain this via:
+
+```lua
+function active_tab(window)
+  for _, item in ipairs(window:tabs_with_info()) do
+    if item.is_active then
+      return item.tab
+    end
+  end
+end
+
+function active_pane(tab)
+  for _, item in ipairs(tab:panes_with_info()) do
+    if item.is_active then
+      return item.pane
+    end
+  end
+end
+```
+
+See also [gui_window:active_pane()](../window/active_pane.md), which is similar
+to this method, but which can return overlay panes that are not visible to
+the mux layer of the API.
+

docs/config/lua/mux-window/active_tab.md

@@ -0,0 +1,17 @@
+# `window:active_tab()`
+
+{{since('nightly')}}
+
+A convenience accessor for returning the active tab within the window.
+
+In earlier versions of wezterm, you could obtain this via:
+
+```lua
+function active_tab(window)
+  for _, item in ipairs(window:tabs_with_info()) do
+    if item.is_active then
+      return item.tab
+    end
+  end
+end
+```

docs/config/lua/window/active_pane.md

@@ -0,0 +1,11 @@
+# `window:active_pane()`
+
+{{since('20221119-145034-49b9839f')}}
+
+A convenience accessor for returning the active pane in the active tab of the
+GUI window.
+
+This is similar to [mux_window:active_pane()](../mux-window/active_pane.md)
+but, because it operates at the GUI layer, it can return *Pane* objects for
+special overlay panes that are not visible to the mux layer of the API.
+

docs/config/lua/window/active_tab.md

@@ -0,0 +1,18 @@
+# `window:active_tab()`
+
+{{since('nightly')}}
+
+A convenience accessor for returning the active tab within the window.
+
+In earlier versions of wezterm, you could obtain this via:
+
+```lua
+function active_tab_for_gui_window(gui_window)
+  for _, item in ipairs(gui_window:mux_window():tabs_with_info()) do
+    if item.is_active then
+      return item.tab
+    end
+  end
+end
+```
+

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

@@ -46,6 +46,11 @@ impl UserData for MuxTab {
             let tab = this.resolve(&mux)?;
             Ok(tab.set_title(&title))
         });
+        methods.add_method("active_pane", |_, this, _: ()| {
+            let mux = get_mux()?;
+            let tab = this.resolve(&mux)?;
+            Ok(tab.get_active_pane().map(|pane| MuxPane(pane.pane_id())))
+        });
         methods.add_method("panes", |_, this, _: ()| {
             let mux = get_mux()?;
             let tab = this.resolve(&mux)?;

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

@@ -93,5 +93,17 @@ impl UserData for MuxWindow {
             }
             Ok(result)
         });
+        methods.add_method("active_tab", |_, this, _: ()| {
+            let mux = get_mux()?;
+            let window = this.resolve(&mux)?;
+            Ok(window.get_active().map(|tab| MuxTab(tab.tab_id())))
+        });
+        methods.add_method("active_pane", |_, this, _: ()| {
+            let mux = get_mux()?;
+            let window = this.resolve(&mux)?;
+            Ok(window
+                .get_active()
+                .and_then(|tab| tab.get_active_pane().map(|pane| MuxPane(pane.pane_id()))))
+        });
     }
 }

wezterm-gui/src/scripting/guiwin.rs

@@ -45,6 +45,14 @@ impl UserData for GuiWin {
         methods.add_method("mux_window", |_, this, _: ()| {
             Ok(mux_lua::MuxWindow(this.mux_window_id))
         });
+        methods.add_method("active_tab", |_, this, _: ()| {
+            let mux = Mux::try_get().ok_or_else(|| mlua::Error::external("cannot get Mux!?"))?;
+            let window = mux.get_window(this.mux_window_id).ok_or_else(|| {
+                mlua::Error::external(format!("invalid window {}", this.mux_window_id))
+            })?;
+            Ok(window.get_active().map(|tab| mux_lua::MuxTab(tab.tab_id())))
+        });
+
         methods.add_method(
             "set_inner_size",
             |_, this, (width, height): (usize, usize)| {