Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AhmedSaadi0/NibrasShell/llms.txt

Use this file to discover all available pages before exploring further.

The Desktop is a full-screen PanelWindow that sits behind every other shell layer. It is defined in desktop/ and instantiated once per monitor by shell.qml. Beyond simply rendering a wallpaper, the desktop hosts a customisable clock widget and supports a depth-shadow overlay that creates a sense of three-dimensional space between the wallpaper and your windows.

​
Wallpaper types

NibrasShell supports three wallpaper modes. Wallpaper settings are stored in the active theme’s cache file — you typically set them through the Settings App rather than editing files by hand.
Any common image format (PNG, JPG, WebP) works as a static wallpaper. Set the path in the Settings App → Wallpapers section, or point _wallpaper in your theme file directly at the image path.
// In your theme cache file
_wallpaper: "/home/you/wallpapers/mountain.png"
When the left panel is open, the desktop can apply a configurable blur to the wallpaper so the panel content stays readable against busy backgrounds.

​
Clock widget

The desktop clock widget overlays the wallpaper and supports extensive customisation. All clock settings are stored in the active theme’s cache file and managed through the Settings App → Desktop clock section. The underlying theme properties are:
Theme propertyDescription
_desktopClockEnabledShow or hide the clock widget.
_desktopClockFontFont family (e.g., "JetBrainsMono Nerd Font").
_desktopClockSizeWidth and height of the clock area as a Qt size.
_desktopClockPositionPosition on screen as a Qt point (x, y).
_desktopClockColorClock text colour in hex (e.g., "#ffffff").
_desktopClockUseThemeColorUse the theme’s primary colour for the clock instead of a fixed colour.
_desktopClockFormatTime format string (e.g., "hh:mm:ss", "h:mm AP").
_desktopClockLocalLocale for language-aware formatting (e.g., "ar", "en_US").
_desktopClockSahdowEnabledEnable a drop shadow behind the clock text.
_desktopClockSahdowColorShadow colour in hex.
_desktopClockUseAnimationAnimate the clock when the time changes.
Use the Settings App → Desktop clock section to adjust all clock properties visually. Changes are written to the theme cache file at ~/.cache/nibrasshell/themes/ and applied immediately.

​
Depth effect

The depth effect adds a subject-isolation layer on top of the wallpaper: the foreground subject is extracted from the image and composited back over a blurred version of the background, creating a subtle parallax-like sense of depth.
1

Enable the effect

Go to Settings App → Wallpapers → Depth Effect and toggle the effect on. The _desktopClockDepthEffectEnabled theme property is set to true. The desktop then renders an Overlay layer on top of the wallpaper.
2

Choose a generation method

NibrasShell supports two tools for generating the subject mask, selectable from the Depth Effect settings panel:
  • rembg — uses a neural network (U-2-Net or ISNet) to remove the background. Produces higher-quality masks but requires a one-time model download and the rembg Python package.
  • OpenCV — a faster, CPU-based approach with no model download. Results are less precise on complex subjects.
3

Cache management

Generated overlays are stored in ~/.cache/nibrasshell/themes/ and reused on subsequent loads. NibrasShell automatically clears unused overlays via overlay_cache_images_cleaner.py.
The rembg method requires Python and the rembg package. Run pip install rembg before enabling it, or choose OpenCV if you prefer no additional dependencies.

Build docs developers (and LLMs) love

Get started for freeTalk to us