ZacharyZhang-NY
fcd681c099
Qt 6.12 shadows the bare Color singleton, so the bar and every Color role read undefined on fresh installs. Keep our I18n text in the four conflicting files, qualify #14433's notification button color, give the new dictation menu rows and notifications Chinese, and drop table entries for the removed Voxtype and FIDO2 texts.
56 lines
4.2 KiB
Markdown
56 lines
4.2 KiB
Markdown
# Omarchy Shell Development
|
|
|
|
Read this before editing the Quickshell desktop under `shell/`.
|
|
|
|
The Quickshell desktop runs as a single long-running process out of
|
|
`shell/`. Hyprland autostart launches it directly with `quickshell -n -p`;
|
|
do not start additional standalone Quickshell instances for individual
|
|
components.
|
|
|
|
Run `omarchy-restart-shell` after making changes to QML files.
|
|
|
|
## Plugin contract
|
|
|
|
- First-party plugins live directly under `shell/plugins/` or one category
|
|
level deeper, such as `shell/plugins/panels/weather/`. First-party bar-only
|
|
widgets may use adjacent `*.manifest.json` files. Third-party plugins live
|
|
at `~/.config/omarchy/plugins/<id>/` with a `manifest.json` at the root.
|
|
- Every plugin manifest declares `schemaVersion`, `id`, `name`, `version`,
|
|
`kinds`, and `entryPoints`. See
|
|
[`docs/omarchy-shell.md`](../../docs/omarchy-shell.md) and
|
|
`shell/services/PluginRegistry.qml` for the current contract; fields such as
|
|
`activation` are optional.
|
|
- Entry-point QML files are `Item`s (not `ShellRoot`), and accept the shell-injected properties `omarchyPath`, `shell`, `manifest`, and `pluginRegistry` / `barWidgetRegistry` as appropriate. First-party plugins receive the host objects. Third-party plugins receive capability-scoped facades: ordinary plugins may look up and control only their own service and lifecycle, built-in clones retain narrow source-specific configuration and UI compatibility, menu plugins receive an application-library facade, and plugins can read detached scalar bar state; full-bar plugins additionally receive detached bar configuration and widget-catalog snapshots, narrow proxies for the non-authentication services used by built-in bar widgets, and lifecycle control over configured non-authentication UI plugins. Authentication capabilities must be stamped from trusted first-party manifests, and third-party registry views and bar configuration must be detached snapshots rather than shared objects. These facades reduce accidental authority but are not a same-process QML sandbox: a visual bar widget can walk its parent hierarchy to ordinary host objects. Authentication services must therefore remain outside both `ShellRoot._services` and the host QObject tree. Do not expose authentication services through new third-party-facing properties.
|
|
- Panel / overlay / menu plugins must expose `open(payloadJson)` and
|
|
`close()` lifecycle methods for `shell summon` and `shell hide`.
|
|
|
|
## Text
|
|
|
|
Wrap every user-visible string in `I18n.tr()` (`import qs.Commons`) and add its Chinese to `shell/Commons/I18nZh.js`; plain JS models that Node tests load stay English, and their text is wrapped where QML shows it.
|
|
|
|
## IPC
|
|
|
|
- `bin/omarchy-shell` is the canonical IPC entry point. It forwards to
|
|
the running shell and does not start it. Prefer it over re-implementing
|
|
direct Quickshell socket calls in every CLI.
|
|
- The `shell` IPC target exposes lifecycle and configuration methods including
|
|
`ping`, `summon`, `hide`, `toggle`, `call`, `rescanPlugins`, `reloadConfig`,
|
|
`setPluginEnabled`, and `listPlugins`. `shell.qml` also registers
|
|
`image-selector`, which drives the `omarchy.image-picker` panel.
|
|
- Individual plugins register their own IPC targets, named for the plugin rather
|
|
than for where they appear: the background switcher registers `background`, and
|
|
bar widgets register one target each — `omarchy.indicators`,
|
|
`omarchy.system-update`, `omarchy.clock`. There is no `bar` target.
|
|
|
|
## Editing widget files with glyphs
|
|
|
|
Widget files in `shell/plugins/bar/widgets/` contain Nerd Font glyphs as raw
|
|
unicode characters. Agent file-editing tools can strip multi-byte codepoints
|
|
in some positions — do **not** rewrite widget files wholesale through those
|
|
tools. For glyph fixes, make a targeted edit with the surrounding context, or
|
|
use a Python script that inserts codepoints via `chr(0xXXXXX)`.
|
|
|
|
## Palette references
|
|
|
|
Import `qs.Commons as Commons` and use `Commons.Color` for the palette singleton, including `Connections.target`. Qt 6.12 introduces a `Color` type in `QtQuick` that shadows unqualified palette references. This applies to first-party components and third-party plugin QML alike. Keep the unqualified `qs.Commons` import when the file also uses `Style`, `Util`, or `Border`.
|