Quick Settings

Warning: This project is no longer actively maintained. I am migrating away from Linux Mint, and this app was built specifically for that environment. No further updates or bug fixes are planned. Feel free to fork and continue development.

A Windows 11-style quick settings panel for Linux Mint / Cinnamon. Sits in the system tray and provides one-click access to WiFi, Bluetooth, volume, brightness, media controls, and more -- all in a borderless popup with the Catppuccin Mocha dark theme.

Screenshot placeholder -- replace with an actual capture of the panel.

---

Features

Toggle Tiles (2-column grid, Windows 11 Fluent style)

• WiFi -- enable/disable wireless radio, shows connected SSID; chevron expands a full network list with signal strength, security indicators, and connect/disconnect buttons
• Bluetooth -- power on/off the adapter; chevron opens a paired device list with battery levels and connect/disconnect controls
• Hotspot -- toggle a pre-configured NetworkManager hotspot connection
• Night Light -- activate Redshift with a warm color temperature (4500 K default)
• Do Not Disturb -- suppress Cinnamon desktop notifications via D-Bus
• Airplane Mode -- composite toggle that disables both WiFi and Bluetooth, restoring their previous states when turned off
• Power Saver -- switch the CPU scaling governor between schedutil and powersave

Sliders

• Volume -- controls the default PipeWire/WirePlumber audio sink (0--150%); click the icon to toggle mute; scroll the tray icon to adjust
• Brightness -- adjusts the backlight via sysfs (intel_backlight), with a brightnessctl fallback for permission handling; hidden automatically on desktops without a backlight

Media Controls

• Now-playing card showing track title, artist, and player name
• Play/pause, next, and previous transport buttons via playerctl
• Integrates with Audio Router's active-player selection if present

Battery Status

• Percentage, charge state (Charging / Discharging / Full), and estimated time remaining
• Dynamic icon that reflects charge level and charging state
• Visual warning when battery drops below 20%

App Launcher Row

Quick-launch buttons for companion utilities: Audio Router, PowerPulse, Phosphor Display Manager, Bluetooth Manager, FreezeGuard, and Cinnamon Settings.

Detail Views

WiFi and Bluetooth tiles have a chevron arrow that slides open a full-screen detail view (animated Gtk.Stack slide transition):

• WiFi Detail -- toggle switch, scrollable network list with signal strength icons, security lock indicators, and connect/disconnect per network; link to Cinnamon Network Settings
• Bluetooth Detail -- toggle switch, sections for connected and paired devices with battery percentages, connect/disconnect per device; link to Cinnamon Bluetooth Settings

Panel Behavior

• Borderless popup window, positioned bottom-right above the taskbar on the active monitor
• Dismisses on focus loss or Escape key
• Polls dynamic data (media, battery) every 5 seconds while visible
• Full state refresh on every open

---

Dependencies

Runtime

Dependency	Package (Debian/Ubuntu)	Purpose
Python 3.8+	python3	Runtime
GTK 3 (PyGObject)	gir1.2-gtk-3.0, python3-gi	UI framework
GLib / Gdk	(included with GTK)	Event loop, display
NetworkManager	network-manager	WiFi control
nmcli	(included with network-manager)	WiFi CLI
BlueZ	bluez	Bluetooth stack
bluetoothctl	(included with bluez)	Bluetooth CLI
PipeWire + WirePlumber	pipewire, wireplumber	Audio
wpctl	(included with wireplumber)	Audio CLI
playerctl	playerctl	Media controls
Redshift	redshift	Night light
UPower (GI bindings)	gir1.2-upowerglib-1.0	Battery info

Optional

Dependency	Package	Purpose
brightnessctl	brightnessctl	Brightness fallback when sysfs write is not permitted
cpupower	linux-tools-common	CPU governor change when direct sysfs write requires root

---

Installation

Quick install (copy to /opt)

# Copy the package
sudo cp -r /home/alaa/quick_settings /opt/quick-settings

# Create the launcher script
sudo tee /usr/local/bin/quick-settings > /dev/null << 'LAUNCHER'
#!/usr/bin/env python3
"""Quick Settings launcher."""
import sys
sys.path.insert(0, "/opt/quick-settings")
from quick_settings.__main__ import main
main()
LAUNCHER
sudo chmod +x /usr/local/bin/quick-settings

# Install the desktop entry
sudo tee /usr/share/applications/quick-settings.desktop > /dev/null << 'DESKTOP'
[Desktop Entry]
Type=Application
Name=Quick Settings
Comment=Windows 11-style quick settings panel
Exec=quick-settings
Icon=ayatana-settings
Categories=System;Settings;
StartupNotify=false
Terminal=false
Keywords=settings;quick;volume;wifi;bluetooth;brightness;
DESKTOP

# Enable autostart
mkdir -p ~/.config/autostart
cat > ~/.config/autostart/quick-settings.desktop << 'AUTOSTART'
[Desktop Entry]
Type=Application
Name=Quick Settings
Exec=quick-settings
Hidden=false
NoDisplay=true
X-GNOME-Autostart-enabled=true
AUTOSTART

Install dependencies (Debian/Ubuntu/Mint)

sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-upowerglib-1.0 \
    network-manager bluez pipewire wireplumber playerctl redshift brightnessctl

---

Usage

Launch

# Run from terminal
quick-settings

# Run with debug logging
quick-settings --debug

Tray interaction

Action	Behavior
Left-click tray icon	Toggle the quick settings popup
Right-click tray icon	Context menu (Quit)
Scroll up/down on tray icon	Adjust system volume by 5% per tick

Keyboard

Key	Action
Escape	Close the panel

The panel also closes automatically when it loses focus (clicking anywhere outside).

---

Configuration

Quick Settings has no configuration file. All settings are applied live through the toggle tiles and sliders. State is read directly from system backends on every panel open.

Brightness control targets /sys/class/backlight/intel_backlight. If your system uses a different backlight device (e.g., amdgpu_bl0), edit the DEVICE path in backends.py:

class BrightnessBackend:
    DEVICE = Path("/sys/class/backlight/intel_backlight")  # change this

The Night Light toggle uses a fixed color temperature of 4500 K. To change it, modify the enable() method in the NightLightBackend class.

---

Architecture

quick_settings/
├── __init__.py          # Package marker
├── __main__.py          # Entry point, argument parsing, GTK main loop bootstrap
├── app.py               # QuickSettingsApp — initializes backends, panel, tray, polling
├── tray.py              # TrayIcon — Gtk.StatusIcon with left-click/right-click/scroll
├── panel.py             # PanelWindow — borderless popup, toggle grid, sliders, media, battery, app launchers
├── widgets.py           # Custom widgets: ToggleTile, SliderWidget, MediaWidget, BatteryBar
├── detail_view.py       # WiFiDetailView, BluetoothDetailView — slide-in detail panels
├── theme.py             # Catppuccin Mocha CSS theme (all .qs-* prefixed selectors)
└── backends.py          # System backends: WiFi, Bluetooth, Audio, Brightness, Battery,
                         #   NightLight, Media, AirplaneMode, DND, PowerSaver, Hotspot

Key design decisions

• Gtk.StatusIcon is used instead of AppIndicator because it provides native left-click (activate signal) for toggling the popup, right-click for context menus, and scroll events for volume -- none of which are available through AppIndicator's menu-only model.
• Borderless popup is achieved with Gdk.WindowTypeHint.POPUP_MENU, set_decorated(False), and set_keep_above(True). The panel auto-positions at the bottom-right of the monitor workarea.
• Non-blocking backend calls -- all potentially slow operations (nmcli, bluetoothctl, mount) run in daemon threads. UI updates are marshalled back via GLib.idle_add.
• CSS scoping -- every CSS class is prefixed with qs- to prevent collisions with the system GTK theme. CSS is generated from Python f-strings using the Catppuccin Mocha palette dictionary.
• Gtk.Stack provides animated slide transitions between the main view and WiFi/Bluetooth detail views.

Backend summary

Backend	CLI / API	Description
WiFiBackend	nmcli	Enable/disable radio, list networks, connect/disconnect
BluetoothBackend	bluetoothctl	Power on/off, list paired devices, connect/disconnect
AudioBackend	wpctl	Get/set volume, mute/unmute (PipeWire default sink)
BrightnessBackend	sysfs / brightnessctl	Read/write backlight percentage
BatteryBackend	UPowerGlib (GI)	Battery percentage, charge state, time estimates
NightLightBackend	redshift	Toggle warm color temperature
MediaBackend	playerctl	Now-playing metadata, play/pause/next/previous
AirplaneModeBackend	(composite)	Disables WiFi + Bluetooth together
DNDBackend	dbus-send	Toggle Cinnamon notification suppression
PowerSaverBackend	sysfs / cpupower	Switch CPU scaling governor
HotspotBackend	nmcli	Toggle a named "Hotspot" connection

---

File Locations

Item	Path
Installed package	/opt/quick-settings/
Launcher script	/usr/local/bin/quick-settings
Desktop entry	/usr/share/applications/quick-settings.desktop
Autostart entry	~/.config/autostart/quick-settings.desktop
Source code	/home/alaa/quick_settings/

---

License

MIT License. See LICENSE for details.