Plasma Framework

The Plasma Framework provides the foundational libraries, components, and tools required to build Plasma workspaces. It consists of three main pillars:

1. QML Components: A collection of QML modules for UI development, categorized into core bindings, standard graphical components, extra components, and plasmoid-specific properties.
2. libplasma: A C++ library handling low-level tasks like SVG theme rendering, package loading, data engine access, and workspace plugin structures (containments and applets).
3. Script Engines: Support for creating applets and containments using various scripting languages.

Plasma Components 3 provides a specific visual style for QtQuick Controls 2 (QQC2). It can be used in two ways:

1. As an explicit import: You can force the Plasma theme by importing the components directly in your QML files.
2. As a style: It can be applied as the underlying style for the QtQuick Controls 2 engine.

Note that this module is intended to contain inherited templates from QQC2 desktop themes. It does not introduce new components or properties; for new APIs, use upstream QQC2, PlasmaExtras, or Kirigami.

The framework provides several QML modules for different levels of UI development:

• org.kde.plasma.core: Provides bindings for libplasma functionality (e.g., FrameSvg).
• org.kde.plasma.components: Provides standard graphical components for common UI elements like buttons, line edits, and tab bars.
• org.kde.plasma.extras: Provides extended graphical components that build upon org.kde.plasma.components but are not part of the standard API.
• org.kde.plasma.plasmoid: Provides attached properties used to manipulate the current applet or containment.

The libplasma C++ library is used for core workspace functionality, including:

• Rendering of SVG themes.
• Loading files from the packages filesystem structure.
• Accessing data through data engines.
• Loading the workspace plugin structure, specifically containments and applets.

The libplasma library provides the core framework used by Plasma applications, including the Plasma desktop shell and its components. It handles fundamental tasks such as:

• Applet and Extension Management: Definitions and loading of applets and extensions.
• GUI Elements: Common graphical user interface components.
• Data and Service Interaction: Mechanisms for interacting with system data and services.
• Search System: Integration with the Plasma search infrastructure.

Note that domain-specific functionality (such as network awareness, sensors, wallpapers, or containment actions) is implemented via specialized plugins rather than being part of the core libplasma library.

The generated template uses the org.kde.plasma namespace for the plugin identifier. Because this namespace is reserved for official Plasma modules, you must change it to a unique identifier using reverse domain name notation to avoid naming collisions and ensure translation catalogs are found correctly.

Use the following notation for your identifier:

• $(my.domain).* - For your 3rd-party plugins.
• org.kde.* - For plugins coming from other KDE software.
• org.kde.plasma.* - Reserved for official Plasma modules.

Plasma plugins use reverse domain name notation for their unique identifiers to prevent naming collisions. The generated code from this template defaults to the org.kde.plasma namespace.

Important: The org.kde.plasma namespace is reserved for plugins that are part of official Plasma modules. If you are developing a 3rd-party plugin, you must change this namespace to your own domain (e.g., com.my.domain) to avoid collisions and ensure translation catalogs are found correctly.

After installing a new applet, you can either restart the Plasma shell to load it into the desktop environment or use the plasmoidviewer tool for testing.

To restart Plasma Shell:

1. Terminate the current session: kquitapp plasmashell
2. Start it again: plasmashell

To preview the applet directly: Use plasmoidviewer -a YourAppletName, replacing YourAppletName with the identifier of your applet.

# Restarting Plasma
kquitapp plasmashell
plasmashell

# Previewing the applet
plasmoidviewer -a YourAppletName

After installing your applet, you can either restart the Plasma shell to load it into the desktop environment or use the plasmoidviewer tool to preview it directly.

To restart Plasma:

1. Quit the current session: kquitapp plasmashell
2. Start it again: plasmashell

To preview a specific applet: Use plasmoidviewer -a YourAppletName.

kquitapp plasmashell
plasmashell

# Or to preview specifically:
plasmoidviewer -a YourAppletName

To build the generated applet, use CMake and make. You must specify a CMAKE_INSTALL_PREFIX pointing to your Plasma installation directory.

Follow these steps in your terminal:

1. Navigate to the generated applet directory.
2. Create and enter a build directory.
3. Run cmake with the installation prefix.
4. Compile and install.

cd /where/your/applet/is/generated
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=MYPREFIX .. 
make 
make install

The ToolTip component (available via org.kde.plasma.core) manages a Plasma-themed tooltip rendered in its own window. It can be configured using simple text properties or by providing a custom QML component as the mainItem.

By default, the tooltip is rendered when hovering over the parent item. The item inside the ToolTipArea is loaded on demand and destroyed when the tooltip is hidden.

Import Statement: import org.kde.plasma.core

import org.kde.plasma.core as PlasmaCore
import org.kde.kirigami 2.20 as Kirigami

Kirigami.Icon {
    PlasmaCore.ToolTipArea {
        mainText: i18n("Tooltip Title")
        subText: i18n("Some explanation.")
        icon: "plasma"
        // alternatively, you can specify your own component
        // to be loaded when the tooltip shows
        mainItem: YourCustomItem { }
    }
}

To build and install the generated wallpaper plugin, follow these steps from the directory where your wallpaper was generated:

1. Create and enter a build directory.
2. Run cmake specifying your installation prefix.
3. Compile and install using make.

Note: MYPREFIX should be the path where you install your Plasma setup.

cd /where/your/wallpaper/is/generated
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=MYPREFIX ..
make
make install