Virtual Desktop Switcher

English | Español | 中文

---

English

A KDE Plasma 5 widget that displays the current virtual desktop name and provides a visual overview of all desktops with real window positions.

Features

• Real-time desktop name in panel - Shows active virtual desktop name
• Hover to open - Popup appears automatically when hovering (80ms delay)
• Real window geometry - Windows displayed in actual positions using native KDE pager API
• Window icons - Application icons shown inside window previews
• Proper aspect ratio - Desktop previews match your screen proportions
• Grid layout - Automatically arranges desktops in optimal columns/rows
• Desktop management:
  • Click to switch desktop
  • Right-click to rename or delete
  • Add new desktops with "Add" button
  • Scroll wheel to cycle through desktops
• High performance - Uses native PagerModel instead of shell commands

Installation

# Clone the repository
git clone https://github.com/andresgarcia0313/plasma-virtual-desktop-switcher.git

# Copy to Plasma plasmoids directory
cp -r plasma-virtual-desktop-switcher ~/.local/share/plasma/plasmoids/org.kde.virtualdesktopswitcher

# Restart Plasma
kquitapp5 plasmashell && kstart5 plasmashell

Add to Panel

1. Right-click on your panel → Add Widgets
2. Search for "Virtual Desktop Switcher"
3. Drag to your panel

Configuration

Right-click on the widget → Configure Virtual Desktop Switcher

Option	Description
Show window previews	Display window outlines inside desktop previews
Show window icons	Display application icons on window rectangles

Usage

Action	Result
Hover	Opens desktop overview popup
Click on desktop	Switches to that desktop
Right-click on desktop	Context menu (Rename, Delete)
Scroll wheel	Cycles through desktops
Add button	Creates new virtual desktop

Requirements

• KDE Plasma 5.27 or later
• KWin window manager
• Qt 5.15+

---

Español

Un widget de KDE Plasma 5 que muestra el nombre del escritorio virtual actual y proporciona una vista general de todos los escritorios con las posiciones reales de las ventanas.

Características

• Nombre del escritorio en tiempo real en el panel - Muestra el nombre del escritorio virtual activo
• Abrir al pasar el mouse - El popup aparece automáticamente al pasar el cursor (80ms de retraso)
• Geometría real de ventanas - Las ventanas se muestran en sus posiciones reales usando la API nativa del pager de KDE
• Iconos de ventanas - Iconos de aplicaciones mostrados dentro de las previsualizaciones
• Relación de aspecto correcta - Las previsualizaciones coinciden con las proporciones de tu pantalla
• Diseño en cuadrícula - Organiza automáticamente los escritorios en columnas/filas óptimas
• Gestión de escritorios:
  • Clic para cambiar de escritorio
  • Clic derecho para renombrar o eliminar
  • Agregar nuevos escritorios con el botón "Add"
  • Rueda del mouse para navegar entre escritorios
• Alto rendimiento - Usa PagerModel nativo en lugar de comandos de shell

Instalación

# Clonar el repositorio
git clone https://github.com/andresgarcia0313/plasma-virtual-desktop-switcher.git

# Copiar al directorio de plasmoids de Plasma
cp -r plasma-virtual-desktop-switcher ~/.local/share/plasma/plasmoids/org.kde.virtualdesktopswitcher

# Reiniciar Plasma
kquitapp5 plasmashell && kstart5 plasmashell

Agregar al Panel

1. Clic derecho en el panel → Añadir elementos gráficos
2. Buscar "Virtual Desktop Switcher"
3. Arrastrar al panel

Configuración

Clic derecho en el widget → Configurar Virtual Desktop Switcher

Opción	Descripción
Mostrar previsualizaciones	Mostrar contornos de ventanas dentro de las previsualizaciones
Mostrar iconos de ventanas	Mostrar iconos de aplicaciones en los rectángulos de ventanas

Uso

Acción	Resultado
Pasar el mouse	Abre el popup de vista general
Clic en escritorio	Cambia a ese escritorio
Clic derecho en escritorio	Menú contextual (Renombrar, Eliminar)
Rueda del mouse	Navega entre escritorios
Botón Add	Crea nuevo escritorio virtual

Requisitos

• KDE Plasma 5.27 o posterior
• Gestor de ventanas KWin
• Qt 5.15+

---

中文

一个 KDE Plasma 5 小部件，显示当前虚拟桌面名称，并提供所有桌面的可视化概览，包含真实的窗口位置。

功能特点

• 实时桌面名称 - 在面板中显示当前活动的虚拟桌面名称
• 悬停打开 - 鼠标悬停时自动显示弹出窗口（80毫秒延迟）
• 真实窗口位置 - 使用 KDE 原生 pager API 显示窗口的实际位置
• 窗口图标 - 在窗口预览中显示应用程序图标
• 正确的宽高比 - 桌面预览匹配您的屏幕比例
• 网格布局 - 自动以最佳列/行排列桌面
• 桌面管理：
  • 点击切换桌面
  • 右键重命名或删除
  • 使用"Add"按钮添加新桌面
  • 滚轮在桌面间循环切换
• 高性能 - 使用原生 PagerModel 而非 shell 命令

安装

# 克隆仓库
git clone https://github.com/andresgarcia0313/plasma-virtual-desktop-switcher.git

# 复制到 Plasma plasmoids 目录
cp -r plasma-virtual-desktop-switcher ~/.local/share/plasma/plasmoids/org.kde.virtualdesktopswitcher

# 重启 Plasma
kquitapp5 plasmashell && kstart5 plasmashell

添加到面板

1. 右键点击面板 → 添加部件
2. 搜索 "Virtual Desktop Switcher"
3. 拖拽到面板

配置

右键点击小部件 → 配置 Virtual Desktop Switcher

选项	描述
显示窗口预览	在桌面预览中显示窗口轮廓
显示窗口图标	在窗口矩形上显示应用程序图标

使用方法

操作	结果
悬停	打开桌面概览弹窗
点击 桌面	切换到该桌面
右键点击 桌面	上下文菜单（重命名、删除）
滚轮	在桌面间循环
Add 按钮	创建新的虚拟桌面

系统要求

• KDE Plasma 5.27 或更高版本
• KWin 窗口管理器
• Qt 5.15+

---

Technical Details / Detalles Técnicos / 技术细节

Architecture

The widget uses the native KDE pager plugin (org.kde.plasma.private.pager) which provides:

• PagerModel - Virtual desktop model with real-time updates
• TasksModel - Window information including geometry
• pagerItemSize - Screen dimensions for aspect ratio

Key Files

org.kde.virtualdesktopswitcher/
├── metadata.desktop          # Plugin metadata
├── contents/
│   ├── config/
│   │   ├── main.xml         # Configuration schema
│   │   └── config.qml       # Config page registration
│   └── ui/
│       ├── main.qml         # Main widget code
│       └── configGeneral.qml # Settings UI

QML Imports

import org.kde.plasma.plasmoid 2.0
import org.kde.plasma.core 2.0 as PlasmaCore
import org.kde.plasma.components 3.0 as PlasmaComponents
import org.kde.plasma.private.pager 2.0  // Native pager API

KWin D-Bus API

# List virtual desktops
qdbus org.kde.KWin /VirtualDesktopManager desktops

# Get current desktop
qdbus org.kde.KWin /VirtualDesktopManager current

# Rename desktop
qdbus org.kde.KWin /VirtualDesktopManager setDesktopName '<id>' 'New Name'

# Create desktop
qdbus org.kde.KWin /VirtualDesktopManager createDesktop <position> 'Name'

# Remove desktop
qdbus org.kde.KWin /VirtualDesktopManager removeDesktop '<id>'

---

License / Licencia / 许可证

GPL-3.0 - See LICENSE

Author / Autor / 作者

Andres Garcia - GitHub