C++ API

Up Root

struct libtmux-cxx latest

NewWindowOptions

What a new window is created as, and where it lands.

Source and package

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

struct libtmux::NewWindowOptions struct [source] ¶

Description#

Placing a window after the current one shifts the windows above it up, so an index a caller is holding can change.

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.

Members7#

after_current: bool attribute Immediately after the current window rather than at the end.
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
index: std::optional<long long> attribute Put the window at this index rather than at the next free one.
name: std::string attribute
shell_command: std::string attribute
start_directory: std::string attribute

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

NewWindowOptions

Description#

Examples#

Members7#