C++ API

struct libtmux-cxx latest

SplitOptions

What a creation command can be told.

Source and package

Qualified name: libtmux::SplitOptions
Namespace: libtmux
Package: libtmux-cxx
Source: include/libtmux/entities.hpp

struct libtmux::SplitOptions struct [source] ¶

Description#

Every field maps to a flag tmux 3.3a already has, and every default is what tmux does when the flag is absent — except focus, which defaults to leaving it where the user put it. A library that moves someone's cursor because it created something is a library people stop calling.

Aggregates rather than parameters: a caller writes only the fields it cares about, and a field added later does not renumber anything.

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.

Members8#

before: bool attribute Before the target rather than after it.
environment: std::vector<std::pair<std::string, std::string>> attribute Variables the new process starts with, on top of what tmux passes down.
focus: bool attribute Make the new pane the active one.
full_size: bool attribute Spanning the full width or height of the window rather than of the pane.
horizontal: bool attribute Side by side. tmux stacks by default.
percentage: std::optional<int> attribute Size as a percentage of the space being divided.
shell_command: std::string attribute Run this instead of the default shell.
start_directory: std::string attribute Where the new pane starts. Empty inherits from the window.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

SplitOptions

Description#

Examples#

Members8#