There will be two shell packages (with the same PackageStructure) loaded on the shell: a "global" one that will provide fallback files, while another package will be loaded specific of the device form factor. Files will be searched for in the formfactor package, then if not found will be searched for in the "global" package.

Package filesystem

Package Type in desktop file: Plasma/Shell

contents/components/
contents/views/
contents/layout.js -> file
contents/defaults ->file

contents/components/

Shell UI components - named files AppletError.qml CompactApplet.qml Configuration.qml WidgetExplorer.qml

TODO: this folder goes away, every named file gets its own directory Current files:

"appleterror", "components/AppletError.qml": Error message shown when an applet fails loading
"compactapplet", "components/CompactApplet.qml": QML component that shows an applet in a popup
"configurationui", "components/Configuration.qml": QML component for the configuratuion dialog
"defaultcompactrepresentation", "components/DefaultCompactRepresentation.qml": Compact representation of an applet when collapsed in a popup, for instance as an icon. applets can override this component.
"widgetexplorer", "explorer/WidgetExplorer.qml": Widgets explorer UI
"panelconfigurationui", "components/PanelConfiguration.qml": Panel configuration UI

contents/views/

Each view (panel view or desktop view) will load a qml file that will "contain the containment", it will have the form <containment type>.qml Where <containment type> is allowed to be Desktop or Panel

Desktop.qml

The file Desktop.qml will be instantiates by the desktop view, and will manage the containment for the given screen/activity: changing activity the containment will change, the Desktop.qml instance no, so it can do things like animate the activity switch. There is a minimal API between the actual desktop view window and Dsktop.qml, available troughthe import

 import org.kde.plasma.shell 2.0 as Shell

the view instance will be available as the variable desktop
the desktop will provide two properties:
- dashboardShown: Read only, is true when the desktop is in "Dashboard" mode
- windowType: read/write, it's how the view will behave (default, Desktop)

The legal values for windowType are:

Shell.Desktop.Window: The window is a normal resizable window with titlebar and appears in the taskbar
Shell.Desktop.FullScreen: The window is fullscreen and goes over all the other windows
Shell.Desktop.Desktop: The window is the desktop layer, under everything else, doesn't appear in the taskbar
Shell.Desktop.WindowedDesktop: full screen and borderless as Desktop, but can be brought in front and appears in the taskbar, for instance Plasma Active uses this behavior

Panel.qml

Similarly to Desktop, the file Panel.qml will be instantiated to manage panel containments and offers a simple API to access the panel view via some properties:

Qt::Alignment alignment: Alignment of the panel: when not fullsize it can be aligned at left, right or center of the screen (left and right work as top/bottom too for vertical panels)
int offset: how much the panel is moved from the left/right/center anchor point
int thickness: height of horizontal panels, width of vertical panels
int length: width of horizontal panels, height of vertical panels
int maximumLength: if the panel resizes itself, never resize more than that
int minimumLength: if the panel resizes itself, never resize less than that
int distance: how much the panel is distant for the screen edge: used by the panel controller to drag it around
QScreen *screen: informations about the screen in which the panel is in (exposes all properties of QScreen)
VisibilityMode visibilityMode: how the panel behaves, visible, autohide etc.

possible values for visibilityMode are:

Shell.Panel.NormalPanel: default, always visible panel, the windowmanager reserves a places for it
Shell.Panel.AutoHide: the panel will be shownn only if the mouse cursor is on screen edges
Shell.Panel.LetWindowsCove: always visible, windows will go over the panel, no area reserved
Shell.Panel.WindowsGoBelow: always visible, windows will go under the panel, no area reserved

contents/layout.js

The default layout JavaScript file supports a similar API to Plasma1 desktop scripting. The manipulation of Applet geometry will change a bit, see Applet geometry manipulation from scripts

contents/defaults

Default settings ContainmentActions Default containment for each type Default toolbox

Example defaults config file

[Desktop]
Containment=org.kde.desktop
ToolBox=org.kde.standardtoolbox
[Desktop][ContainmentActions]
Ctrl;LeftButton=org.kde.standardmenu
MiddleButton=org.kde.paste
 
[Panel]
Containment=org.kde.panel
ToolBox=org.kde.standardtoolbox
[Panel][ContainmentActions]
Ctrl;LeftButton=org.kde.standardmenu

[Theme]
Theme=air-mobile

Layout package details In metadata.desktop: X-Plasma-ContainmentCategories=<containment type>

Applet geometry setting Containment geometry strategies: * None * Indexed * Grid * Free * Grouped

TODO

defaults for kwin configuration
default plugins for loaded kwin effects

Applet geometry manipulation from scripts

QML part

Item {
    property int appletPlacementStrategy: “indexed”
 
    Connections {
  	    target: parent
           onIndexedPlacementRequest: {
               parameters: applet, index
           }
           onGridPlacementRequest: {
               parameters: applet, x, y
           }
           onFreePlacementRequest: {
               parameters: applet, point
           }
    }
   [...]
}

C++ part in ScriptEngine

PlacementStrategy ContainmentInterface::placementStrategy() const
{
     // look up the appletPlacementStrategy property and return it
}
[...]
void ContainmentInterface::requestIndexedPlacement(Applet *applet, int index)
{
       if (placementStrategy() == IndexedStrategy) {
           emit indexedPlacementRequest(applet, index);
       }
}