Plasma/shellPackage: Difference between revisions
Created page with "=Package filesystem= Package Type in desktop file: Plasma/Shell contents/components/ contents/views/ contents/layout.js -> file contents/defaults ->file ==contents/compo..." |
|||
(18 intermediate revisions by one other user not shown) | |||
Line 1: | Line 1: | ||
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 filesystem= | ||
Package Type in desktop file: Plasma/Shell | Package Type in desktop file: Plasma/Shell | ||
Line 13: | Line 15: | ||
Configuration.qml | Configuration.qml | ||
WidgetExplorer.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/== | ==contents/views/== | ||
Line 19: | Line 30: | ||
Where <containment type> is allowed to be '''Desktop''' or '''Panel''' | 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|Applet geometry manipulation from scripts]] | |||
==contents/defaults== | |||
Default settings | Default settings | ||
Line 26: | Line 73: | ||
Default containment for each type | Default containment for each type | ||
Default toolbox | Default toolbox | ||
Example defaults config file | Example defaults config file | ||
[Desktop] | [Desktop] | ||
Containment=org.kde.desktop | |||
ToolBox=org.kde.standardtoolbox | ToolBox=org.kde.standardtoolbox | ||
[Desktop][ContainmentActions] | [Desktop][ContainmentActions] | ||
Line 40: | Line 84: | ||
[Panel] | [Panel] | ||
Containment=org.kde.panel | |||
ToolBox=org.kde.standardtoolbox | ToolBox=org.kde.standardtoolbox | ||
[Panel][ContainmentActions] | [Panel][ContainmentActions] | ||
Line 60: | Line 104: | ||
* Grouped | * Grouped | ||
==TODO== | |||
* defaults for kwin configuration | |||
* default plugins for loaded kwin effects | |||
=Applet geometry manipulation from scripts= | =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); | |||
} | |||
} | |||
PlacementStrategy ContainmentInterface::placementStrategy() const | |||
{ | |||
} | |||
void ContainmentInterface::requestIndexedPlacement(Applet *applet, int index) | |||
{ | |||
} |
Latest revision as of 11:16, 29 September 2014
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); } }