On this page

pane.Pane.break_out

Module: pane
Declared in: Pane
Package: libtmux
Source: crates/libtmux/src/pane.rs

break_out ( self ) → Result<Self, Error> method [source] ¶ method [source] ¶ break_out

Move this pane out into a window of its own.

This consumes the handle, because the pane's window changes and any snapshot of its old position is now wrong.

A pane that is already alone in its window is a no-op, not a refusal. tmux relinks the window rather than rejecting the command -- see cmd-break-pane.c, which links the window into the target session and unlinks it from the source when the pane count is one -- so within one session nothing moves and the call still succeeds. The returned handle names the window it is in either way, which is how a caller tells the two apart.

Errors

Returns an error when tmux refuses the command. Being the window's only pane is not one of those, and neither is it a no-op: tmux relinks the window rather than breaking a pane out of it, which moves the window to a free index. The window and pane ids are unchanged, so a [Window] held across this call keeps its identity and loses its index.

[Window]: crate::Window

Examples

use libtmux::{SplitDirection, SplitOptions};

let guard = libtmux::test::TestServer::new().await?;
let session = guard.server().new_session("broken-out").await?;
let pane = session.panes().await?.remove(0);
let stays = pane.window_id().clone();

let moved = pane.split(SplitOptions::new(SplitDirection::Below)).await?;
let moved = moved.break_out().await?;

// The window it landed in, without listing the server to find it.
assert_ne!(moved.window_id(), &stays);

0 declared, 0 inherited