About¶

Welcome to the WTQ docs!

WTQ runs in the background, and enables sliding applications on- and off the screen, Quake style.

Supports:

Windows 10 and 11
KDE Plasma 5 & 6 (Wayland only)

See Installation to get started.

Here's an example where WTQ runs on Windows 10, toggling Windows Terminal, Double Commander, Process Hacker and KeePassXC.

And here's one on KDE Plasma 6, toggling WezTerm, Dolphin System Monitor and KeePassXC.

Why "Quake" Style

The game Quake (by id Software) is generally considered the game that popularized toggling of the console onto the screen, by sliding it from the top. See this video for an example of what that looked like.

The "WTQ" Name

WTQ initially started as a companion app for Microsoft's thrilling sequel to the classic command prompt; Windows Terminal. Fit that with Quake-style toggling, and you get "Windows Terminal Quake".

Much later, support for other terminals was added, and support for toggling apps that were not terminals at all.

So now I refer to it as "WTQ", not having the balls to straight up rename it.

Installation¶

Windows¶

Scoop¶

A command-line installer for Windows.

scoop install https://raw.githubusercontent.com/flyingpie/windows-terminal-quake/master/scoop/wtq-latest.json

A shortcut is then available named "WTQ - Windows Terminal Quake", or you can just run "wtq" from a command line or Win+R.

Update (just WTQ):

scoop update wtq-latest

WinGet¶

The Windows package manager.

winget install windows-terminal-quake

You can then call "wtq" from the command line.

After having done that at least once, a shortcut will appear in the start menu, called "WTQ - Main Window".

Update (just WTQ):

winget upgrade windows-terminal-quake

Where's WTQ Installed?

You can run

winget --info

To find out where apps are installed:

Windows Package Manager v1.10.340
(...)
Portable Package Root (User)       %LOCALAPPDATA%\Microsoft\WinGet\Packages

Manual¶

See the latest release, and pick a zip.

Self-Contained
Slightly larger, but does not require dependencies to be installed (i.e. .Net).
Framework-Dependent
Smaller, but requires .Net 9 to be installed.

Linux¶

Manual¶

See the ~/linux/install-or-upgrade-wtq.sh script that downloads the latest version of WTQ, installs it to ~/.local/share/wtq, and creates a wtq.desktop file.

As a 1-liner:

bash <(curl -s https://raw.githubusercontent.com/flyingpie/windows-terminal-quake/refs/heads/master/linux/install-or-upgrade-wtq.sh)

And the ~/linux/uninstall-wtq.sh uninstall script.

bash <(curl -s https://raw.githubusercontent.com/flyingpie/windows-terminal-quake/refs/heads/master/linux/uninstall-wtq.sh)

Settings File Remains

The WTQ settings are not removed by this script. These are usually located at ~/.config/wtq, also see Settings.

Flatpak¶

TODO

App examples¶

TODO

Settings¶

Settings are stored in a JSON file, usually named wtq.jsonc.

The file can use the extension .json, .jsonc or .json5. The latter two are supported, so that editors like VSCode automatically switch to "JSON with Comments", making working with comments nicer.

Settings File Locations¶

Where's My Settings File?

The file can be in several places, to support different use cases and preferences.

You can quickly open either the settings file, or the directory that contains the settings file by clicking the tray icon -> Open Settings File, or Open Settings Directory.

Tray icon menu options.

Additionally, it's also displayed in the GUI, with a link for convenience.

On Windows¶

These locations are considered, in order:

A path defined by an environment variable named WTQ_CONFIG_FILE (regardless of filename or extension)
Next to the WTQ executable
- When using Scoop: C:\Users\username\scoop\apps\wtq-latest\current
- When using WinGet: C:\Users\username\AppData\Local\Microsoft\WinGet\Packages\flyingpie.windows-terminal-quake_Microsoft.Winget.Source_8wekyb3d8bbwe
- Or wherever else the wtq.exe file is
In %USERPROFILE%\.config
- C:\users\username\.config\wtq.json
In user home
- C:\users\username\wtq.json
In user home, as a dot file
- C:\users\username\.wtq.json
In app data
- C:\users\username\AppData\Roaming\wtq\wtq.json

If no settings were found at any of these locations, WTQ creates a settings file at C:\Users\username\AppData\Roaming\wtq\wtq.jsonc.

On Linux¶

These locations are considered, in order:

A path defined by an environment variable named WTQ_CONFIG_FILE (regardless of filename or extension)
Next to the WTQ executable
- When using the install script: /home/username/.local/share/wtq
In $XDG_CONFIG_HOME, if defined (following to the XDG spec)
- /home/username/.config/wtq.json
In ~/.config (the default for XDG_CONFIG_HOME, if is it not defined)
- /home/username/.config/wtq.json
In user home
- /home/username/wtq.json
In user home, as a dot file
- /home/username/.wtq.json

If no settings were found at any of these locations, WTQ creates a settings file at $XDG_CONFIG_HOME: /home/username/.config/wtq/wtq.jsonc.

TODO

TODO: Mention wtq.schema.json

TODO

TODO: Mention GUI

Global options¶

Defines WTQ-wide options, including the list of configured apps.

General¶

Apps¶

Applications to enable Quake-style dropdown for.

{
  "Apps": [
    { "Name": "App 1" },
    { "Name": "App 2" },
    // ...
  ]
}

Hotkeys¶

Global hotkeys, that toggle either the first, or the most recently toggled app.

Defaults to None

{
  "Hotkeys": [
    { "Modifiers": "Control", "Key": "Q" }
  ]
}

Feature flags¶

Sometimes functionality is added or changed that carries more risk of introducing bugs.

For these cases, such functionality can be put behind a "feature flag", which makes them opt-in or opt-out.

That way, we can still merge to master, and make it part of the stable release version (reducing branches and dev builds and what not), but still have a way back should things go awry.

Defaults to None

{
    "FeatureFlags": "None",
    // ...
}

Show UI on start¶

Whether to show the GUI when WTQ is started.

Defaults to False

{
    "ShowUiOnStart": "False",
    // ...
}

Animation¶

Animation target FPS¶

How many frames per second the animation should be.

Note that this may not be hit if moving windows takes too long, hence "target" fps.

Must be between 5 and 120, to prevent issues that can arise with values that are too low or too high.

Defaults to 40

{
    "AnimationTargetFps": "40",
    // ...
}

None¶

Api¶

Options related to the HTTP API, that can be used to control WTQ programmatically.

Defaults to None

{
    "Api": "None",
    // ...
}

App options¶

Defines the options for a single toggleable app (eg. Windows Terminal, some other terminal, a file browser, etc.).

App¶

Name¶

A logical name for the app, used to identify it across config reloads.

Appears in logs.

{
  "Name": "Terminal",
  // ...
}

Hotkeys¶

One or more keyboard shortcuts that toggle in- and out this particular app.

Defaults to None

{
    "Apps": [
        {
            "Hotkeys": "None"
            // ...
        }
    ]
}

Process¶

Filename¶

The filename to use when starting a new process for the app.

E.g. notepad, dolphin, etc.

Note that you can also put absolute paths in here.

{
    "Apps": [
        {
            "FileName": "wt"
            // ...
        }
    ]
}

Arguments¶

Command-line arguments that should be passed to the app when it's started.

Note that this only applies when using an AttachMode that starts the app.

Defaults to None

{
    "Apps": [
        {
            "Arguments": "None"
            // ...
        }
    ]
}

Argument list¶

Command-line arguments that should be passed to the app when it's started.

Note that this only applies when using an AttachMode that starts the app.

Defaults to None

{
  "Apps": [
    {
      "ArgumentList": [
        "--allow-screencapture",
        "--debug-info",
      ],
      // ...
    }
  ]
}

Working directory¶

Working directory when starting a new process.

Useful if the filename isn't available through PATH.

Defaults to None

{
    "Apps": [
        {
            "WorkingDirectory": "None"
            // ...
        }
    ]
}

Process name¶

Apps sometimes have process names different from their filenames. This field can be used to look for the process name in such cases. Windows Terminal is an example, with filename wt, and process name WindowsTerminal.

Supports regular expressions.

Defaults to None

{
  // Using with Windows Terminal requires both "Filename" and "ProcessName".
  "Apps": {
    "Filename": "wt",
    "ProcessName": "^WindowsTerminal$"
  }
}

Window class¶

(Windows only) Matches windows based on their Win32 Window Class.

Supports regular expressions.

Defaults to None

{
    "Apps": [
        {
            "WindowClass": "^ApplicationFrameWindow$"
            // ...
        }
    ]
}

Window title¶

Match windows based on their title (sometimes referred to as "caption").

Supports regular expressions.

Defaults to None

{
    "Apps": [
        {
            "WindowTitle": "^Mozilla Firefox - WhatsApp$"
            // ...
        }
    ]
}

Behavior¶

Window title override¶

Attempt to set the window title to a specific value.

Useful for cases where multiple programs control window placement (such as when using WTQ together with a window manager) and the window title can be used to opt-out in the other program.

Defaults to None

{
    "Apps": [
        {
            "WindowTitleOverride": "None"
            // ...
        }
    ]
}

Shared options¶

Options that are available both in global- and per-app options.

Process¶

Attach mode¶

How WTQ should get to an instance of a running app.

I.e. whether to start an app instance if one cannot be found.

Defaults to FindOrStart

Find
Only look for existing app instances (but don't create one).
FindOrStart
Look for an existing app instance, create one if one does not exist yet.
Manual
Attach to whatever app is in the foreground when pressing an assigned hotkey.

{
    // Globally:
    "AttachMode": "FindOrStart",

    // For one app only:
    "Apps": [
        {
            "AttachMode": "FindOrStart"
        }
    ]
}

Behavior¶

Always on top¶

Whether the app should always be on top of other windows, regardless of whether it has focus.

Defaults to False

{
    // Globally:
    "AlwaysOnTop": "False",

    // For one app only:
    "Apps": [
        {
            "AlwaysOnTop": "False"
        }
    ]
}

Hide on focus lost¶

Whether the app should be toggled off when another app gets focus.

Defaults to Always

Always
Toggle off the app when focus is lost.
Never
Do not toggle off the app when focus is lost.

{
    // Globally:
    "HideOnFocusLost": "Always",

    // For one app only:
    "Apps": [
        {
            "HideOnFocusLost": "Always"
        }
    ]
}

Taskbar icon visibility¶

When to show the app window icon on the taskbar.

Defaults to AlwaysHidden

AlwaysHidden
Never show the taskbar icon.
AlwaysVisible
Always show the taskbar icon (note that this can look a bit weird when the app is toggled off).
WhenAppVisible
Only show the taskbar icon when the app is toggled on.

{
    // Globally:
    "TaskbarIconVisibility": "AlwaysHidden",

    // For one app only:
    "Apps": [
        {
            "TaskbarIconVisibility": "AlwaysHidden"
        }
    ]
}

Opacity¶

Make the window see-through (applies to the entire window, including the title bar).

0 (invisible) - 100 (opaque).

Defaults to 100

{
    // Globally:
    "Opacity": "80",

    // For one app only:
    "Apps": [
        {
            "Opacity": "80"
        }
    ]
}

Position¶

Horizontal screen coverage¶

Horizontal screen coverage, as a percentage.

Defaults to 95

{
    // Globally:
    "HorizontalScreenCoverage": "95",

    // For one app only:
    "Apps": [
        {
            "HorizontalScreenCoverage": "95"
        }
    ]
}

Horizontal align¶

Where to position an app on the chosen monitor, horizontally.

Defaults to Center

Center
Center of the screen.
Left
Left of the screen.
Right
Right of the screen.

{
    // Globally:
    "HorizontalAlign": "Center",

    // For one app only:
    "Apps": [
        {
            "HorizontalAlign": "Center"
        }
    ]
}

Vertical screen coverage¶

Vertical screen coverage as a percentage (0-100).

Defaults to 95

{
    // Globally:
    "VerticalScreenCoverage": "95",

    // For one app only:
    "Apps": [
        {
            "VerticalScreenCoverage": "95"
        }
    ]
}

Vertical offset¶

How much room to leave between the top of the app window and the top of the screen, in pixels.

Defaults to 0

{
    // Globally:
    "VerticalOffset": "0",

    // For one app only:
    "Apps": [
        {
            "VerticalOffset": "0"
        }
    ]
}

Off-screen locations¶

When moving an app off the screen, WTQ looks for an empty space to move the window to.

Depending on your monitor setup, this may be above the screen, but switches to below if another monitor exists there.

By default, WTQ looks for empty space in this order: Above, Below, Left, Right.

Defaults to None

{
    // Globally:
    "OffScreenLocations": ["Above", "Below", "Left", "Right"],

    // For one app only:
    "Apps": [
        {
            "OffScreenLocations": ["Above", "Below", "Left", "Right"],
        }
    ]
}

Monitor¶

Prefer monitor¶

Which monitor to preferably drop the app.

Defaults to WithCursor

WithCursor
The monitor where the mouse cursor is currently at.
AtIndex
The monitor at the index as specified by MonitorIndex (0-based).
Primary
The monitor considered primary by the OS.

{
    // Globally:
    "PreferMonitor": "WithCursor",

    // For one app only:
    "Apps": [
        {
            "PreferMonitor": "WithCursor"
        }
    ]
}

Monitor index¶

If PreferMonitor is set to AtIndex, this setting determines what monitor to choose.

Zero based, e.g. 0, 1, etc.

Defaults to 0

{
    // Globally:
    "MonitorIndex": "0",

    // For one app only:
    "Apps": [
        {
            "MonitorIndex": "0"
        }
    ]
}

Animation¶

Animation duration¶

How long the animation should take, in milliseconds.

Defaults to 250

{
    // Globally:
    "AnimationDurationMs": "250",

    // For one app only:
    "Apps": [
        {
            "AnimationDurationMs": "250"
        }
    ]
}

Animation type (toggle ON)¶

The animation type to use when toggling on an application.

Defaults to EaseOutQuart

Linear
EaseInOutSine
EaseInBack
EaseInCubic
EaseInQuart
EaseOutBack
EaseOutCubic
EaseOutQuart

{
    // Globally:
    "AnimationTypeToggleOn": "EaseOutQuart",

    // For one app only:
    "Apps": [
        {
            "AnimationTypeToggleOn": "EaseOutQuart"
        }
    ]
}

Animation type (toggle OFF)¶

The animation type to use when toggling off an application.

Defaults to EaseInQuart

Linear
EaseInOutSine
EaseInBack
EaseInCubic
EaseInQuart
EaseOutBack
EaseOutCubic
EaseOutQuart

{
    // Globally:
    "AnimationTypeToggleOff": "EaseInQuart",

    // For one app only:
    "Apps": [
        {
            "AnimationTypeToggleOff": "EaseInQuart"
        }
    ]
}

Events¶

Event hooks¶

Execute a program when some event occurs.

Defaults to None

{
    // Globally:
    "EventHooks": "None",

    // For one app only:
    "Apps": [
        {
            "EventHooks": "None"
        }
    ]
}

Building From Source¶

TODO

Architecture¶

TODO

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];