Shell Quickshell
La interfaz Quickshell de equisdots: motores de barra, paneles, editor de ajustes, widgets de escritorio e IPC.
El shell de equisdots/shell es una aplicación Quickshell que proporciona la barra, los emergentes, los paneles, el editor de ajustes, los widgets de escritorio y la pantalla de bloqueo. Está escrito en QML con una pequeña capa JavaScript para la lógica pura.
Es neutral al compositor: core/Compositor.qml selecciona un backend en
tiempo de ejecución (Hyprland por defecto, niri cuando
XDG_CURRENT_DESKTOP contiene niri o hay un NIRI_SOCKET definido). Los
widgets nunca ramifican por compositor; consumen la misma superficie del
adaptador. Bajo niri el shell compartido se completa con el overlay
niri-shell (ver Arquitectura).
También está guiado por plugins: hosts genéricos montan los plugins activos, sus paneles, módulos de barra y barras completas sin conocer ids de plugins. Nyx, timex, screenshots y el editor de atajos son las primeras superficies; ver Plugins y extensiones.
Shell.qml es la entrada principal: monta la ventana maestra, la barra, la
capa flotante y los widgets de escritorio. Lock.qml es la entrada alternativa
para el bloqueo de sesión PAM (WlSessionLock), lanzada por lock.sh; ambas
importan los mismos servicios de core/.
Arquitectura
Shell.qml
core/ services and contracts (no visuals)
Config.qml settings.json: rawSettings + setSetting/updateJsonBulk
WindowRegistry.js widget layout + position math
Personalization.js option tables; EditorNav.js panel pages
Theme, Cava, SysData, WidgetSync, compositors/, scripts/watchers/
ui/
Main.qml master window, widget stack, morph, IPC handler
PluginHosts.qml punto de montaje genérico de hosts y barras de plugin
bar/ host, motor de zonas, módulos, popups
plugins/ páginas de ajustes dinámicas de plugins (p_<id>)
panels/ clipboard, wallpaper, file search, system and tools
widgets/ floating desktop widgets and their redactor
La cadena de llamadas de los widgets es siempre la misma:
keybind -> qs_manager.sh -> qs ipc call main handleCommand "toggle <widget>" -> ui/Main.qml -> WindowRegistry.getLayout() -> StackView.replace.
settings.json es la única fuente de verdad. Los paneles escriben mediante
Config.setSetting(key, value) y vigilan el archivo para que las ediciones
externas (xturing, ediciones manuales del JSON) se apliquen en vivo.
La barra
El host de la barra (ui/bar/Bar.qml) ejecuta un único motor de zonas en
cualquier borde de pantalla (top, bottom, left, right). Las islas se
agrupan en zonas basadas en datos (start, center, end) con arrastrar y
soltar de módulos, fondos por zona y modo unificado. settings.json -> bar.enabled es el interruptor maestro: apagado desmapea todas las ventanas de
barra y libera el borde reservado, en vivo. Las barras completas también pueden
venir de plugins (provides.bar.provider) y convivir con sus propios
interruptores.
La barra del núcleo comparte la paleta y 18 módulos: help, search, settings,
update, recording, time, date, media, workspaces, tray, keyboard, wifi,
bluetooth, sysmon, volume, battery, weather y focus. weather y focus se
distribuyen desactivados para que las actualizaciones nunca cambien un diseño
por sí solas. Los módulos pueden venir de plugins
(provides.bar.modules.<id>): el indicador de grabación, el clima y sysmon son
los primeros casos, y el hueco del núcleo conserva el diseño y la configuración
del usuario.
Personalizar la barra y sus módulos
Cada módulo de ui/bar/modules/ es una isla construida sobre el componente
compartido ModulePill: el módulo declara qué muestra y la píldora se encarga
del fondo, el borde, la escala al pasar, la animación de entrada y los clics.
La zona inyecta siempre las mismas siete propiedades — bar, colors,
zoneReady, slotIndex, effectiveBorderWidth, effectiveBorderColor y
unified — y ModulePill añade los ayudantes de orientación y la configuración
normalizada del módulo.
Los valores por módulo viven bajo bar.modules.<id> y todos los campos son
opcionales:
| Campo | Significado |
|---|---|
icon |
Glifo de reemplazo (help, search, settings, update, keyboard, wifi, bluetooth, volume, battery, weather, focus, recording). |
color |
Color del contenido: un rol colors.* o una cadena #hex. |
fill |
Relleno de la isla: default / on / off. |
accent |
Rol de acento de reemplazo (por ejemplo green), convirtiendo la isla en isla de acento. |
size |
Tamaño de fuente en píxeles (0 mantiene el predeterminado). |
effect / cursor |
Efecto de vista por módulo (typewriter en el reloj) y su cursor parpadeante. |
El módulo workspaces tiene sus propias opciones globales de barra:
workspacesMarker (number, dot, letter, custom) y
workspacesMarkerText. Los valores integrados dan a battery, settings,
search, time y help su relleno de paleta, y cada módulo tiene un rol de
acento integrado que sigue la paleta activa.
Opciones clave bajo bar en settings.json:
{
"bar": {
"enabled": true,
"position": "top",
"palette": "x",
"thickness": 48,
"edgeGap": 8,
"pillBg": true,
"barBg": false,
"dragModules": true,
"zones": [
{ "id": "start", "align": "start",
"modules": [ { "id": "help", "enabled": true } ] }
]
}
}
El editor de barra (grupos Tema y Barra) expone las mismas claves de forma
visual; consulte las páginas indicadas abajo. Los colores siempre provienen de
la paleta activa mediante ui/bar/Colors.qml.
Widgets y paneles
Todos los emergentes se despachan mediante qs_manager.sh. Atajos principales:
| Atajo | Widget |
|---|---|
SUPER + D |
Lanzador de aplicaciones |
SUPER + C / V / B / N |
Portapapeles / volumen / batería / red |
SUPER + S / Z |
Calendario (timex) / escala de pantalla |
SUPER + M / SUPER + P |
Música / inactividad |
SUPER + W |
Selector de fondos (davinci) |
SUPER + I / SUPER + U |
Monitor del sistema / actualizador |
SUPER + Y / SUPER + O |
Notas rápidas / lector RSS |
SUPER + ' |
Búsqueda de archivos |
SUPER + SHIFT + S / D |
Panel de ajustes (editor de barra) |
SUPER + SHIFT + M |
Panel de plugins |
SUPER + SHIFT + W |
Editor de widgets de escritorio |
SUPER + SHIFT + P |
Widget de paleta |
El panel de ajustes se basa en datos de core/EditorNav.js con los grupos
Shell, Barra, Tema, Comportamiento, Widgets, Sistema y Plugins. El estado de
plegado y el orden de las páginas persisten en settings.editor. El grupo
Plugins lista los plugins instalados, sus interruptores maestros y una página de
configuración por plugin que declare settings.page. El sistema de
notificaciones tiene sus propias opciones (settings.notifications), y las
sombras, el cristal y las mascotas se configuran desde el grupo Tema.
Ventanas, sombras y cristal
Shell.qml monta ui/Main.qml (ventana maestra, pila de widgets, morph, IPC),
ui/bar/Bar.qml (el host de la barra), ui/Floating.qml (notificaciones y
superficies tipo OSD), ui/PluginHosts.qml (hosts genéricos de plugins,
incluida la isla Nyx; véase Isla de mascotas Nyx),
ui/widgets/Widgets.qml (un cargador de widgets por pantalla) y el overlay del
plugin de capturas; Lock.qml es la entrada alternativa de bloqueo de sesión
PAM.
Hyprland no decora las superficies layer-shell, así que las sombras de los
emergentes las dibuja QML en Main.qml y siguen la caja animada (posición,
tamaño, morph y fundido). Se configuran en settings.json -> shadows
(enabled, blur, spread, offsetX, offsetY, opacity, radius;
escaladas por la escala de UI) desde Tema -> Sombras; settings.json -> glass
(enabled, opacity) vuelve translúcidos los fondos del shell para que se vea
el blur del compositor. La barra dibuja sus propias sombras con la misma
configuración.
Widgets de escritorio
Pulse SUPER + SHIFT + W para abrir el editor en el monitor actual. Las
ventanas reales de los widgets se ocultan durante la edición, y cada cambio se
guarda automáticamente unos 300 ms después de la última edición.
Cinco tipos con variantes: Reloj (digital, analógico, minimalista), Música, Tiempo (lee la caché de timex), Visualizador (instancia compartida de cava) e Imagen (desde la carpeta de fondos de pantalla). Los diseños se almacenan por monitor:
~/.local/state/quickshell/widgets/<monitor>/layout.json
Cada entrada del diseño guarda la variante, la posición, el tamaño, la rotación, la opacidad y, para los widgets de Imagen, el archivo elegido; el selector navega la carpeta de fondos. Los widgets se dibujan por encima del fondo de pantalla y por debajo de las ventanas, en todos los monitores, con ajuste a cuadrícula y bordes, rotación, opacidad y tiradores de redimensionado. Los cambios de paleta los recolorean al instante.
IPC
~/.config/hypr/scripts/qs_manager.sh toggle volume
~/.config/hypr/scripts/qs_manager.sh close
~/.config/hypr/scripts/qs_manager.sh 3 # switch to workspace 3
~/.config/hypr/scripts/qs_manager.sh 3 move # move the window there
~/.config/hypr/scripts/qs_manager.sh prev
~/.config/hypr/scripts/qs_manager.sh next
qs ipc call main handleCommand "toggle calendar"
qs ipc call main forceReload
Los nombres de los widgets son las claves de WindowRegistry.js (bar-editor,
calendar, volume, etc.).
Desarrollo
No hay CI; cada repositorio incluye una comprobación local:
scripts/check.sh # qmllint over every .qml + node --check over JS modules
Recargue mientras desarrolla con qs ipc call main forceReload, o ejecute una
copia de la configuración (quickshell -p /tmp/qstest/Shell.qml) para ver los
errores de QML en primer plano. Process de QML llama a los scripts
directamente, por lo que los scripts copiados deben seguir siendo ejecutables,
y los glifos deben existir en la Hack Nerd Font.
Páginas relacionadas
- Temas y paletas para
Colors.qmly las paletas. - Fondos de pantalla para el selector y davinci.
- Arquitectura y repositorios para el diseño de la instalación.