C++ API

class libtmux-cxx latest

Pane

One pane, as one listing saw it.

Source and package

Qualified name: libtmux::Pane
Namespace: libtmux
Package: libtmux-cxx
Source: include/libtmux/entities.hpp
Other languages: Perlclass ErlangPowerShellcmdlet Juliastruct Elixirstruct Haskell Common Lispclass PythonRubyLuaTypeScriptRustGoJavaC#SwiftKotlinScalaOCamlF#module Clojurefunction

class libtmux::Pane class [source] ¶

Description#

The narrowest thing tmux addresses, and the only one that owns a process: pid() is the command tmux started, not the shell's children, so a pane running a program under a shell reports the shell.

Reads its own fields without touching tmux, on the same terms as Session.

Examples#

Traverse a session and its children. List windows and panes within one session, then follow a pane back to its owning window and session. Each relation method performs a new read; the original entity still holds its earlier snapshot. libtmux-cxx is not published to a package registry yet, so this builds it from its repository. Use Clang 18 or newer with libc++, CMake 3.25 or newer, Ninja, Git, and tmux 3.3a or newer on Linux. In an empty directory, fetch the documented library revision:

$ git clone https://github.com/libtmux/libtmux-cxx.git libtmux-source && \
  git -C libtmux-source checkout 542fdc204ff3cfa56f5484327cda0c69bad2307d

Build and install the C++23 library and its public testing component into this directory:

$ cmake -S libtmux-source -B libtmux-build -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE="$PWD/libtmux-source/cmake/toolchains/clang-libcxx.cmake" \
    -DCMAKE_C_COMPILER=clang \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DCMAKE_BUILD_TYPE=Release \
    -DLIBTMUX_BUILD_TESTS=OFF \
    -DLIBTMUX_BUILD_EXAMPLES=OFF \
    -DLIBTMUX_BUILD_TESTING_LIBRARY=ON && \
  cmake --build libtmux-build --parallel 2 && \
  cmake --install libtmux-build --prefix "$PWD/libtmux-prefix"

Save this complete consumer project as CMakeLists.txt: View source

cmake_minimum_required(VERSION 3.25)
project(libtmux_api_example LANGUAGES CXX)

find_package(libtmux REQUIRED COMPONENTS testing)

add_executable(api_example main.cpp)
target_link_libraries(api_example PRIVATE libtmux::libtmux libtmux::testing)

Save this complete program as main.cpp. ScopedTmuxServer owns a private daemon and stops it when the program exits. Ordinary applications use Server for their own socket; these examples use the fixture until setup moves to ordinary server objects. View source

#include <cstdio>

#include <libtmux/libtmux.hpp>
#include <libtmux/testing/scoped_server.hpp>

int main() {
  // The fixture owns this private server and cleans it up on every return path.
  auto fixture = libtmux::test::ScopedTmuxServer::start({
      .session_name = "api",
      .socket_namespace = libtmux::test::SocketNamespace::consumer("api"),
  });
  if (!fixture.has_value()) {
    std::fprintf(stderr, "%s\n", fixture.error().c_str());
    return 1;
  }
  auto server = libtmux::Server::at_socket_path(fixture->socket_path());
  if (!server.has_value()) {
    std::fprintf(stderr, "%s\n", server.error().diagnostic.c_str());
    return 1;
  }

  const auto sessions = server->sessions();
  if (!sessions.has_value()) {
    std::fprintf(stderr, "%s\n", sessions.error().diagnostic.c_str());
    return 1;
  }
  if (sessions->size() != 1) {
    std::fputs("expected one session\n", stderr);
    return 1;
  }
  const auto& session = sessions->front();
  const auto windows = session.windows();
  const auto session_panes = session.panes();
  if (!windows.has_value()) {
    std::fprintf(stderr, "%s\n", windows.error().diagnostic.c_str());
    return 1;
  }
  if (!session_panes.has_value()) {
    std::fprintf(stderr, "%s\n", session_panes.error().diagnostic.c_str());
    return 1;
  }
  if (windows->size() != 1 || session_panes->size() != 1) {
    std::fputs("expected one window and pane\n", stderr);
    return 1;
  }
  const auto& window = windows->front();
  const auto panes = window.panes();
  if (!panes.has_value()) {
    std::fprintf(stderr, "%s\n", panes.error().diagnostic.c_str());
    return 1;
  }
  if (panes->size() != 1) {
    std::fputs("expected one window pane\n", stderr);
    return 1;
  }
  const auto owner_window = panes->front().window();
  const auto owner_session = panes->front().session();
  if (!owner_window.has_value()) {
    std::fprintf(stderr, "%s\n", owner_window.error().diagnostic.c_str());
    return 1;
  }
  if (!owner_session.has_value()) {
    std::fprintf(stderr, "%s\n", owner_session.error().diagnostic.c_str());
    return 1;
  }
  if (*owner_window != window || *owner_session != session ||
      panes->front() != session_panes->front()) {
    std::fputs("entity ownership does not match\n", stderr);
    return 1;
  }
  std::puts("api session -> one window -> one pane; owners match.");
  return 0;
}

Build against the installed library and run the saved program. An operation error produces a failing exit status:

$ cmake -S . -B build -G Ninja \
    -DCMAKE_PREFIX_PATH="$PWD/libtmux-prefix" \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DCMAKE_CXX_FLAGS=-stdlib=libc++ && \
  cmake --build build --parallel 2 && \
  ./build/api_example

Expected output:

api session -> one window -> one pane; owners match.

Members59#

Parent objects3#

window method
session method
server method inherited The server this entity came from, for a command the typed surface does not cover.

Common operations44#

capture method The visible contents, as tmux printed them.
send_text method Literal text, never interpreted as key names or formats, and never followed by a newline the caller did not ask for.
kill method
respawn method Start the pane's command again.
select method
id method
index method
break_out method Take this pane out into a window of its own, which is returned.
set_title method Name this pane.
height method
width method
title method
active method
command method What is running in the pane now, which is not what started it.
swap_with method
clear_history method Forget the scrollback, which is the only way to bound a pane's memory without restarting what is running in it.
paste method Deliver a buffer's text to this pane, as if it had been typed.
options method Pane options, the narrowest scope tmux has, and the end of an inheritance chain that runs pane, window, session, global.
join method Move this pane into another window, splitting it.
pipe_to method Copy everything this pane prints to a shell command, until told to stop.
set_option method
unset_option method
enter_copy_mode method Put this pane into copy mode, where its contents can be scrolled and selected rather than typed into.
option method
pid method
window_id method
refresh method
at_top method
at_bottom method
at_left method
at_right method
show_message method Show a message to the clients watching this pane's session, expanded against this pane.
dead method A pane whose program exited while remain-on-exit kept it on screen.
tty method
session_id method
set_height method
set_width method
in_mode method Copy mode and its relatives, in which sent keys move the cursor rather than reaching the program.
path method
expand method Ask tmux to expand a format against this pane.
send_key method
send_line method The text and then Enter, as one tmux invocation.
split method Split this exact pane rather than whichever pane in its window happens to be active.
wait_for_text method Wait until this pane produces wanted, rather than until it merely appears on screen.

Other members12#

exit_status method What the pane's process exited with, once it has.
kFields: std::array attribute
kNoun: std::string_view attribute
kSessionNameField: std::string_view attribute
leave_mode method Leave whatever mode the pane is in.
left method Position within the window, in cells from its top-left corner — the geometry select_layout()'s saved arrangement places panes at.
Pane method
piping method Whether this pane's output is currently being copied to a command.
session_name method The owning psmux route carried by Windows live snapshots.
stop_piping method Stop copying. Harmless on a pane that was not piping.
toggle_zoom method Toggle whether this pane's window is zoomed onto it — the whole window given over to one pane, full size.
top method Its counterpart along the other axis.

Guides#

Pages that discuss Pane.

Concepts: Server, session, window, pane
Topics: Architecture
Ownership and cleanup
Format-token fields
Options and hooks
Traversal

In other ports#

A tmux pane

Equivalents of A tmux pane in other languages
Language	Equivalent
Python	`libtmux.Pane`
Ruby	`LibTmux::Pane`
Lua	`libtmux.Pane`
PowerShell	`LibTmux\Get-TmuxPane` This cmdlet reads shared .NET `LibTmux.Pane` objects. Its `-Server`, `-Session`, and `-Window` parameter sets select the scope.
Julia	`LibTmux.PaneSnapshot` `PaneSnapshot` holds captured pane data. Actions use its `PaneRef`; `PaneOccurrence` adds a window placement in a session.
Erlang	`#tmux_model:pane{}`
Elixir	`LibTmux.Pane` `Pane` is an immutable physical pane observation. It does not send keys or capture text.
Haskell	No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
Common Lisp	`libtmux:pane` `pane` is an immutable captured physical pane.
TypeScript	`pane.Pane`
Rust	`pane.Pane`
Go	`tmux.Pane`
Java	`io.github.libtmux.Pane`
Clojure	`libtmux.data/panes` Traverses captured pane maps without I/O. Use keyword lookup for scalar observations and the preserved :tmux/ref for effects.
Kotlin	`io.github.libtmux.kotlin.Pane`
Scala	`io.github.libtmux.scaladsl.Pane`
C#	`LibTmux.Pane`
F#	`LibTmux.FSharp.Pane` This F# module reads captured fields and starts explicit operations on the shared .NET `LibTmux.Pane` type.
Swift	`Pane`
OCaml	`Libtmux.Pane.t`
Perl	`LibTmux::Pane` A physical pane retains its captured graph, without retaining transport.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Pane

Description#

Examples#

Members59#

Parent objects3#

Common operations44#

Other members12#

Guides#

In other ports#

Description#

Examples#

Members59#

Parent objects3#

Common operations44#

Other members12#

Guides#

In other ports#

Related types#