docs: add book
This commit is contained in:
Claude
Julian Orth
parent
c9d6fb9e40
commit
d14105eb1a
43 changed files with 7254 additions and 1204 deletions
608
book/src/control-center.md
Normal file
608
book/src/control-center.md
Normal file
|
|
@ -0,0 +1,608 @@
|
|||
# Control Center
|
||||
|
||||
The control center is Jay's built-in graphical interface for inspecting and
|
||||
modifying compositor settings. It provides a convenient alternative to editing
|
||||
configuration files or running CLI commands -- most settings that can be changed
|
||||
in `config.toml` or via the CLI can also be changed here.
|
||||
|
||||
> [!NOTE]
|
||||
> Changes made in the control center are not persisted across compositor
|
||||
> restarts. To make settings permanent, add them to your `config.toml`.
|
||||
|
||||
> [!TIP]
|
||||
> The control center consumes GPU and CPU resources while open. Close it when
|
||||
> not in use to avoid reducing compositor performance.
|
||||
|
||||
## Opening the Control Center
|
||||
|
||||
- Press `alt-c` (the default shortcut for the `open-control-center` action).
|
||||
- Run the CLI command:
|
||||
|
||||
```shell
|
||||
~$ jay control-center
|
||||
```
|
||||
|
||||
## Interface Overview
|
||||
|
||||
The control center window has a sidebar on the left listing all available panes
|
||||
and a central panel area on the right.
|
||||
|
||||
- **Click** a pane name in the sidebar to open it.
|
||||
- **Multiple panes** can be open at the same time -- they appear as tabs in the
|
||||
panel area.
|
||||
- **Drag** pane tabs to rearrange them or to split the panel area into
|
||||
side-by-side or stacked layouts.
|
||||
- **Close** a pane by clicking its X button or middle-clicking its tab.
|
||||
|
||||
## Panes
|
||||
|
||||
### Compositor
|
||||
|
||||
General information and top-level controls for the running compositor.
|
||||
|
||||
Repository
|
||||
: Link to the Jay GitHub repository
|
||||
|
||||
Version
|
||||
: The running Jay version
|
||||
|
||||
PID
|
||||
: The compositor process ID
|
||||
|
||||
WAYLAND_DISPLAY
|
||||
: The Wayland socket name (shown when available)
|
||||
|
||||
Config DIR
|
||||
: Path to the active configuration directory (shown when available)
|
||||
|
||||
Libei Socket
|
||||
: Toggle the libei input emulation socket
|
||||
|
||||
LIBEI_SOCKET
|
||||
: The socket name (shown when the Libei Socket toggle is enabled)
|
||||
|
||||
Workspace Display Order
|
||||
: Dropdown to select how workspaces are ordered in the bar
|
||||
|
||||
Log Level
|
||||
: Dropdown to change the active log level at runtime (shown when the logger is available)
|
||||
|
||||
Log File
|
||||
: Click to copy the log file path to the clipboard (shown when the logger is available)
|
||||
|
||||
Buttons at the bottom:
|
||||
|
||||
- **Quit** -- stop the compositor.
|
||||
- **Reload Config** -- reload the configuration file.
|
||||
- **Switch to VT** -- switch to another virtual terminal (with a numeric input
|
||||
to select which one).
|
||||
|
||||
### Outputs
|
||||
|
||||
The Outputs pane is the largest and most interactive pane. It has two sub-views:
|
||||
a visual **arrangement editor** and per-connector **settings**.
|
||||
|
||||
#### Arrangement editor
|
||||
|
||||
A 2D preview of your monitor layout. Monitors are drawn as labeled rectangles
|
||||
at their configured positions and sizes.
|
||||
|
||||
- **Click** a monitor to select it (highlighted with a shadow).
|
||||
- **Drag** a selected monitor to reposition it.
|
||||
- **Scroll** to zoom in and out.
|
||||
- **Middle-click drag** or **right-click drag** to pan the viewport.
|
||||
- **Arrow keys** nudge the selected monitor by 1 pixel.
|
||||
- **Snap to neighbor** -- when enabled, dragged monitors snap to the edges of
|
||||
neighboring monitors within a 10-pixel threshold. Hold **Shift** to
|
||||
temporarily invert the snapping behavior.
|
||||
- **Guide lines** -- optional horizontal and vertical lines at the edges of all
|
||||
monitors, helping you align them precisely.
|
||||
|
||||
A **Zoom To Fit** checkbox in the top bar auto-scales the view to fit all
|
||||
monitors. It is disabled when you manually pan or zoom.
|
||||
|
||||
Arrangement settings (accessible via the Settings button):
|
||||
|
||||
Show guide lines
|
||||
: Draw alignment guide lines
|
||||
|
||||
Snap to neighbor
|
||||
: Snap edges when dragging (hold Shift to invert)
|
||||
|
||||
Show arrangement area
|
||||
: Toggle the visual arrangement sub-pane
|
||||
|
||||
Layout
|
||||
: How the arrangement and settings are split: Auto, Vertical, or Horizontal
|
||||
|
||||
Show disconnected heads
|
||||
: Include outputs that are no longer connected
|
||||
|
||||
Show disabled heads
|
||||
: Include outputs that are disabled
|
||||
|
||||
#### Staged changes
|
||||
|
||||
Changes made in the Outputs pane are **staged** -- they are not applied
|
||||
immediately. Three buttons in the top bar control the workflow:
|
||||
|
||||
- **Test** -- validates the staged changes against the display backend without
|
||||
applying them. Errors are shown in the pane.
|
||||
- **Commit** -- applies all staged changes. The pane title shows `Outputs (*)`
|
||||
when there are uncommitted changes.
|
||||
- **Reset** -- discards all staged changes and reverts to the live state.
|
||||
This is displayed as a checkbox; checking it resets the staged changes.
|
||||
|
||||
When a staged value differs from the live value, the current (live) value is
|
||||
shown alongside with a `^ current` annotation.
|
||||
|
||||
#### Per-connector settings
|
||||
|
||||
Each connected display appears as a collapsible section with the connector name,
|
||||
manufacturer, and model. Inside:
|
||||
|
||||
Serial Number
|
||||
: Read-only identifier
|
||||
|
||||
Enabled
|
||||
: Toggle the connector on or off
|
||||
|
||||
Position
|
||||
: X and Y coordinates in compositor space
|
||||
|
||||
Scale
|
||||
: Fractional scaling factor, with +/- buttons for fine adjustment
|
||||
|
||||
Mode
|
||||
: Resolution and refresh rate (dropdown when multiple modes are available)
|
||||
|
||||
Physical Size (mm)
|
||||
: Read-only physical dimensions in millimeters
|
||||
|
||||
Size
|
||||
: Read-only computed pixel dimensions of the output
|
||||
|
||||
Transform
|
||||
: Rotation and mirroring (none, rotate-90, rotate-180, rotate-270, flip, and flipped rotations)
|
||||
|
||||
Custom Brightness
|
||||
: Toggle whether to use a custom SDR content brightness
|
||||
|
||||
Brightness
|
||||
: Brightness value in cd/m^2 (shown when Custom Brightness is enabled)
|
||||
|
||||
Colorimetry
|
||||
: Color space (depends on monitor capabilities)
|
||||
|
||||
EOTF
|
||||
: Transfer function (depends on monitor capabilities)
|
||||
|
||||
Format
|
||||
: Framebuffer pixel format
|
||||
|
||||
Tearing
|
||||
: Tearing mode. When set to a "Fullscreen" mode, a **Limit Windows** checkbox appears; inside that, a **Requests Tearing** checkbox filters by whether the window has requested tearing.
|
||||
|
||||
VRR Active
|
||||
: Read-only indicator of whether VRR is currently active (only shown when the monitor supports VRR)
|
||||
|
||||
VRR
|
||||
: Variable refresh rate mode (only shown when the monitor supports VRR). When set to a "Fullscreen" mode, a **Limit Windows** checkbox appears; inside that, a **Limit Content Types** checkbox enables filtering by content type (**Photos**, **Videos**, **Games** checkboxes).
|
||||
|
||||
Non-desktop
|
||||
: Read-only indicator (Yes/No) of whether the connector is inherently non-desktop
|
||||
|
||||
Override
|
||||
: Force the connector to be treated as desktop or non-desktop
|
||||
|
||||
Blend Space
|
||||
: How colors are blended during compositing (sRGB or linear)
|
||||
|
||||
Use Native Gamut
|
||||
: Use the display's advertised color primaries instead of assuming sRGB
|
||||
|
||||
Native Gamut
|
||||
: Read-only CIE xy primaries for red, green, blue, and white point
|
||||
|
||||
Limit Cursor HZ
|
||||
: Toggle to limit cursor-triggered refresh rate when VRR is active
|
||||
|
||||
Cursor HZ
|
||||
: Cursor refresh rate value (shown when Limit Cursor HZ is enabled)
|
||||
|
||||
Flip Margin (ms)
|
||||
: Read-only page-flip margin for this connector
|
||||
|
||||
### Virtual Outputs
|
||||
|
||||
Manage headless virtual outputs. These are useful for screen sharing, testing,
|
||||
or running applications on a display without a physical monitor.
|
||||
|
||||
- View the list of existing virtual outputs.
|
||||
- **Add** a new virtual output by entering a name and clicking Add.
|
||||
- **Remove** an existing virtual output by clicking its X button.
|
||||
|
||||
### GPUs
|
||||
|
||||
Inspect and configure graphics cards (DRM devices). Each GPU appears as a
|
||||
collapsible section showing its device path and model name.
|
||||
|
||||
Vendor
|
||||
: Read-only GPU vendor name
|
||||
|
||||
Model
|
||||
: Read-only GPU model name
|
||||
|
||||
Devnode
|
||||
: Read-only device path
|
||||
|
||||
Syspath
|
||||
: Read-only sysfs path
|
||||
|
||||
PCI ID
|
||||
: Read-only vendor:model in hex
|
||||
|
||||
Dev
|
||||
: Read-only major:minor device numbers
|
||||
|
||||
API
|
||||
: Dropdown to select the graphics API -- Vulkan (recommended) or the legacy OpenGL renderer
|
||||
|
||||
Primary Device
|
||||
: Checkbox to make this GPU the render device
|
||||
|
||||
Direct Scanout
|
||||
: Toggle direct scanout (bypasses composition for lower latency)
|
||||
|
||||
Flip Margin
|
||||
: Adjust the page-flip margin in milliseconds, with +/- buttons for 0.1 ms steps
|
||||
|
||||
Connectors
|
||||
: List of display connectors attached to this GPU
|
||||
|
||||
### Input
|
||||
|
||||
The Input pane is divided into per-seat and per-device sections.
|
||||
|
||||
#### Per-seat settings
|
||||
|
||||
Each seat (typically just `default`) appears as a collapsible section:
|
||||
|
||||
Repeat Rate
|
||||
: Key repeat speed, with +/- 20 buttons
|
||||
|
||||
Repeat Delay
|
||||
: Initial delay before key repeat begins, with +/- 20 buttons
|
||||
|
||||
Cursor Size
|
||||
: Size of the seat cursor in pixels
|
||||
|
||||
Simple IM
|
||||
: Toggle the built-in XCompose-based input method
|
||||
|
||||
Hardware Cursor
|
||||
: Toggle hardware cursor rendering
|
||||
|
||||
Pointer Revert Key
|
||||
: Text field for the keysym name of the cancel key
|
||||
|
||||
Focus Follows Mouse
|
||||
: Toggle whether moving the pointer over a window gives it focus
|
||||
|
||||
Fallback Output Mode
|
||||
: Dropdown to choose between cursor-based and focus-based output selection
|
||||
|
||||
Below the settings grid:
|
||||
|
||||
- **Focus History** -- checkboxes for "Only Visible" and "Same Workspace".
|
||||
- **Reload Simple IM** -- button to reload XCompose files without restarting.
|
||||
|
||||
##### Keymap management
|
||||
|
||||
Each seat has a full keymap management section:
|
||||
|
||||
- **Copy Keymap** -- copies the current keymap text to the clipboard.
|
||||
- **Load Default Keymap** -- restores the compositor's default keymap.
|
||||
- **Backup / Restore Keymap** -- save and restore a keymap backup.
|
||||
- **Load Keymap from Clipboard** -- paste a keymap from the clipboard.
|
||||
- **Create Keymap from Names** -- build a keymap from RMLVO (Rules, Model,
|
||||
Layout, Variant, Options) fields. Rules and Model have a text input and a
|
||||
"Default" checkbox; Layouts, Variants, and Options have text inputs only.
|
||||
Click **Load** to apply.
|
||||
|
||||
#### Per-device settings
|
||||
|
||||
Each input device appears as a collapsible section. The available settings
|
||||
depend on the device's capabilities:
|
||||
|
||||
Seat
|
||||
: Dropdown to assign the device to a seat, with a Detach button. Shown for all devices.
|
||||
|
||||
Syspath / Devnode
|
||||
: Read-only device paths. Shown for all devices.
|
||||
|
||||
Capabilities
|
||||
: Read-only list (e.g. Keyboard, Pointer, Touch). Shown for all devices.
|
||||
|
||||
Natural Scrolling
|
||||
: Toggle scroll direction. Shown for devices that support it.
|
||||
|
||||
Scroll Distance (px)
|
||||
: Pixels per legacy scroll event. Shown for pointer devices.
|
||||
|
||||
Accel Profile
|
||||
: Dropdown: Flat or Adaptive. Shown for devices with acceleration.
|
||||
|
||||
Accel Speed
|
||||
: Numeric input (0.0 to 1.0). Shown for devices with acceleration.
|
||||
|
||||
Click Method
|
||||
: Dropdown: none, button-areas, clickfinger. Shown for devices that support it.
|
||||
|
||||
Tap Enabled
|
||||
: Toggle tap-to-click. Shown for touchpads.
|
||||
|
||||
Tap Drag Enabled
|
||||
: Toggle tap-and-drag. Shown for touchpads.
|
||||
|
||||
Tap Drag Lock Enabled
|
||||
: Toggle tap-drag lock. Shown for touchpads.
|
||||
|
||||
Left Handed
|
||||
: Swap primary and secondary buttons. Shown for devices that support it.
|
||||
|
||||
Middle Button Emulation
|
||||
: Simultaneous left+right produces middle click. Shown for devices that support it.
|
||||
|
||||
Output
|
||||
: Dropdown to map the device to a specific output (only has effect for touch and tablet devices), with a Detach button. Shown for all devices.
|
||||
|
||||
Transform Matrix
|
||||
: 2x2 matrix applied to relative motion. Shown for pointer devices.
|
||||
|
||||
Calibration Matrix
|
||||
: 2x3 matrix for absolute input calibration. Shown for devices that support it.
|
||||
|
||||
Device Keymap
|
||||
: Override the seat keymap for this device, with full keymap management UI and a "Use Seat Keymap" button to revert. Shown for keyboards.
|
||||
|
||||
### Idle
|
||||
|
||||
Configure the screensaver and idle behavior:
|
||||
|
||||
Interval
|
||||
: Minutes and seconds of inactivity before the on-idle action fires
|
||||
|
||||
Grace period
|
||||
: Minutes and seconds of the warning phase (screen goes black but is not yet locked)
|
||||
|
||||
Inhibitors
|
||||
: Collapsible list showing which applications are currently preventing idle (e.g. video players), with a count in the header
|
||||
|
||||
### Look and Feel
|
||||
|
||||
Visual customization with live preview. Changes take effect immediately.
|
||||
|
||||
Show Bar
|
||||
: Toggle the status bar
|
||||
|
||||
Bar Position
|
||||
: Dropdown to select the bar position
|
||||
|
||||
Show Titles
|
||||
: Toggle window title bars
|
||||
|
||||
Primary Selection
|
||||
: Toggle middle-click paste (requires application restart to take effect)
|
||||
|
||||
UI Drag
|
||||
: Toggle whether workspaces and tiles can be dragged
|
||||
|
||||
UI Drag Threshold (px)
|
||||
: Minimum distance in pixels before a drag begins
|
||||
|
||||
Float Pin Icon
|
||||
: Show the pin icon on floating windows even when not pinned
|
||||
|
||||
Float Above Fullscreen
|
||||
: Show floating windows above fullscreen windows
|
||||
|
||||
Font
|
||||
: Text field for the main compositor font family
|
||||
|
||||
Title Font
|
||||
: Override font for window title bars (empty = use main font)
|
||||
|
||||
Bar Font
|
||||
: Override font for the status bar (empty = use main font)
|
||||
|
||||
Three reset buttons at the bottom: **Reset Sizes**, **Reset Colors**, and
|
||||
**Reset Fonts**.
|
||||
|
||||
#### Sizes
|
||||
|
||||
A collapsible section with numeric inputs for every theme size: border widths,
|
||||
title heights, bar height, gaps, and other spacing values.
|
||||
|
||||
#### Colors
|
||||
|
||||
A collapsible section with **color pickers** for every theme color. Click a
|
||||
color swatch to open a full RGBA color picker with sliders and hex input.
|
||||
This includes colors for backgrounds, borders, text, the status bar, focused
|
||||
and unfocused windows, attention indicators, and more.
|
||||
|
||||
### Clients
|
||||
|
||||
Inspect and manage connected Wayland clients.
|
||||
|
||||
A **Filter** toggle at the top enables the composable filter builder (see
|
||||
[Filtering](#filtering) below). When filtering is off, all clients are shown.
|
||||
|
||||
Each client appears as a collapsible section showing its ID and process name.
|
||||
Expand it to see:
|
||||
|
||||
ID
|
||||
: Client identifier
|
||||
|
||||
PID
|
||||
: Process ID
|
||||
|
||||
UID
|
||||
: User ID
|
||||
|
||||
comm
|
||||
: Process name
|
||||
|
||||
exe
|
||||
: Executable path
|
||||
|
||||
Sandboxed
|
||||
: Whether the client is sandboxed (only shown for sandboxed clients)
|
||||
|
||||
Secure
|
||||
: Whether the client uses the privileged socket (only shown for secure clients)
|
||||
|
||||
Xwayland
|
||||
: Shown only for X11 clients
|
||||
|
||||
Sandbox Engine
|
||||
: Sandbox engine name (shown when sandboxed)
|
||||
|
||||
App ID
|
||||
: Sandbox application ID (shown when sandboxed)
|
||||
|
||||
Instance ID
|
||||
: Sandbox instance ID (shown when sandboxed)
|
||||
|
||||
Tag
|
||||
: The connection tag, if any
|
||||
|
||||
Kill
|
||||
: Button to forcefully disconnect the client
|
||||
|
||||
Capabilities
|
||||
: Collapsible list of effective Wayland capabilities
|
||||
|
||||
Windows
|
||||
: Collapsible list of all windows owned by this client
|
||||
|
||||
Click the **open in new pane** icon on any client to open a dedicated pane for
|
||||
that client, allowing you to keep it visible while browsing other panes.
|
||||
|
||||
### Window Search
|
||||
|
||||
Search and filter windows across the compositor using the composable filter
|
||||
builder (see [Filtering](#filtering) below).
|
||||
|
||||
Each matching window appears as a collapsible section showing its title. Expand
|
||||
it to see:
|
||||
|
||||
ID
|
||||
: Window identifier
|
||||
|
||||
Title
|
||||
: Window title
|
||||
|
||||
Workspace
|
||||
: Which workspace the window is on
|
||||
|
||||
Type
|
||||
: Container, xdg_toplevel, X Window, or Placeholder
|
||||
|
||||
Tag
|
||||
: Toplevel tag (set via window rules); only shown for xdg_toplevel windows
|
||||
|
||||
X11 properties
|
||||
: Class, Instance, and Role (only shown for Xwayland windows)
|
||||
|
||||
App ID
|
||||
: Application identifier
|
||||
|
||||
Floating
|
||||
: Whether the window is floating
|
||||
|
||||
Visible
|
||||
: Whether the window is visible
|
||||
|
||||
Urgent
|
||||
: Whether the window has the urgency flag
|
||||
|
||||
Fullscreen
|
||||
: Whether the window is fullscreen
|
||||
|
||||
Content Type
|
||||
: The content type hint (photo, video, game), if set
|
||||
|
||||
Client
|
||||
: Full client details (same as the Clients pane)
|
||||
|
||||
Click the **open in new pane** icon on any window to open a dedicated pane for
|
||||
that window.
|
||||
|
||||
### Xwayland
|
||||
|
||||
Manage the Xwayland compatibility layer for running X11 applications:
|
||||
|
||||
Enabled
|
||||
: Toggle Xwayland on or off
|
||||
|
||||
Scaling Mode
|
||||
: Dropdown: `default` or `downscaled` (renders at highest integer scale then downscales for sharper text on HiDPI)
|
||||
|
||||
DISPLAY
|
||||
: Read-only X11 display number (only shown when Xwayland is running)
|
||||
|
||||
Running
|
||||
: Whether Xwayland is currently running
|
||||
|
||||
PID
|
||||
: Xwayland process ID (only shown when Xwayland is running)
|
||||
|
||||
Kill
|
||||
: Button to forcefully terminate Xwayland (only shown when Xwayland is running)
|
||||
|
||||
Client
|
||||
: Collapsible section with full client details for the Xwayland process (only shown when Xwayland is running)
|
||||
|
||||
### Color Management
|
||||
|
||||
Configure the Wayland color management protocol:
|
||||
|
||||
Enabled
|
||||
: Toggle the color management protocol for clients
|
||||
|
||||
Available
|
||||
: Read-only indicator of whether color management is available with the current renderer and hardware
|
||||
|
||||
## Filtering
|
||||
|
||||
The **Clients** and **Window Search** panes share a composable filter system
|
||||
for narrowing down results. The filter builder works as follows:
|
||||
|
||||
At the top level, select a combinator or a leaf criterion from the dropdown:
|
||||
|
||||
- **Not** -- inverts a single child criterion.
|
||||
- **All** -- all child criteria must match (AND).
|
||||
- **Any** -- at least one child criterion must match (OR).
|
||||
- **Exactly(n)** -- exactly *n* child criteria must match (with a numeric input
|
||||
for *n*).
|
||||
|
||||
Compound criteria contain a list of children. Click **Add** to append a new
|
||||
criterion; click the X button on any child to remove it. Criteria can be nested
|
||||
to arbitrary depth.
|
||||
|
||||
Leaf criteria vary by context:
|
||||
|
||||
**Client criteria:** Comm, Exe, Tag, Sandbox Engine, Sandbox App ID, Sandbox
|
||||
Instance ID (all regex-matched text fields with a "Regex" checkbox), Sandboxed,
|
||||
Is Xwayland (boolean), UID, PID (numeric inputs).
|
||||
|
||||
**Window criteria:** Title, App ID, Tag, Workspace, X Class, X Instance, X Role
|
||||
(all regex-matched text fields), Floating, Visible, Urgent, Fullscreen
|
||||
(boolean), Content Types (checkboxes for Photo, Video, Game), and **Client**
|
||||
(a nested client criterion builder for filtering by the owning client's
|
||||
properties).
|
||||
|
||||
Text-matching criteria have a **Regex** checkbox. When unchecked, the input is
|
||||
matched as a literal string. When checked, it is treated as a regular
|
||||
expression. Invalid regex patterns show an error message.
|
||||
Loading…
Add table
Add a link
Reference in a new issue