C++ API

class libtmux-cxx latest

Window

One window, as one listing saw it.

Source and package

Qualified name: libtmux::Window
Namespace: libtmux
Package: libtmux-cxx
Source: include/libtmux/entities.hpp
Other languages: Perlclass Erlangstruct PowerShellcmdlet Juliastruct Elixirstruct Haskell Common Lispclass PythonRubyLuaTypeScriptRustGoJavaC#SwiftKotlinScalaOCamltypealias F#module Clojurefunction

class libtmux::Window class [source] ¶

Description#

A window can be linked into more than one session; this handle carries the session it was reached through, which is the one its qualified target addresses.

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.

Members45#

Parent objects2#

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

Collections and queries1#

panes method

Common operations31#

select_layout method Rearrange the panes.
kill method
rename method
link_to method Show this window in another session as well.
unlink method Stop showing it in the session this value came from.
select method
id method
name method
move_to method Move to another index within the same session.
split method
height method
width method
options method Window options.
index method Position within its session, which base-index is free to start anywhere.
resize method
rotate method
set_option method
unset_option method
active method
layout method An opaque token: hand it back to select_layout() exactly as received, and do not parse its shape.
swap_with method Exchange positions with another window, keeping both ids.
active_pane method
option method
next_layout method Step through tmux's preset arrangements, and turn the panes within the one in use.
refresh method
previous_layout method
select_last_pane method Go back to the pane that was selected before the current one, and answer with it.
pane_count method
show_message method Show a message to the clients watching this window's session.
session_id method The link to the parent, carried in the row so traversal upward costs nothing until the parent itself is wanted.
activity method

Other members11#

bell method
checked_target method
expand method Ask tmux to expand a format against this window: the same reach the session form gives, guarded the same way.
kFields: std::array attribute
kNoun: std::string_view attribute
kSessionNameField: std::string_view attribute
linked_sessions method How many sessions hold this window.
session_name method The owning psmux route carried by Windows live snapshots.
target method How to address this window, and the reason a window id alone will not do.
Window method
zoomed method

Guides#

Pages that discuss Window.

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

In other ports#

A tmux window

Equivalents of A tmux window in other languages
Language	Equivalent
Python	`libtmux.Window`
Ruby	`LibTmux::Window`
Lua	`libtmux.Window`
PowerShell	`LibTmux\Get-TmuxWindow` This cmdlet reads shared .NET `LibTmux.Window` placements. Use `-Server` for all sessions or `-Session` for one session.
Julia	`LibTmux.WindowSnapshot` `WindowSnapshot` holds captured physical-window data. `WindowLink` records a placement in a session; actions use `WindowRef`.
Erlang	`#tmux_model:window{}` A physical window can have several session memberships. `window_link` holds the session-relative index and active flag.
Elixir	`LibTmux.Window` `Window` is a physical window. `WindowLink` records its session index and active state.
Haskell	No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
Common Lisp	`libtmux:window` `window` is a physical captured window. `window-link` preserves each session placement.
TypeScript	`window.Window`
Rust	`window.Window`
Go	`tmux.Window`
Java	`io.github.libtmux.Window`
Clojure	`libtmux.data/windows` Traverses captured window-placement maps without I/O; the window value is a map with an explicit Java reference for effects.
Kotlin	`io.github.libtmux.kotlin.Window`
Scala	`io.github.libtmux.scaladsl.Window`
C#	`LibTmux.Window`
F#	`LibTmux.FSharp.Window` This F# module identifies shared .NET `LibTmux.Window` placements and builds deferred pane queries. `Query.list` acquires their results from tmux.
Swift	`Window`
OCaml	`Libtmux.Window.t` A global window can have several session placements. Window_link holds the session, index and current flag.
Perl	`LibTmux::Window` Physical window identity. WindowLink owns each session/index placement.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Window

Description#

Examples#

Members45#

Parent objects2#

Collections and queries1#

Common operations31#

Other members11#

Guides#

In other ports#

Description#

Examples#

Members45#

Parent objects2#

Collections and queries1#

Common operations31#

Other members11#

Guides#

In other ports#

Related types#