Session.new_window
Created detached: a library call that stole the terminal would be a surprise, and attaching is a separate decision.
Source and package
- [[
C++ nodiscard attributeAsks the compiler to warn when a result is discarded. An explicit cast to void acknowledges that the result is intentionally ignored.]] expected<Window, CommandFailure > new_window(std::string name) const;[[_view C++ nodiscard attributeAsks the compiler to warn when a result is discarded. An explicit cast to void acknowledges that the result is intentionally ignored.]] expected<Window, CommandFailure > new_window(NewWindow options) const;Options -
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:
Terminal window $ git clone https://github.com/libtmux/libtmux-cxx.git libtmux-source && \git -C libtmux-source checkout 542fdc204ff3cfa56f5484327cda0c69bad2307dBuild and install the C++23 library and its public testing component into this directory:
Terminal window $ 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 sourcecmake_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.ScopedTmuxServerowns a private daemon and stops it when the program exits. Ordinary applications useServerfor 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:
Terminal window $ 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_exampleExpected output:
Created editor with two panes; the active window is unchanged.- Parameters
-
-
name(std::string ) # for_view new_window(name) -
options(NewWindow ) # forOptions new_window(options)
-
tmux command#
The tmux commands behind new_window.
tmux C API#
The C declarations in tmux that implement these commands.
In other ports#
Create a window
| Language | Equivalent |
|---|---|
| Python | libtmux |
| Ruby | Lib |
| Lua | libtmux |
| Erlang | tmux |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| TypeScript | session |
| Rust | session |
| Go | tmux |
| Java | io |
| Clojure | libtmux |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| Swift | Server |
| OCaml | Libtmux |
| Perl | Lib Explicit Server operation. Captured entities remain local observations; use a new snapshot to observe changes. |
No equivalent is recorded in PowerShell, Julia, Elixir, Common Lisp or F#.