Quake-style drop-down window: portal and layering first #12

New issue

Open

opened 2026-08-19 23:56:55 +00:00 by dusan · 0 comments

dusan commented

2026-08-19 23:56:55 +00:00

Owner

Context

Terminalko is a normal windowed application: TkWindow is an
adw::ApplicationWindow created on activation
(crates/terminalko/src/application.rs). It already has fullscreen (F11, with
the header bar revealed at the top edge) and multiple windows
(Ctrl+Shift+N).

The original plan's M7 listed a quake-style drop-down window: a terminal that
slides in from an edge on a global key, over whatever is on screen, and hides
again.

The hard part is not the window

Under Wayland an application cannot bind a global shortcut itself, and cannot
place or raise its own window. The two things this feature needs are exactly the
two things the display protocol refuses. So:

the shortcut has to come from the desktop, through the GlobalShortcuts
portal (org.freedesktop.portal.GlobalShortcuts), which the user grants once
and can revoke; a compositor without it means no shortcut at all;
positioning and layering need zwlr_layer_shell_v1 or the compositor's
equivalent, which GTK does not expose. GTK4 has no supported way to make a
layer-shell surface; gtk4-layer-shell exists as a separate library and works
by intercepting surface creation.

That makes this a genuinely different kind of change from everything else in this
repository, and it may reasonably be declined: a session-oriented terminal
whose whole point is that sessions outlive their windows overlaps oddly with a
window that hides itself.

If it is attempted

start with the portal and a plain window that presents and hides on the
shortcut. That much is achievable and useful, and does not need layer-shell;
only then consider gtk4-layer-shell for the drop-down placement, behind a
build option, so a build without it still works;
which session does it show? A dedicated one, remembered across invocations, is
the obvious answer — and the agent already makes that sensible: the session
keeps running while the window is hidden;
hiding must detach, not stop, or the point is lost.

Acceptance criteria

A shortcut granted through the GlobalShortcuts portal shows and hides the
window, and the session inside it keeps running while hidden.
Denying or revoking the portal permission leaves the application working
normally, with an explanation rather than a broken shortcut.
On a compositor without the portal, the feature is absent rather than broken.
No regression to ordinary windows: ./build-aux/smoke.sh still passes.
docs/spec/ gains a spec explaining the portal and layering decisions.

Notes

https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.GlobalShortcuts.html
https://github.com/wmww/gtk4-layer-shell
BSD-2: gtk4-layer-shell is MIT, which is compatible; record it in NOTICE if
it is used.

## Context Terminalko is a normal windowed application: `TkWindow` is an `adw::ApplicationWindow` created on activation (`crates/terminalko/src/application.rs`). It already has fullscreen (`F11`, with the header bar revealed at the top edge) and multiple windows (`Ctrl+Shift+N`). The original plan's M7 listed a **quake-style drop-down window**: a terminal that slides in from an edge on a global key, over whatever is on screen, and hides again. ## The hard part is not the window Under Wayland an application **cannot bind a global shortcut itself**, and cannot place or raise its own window. The two things this feature needs are exactly the two things the display protocol refuses. So: * the shortcut has to come from the desktop, through the **GlobalShortcuts portal** (`org.freedesktop.portal.GlobalShortcuts`), which the user grants once and can revoke; a compositor without it means no shortcut at all; * positioning and layering need `zwlr_layer_shell_v1` or the compositor's equivalent, which GTK does not expose. GTK4 has no supported way to make a layer-shell surface; `gtk4-layer-shell` exists as a separate library and works by intercepting surface creation. That makes this a genuinely different kind of change from everything else in this repository, and it may reasonably be **declined**: a session-oriented terminal whose whole point is that sessions outlive their windows overlaps oddly with a window that hides itself. ## If it is attempted * start with the portal and a plain window that presents and hides on the shortcut. That much is achievable and useful, and does not need layer-shell; * only then consider `gtk4-layer-shell` for the drop-down placement, behind a build option, so a build without it still works; * which session does it show? A dedicated one, remembered across invocations, is the obvious answer — and the agent already makes that sensible: the session keeps running while the window is hidden; * hiding must **detach**, not stop, or the point is lost. ## Acceptance criteria - A shortcut granted through the GlobalShortcuts portal shows and hides the window, and the session inside it keeps running while hidden. - Denying or revoking the portal permission leaves the application working normally, with an explanation rather than a broken shortcut. - On a compositor without the portal, the feature is absent rather than broken. - No regression to ordinary windows: `./build-aux/smoke.sh` still passes. - `docs/spec/` gains a spec explaining the portal and layering decisions. ## Notes - <https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.GlobalShortcuts.html> - <https://github.com/wmww/gtk4-layer-shell> - BSD-2: `gtk4-layer-shell` is MIT, which is compatible; record it in `NOTICE` if it is used.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

dusan/terminalko#12

No description provided.

Rows
Columns