Skip to content

application-contract.md

Latest commit

 

History

History
174 lines (118 loc) · 3.63 KB

application-contract.md

File metadata and controls

174 lines (118 loc) · 3.63 KB
Raw

APPLaunch Application Contract

ZeroShell discovers apps through APPLaunch-compatible desktop entries.

Directory

Production scan directory:

/usr/share/APPLaunch/applications

ZeroShell scans:

/usr/share/APPLaunch/applications/*.desktop

It does not scan /usr/share/applications.

Data Paths

The APPLaunch data root is:

/usr/share/APPLaunch

Common icon path:

/usr/share/APPLaunch/share/images

Relative icon paths such as share/images/app.png resolve under the data root.

Desktop Entry Subset

Example:

[Desktop Entry]
Name=LoFiBox
TryExec=lofibox
Exec=lofibox
Icon=share/images/lofibox.png
Categories=Audio;Player;
X-Zero-Display=xwayland
StartupWMClass=lofibox

Supported fields:

Field Required Meaning
Name yes Display name.
Exec yes Command to launch.
Icon no APPLaunch-compatible icon path.
Categories no Desktop-entry categories used by the launcher category drawer.
TryExec no Hide entry when the command is unavailable.
X-Zero-ShortName no Short label for the 320x170 UI.
StartupWMClass no Xwayland/X11 matching hint.
X-Zero-AppId no Wayland app id matching hint.
X-Zero-Display yes Runtime display contract: wayland or xwayland.

Unknown fields are ignored.

Categories

Categories= is the only source used by ZeroShell's launcher category drawer. It follows the desktop-entry semicolon-list form:

Categories=Settings;System;

ZeroShell does not infer categories from app names, icons, commands, running tasks, or packages. All is added by the shell and means no filter. Apps with no usable Categories= value appear under Other.

Display Contract

X-Zero-Display is required. Valid values:

X-Zero-Display=wayland
X-Zero-Display=xwayland

The app must create a compositor-visible window. That is what allows labwc to minimize, close, focus, stack, and expose it as a task.

Name And Short Name

Name is the normal label:

Name=App Store

X-Zero-ShortName is optional and lets the package choose a compact launcher label:

X-Zero-ShortName=STORE

ZeroShell must not hard-code app-specific aliases. Packages own their displayed names through their desktop entries.

Exec

Exec is run through /bin/sh -lc as the current authenticated user:

Exec=lofibox

Launch is non-blocking. ZeroShell returns to its event loop while the app creates its window.

TryExec

If TryExec is present, ZeroShell hides the app when the command is not available:

TryExec=lofibox

If TryExec is missing, ZeroShell checks the first token of Exec.

Window Matching

ZeroShell matches running task state to an app by:

  • X-Zero-AppId,
  • StartupWMClass,
  • desktop-entry id,
  • display name/title matching when needed.

Wayland-native apps should set a stable app id. Xwayland apps should set a stable StartupWMClass when possible.

Duplicate Handling

If multiple entries have the same Exec, the first loaded entry wins. Entries are loaded in sorted path order.

Installing An App

Install a desktop entry:

sudo install -m 0644 my-tool.desktop /usr/share/APPLaunch/applications/my-tool.desktop

Install its icon:

sudo install -m 0644 my-tool.png /usr/share/APPLaunch/share/images/my-tool.png

Then press R in ZeroShell, or wait for directory metadata polling to reload the app list.

Fixed Tools

Settings, Files, Terminal, App Store, System Monitor, HDMI tools, and other utilities are app packages. They appear through desktop entries. They are not built into ZeroShell.