C++ API

method libtmux-cxx latest

Pane.split

Split this exact pane rather than whichever pane in its window happens to be active.

Source and package

Qualified name: libtmux::Pane::split
Namespace: libtmux
Declared in: Pane
Package: libtmux-cxx
Source: include/libtmux/entities.hpp

[[C++ nodiscard attributeAsks the compiler to warn when a result is discarded. An explicit cast to void acknowledges that the result is intentionally ignored.Language documentation]] expected<Pane, CommandFailure> split(SplitOptions options = {}) const; method readonly [source] ¶

Examples#

Create a window and split a pane. Create a detached window, split it side by side, and verify both panes belong to it. The cat processes keep each pane alive until fixture cleanup. Creation leaves the session selection unchanged because focus defaults to false. 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 before = session.active_window();
  if (!before.has_value()) {
    std::fprintf(stderr, "%s\n", before.error().diagnostic.c_str());
    return 1;
  }
  const auto window = session.new_window(
      libtmux::NewWindowOptions{.name = "editor", .shell_command = "exec cat"});
  if (!window.has_value()) {
    std::fprintf(stderr, "%s\n", window.error().diagnostic.c_str());
    return 1;
  }
  const auto first = window->active_pane();
  if (!first.has_value()) {
    std::fprintf(stderr, "%s\n", first.error().diagnostic.c_str());
    return 1;
  }
  const auto second = first->split(
      libtmux::SplitOptions{.horizontal = true, .shell_command = "exec cat"});
  if (!second.has_value()) {
    std::fprintf(stderr, "%s\n", second.error().diagnostic.c_str());
    return 1;
  }
  const auto panes = window->panes();
  const auto after = session.active_window();
  if (!panes.has_value()) {
    std::fprintf(stderr, "%s\n", panes.error().diagnostic.c_str());
    return 1;
  }
  if (!after.has_value()) {
    std::fprintf(stderr, "%s\n", after.error().diagnostic.c_str());
    return 1;
  }
  if (panes->size() != 2 || *before != *after ||
      first->window_id() != second->window_id() || *first == *second) {
    std::fputs("created panes or selection do not match\n", stderr);
    return 1;
  }
  std::puts("Created editor with two panes; the active window is unchanged.");
  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:

Created editor with two panes; the active window is unchanged.

Parameters

options (SplitOptions) #

tmux command#

The tmux commands behind split.

split-window

tmux C API#

The C declarations in tmux that implement these commands.

cmd_split_window_entry cmd_split_window_exec

Each path starts at a function a command runs, which is degree 1. The degree counts steps from there along the path, and each step is a call or a reference: degree 2 is reached from that function, degree 3 from the next, and so on.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Pane.split

Examples#

tmux command#

tmux C API#

Split a window

Examples#

tmux command#

tmux C API#

Split a window

Related types#