Session.newWindow
Creates a window in this session and returns that exact window.
Source and package
- Qualified name
-
io.github .libtmux .Session. new Window - Package
- io.github.libtmux
- Declared in
Session- Distribution
- io.github.libtmux:libtmux
- Source
- libtmux/src/main/java/io/github/libtmux/Session.java
- Other languages
- Perlmethod Erlang PowerShell Julia Elixir Haskell Common Lisp PythonRubyLuaTypeScriptRustGoC#C++SwiftKotlinScalaOCaml F# Clojure
- @Operation(Kind
.MUTATION ) public Window newWindow(String name)@Operation(Kind.MUTATION ) public Window newWindow( Consumer<WindowSpec > configure)@Operation(Kind.Builder .MUTATION ) public Window newWindow(WindowSpec spec) -
Description#
The creating command reports which window it made, rather than the name being looked up afterwards: two windows may share a name, and then a lookup cannot say which one is new.
Examples#
Create a window and read the updated session. Use JDK 25, Gradle 9 or newer, and tmux 3.3a or newer on Linux, with
/bin/catand/bin/shavailable. In an empty directory, save this consumer setup assettings.gradle.kts:rootProject.name = "api-example"Save this consumer setup as
build.gradle.kts. It depends on the 0.1.2 release from Maven Central:plugins {application}repositories { mavenCentral() }dependencies {implementation("io.github.libtmux:libtmux:0.1.2")}java { toolchain { languageVersion.set(JavaLanguageVersion.of(25)) } }application { mainClass.set(providers.gradleProperty("exampleMain")) }Save this consumer setup as
gradle.properties: View sourceorg.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=768m -Dfile.encoding=UTF-8kotlin.daemon.jvmargs=-Xmx2gorg.gradle.workers.max=2Save this launcher as
run.sh. It creates and stops a private tmux server, including after program failure. A shutdown failure retains its socket directory and exits unsuccessfully. View source#!/bin/shset -euif [ "$#" -eq 0 ]; thenprintf 'Usage: sh run.sh program [arguments...]\n' >&2exit 2fibinary=$(command -v "${TMUX_BIN:-tmux}")root=${API_RUN_ROOT:-/tmp/libtmux-java-dev}# A client that names no socket follows TMUX or LIBTMUX_SOCKET*, and otherwise lands on the default# socket under TMUX_TMPDIR. The program gets none of them, and a TMUX_TMPDIR of its own below.unset TMUX TMUX_PANEfor name in $(env | sed -n 's/^\(LIBTMUX_SOCKET[A-Za-z0-9_]*\)=.*/\1/p'); dounset "$name"donemkdir -p "$root"directory=$(mktemp -d "$root/api.XXXXXX")tmpdir=$(mktemp -d "$root/tmpdir.XXXXXX")socket="$directory/tmux.sock"config="$directory/tmux.conf"serves() {"$binary" -S "$1" display-message -p '#{pid}' >/dev/null 2>&1}# Stops the server on the socket, then waits for it to stop answering.stop() {"$binary" -S "$1" kill-server || return 1attempts=0while serves "$1" && [ "$attempts" -lt 60 ]; dosleep 0.05attempts=$((attempts + 1))done! serves "$1"}cleanup() {status=$?trap - 0 HUP INT TERM PIPE# A closed output must not end the cleanup, whose messages are the only thing left to write.trap '' PIPEset +estuck=left=if [ -S "$socket" ] && serves "$socket" && ! stop "$socket"; thenstuck="$stuck tmux.sock"fi# Every socket anywhere under either directory, without following links. Only one a server answers# on is a leak; the runner's own is expected to be there.old_ifs=$IFSIFS=''set -ffor candidate in $(find "$tmpdir" "$directory" -type s 2>/dev/null); do[ "$candidate" = "$socket" ] && continueserves "$candidate" || continuecase "$candidate" in"$tmpdir"/*) name=${candidate#"$tmpdir"/} ;;*) name=${candidate#"$directory"/} ;;esacleft="$left $name"stop "$candidate" || stuck="$stuck $name"doneset +fIFS=$old_ifsif [ -n "$stuck" ]; thenprintf 'tmux still answers on%s after kill-server; kept %s and %s under the runner root\n' \"$stuck" "${directory##*/}" "${tmpdir##*/}" >&2exit 1firm -rf "$directory" "$tmpdir" || exit 1if [ -n "$left" ]; thenprintf 'The program left a tmux server running:%s\n' "$left" >&2exit 1fiexit "$status"}trap cleanup 0trap 'exit 1' HUP INT TERM PIPE# A default socket path longer than this does not fit in sun_path.default_socket="$tmpdir/tmux-$(id -u)/default"if [ "$(printf '%s' "$default_socket" | wc -c)" -gt 100 ]; thenprintf 'API_RUN_ROOT is too long for a tmux socket\n' >&2exit 1fiTMUX_TMPDIR=$tmpdirexport TMUX_TMPDIRprintf 'set-option -g default-shell /bin/sh\n' > "$config""$binary" -S "$socket" -f "$config" new-session -d -s work-one -n editor /bin/cat"$binary" -S "$socket" split-window -h -t '=work-one:editor' /bin/cat"$binary" -S "$socket" new-window -d -t '=work-one' -n logs /bin/cat"$binary" -S "$socket" new-session -d -s work-two -n editor /bin/cat"$@" "$binary" "$socket" "$config""$binary" -S "$socket" has-session -t '=work-one'"$binary" -S "$socket" has-session -t '=work-two'Save this complete program as
src/main/java/NewWindow.java. It opens an ordinary client for the launcher's server; closing the client releases its transport. View sourcepackage io.github.libtmux.examples.api.java;import io.github.libtmux.Server;import io.github.libtmux.ServerConfig;import io.github.libtmux.ServerEndpoint;import io.github.libtmux.WindowSpec;import java.nio.file.Path;import java.util.stream.Collectors;/** Create a window and read the updated session. */public final class NewWindow {private NewWindow() {}public static void main(String[] args) {try {if (args.length != 3) {throw new IllegalArgumentException("expected: tmux-binary socket-path config-file");}var config = ServerConfig.builder().binary(args[0]).endpoint(ServerEndpoint.socketPath(Path.of(args[1]))).configFile(Path.of(args[2])).build();try (Server server = Server.open(config)) {var session = server.session("work-one").orElseThrow();var window = session.newWindow(WindowSpec.builder().named("api-window").running("/bin/cat").build());System.out.println("created=" + window.name());var refreshed = server.session("work-one").orElseThrow();System.out.println("windows="+ refreshed.windows().stream().map(item -> item.name()).sorted().collect(Collectors.joining(",")));}} catch (Exception error) {if (error instanceof InterruptedException) Thread.currentThread().interrupt();System.err.println("Example failed: " + error.getMessage());System.exit(1);}}}Build the minimal consumer with Gradle and run the saved program with the private fixture. An operation or cleanup error makes the command exit unsuccessfully:
Terminal window $ gradle --console=plain --quiet installDist -PexampleMain=io.github.libtmux.examples.api.java.NewWindow && \sh run.sh build/install/api-example/bin/api-exampleExpected output:
created=api-windowwindows=api-window,editor,logs- Parameters
-
-
configure(Consumer<WindowSpec >) # – receives a builder holding tmux's defaults for.Builder newWindow(configure) -
spec(WindowSpec ) # fornewWindow(spec)
- Returns
-
a handle on the created window, from a fresh capture
tmux command#
The tmux commands behind newWindow.
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 |
| Clojure | libtmux |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| C++ | libtmux:: |
| 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#.