Cynosphere/aerothemeplasma
1
0
Fork 0
mirror of https://gitgud.io/wackyideas/aerothemeplasma.git synced 2026-06-18 19:35:47 +00:00
Code Issues Projects Releases Packages Wiki Activity
aerothemeplasma/DOCUMENTATION.md

13 KiB
Raw Permalink Blame History

Documentation

Table of contents

  1. Introduction
  2. Frequently asked questions
  3. List of components
  4. Development resources
  5. Current Wayland issues

Introduction

AeroThemePlasma is a project with a lot of moving parts, ranging from simple themes to entire codebases. This documentation aims to provide the following details:

  • Structure and list of components
  • Usage guides
  • Development resources

Documentation is currently a WIP, so expect most things to not be present.

Frequently asked questions

Is this project intended to help Windows users migrate to Linux?

No, not really.

Ultimately, this project doesn't change the fact that the underlying operating system is still Linux, and ATP's workflow doesn't diverge greatly from the typical KDE & Linux workflow. The goal of AeroThemePlasma isn't to make a 1:1 Windows desktop replacement (even though it feels like that's the intention sometimes), and it's not particularly focused on getting Windows users to migrate. The primary goal of ATP is to keep Windows 7's Aero interface alive and adapt it for modern desktops on Linux.

Are we Wayland yet?

Kinda.

AeroThemePlasma should largely work on Wayland, save for some visual quirks that haven't been ironed out yet. There are certain issues that Wayland presents that makes development on it a bit cumbersome, as well as KWin lacking features that ATP relies on under X11. See Current Wayland issues for specific details.

What about HiDPI?

Currently AeroThemePlasma works best on 100% scaling, but work is slowly being made towards HiDPI support. However, there are some unavoidable issues with HiDPI that ATP can't get around unfortunately, such as QTBUG-135833 and certain Wayland problems.

What distros are supported?

Only Arch-based distributions are supported officially for AeroThemePlasma, and the installation scripts are written with Arch-based distributions in mind. Contributions related to supporting other distributions are welcome (in the form of providing dependencies, etc.), but I don't intend to maintain that support and keep it up to date.

Do you plan on recreating the file explorer (along with other Windows applications)?

Most likely no. It's out of ATP's scope. Sevulet is a set of projects that, among other things, features a solid file explorer recreation. Please support their work!

List of components

Development resources

Useful commands

Restarting KDE

When developing most things related to ATP (and KDE in general), it's useful to be able to quickly restart either Plasmashell or KWin on demand. Add the following shorthand commands to ~/.bashrc:

alias restart-plasma='setsid plasmashell --replace'
alias restart-kwin_x11='setsid kwin_x11 --replace'
alias restart-kwin_wayland='setsid kwin_wayland --replace'

Which can then be used like any other command in the terminal:

restart-plasma

Note however that restarting KWin when using Wayland will restart the entire compositor, which may result in certain applications being killed.

Starting a nested Wayland session within X11

A KWin Wayland session can be loaded within an X11 environment using the following command:

dbus-run-session kwin_wayland --width 1366 --height 768 --xwayland "plasmashell"

This spawns a nested Wayland session with the resolution of 1366x768, while also running an instance of the desktop shell.

Get window information

For X11-specific window properties, use xprop. KWin can also query windows using the following command (works on both X11 and Wayland):

qdbus6 org.kde.KWin /KWin queryWindowInfo

KWin effects

A list of KWin effects can be printed out using DBus:

qdbus6 org.kde.KWin /Effects activeEffects
qdbus6 org.kde.KWin /Effects listOfEffects
qdbus6 org.kde.KWin /Effects loadedEffects

To check an effect's state:

qdbus6 org.kde.KWin /Effects isEffectLoaded your_effect_name
qdbus6 org.kde.KWin /Effects isEffectSupported your_effect_name

To change an effect's loaded state:

qdbus6 org.kde.KWin /Effects loadEffect your_effect_name
qdbus6 org.kde.KWin /Effects unloadEffect your_effect_name
qdbus6 org.kde.KWin /Effects toggleEffect your_effect_name

Testing

SDDM

sddm-greeter-qt6 --test-mode --theme /path/to/sddm/theme

One thing to keep in mind when testing SDDM themes is that user resources (such as locally installed icon themes, files present in the home directory, etc.) are available only when testing like this. SDDM will fail to load any user resources in a real scenario. QML UI components may also look different in test mode.

Splash screen

ksplashqml --test --window /path/to/global/theme

The --test parameter can be omitted for slightly more realistic results.

Lock screen

/usr/lib/kscreenlocker_greet --testing

Runs the lock screen in testing mode, opening a lock screen window for every display.

Ctrl+Alt+Del screen

/usr/lib/ksmserver-logout-greeter --windowed

Qt test application

kvantumpreview -style [qstyle]

Running without passing -style will simply load the application with the currently applied QStyle.

Testing notifications

notify-send -a Dolphin -h string:desktop-entry:org.kde.dolphin "Lorem ipsum dolor sit amet" "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." -i org.kde.dolphin --action=inline-reply="Reply" --action="Test"

This will spawn a notification with a sufficiently long body, presenting as Dolphin, and provides actions in the form of regular actions and inline replies.

In order to test thumbnail previews for notifications, one or more URLs need to be passed to the notification as well. This can't be done in the terminal (to my knowledge, at least), so some kind of scripting or the use of KNotification is required.

Logging

From the terminal

Restarting Plasmashell or KWin as described above results in output being printed to stdout which is readable by the terminal emulator. By default, kwin_wayland doesn't output logs to stdout, and in that case it's difficult to get logs this way.

As for KCMs, their respective logs can be retrieved by running System settings from the terminal:

systemsettings

Getting logs from KSystemLog

Alternatively, logs can be retrieved graphically from systemd's journal by using KSystemLog.

Useful tools

  • AeroGlassPane - Useful for testing AeroGlassBlur and SMOD Decorations
  • Heaptrack - Heap memory profiler, useful for detecting memory leaks and call stacks
  • KAppTemplate - Templates for Qt and Plasma projects
  • KDebugSettings - Configures the verbosity of log output for KDE applications/services
  • Kirigami Gallery - Useful for viewing color groups and color sets
  • KSystemLog - General logging application
  • msstyleEditor - Useful for viewing and modifying msstyle themes on Windows
  • Plasma SDK - Features several useful applications for Plasma development
  • Qt Creator - IDE for Qt applications, useful for QtWidgets codebases and standalone KDE projects
  • RccExtended - Required for editing SMOD resource files
  • ResourceHacker - Useful for viewing and extracting resources from Windows

External references

*While Kvantum won't be discussed here, one important detail worth mentioning is that Kvantum does not respect KDE's color schemes for the most part and that this sometimes leads to unexpected visual results. Still, it's recommended to apply a KDE color scheme alongside Kvantum for maximum compatibility.

Current Wayland issues

Some of these issues are fixable but not a lot of effort has been put into doing so, while some are inherent issues with Wayland that as of now cannot be easily fixed. This list will be updated accordingly if/when issues are resolved.

  1. Wayland cannot properly identify context menus and dropdown context menus (labelled as popupMenu and dropdownMenu respectively in the KWin effects API). As a result, context menus on Wayland will always fade in and out with the fadingpopupsaero effect.
  2. Certain animation effects play for certain windows even though they shouldn't, this is usually caused by different window identification and/or the inability to identify such windows (As the first issue points out). Most of these can likely be fixed in the future.
  3. SevenTasks uses window positioning to animate its jumplists which isn't smooth or reliable on Wayland, as client-side window positioning on Wayland is not supported as part of the protocol spec. (See xx-zones for more insight on the state of window positioning on Wayland). This is arguably bad practice in any case and should be replaced with some kind of KWin effect that actually performs the sliding animation.
  4. SevenTasks jumplists (and context menus in general) cannot steal mouse inputs from all other windows, which might potentially result in strange behavior.
  5. SevenStart's blur region often lags behind or doesn't appear at all upon opening the menu. This can likely be fixed by restructuring SevenStart in some way, but not much time has been spent fixing this bug.
  6. SevenStart's floating orb positioning fails only sometimes. Additionally, because Wayland doesn't allow client windows to raise themselves, in some cases the floating orb will appear permanently stuck underneath the panel and its child windows until the shell is restarted.
  7. Aero Peek is not visible on Wayland, although the windows do properly fade in and out of view. This should most likely be replaced with a proper KWin effect that renders the Aero Peek windows in place of regular windows.
  8. HiDPI is not properly supported for SMOD. See #252 for more details. This is an issue for both X11 and Wayland, but X11 has an easier workaround as KDecoration3 on X11 ignores DPI scaling entirely.