Plasma/ShellDesign

Introduction

To create a full featured Plasma shell, whether it is a full primary user interface such as Plasma Desktop or Plasma Netbook or an application helper like the Plasma KPart of Plasma Media Center, there are a number of components that the application needs to provide and even more that are optional to create a well working experience.

This article documents each of these components and how they fit together.

Core Presentation

The Base Canvas: Corona

Corona is a subclass of QGraphicsScene, however provides several additional facilities:

• it manages Containments (all items added directly to a Corona are Containments), including saving and restoring the whole layout into KConfig
• it manages the association between Containments and screens: the mapped ones will be displayed by a Plasma::View
• It manages the concept of available space for screen (reimplementations of screenGeometry() and availableScreenRegion() can take into account position and size of panels for instance)
• QActions can be assigned to the corona: they can be visualized by the Containments ToolBox, but unlike the Containments Actions, those are global
• It has the concept of /Immutability/: part of the user interaction can be blocked, to prevent accidental data loss or for kiosk environments

Views

Plasma::View is a subclass of QGraphicsView. It has some peculiarities over its base class:

• Its scene will be always the global unique scene: the Corona
• It will always have an 1:1 association with a Containment
• Its sceneRect() will always be synchronized with its Containment geometry()
• It has a /screen/ and /desktop/ property: a view will be associated to a phisical screen and a virtual desktop, and will be syncronized with the Containment. Not all reimplementations need to actually associate physical screens: for instance in an application dashboardthere won't be this physical->logic association of screens
• It has its own configuration, of all values that don't depend on scene items, but from actual window geometry/properties (such as panel position, or showing the view on all virtual desktops)

Window Dressings

Containment Tool Boxes

Each containment shown by the Plasma Shell, can have a central place to show the main actions that can be performed.

A default set of toolbox actions is present in the base Containment implementation. Containment subclasses, as well as the Corona implementation of the Plasma shell can add their own.

The method Containment::AddToolBoxAction(QAction *a) adds the action a to the toolbox.

The action can contain metadata about its category, to help the toolbox implementations to visually group together similar actions, to do that call

QAction::setData(AbstractToolBox::ToolType)

A ToolBox is a subclass of Plasma::AbstractToolBox and is usually loaded as a plugin, whose desktop file will have the entry X-KDE-ServiceTypes=Plasma/ToolBox

A Containment implementation can force its own ToolBox implementation, but this is discouraged, especially in containments of type DesktopContainment or PanelContainment.

By default, containments will load the ToolBox plugin the Corona tells them. To set a default ToolBox plugin, use the function

Corona::setDefaultToolBoxPlugin(const QString &PluginName, Plasma::ContainmentType type)

in the constructor of your Corona implementation.