View source for Plasma/Active/DeviceShell

== Device specific workspaces ==
The Plasma Device shell that is used in the Plasma Active tablet shell is a generic user interface loader that doesn't provide any UI by itself.

The device shell will load:

* A set of QML files that will define the behavior of the workspace for this form factor, in the form of a Plasma::Package file structure
* That package may eventually load other packages via QML
* The plasma containments will be loaded and put into the scene
* Every activity corresponds to 1 containment
* there may be containments not linked to activities (e.g. panels)
* the containment are placed in the screen by logic written in JavaScript inside the main homescreen QML package

=== Structure of the homescreen QML package ===
[TODO]

=== API of the homescreen root QML item ===
The root QML item should expose some properties and signals, that the Plasma shell will use to interact with it.

==== Properties ====
Mandatory properties: the root object '''must''' offet those:
* QGraphicsWidget '''activeContainment''': It's a pointer to the containment that owns the screen and is set by the plasma shell (the qml part must not write it). The qml part should make sure activeContainment is disaplayed in a prominent place, e.g. filling the whole screen.

Option al properties: (they are now named objects, TODO: must become properties).
* Item '''availableScreenRect''': an item as big as the usable area of the main containment, make it smaller to prevent the containment to lay out items out of the ''availableScreenRect'' geometry. The item can offer four additional properties:
** int '''leftReserved''': space reserved at the left edge of the screen. a maximized window will not go over this area of the screen.
** int '''topReserved''': space reserved at the top edge of the screen. a maximized window will not go over this area of the screen.
** int '''rightReserved''': space reserved at the right edge of the screen.
** int '''bottomReserved''': space reserved at the bottom edge of the screen.

==== Methods ====
* '''void addPanel(Containment panel, Plasma::FormFactor formFactor, Plasma::Location location)''': Position a new panel in this home screen. The final position can depend from the panel formfactor and/or location. The homescreen must implement this method in order to be able to use panels.

==== Signals ====
* '''newActivityRequested()''': Asks the shell to show the user interface to create a new activity: call this signal from qml if you want to provide a control for a new activity creation. The shell may decide wether to honor this request or not.
* '''focusActivityView()''': Ask the shell to show the main activity screen, even if it was covered by some application, by raising and focusing its window. The shell may decide wether to honor this request or not.

==== QML types available to the Home screen QML ====
Those are additional types that can be accessed in the homescreen QML and only there.

===== DevicePanel =====
'''DevicePanel''' is available by importing org.kde.plasma.deviceshell, It's a top level window that can be used to display a panel for things like a system tray and offers the following properties:
* '''Item mainItem''': The '''Item''' that will fill the panel window. it must draw its own background.
* '''bool visible''': if true the panel window will be visible. It has nothing to do with ''mainItem'' visibility.
* '''int x''': x position in screen coordinates of the panel window.
* '''int y''': y position in screen coordinates of the panel window.
* '''rect windowListArea''': the area that the windowmanager may fill with a task manager widget.
* '''bool acceptsFocus''': if true the window will accept window focus and keyboard input, otherwise the window behaves like a notmak panel.
* '''bool activeWindow''' (read only): when true the window has active focus from the windowmanager.
* '''bool windowStripEnabled''': when true the windowmanager can display a window switcher widget in the panel window, with the geometry defined by ''windowListArea''

==== ContainmentProperties ====
'''ContainmentProperties''' defines some enums and can never be created, it may be used only to access them.

* '''enum Location''': describes where in the screen is the containment
** '''Floating''': Free floating. Neither geometry or z-ordering is described precisely by this value.
** '''Desktop''': On the planar desktop layer, extending across the full screen from edge to edge
** '''FullScreen''': Full screen
** '''TopEdge''': Along the top of the screen
** '''BottomEdge''': Along the bottom of the screen
** '''LeftEdge''': Along the left side of the screen
** '''RightEdge''': Along the right side of the screen

* '''enum FormFactor''': The FormFactor enumeration describes how the containment arranges itself
** '''Planar''': The applet lives in a plane and has two degrees of freedom to grow. Optimize for desktop, laptop or tablet usage: a high resolution screen 1-3 feet distant from the viewer.
** '''MediaCenter''': As with Planar, the applet lives in a plane but the interface should be optimized for medium-to-high resolution screens that are 5-15 feet distant from the viewer. Sometimes referred to as a "ten foot interface".
** '''Horizontal''': The applet is constrained vertically, but can expand horizontally.
** '''Vertical''': The applet is constrained horizontally, but can expand vertically.

== How to load a different default workspace ==
the file plasma-devicerc, located either in the system-wide or user-local config directory should contain the following entry:
<pre>
[General]
HomeScreenPackage=org.kde.active.contour-tablet-homescreen
</pre>

Where HomeScreenPackage is the plugin name of the package that contains the homescreen QML files. In this example ''org.kde.active.contour-tablet-homescreen'' is the name of the default homescreen for tablet devices currently shipped with Plasma Active.