Plasma Mobile

Folio is the paged homescreen implementation for Plasma Mobile. It provides a multi-page interface for accessing applications and widgets.

Architecture and Behavior

• Implementation: The core logic is implemented in C++ to centralize management, while QML is used strictly for rendering the display and handling user input.
• Layout Control: Positioning, placement of delegates (icons/widgets) on the screen, and drag-and-drop behaviors are managed top-down from the C++ model rather than being handled individually by the QML components.

Plasma Mobile is a collection of shell components designed for mobile devices. The repository is organized into several functional areas:

• mobileshell: A private shell component library. Note that its API is not guaranteed to be stable.
• containments: Contains shell panels such as homescreens, status bars, and task panels.
• kcms: Contains settings modules.
• look-and-feel: Contains Plasma look-and-feel packages (e.g., lockscreen, logout).
• shell: The Plasma shell package, providing implementations for applet and containment configuration dialogs.
• quicksettings: Quick settings packages for the action drawer.
• tests: Small runnable snippets for testing shell parts in isolation without loading the full Plasma environment.

The configuration windows for applets and containments (such as homescreens) are implemented using QML files located in the shell/contents/configuration/ directory.

When the shell requests a configuration interface, libplasma dynamically loads one of two files based on the target type:

• Applets: Loads AppletConfiguration.qml
• Containments (e.g., homescreens): Loads ContainmentConfiguration.qml

Developers looking to customize or extend the configuration UI for these components should modify these specific QML files.

To add support for a new device:

1. Create a new configuration file in the configs directory using the device ID as the filename. Refer to spec.conf for the configuration specification. Omitted settings will fall back to system defaults.
2. To test the new configuration on a running system, install the file to /usr/share/plasma-mobile-device-presets/<your-device-id>.conf.
3. Apply the changes using plasma-mobile-envmanager and restart the mobile shell.

# Install your config file to the presets directory first,
# then run:

plasma-mobile-envmanager --apply-settings
plasmashell -p org.kde.plasma.mobileshell --replace

The apns-full-conf.xml file used for APN (Access Point Name) autodetection is sourced directly from the Android open source project. To ensure your local copy is up to date with the latest carrier information provided by Android, follow these steps:

1. Download the latest apns-full-conf.xml from the Android source using curl and decoding the base64 format.
2. Add the appropriate SPDX license headers to the file.

Note: The file is taken from the Android device sample repository where carriers add their APN information for autodetection.

curl "https://android.googlesource.com/device/sample/+/master/etc/apns-full-conf.xml?format=TEXT" | base64 --decode > apns-full-conf.xml

Plasma Mobile's envmanager attempts to autodetect the device ID by reading /sys/firmware/devicetree/base/compatible.

You can determine your device's specific ID by running the following command to parse the compatible string:

sed -z 's/$/\n/' /sys/firmware/devicetree/base/compatible

If the device ID is not automatically detected by the system, you can ship a specific device preset by creating a configuration file at /etc/xdg/plasmamobilerc.

In this file, define the [Device] section with the device key set to the identifier found in /usr/share/plasma-mobile-device-presets (which corresponds to the files in the configs folder).

[Device]
device=oneplus,enchilada # replace with the device id

The Start module is a KDED (KDE Daemon) plugin designed to trigger specific environment and initialization processes when the daemon starts. Upon instantiation, it automatically launches two asynchronous command jobs using KIO::CommandLauncherJob:

1. Environment Manager: Executes plasma-mobile-envmanager --apply-settings to apply system settings. It uses the desktop name org.kde.plasma-mobile-envmanager and handles errors automatically via KNotificationJobUiDelegate.
2. Initial Start: Executes plasma-mobile-initial-start to handle first-run or initial setup logic. It uses the desktop name org.kde.plasma-mobile-initial-start and also handles errors automatically via KNotificationJobUiDelegate.

This module is registered as a plugin via K_PLUGIN_FACTORY_WITH_JSON using the metadata file kded_plasma_mobile_start.json.

When running the Plasma Mobile shell in a window for testing, you can use specific flags to control the display properties:

• --output-count: Specifies the number of displays.
• --width: Sets the window width.
• --height: Sets the window height.

Example command to run with 2 displays and a mobile-sized resolution (360x720):

QT_QPA_PLATFORM=wayland dbus-run-session kwin_wayland --xwayland "plasmashell -p org.kde.plasma.mobileshell" --output-count 2 --width 360 --height 720

The plasma-mobile-initial-start application supports the following command line option:

• --test-wizard: Opens the initial start wizard without modifying configuration.