LatteDock: Difference between revisions
(LatteDock) |
m (The property 'providesClickAnimation' does not exist (launching Latte in debug mode returns 'cannot assign to non-existent property') whereas 'providesClickedAnimation' does exist and does what the developer expects it to do.) |
||
(57 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
[[File:LLoXdgK.png|right|Latte Dock!]] | |||
== Technical Details == | |||
<p align='justify'>This is an effort to expose some of the Latte tricks and APIs that developers can use in order to leverage Latte Dock capabilities. Two major sections are currently provided, Applets and Indicators. In the <strong>Applets</strong> section you will understand how a Plasma QML applet can obtain information from Latte and how it can be implemented properly in order to work just fine with parabolic effect. In <strong>Indicators</strong> section you will learn how you can create your own Latte Indicators.</p> | |||
<p align='justify'><strong>NOTE:</strong> All mentioned APIs are provided since [v0.9.0] and if new properties or functions are added; a relevant reference will be presented, for example [v0.9.4] </p> | |||
== Applets == | |||
=== Can a Plasma Applet access Latte Information? === | |||
<p align='justify'>Most definitely! This is very simple. The only thing you need to add in your applet main QML file is:</p> | |||
{{Input|<syntaxhighlight lang="QML" line> | |||
import QtQuick 2.0 | |||
Item { | |||
id: root | |||
//! Latte Connection | |||
property Item latteBridge: null | |||
//! | |||
} | |||
</syntaxhighlight>}} | |||
<p align='justify'> | |||
The <strong>latteBridge</strong> object is assigned from Latte when applet is loaded and it is the ''“ONE to rule them ALL”'' way to communicate with Latte. Important thing to mention is that if your applet is using both Compact and FullRepresentation(s) then the relevant code should be placed in CompactRepresentation.</p> | |||
{{Input|<syntaxhighlight lang="QML" line> | |||
import QtQuick 2.0 | |||
Item { | |||
id: root | |||
Plasmoid.compactRepresentation: Item { | |||
//! Latte Connection | |||
property Item latteBridge: null | |||
//! | |||
} | |||
} | |||
</syntaxhighlight>}} | |||
<p align='justify'> | |||
After adding '''latteBridge''' property it is straightforward to identify when your applet is inside a Latte panel/dock or not with:</p> | |||
<pre> | |||
readonly property bool inLatte: latteBridge !== null | |||
</pre> | |||
---- | |||
=== Can a plasma applet behave properly with parabolic effect? === | |||
<p align='justify'> | |||
Parabolic effect is not working properly when applets provide different lengths. Applets with large lengths decrease the animations speed and the applets with small lengths increase it. The best way for parabolic effect to work is for all applets to provide a squared layout that does not update its content positioning when zoomed. In order to make things easy for developers Latte can provide you with the best layout to achieve this without needing from you to make any calculations. To do this, you need to set it up as such: | |||
</p> | |||
{{Input|<syntaxhighlight lang="QML" line> | |||
import QtQuick 2.0 | |||
import org.kde.plasma.plasmoid 2.0 | |||
Item { | |||
id: root | |||
Layout.minimumWidth: inLatte && isHorizontal ? -1 : [plasma case] | |||
Layout.preferredWidth: inLatte && isHorizontal ? -1 : [plasma case] | |||
Layout.maximumWidth: inLatte && isHorizontal ? -1 : [plasma case] | |||
Layout.minimumHeight: inLatte && !isHorizontal ? -1 : [plasma case] | |||
Layout.preferredHeight: inLatte && !isHorizontal ? -1 : [plasma case] | |||
Layout.maximumHeight: inLatte && !isHorizontal ? -1 : [plasma case] | |||
readonly property bool isHorizontal: plasmoid.formFactor === PlasmaCore.Types.Horizontal | |||
//! Latte Connection | |||
property Item latteBridge: null | |||
readonly property bool inLatte: latteBridge !== null | |||
//! | |||
} | |||
</syntaxhighlight>}} | |||
<p align='justify'> | |||
In the above example you can see that when the applet is not providing any information for its Layout [<code>-1</code> case] then Latte has the freedom to set it in the best appropriate.</p> | |||
---- | |||
=== latteBridge === | |||
===== latteBridge <properties>===== | |||
<p align='justify'>After the '''latteBridge''' Item has been set from Latte you can access the following properties:</p> | |||
<p align='justify'> | |||
<code><strong>version</strong>[int] (readonly)</code> : Shows the '''latteBridge''' version which coincides with the Latte Dock version. For example, Latte 0.9.0 produces a unique integer that can be used for numeric comparisons for greater than, lower than etc. If you want to make a version comparison, you can try the following in your code. | |||
</p> | |||
<pre> | |||
latteBridge.version >= latteBridge.actions.version(0,9,2) | |||
</pre> | |||
<p align='justify'> | |||
<code><strong>applyPalette</strong> [bool] (readonly)</code> : <code>true</code> when Latte is advising the applet to use the Latte colors palette in order to draw its contents with proper contrast | |||
</p> | |||
<p align='justify'> | |||
<code><strong>inEditMode</strong> [bool] (readonly)</code> : <code>true</code> when Latte is in Edit Mode | |||
</p> | |||
<p align='justify'> | |||
<code><strong>inPlasmaPanelStyle</strong> [bool] (readonly)</code> : <code>true</code> when Latte behaves as a Plasma Panel concerning external shadow rendering, transparency levels, etc. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>parabolicEffectEnabled</strong> [bool] (readonly)</code> : <code>true</code> when Latte Parabolic Effect is enabled. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>iconSize</strong>[int] (readonly)</code> : the current icon size used for all applets in the containment where this applet is present | |||
</p> | |||
<p align='justify'> | |||
<code><strong>screenEdgeMargin</strong> [int] (readonly) </code> '''[v0.10]''' : used in floating docks and panels to specify how many pixels is the gap between the dock and the screen edge | |||
</p> | |||
<p align='justify'> | |||
<code><strong>maxZoomFactor</strong>[real] (readonly)</code> : the current zoom factor with values from <strong>1.0 to 2.0</strong> | |||
</p> | |||
<pre> | |||
1 = No Scaling | |||
1.2 = Scale to 120% | |||
2 = Scale to 200% | |||
</pre> | |||
<br> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>actions</strong> [QtObject] (readonly)</code> : Used to pass information to Latte concerning your applet requirements. This is explained in detail at [https://techbase.kde.org/index.php?title=LatteDock&action=submit#latteBridge.actions_.3Cobject.3E latteBridge.actions] section | |||
</p> | |||
<p align='justify'> | |||
<code><strong>palette </strong>[SchemeColors *QtObject] (readonly)</code> : the current Latte color scheme palette used. Properties available for color scheme object are provided through [https://phabricator.kde.org/source/latte-dock/browse/master/app/wm/schemecolors.h schemecolors.h] | |||
</p> | |||
<p align='justify'> | |||
<code><strong>windowsTracker</strong> [QtObject] (readonly)</code> : all windows tracking information that can be used from applets to update their contents. This is explained in detail in the [https://techbase.kde.org/index.php?title=LatteDock&action=submit#latteBridge.windowsTracker latteBridge.windowsTracker] section. <strong>Important:</strong>You need to enable <code>windowsTrackingEnabled</code> first through [https://techbase.kde.org/index.php?title=LatteDock&action=submit#latteBridge.actions_.3Cobject.3E latteBridge.actions] object. | |||
</p> | |||
---- | |||
===== latteBridge <signals> ===== | |||
<code>broadcasted(string action, variant value)</code> | |||
<p align='justify'> | |||
Applets in Latte can create their own protocols in order to communicate with their neighbour applets. When such signal is received from your applet it means that some other applet is requesting from you to execute '''“action”''' with parameter '''“value”'''. A good example are the Window Title and Window AppMenu applets. These applets need to communicate with each other in order to hide or show themselves in Unity Mode. Window Title is shown when there is no mouse hovering and Window AppMenu when there is one. All this is orchestrated through applets without Latte taking any responsibility except broadcasting the requested actions to appropriate recipients. How applets are sending such actions through '''latteBridge.actions''' is explained in detail at the relevant [https://techbase.kde.org/index.php?title=LatteDock&action=submit#latteBridge.actions_.3Cobject.3E section]. In you want to track this '''broadcasted''' signal you can use: | |||
</p> | |||
{{Input|<syntaxhighlight lang="QML" line> | |||
import QtQuick 2.0 | |||
Item { | |||
id: root | |||
//! Latte Connection | |||
property Item latteBridge: null | |||
readonly property bool inLatte: latteBridge !== null | |||
//! | |||
Connections { | |||
target: latteBridge | |||
onBroadcasted: { | |||
if (action === "actionname1") { | |||
//! your code here | |||
} else if (action === "actionname2") { | |||
//! your code here | |||
} | |||
} | |||
} | |||
} | |||
</syntaxhighlight>}} | |||
---- | |||
=====latteBridge.actions <object>===== | |||
<p align='justify'> | |||
Through actions an applet can send information to Latte and other neighbour applets. The following functions can be used to accomplish this: | |||
</p> | |||
<code><strong>setProperty(appletId, parameter, value)</strong></code> | |||
<p align='justify'> | |||
Applets can set their characteristics and demands through this function. For example when an applet wants to disable the Active Indicator in Latte Side can use: | |||
</p> | |||
<pre> | |||
latteBridge.actions.setProperty(plasmoid.id, “activeIndicatorEnabled”, false); | |||
</pre> | |||
<p align='justify'> | |||
or when it wants to disable the Latte Side Coloring that overlays the applets monochromatic in Smart Coloring mode then it can use: | |||
</p> | |||
<pre> | |||
latteBridge.actions.setProperty(plasmoid.id, “latteSideColoringEnabled”, false); | |||
</pre> | |||
<br> | |||
<code><strong>getProperty(appletId, parameter)</strong></code> | |||
<p align='justify'> | |||
Applets can read the current assigned characteristics through this function: | |||
</p> | |||
<pre> | |||
var indicatorEnabled = latteBridge.actions.readProperty(plasmoid.id, “activeIndicatorEnabled”); | |||
</pre> | |||
<br> | |||
<code><strong>broadcastToApplet(receiverPluginId, action, value)</strong></code> | |||
<p align='justify'> | |||
Applets can communicate with other neighbour applets. For example when Window Title is informing AppMenu that needs to hide itself it sends: | |||
</p> | |||
<pre> | |||
latteBridge.actions.broadcastToApplet(“ord.kde.windowappmenu”,”setVisible”, false); | |||
</pre> | |||
<br> | |||
<code><strong>version(major, minor, patch)</strong></code> | |||
<p align='justify'> | |||
It is used to produce a unique integer based on major, minor and patch versions in order to compare different versions, for example: | |||
</p> | |||
<pre> | |||
latteBridge.version >= latteBridge.actions.version(0,9,2) | |||
</pre> | |||
---- | |||
=====latteBridge.actions <applet characteristics>===== | |||
<p align='justify'> | |||
Applets can have different demands and characteristics that can be set and accessed through <strong>setProperty</strong> and <strong>getProperty</strong> functions. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>activeIndicatorEnabled</strong> [bool]</code> : <code>false</code> means Latte will not draw any indicator for this applet, a good example being the Global Menu plasmoid. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>latteIconOverlayEnabled</strong> [bool]</code> : <code>false</code> means Latte will never try to identify the central icon used in order to make this applet draw itself correctly with parabolic effect. Most applets are using PlasmaCore.IconItem in order to draw the CompactRepresentation icon when they are in a panel, but plasma iconitem does not play nice with parabolic effect. This is why Latte is trying to handle the case and take resposibility by hiding the <strong>PlasmaCore.IconItem</strong> and draw a <strong>LatteComponents.IconItem</strong> instead. If you dont want this to happen then you must set this property to <code>false</code>. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>latteSideColoringEnabled</strong> [bool]</code> : <code>false</code> means Latte will never overlay any color over this applet because applet takes responsibility for painting itself at all cases. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>lengthMarginsEnabled</strong> [bool]</code> : <code>false</code> means means Latte will not draw any margins around this applet comparing to its neighbours. Good example is the spacer plasmoid that in panel mode does not need any extra margins around it. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>parabolicEffectLocked</strong> [bool]</code> : <code>true</code> means Latte must disable parabolic effect for that specific applet. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>windowsTrackingEnabled</strong> [bool]</code> : <code>true</code> means Latte must provide a <strong>latteBridge.windowsTracker</strong> object through <strong>latteBridge</strong> | |||
</p> | |||
<p align='justify'> | |||
<code><strong>screenEdgeMarginSupported</strong> [bool]</code> <b>[0.10]</b> : <code>true</code> means this applet can handle screen gaps from floating windows on its own | |||
</p> | |||
---- | |||
=====latteBridge.windowsTracker===== | |||
<p align='justify'> | |||
WindowTracker provides two major objects <strong>currentScreen</strong> and <strong>allScreens</strong> in order to filter windows and provide window states information. | |||
</p> | |||
=====latteBridge.windowsTracker.currentScreen <properties>===== | |||
<p align='justify'> | |||
<code><strong>activeWindowMaximized</strong> [bool] (readonly) </code> : <code>true</code> when there is an active and at the same time maximized window in current screen | |||
</p> | |||
<p align='justify'> | |||
<code><strong>activeWindowTouching</strong> [bool] (readonly) </code> : <code>true</code> when there is an active window in current screen and that window is also touching the Latte dock/panel. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>existsWindowActive</strong> [bool] (readonly) </code> : <code>true</code> when there is an active window in current screen. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>existsWindowMaximized</strong> [bool] (readonly) </code> : <code>true</code> when there is a maximized window in current screen independent if it is active or not. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>existsWindowTouching</strong> [bool] (readonly) </code> : <code>true</code> where there is a window in current screen that is touching the Latte dock/panel independent if it is active or not | |||
</p> | |||
<p align='justify'> | |||
<code><strong>activeWindowScheme</strong>[SchemeColors *QtObject] (readonly) </code> : color scheme object for window that is touching Latte dock/panel in current screen and <code>null</code> if there is none. Properties provided by scheme objects can be found at [https://phabricator.kde.org/source/latte-dock/browse/master/app/wm/schemecolors.h schemecolors.h] | |||
</p> | |||
<p align='justify'> | |||
<code><strong>lastActiveWindow</strong>[LastActiveWindow *QtObject] (readonly) </code> : last active window that is still present and shown in the current screen. Properties provided from '''lastActiveWindow''' can be found at [https://phabricator.kde.org/source/latte-dock/browse/master/app/wm/tracker/lastactivewindow.h lastactivewindow.h] | |||
</p> | |||
---- | |||
=====latteBridge.windowTracker.allScreens <properties>===== | |||
<p align='justify'> | |||
<code><strong>activeWindowMaximized</strong> [bool] (readonly) </code> : <code>true</code> when there is an active maximized window in any screen. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>existsWindowActive</strong> [bool] (readonly) </code> : <code>true</code> when there is an active window in any screen. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>existsWindowMaximized</strong> [bool] (readonly) </code> : <code>true</code> when there is a maximized window in any screen independent if it is active or not. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>activeWindowScheme</strong>[SchemeColors *QtObject] (readonly) </code> : color scheme object for active window in any screen, and <code>null</code> if there is none. Properties available for color scheme objects are provided through [https://phabricator.kde.org/source/latte-dock/browse/master/app/wm/schemecolors.h schemecolors.h] | |||
</p> | |||
<p align='justify'> | |||
<code><strong>lastActiveWindow</strong>[LastActiveWindow *QtObject] (readonly) </code> : last active window that is still present and shown in any screen.Properties provided from '''lastActiveWindow''' can be found at [https://phabricator.kde.org/source/latte-dock/browse/master/app/wm/tracker/lastactivewindow.h lastactivewindow.h] | |||
</p> | |||
=== Applet Examples === | |||
<strong> | |||
[https://github.com/psifidotos/applet-latte-separator Latte Separator]<br /> | |||
[https://github.com/psifidotos/applet-latte-spacer Latte Spacer]<br /> | |||
[https://github.com/psifidotos/applet-window-title Window Title Applet]<br /> | |||
[https://github.com/psifidotos/applet-window-buttons Window Buttons Applet]<br /> | |||
[https://github.com/psifidotos/applet-window-appmenu Window AppMenu Applet]<br /> | |||
</strong> | |||
---- | |||
== Indicators == | |||
=== Introduction === | |||
<p align='justify'> | |||
In Latte v0.9 every indicator style has its own standalone qml implementation that can be found in its own package, just like Plasma qml-only applets. In that way every indicator style can support its own specific user settings and also abstract its implementation from the main Latte development. Online Indicators can be found at the [https://store.kde.org/browse/cat/563/ kde store] and can be installed through Latte → Effects page without needing from the users any special actions to accomplish the task.</p> | |||
=== Package Structure === | |||
The Indicator package should have the following structure: | |||
<pre> | |||
metadata.desktop [required] | |||
package/ui/main.qml [required] | |||
package/config/main.xml [optional] | |||
package/config/config.qml [optional] | |||
</pre> | |||
---- | |||
=== Metadata.desktop === | |||
<p align='justify'> | |||
Every indicator needs a desktop file in order to tell Latte where to find its implementation and what its author details are. The format is as such: | |||
</p> | |||
<pre> | |||
[Desktop Entry] | |||
Name=Latte | |||
Comment=Latte default indicator | |||
Encoding=UTF-8 | |||
Type=Service [required] | |||
Icon=latte-dock | |||
X-Plasma-API=declarativeappletscript [required] | |||
X-KDE-ServiceTypes=Latte/Indicator [required] | |||
X-Latte-MainScript=ui/main.qml [required] | |||
X-Latte-ConfigUi=config/config.qml [optional] | |||
X-Latte-ConfigXml=config/main.xml [optional] | |||
X-KDE-PluginInfo-Author=KDE Awesome Developer | |||
X-KDE-PluginInfo-Name=org.kde.awesome.custom | |||
X-KDE-PluginInfo-Version=0.1 | |||
X-KDE-PluginInfo-Category=Latte Indicator | |||
X-KDE-PluginInfo-License=GPL v2+ | |||
X-KDE-PluginInfo-EnabledByDefault=true | |||
</pre> | |||
<p align='justify'> | |||
<code><strong>X-Plasma-API</strong></code> : it is '''required''' because it defines a qml-only plugin | |||
</p> | |||
<p align='justify'> | |||
<code><strong>X-KDE-ServiceTypes</strong></code> : it is '''required''' with value <code>Latte/Indicator</code> otherwise the indicator can not be installed and loaded | |||
</p> | |||
<p align='justify'> | |||
<strong><code>X-Latte-MainScript</code></strong>: it is '''required''' and defines the main qml file for the indicator implementation | |||
</p> | |||
<p align='justify'> | |||
<code><strong>X-Latte-ConfigXml</strong></code> : defines the xml settings that are going to be used from indicator implementation and user settings. It is ''optional'' and a package may not include it | |||
</p> | |||
<p align='justify'> | |||
<code><strong>X-Latte-ConfigUI</strong></code> : defines the qml settings user interface. It is ''optional'' and is provided only when the indicator has settings that the user can choose from in order to adjust the indicate apprearance and behaviour | |||
</p> | |||
=== QML Implementation === | |||
====package/ui/main.qml==== | |||
<p align='justify'> | |||
Every indicator's main qml file must use <code>LatteComponents.IndicatorItem</code> at its root | |||
</p> | |||
{{Input|<syntaxhighlight lang="QML" line> | |||
import QtQuick 2.0 | |||
import org.kde.latte 0.2 as Latte | |||
import org.kde.latte.components 1.0 as LatteComponents | |||
LatteComponents.IndicatorItem { | |||
id: root | |||
providesFrontLayer: false | |||
providesHoveredAnimation: false | |||
... | |||
} | |||
</syntaxhighlight>}} | |||
<p align='justify'> | |||
The <code><strong>LatteComponents.IndicatorItem</strong></code> provides options to inform Latte what requirements and capabilities this indicator provides in order to appear, function and behave properly. All <strong>IndicatorItem</strong> options are ''[optional]'': | |||
</p> | |||
=====LatteComponents.IndicatorItem [properties]===== | |||
<br> | |||
<p align='justify'> | |||
<code><strong>needsIconColors</strong> [bool] </code> : <code>true</code> when current icon main colors are needed. For example Unity Indicator draws its background and glow based on current icon colors. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>needsMouseEventCoordinates</strong> [bool] </code> : <code>true</code> when mouse event coordinates are needed. An example is click animation in android style from Plasma Indicator. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>providesFrontLayer</strong> [bool] </code> : <code>true</code> when a front layer is provided in order to draw contents <strong>above</strong> the current item/icon. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>providesHoveredAnimation</strong> [bool] </code> : <code>true</code> if Latte built-in hovered animation must be disabled | |||
</p> | |||
<p align='justify'> | |||
<code><strong>providesClickedAnimation</strong> [bool] </code> : <code>true</code> if Latte built-in clicked animation must be disabled | |||
</p> | |||
<p align='justify'> | |||
<code><strong>providesInAttentionAnimation</strong> [bool] </code> '''[v0.10.4]''' : <code>true</code> if Latte built-in inattention animation must be disabled | |||
</p> | |||
<p align='justify'> | |||
<code><strong>providesTaskLauncherAnimation</strong> [bool] </code> '''[v0.10.4]''' : <code>true</code> if Latte built-in bouncing task launcher animation must be disabled | |||
</p> | |||
<p align='justify'> | |||
<code><strong>providesGroupedWindowAddedAnimation</strong> [bool] </code> '''[v0.10.4]''' : <code>true</code> if Latte built-in window added in group animation must be disabled | |||
</p> | |||
<p align='justify'> | |||
<code><strong>providesGroupedWindowRemovedAnimation</strong> [bool] </code> '''[v0.10.4]''' : <code>true</code> if Latte built-in window removed from group animation must be disabled | |||
</p> | |||
<p align='justify'> | |||
<code><strong>enabledForApplets</strong> [bool] </code> '''[v0.10.0]''' : <code>true</code> if indicator should be drawn also for applets and <code>false</code> if it should not. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>extraMaskThickness</strong> [int]</code> : How many pixels are needed above the indicator in order to be drawn correctly. An example is the Latte indicator in reverse mode that supports glowing, but that glow is drawn externally. Latte must be informed for this in order to not visually subtract that glow. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>minThicknessPadding</strong> [real]</code> : Minimum thickness padding that is needed from this indicator | |||
</p> | |||
<pre> | |||
minThicknessPadding: 0.2 // 20% of current icon size | |||
</pre> | |||
<p align='justify'> | |||
<code><strong>lengthPadding</strong> [real]</code> '''[v0.10.0]''' : Default length padding that should be applied both for tasks and applets. | |||
</p> | |||
<pre> | |||
lengthPadding: 0.2 // 20% of current icon size | |||
</pre> | |||
<p align='justify'> | |||
<code><strong>appletLengthPadding</strong> [real]</code> '''[v0.9.2]''' : If enabled then applets should use different length padding value compared to tasks. | |||
</p> | |||
<pre> | |||
appletLengthPadding: -1 // [disabled] use general length paddding | |||
appletLengthPadding: 0.2 // 20% of current icon size | |||
</pre> | |||
<p align='justify'> | |||
<code><strong>backgroundCornerMargin</strong> [real]</code> '''[v0.10.3]''' : How far the indicator should be from the edge of the panel background. It is totally related to panel background roundness and specifies in percentage how much of that roundness is applied for the corner margin. | |||
</p> | |||
<pre> | |||
backgroundCornerMargin: 1.00 // 100% of the panel background roundness;the indicator is never drawn inside the roundness | |||
backgroundCornerMargin: 0.50 // 50% of the panel background roundness;the indicator is using only half of background roundness | |||
</pre> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>svgImagePaths</strong> [Array of strings]</code> : '''Plasma::SVG''' files that must be loaded from Latte in order to avoid high memory consumption. An example could be: | |||
</p> | |||
<pre> | |||
svgImagePaths: [‘widgets/panel-background’, ‘../icons/separator.svg’] | |||
</pre> | |||
<p align='justify'> | |||
In this example first svg icon is provided from current plasma theme and second is located relevant to <code>package/ui</code> folder. | |||
</p> | |||
---- | |||
====Tasks/Applets Information==== | |||
<p align='justify'> | |||
As long as <strong>IndicatorItem</strong> has been set for the main qml file then the entire indicator qml implementation gains two different objects ( '''<code>level</code>''' and '''<code>indicator</code>''' ) in order to access tasks/applets and general information. | |||
</p> | |||
---- | |||
===== level <properties> ===== | |||
<p align='justify'> | |||
<code><strong>isBackground</strong> [bool] (readonly) </code> : <code>true</code> when the indicator background layer must be painted which is below the current icon/applet. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>isForeground</strong> [bool] (readonly) </code> : <code>true</code> when the indicator foreground layer needs to be painted which is above the current icon/applet | |||
</p> | |||
<p align='justify'> | |||
<code><strong>requested.iconOffsetX</strong> [int] [v0.9.2] </code> : adjust the icon placement for x axis in pixels | |||
</p> | |||
<p align='justify'> | |||
<code><strong>requested.iconOffsetY</strong> [int] [v0.9.2] </code> : adjust the icon placement for y axis in pixels | |||
</p> | |||
<p align='justify'> | |||
<code><strong>requested.iconOpacity</strong> [real] [v0.10.4] </code> : adjust the icon opacity | |||
</p> | |||
<p align='justify'> | |||
<code><strong>requested.iconRotation</strong> [real] [v0.10.4] </code> : adjust the icon rotation | |||
</p> | |||
<p align='justify'> | |||
<code><strong>requested.iconScale</strong> [real] [v0.10.4] </code> : adjust the icon scale value | |||
</p> | |||
<p align='justify'> | |||
<code><strong>requested.iconTransformOrigin</strong> [QML TranformOrigin] [v0.10.4] </code> : adjust the icon qml transform origin | |||
</p> | |||
<br/> | |||
===== level <signals> ===== | |||
<p align='justify'> | |||
<code><strong>mousePressed(int x, int y, int button)</strong></code> : can be tracked when <code> needMouseEventSignals</code> property has been enabled in '''IndicatorItem''' in order to get mouse x,y coordinates and which mouse button was released. | |||
</p> | |||
---- | |||
===== indicator <properties>===== | |||
<p align='justify'> | |||
<code><strong>isTask</strong> [bool] (readonly) </code> : <code>true</code> when main item is actually a task | |||
</p> | |||
<p align='justify'> | |||
<code><strong>isApplet</strong> [bool] </code> : <code>true</code> when main item is actually an applet | |||
</p> | |||
<p align='justify'> | |||
<code><strong>isEmptySpace</strong> [bool] </code> '''[v0.9.3]''' : <code>true</code> when the indicator has been loaded at the dock/panel background in order to trigger visual feedback for empty areas. A good example for its use is when the Plasma indicator style is creating android-like click animations for empty areas in a panel. | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>isLauncher</strong> [bool] (readonly) </code> : <code>true</code> when main item is a task in launcher state | |||
</p> | |||
<p align='justify'> | |||
<code><strong>isStartup</strong> [bool] (readonly) </code> : <code>true</code> when main item is a task in startup state | |||
</p> | |||
<p align='justify'> | |||
<code><strong>isWindow [bool]</strong> (readonly) </code> : <code>true</code> when main item is a task in window state | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>isActive</strong> [bool] (readonly) </code> : <code>true</code> when main item is active | |||
</p> | |||
<p align='justify'> | |||
<code><strong>isGroup</strong> [bool] (readonly) </code> : <code>true</code> when main item is a group of tasks | |||
</p> | |||
<p align='justify'> | |||
<code><strong>isHovered</strong> [bool] (readonly) </code> : <code>true</code> when main item is hovered | |||
</p> | |||
<p align='justify'> | |||
<code><strong>isMinimized</strong> [bool] (readonly) </code> : <code>true</code> when main item is a task in minimized state | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>isPressed</strong> [bool] (readonly) </code> : <code>true</code> when main item is pressed | |||
</p> | |||
<p align='justify'> | |||
<code><strong>inAttention</strong> [bool] (readonly) </code> : <code>true</code> when main item requires attention | |||
</p> | |||
<p align='justify'> | |||
<code><strong>inRemoving</strong> [bool] (readonly) </code> : <code>true</code> when main item is in remove stage | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>isSquare</strong> [bool] (readonly) </code> : <code>true</code> when main item has a squared layout | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>hasActive</strong> [bool] (readonly) </code> : <code>true</code> when a group of tasks has an active item | |||
</p> | |||
<p align='justify'> | |||
<code><strong>hasMinimized</strong> [bool] (readonly) </code> : <code>true</code> when a group of tasks has at least one minimized window | |||
</p> | |||
<p align='justify'> | |||
<code><strong>hasShown</strong> [bool] (readonly) </code> : <code>true</code> when a group of tasks has at least one shown (''not minimimed'') window | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>windowsCount</strong> [int] (readonly)</code> : how many windows exist in a grouped task | |||
</p> | |||
<p align='justify'> | |||
<code><strong>windowsMinimizedCount</strong> [int] (readonly)</code> : how many minimized windows exist in a grouped task | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>currentIconSize</strong> [int] (readonly)</code> : current icon size used for the entire dock or panel | |||
</p> | |||
<p align='justify'> | |||
<code><strong>maxIconSize</strong> [int] (readonly)</code> : maximum icon size that can occur from this dock or panel | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>scaleFactor</strong> [real] (readonly)</code> : current scale factor for this item with values from <strong>1.0 to 2.0</strong> | |||
</p> | |||
<pre> | |||
1 = Item is not zoomed | |||
1.2 = Item is zoomed by 20% | |||
2 = Item is zoomed by 100% | |||
</pre> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>panelOpacity</strong> [real] (readonly)</code> : current panel background opacity | |||
</p> | |||
<p align='justify'> | |||
<code><strong>shadowColor</strong> [color] (readonly)</code> : current shadow color used for all items | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>animationsEnabled</strong> [bool] (readonly) </code> : <code>true</code> when animations are enabled | |||
</p> | |||
<p align='justify'> | |||
<code><strong>durationTime</strong> [real] (readonly)</code> : current duration time for animation. It is a multiplier that can be used for animations in order to respect user preference concerning animations speed | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>progressVisible</strong> [bool] (readonly) </code> '''[v0.9.2]''' : <code>true</code> when task progress in active | |||
</p> | |||
<p align='justify'> | |||
<code><strong>progress</strong> [real] (readonly)</code> '''[v0.9.2]''' : current progress percentage | |||
</p> | |||
<pre> | |||
0 = 0% progress | |||
45.2 = 45.2% progress | |||
</pre> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>screenEdgeMargin</strong> [int] (readonly) </code> '''[v0.10]''' : used in floating docks and panels to specify how many pixels is the gap between the dock and the screen edge | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>iconBackgroundColor</strong> [color] (readonly)</code> : main background color produced from the current icon. ['''requires''' from you to have set '''needsIconColors''' to <code>true</code> at main IndicatorItem] | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>iconGlowColor</strong> [color] (readonly)</code> : main glow color produced from the current icon. ['''requires''' from you to have set '''needsIconColors''' to <code>true</code> at main IndicatorItem] | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>palette</strong> [QtObject] (readonly)</code> : current colors palette used. Provides ''backgroundColor, textColor'' etc. Take note that this object provides also a '''scheme''' string pointing absolute path of the current scheme file. A good example for '''indicator.scheme''' is the Window Buttons applet that forwards that information to '''KDecoration2''' in order for plasma window buttons to be drawn. '''Example code:''' | |||
</p> | |||
<pre> | |||
property color backColor: indicator.palette.backgroundColor | |||
</pre> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>configuration</strong> [QtObject] (readonly)</code> : object to access the user settings specified at the main.xml file | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>resources</strong> [QtObject] (readonly)</code> : object to access memory efficient produced resources such as plasma svgs | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
<code><strong>resources.svgs</strong> [Array] (readonly)</code> : object to access memory efficient produced Plasma/Svgs specified at <code>IndicatorItem.svgImagePaths</code> | |||
</p> | |||
{{Input|<syntaxhighlight lang="QML" line> | |||
import QtQuick 2.0 | |||
import org.kde.plasma.core 2.0 as PlasmaCore | |||
import org.kde.latte 0.2 as Latte | |||
import org.kde.latte.components 1.0 as LatteComponents | |||
LatteComponents.IndicatorItem { | |||
id: root | |||
svgImagePaths: [‘widgets/panel-background’, ‘../icons/separator.svg’] | |||
... | |||
PlasmaCore.SvgItem { | |||
id: panelBackgroundSvgItem | |||
svg: indicator.resources.svgs[0] | |||
} | |||
... | |||
} | |||
</syntaxhighlight>}} | |||
---- | |||
=== User Settings Config File === | |||
<p align='justify'> | |||
If you are familiar with plasma applets settings xml files then you are going to feel right at home as indicators follow the same xml scheme. | |||
</p> | |||
<p align='justify'> | |||
Example of Latte indicator '''main.xml''' file: | |||
</p> | |||
<pre> | |||
<?xml version="1.0" encoding="UTF-8"?> | |||
<kcfg xmlns="http://www.kde.org/standards/kcfg/1.0" | |||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | |||
xsi:schemaLocation="http://www.kde.org/standards/kcfg/1.0 | |||
http://www.kde.org/standards/kcfg/1.0/kcfg.xsd" > | |||
<kcfgfile name=""/> | |||
<group name="General"> | |||
<entry name="activeStyle" type="Enum"> | |||
<label>Active indicator style</label> | |||
<choices> | |||
<choice name="Line"/> | |||
<choice name="Dot"/> | |||
</choices> | |||
<default>0</default> | |||
</entry> | |||
<entry name="glowEnabled" type="Bool"> | |||
<default>false</default> | |||
</entry> | |||
<entry name="glowApplyTo" type="Enum"> | |||
<label>Glow for active indicators</label> | |||
<choices> | |||
<choice name="None"/> | |||
<choice name="OnActive"/> | |||
<choice name="All"/> | |||
</choices> | |||
<default>2</default> | |||
</entry> | |||
<entry name="glow3D" type="Bool"> | |||
<default>true</default> | |||
</entry> | |||
<entry name="glowOpacity" type="Double"> | |||
<default>0.35</default> | |||
</entry> | |||
<entry name="reversed" type="Bool"> | |||
<default>false</default> | |||
</entry> | |||
</group> | |||
</kcfg> | |||
</pre> | |||
=== Configuration UI === | |||
<p align='justify'> | |||
If you want the users to be able to adjust settings from config xml file then you need to provide a qml interface which is going to be loaded in Latte → Effects page when your indicator is active. As such it is proposed to try to use QML components that dont break consistency and behavior of Latte Settings different pages. LatteComponents are used in most settings pages but nothing forbids you to choose something else. The configuration ui does not belong to any applet or task and as such it provides different options through two very important objects '''indicator''' and '''dialog'''. | |||
</p> | |||
---- | |||
===== indicator <properties - in configuration user interface> ===== | |||
<p align='justify'> | |||
<code><strong>latteTasksArePresent</strong> [bool] (readonly) </code> : <code>true</code> when the dock or panel contains a Latte Tasks plasmoid. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>configuration</strong> [QtObject] (readonly)</code> : object to access the user settings specified at the main.xml file | |||
</p> | |||
<p align='justify'> | |||
<strong>Important: all other properties provided by ''indicator'' object when is present in a task or applet are not provided here.</strong> | |||
</p> | |||
<br> | |||
---- | |||
===== dialog <properties - in configuration user interface>===== | |||
<p align='justify'> | |||
Through '''dialog''' object the Indicator's configuration user interface can adjust its layout at the settings popup window flexible design when appropriate. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>inConfigureAppletsMode</strong> [bool] (readonly) </code> : <code>true</code> when the user is inConfigureApplets edit mode in contrast to liveEditing mode. | |||
</p> | |||
<p align='justify'> | |||
<code><strong>optionsWidth</strong> [int] (readonly)</code> : the settings popup window current width that can be used from options. | |||
</p> | |||
<br> | |||
<p align='justify'> | |||
Example from Plasma indicator: | |||
</p> | |||
{{Input|<syntaxhighlight lang="QML" line> | |||
import QtQuick 2.7 | |||
import QtQuick.Controls 1.4 | |||
import QtQuick.Layouts 1.3 | |||
import org.kde.plasma.plasmoid 2.0 | |||
import org.kde.plasma.core 2.0 as PlasmaCore | |||
import org.kde.latte 0.2 as Latte | |||
import org.kde.latte.components 1.0 as LatteComponents | |||
ColumnLayout { | |||
id: root | |||
Layout.fillWidth: true | |||
LatteComponents.CheckBoxesColumn { | |||
Layout.topMargin: 1.5 * units.smallSpacing | |||
LatteComponents.CheckBox { | |||
Layout.maximumWidth: dialog.optionsWidth | |||
text: i18n("Reverse indicator style") | |||
checked: indicator.configuration.reversed | |||
onClicked: { | |||
indicator.configuration.reversed = !indicator.configuration.reversed; | |||
} | |||
} | |||
LatteComponents.CheckBox { | |||
Layout.maximumWidth: dialog.optionsWidth | |||
text: i18n("Growing circle animation when clicked") | |||
checked: indicator.configuration.clickedAnimationEnabled | |||
onClicked: { | |||
indicator.configuration.clickedAnimationEnabled = !indicator.configuration.clickedAnimationEnabled; | |||
} | |||
} | |||
} | |||
} | |||
</syntaxhighlight>}} | |||
---- | |||
===Indicator Examples === | |||
<strong> | |||
[https://invent.kde.org/plasma/latte-dock/-/tree/master/indicators/org.kde.latte.plasma Plasma Indicator]<br> | |||
[https://invent.kde.org/plasma/latte-dock/-/tree/master/indicators/default Latte Official Indicator]<br> | |||
[https://github.com/psifidotos/latte-indicator-unity Unity Indicator]<br> | |||
[https://github.com/psifidotos/latte-indicator-dashtopanel DashToPanel Indicator]<br> | |||
</strong> |
Latest revision as of 13:06, 4 July 2022
Technical Details
This is an effort to expose some of the Latte tricks and APIs that developers can use in order to leverage Latte Dock capabilities. Two major sections are currently provided, Applets and Indicators. In the Applets section you will understand how a Plasma QML applet can obtain information from Latte and how it can be implemented properly in order to work just fine with parabolic effect. In Indicators section you will learn how you can create your own Latte Indicators.
NOTE: All mentioned APIs are provided since [v0.9.0] and if new properties or functions are added; a relevant reference will be presented, for example [v0.9.4]
Applets
Can a Plasma Applet access Latte Information?
Most definitely! This is very simple. The only thing you need to add in your applet main QML file is:
import QtQuick 2.0 Item { id: root //! Latte Connection property Item latteBridge: null //! }
The latteBridge object is assigned from Latte when applet is loaded and it is the “ONE to rule them ALL” way to communicate with Latte. Important thing to mention is that if your applet is using both Compact and FullRepresentation(s) then the relevant code should be placed in CompactRepresentation.
import QtQuick 2.0 Item { id: root Plasmoid.compactRepresentation: Item { //! Latte Connection property Item latteBridge: null //! } }
After adding latteBridge property it is straightforward to identify when your applet is inside a Latte panel/dock or not with:
readonly property bool inLatte: latteBridge !== null
Can a plasma applet behave properly with parabolic effect?
Parabolic effect is not working properly when applets provide different lengths. Applets with large lengths decrease the animations speed and the applets with small lengths increase it. The best way for parabolic effect to work is for all applets to provide a squared layout that does not update its content positioning when zoomed. In order to make things easy for developers Latte can provide you with the best layout to achieve this without needing from you to make any calculations. To do this, you need to set it up as such:
import QtQuick 2.0 import org.kde.plasma.plasmoid 2.0 Item { id: root Layout.minimumWidth: inLatte && isHorizontal ? -1 : [plasma case] Layout.preferredWidth: inLatte && isHorizontal ? -1 : [plasma case] Layout.maximumWidth: inLatte && isHorizontal ? -1 : [plasma case] Layout.minimumHeight: inLatte && !isHorizontal ? -1 : [plasma case] Layout.preferredHeight: inLatte && !isHorizontal ? -1 : [plasma case] Layout.maximumHeight: inLatte && !isHorizontal ? -1 : [plasma case] readonly property bool isHorizontal: plasmoid.formFactor === PlasmaCore.Types.Horizontal //! Latte Connection property Item latteBridge: null readonly property bool inLatte: latteBridge !== null //! }
In the above example you can see that when the applet is not providing any information for its Layout [-1
case] then Latte has the freedom to set it in the best appropriate.
latteBridge
latteBridge <properties>
After the latteBridge Item has been set from Latte you can access the following properties:
version[int] (readonly)
: Shows the latteBridge version which coincides with the Latte Dock version. For example, Latte 0.9.0 produces a unique integer that can be used for numeric comparisons for greater than, lower than etc. If you want to make a version comparison, you can try the following in your code.
latteBridge.version >= latteBridge.actions.version(0,9,2)
applyPalette [bool] (readonly)
: true
when Latte is advising the applet to use the Latte colors palette in order to draw its contents with proper contrast
inEditMode [bool] (readonly)
: true
when Latte is in Edit Mode
inPlasmaPanelStyle [bool] (readonly)
: true
when Latte behaves as a Plasma Panel concerning external shadow rendering, transparency levels, etc.
parabolicEffectEnabled [bool] (readonly)
: true
when Latte Parabolic Effect is enabled.
iconSize[int] (readonly)
: the current icon size used for all applets in the containment where this applet is present
screenEdgeMargin [int] (readonly)
[v0.10] : used in floating docks and panels to specify how many pixels is the gap between the dock and the screen edge
maxZoomFactor[real] (readonly)
: the current zoom factor with values from 1.0 to 2.0
1 = No Scaling 1.2 = Scale to 120% 2 = Scale to 200%
actions [QtObject] (readonly)
: Used to pass information to Latte concerning your applet requirements. This is explained in detail at latteBridge.actions section
palette [SchemeColors *QtObject] (readonly)
: the current Latte color scheme palette used. Properties available for color scheme object are provided through schemecolors.h
windowsTracker [QtObject] (readonly)
: all windows tracking information that can be used from applets to update their contents. This is explained in detail in the latteBridge.windowsTracker section. Important:You need to enable windowsTrackingEnabled
first through latteBridge.actions object.
latteBridge <signals>
broadcasted(string action, variant value)
Applets in Latte can create their own protocols in order to communicate with their neighbour applets. When such signal is received from your applet it means that some other applet is requesting from you to execute “action” with parameter “value”. A good example are the Window Title and Window AppMenu applets. These applets need to communicate with each other in order to hide or show themselves in Unity Mode. Window Title is shown when there is no mouse hovering and Window AppMenu when there is one. All this is orchestrated through applets without Latte taking any responsibility except broadcasting the requested actions to appropriate recipients. How applets are sending such actions through latteBridge.actions is explained in detail at the relevant section. In you want to track this broadcasted signal you can use:
import QtQuick 2.0 Item { id: root //! Latte Connection property Item latteBridge: null readonly property bool inLatte: latteBridge !== null //! Connections { target: latteBridge onBroadcasted: { if (action === "actionname1") { //! your code here } else if (action === "actionname2") { //! your code here } } } }
latteBridge.actions <object>
Through actions an applet can send information to Latte and other neighbour applets. The following functions can be used to accomplish this:
setProperty(appletId, parameter, value)
Applets can set their characteristics and demands through this function. For example when an applet wants to disable the Active Indicator in Latte Side can use:
latteBridge.actions.setProperty(plasmoid.id, “activeIndicatorEnabled”, false);
or when it wants to disable the Latte Side Coloring that overlays the applets monochromatic in Smart Coloring mode then it can use:
latteBridge.actions.setProperty(plasmoid.id, “latteSideColoringEnabled”, false);
getProperty(appletId, parameter)
Applets can read the current assigned characteristics through this function:
var indicatorEnabled = latteBridge.actions.readProperty(plasmoid.id, “activeIndicatorEnabled”);
broadcastToApplet(receiverPluginId, action, value)
Applets can communicate with other neighbour applets. For example when Window Title is informing AppMenu that needs to hide itself it sends:
latteBridge.actions.broadcastToApplet(“ord.kde.windowappmenu”,”setVisible”, false);
version(major, minor, patch)
It is used to produce a unique integer based on major, minor and patch versions in order to compare different versions, for example:
latteBridge.version >= latteBridge.actions.version(0,9,2)
latteBridge.actions <applet characteristics>
Applets can have different demands and characteristics that can be set and accessed through setProperty and getProperty functions.
activeIndicatorEnabled [bool]
: false
means Latte will not draw any indicator for this applet, a good example being the Global Menu plasmoid.
latteIconOverlayEnabled [bool]
: false
means Latte will never try to identify the central icon used in order to make this applet draw itself correctly with parabolic effect. Most applets are using PlasmaCore.IconItem in order to draw the CompactRepresentation icon when they are in a panel, but plasma iconitem does not play nice with parabolic effect. This is why Latte is trying to handle the case and take resposibility by hiding the PlasmaCore.IconItem and draw a LatteComponents.IconItem instead. If you dont want this to happen then you must set this property to false
.
latteSideColoringEnabled [bool]
: false
means Latte will never overlay any color over this applet because applet takes responsibility for painting itself at all cases.
lengthMarginsEnabled [bool]
: false
means means Latte will not draw any margins around this applet comparing to its neighbours. Good example is the spacer plasmoid that in panel mode does not need any extra margins around it.
parabolicEffectLocked [bool]
: true
means Latte must disable parabolic effect for that specific applet.
windowsTrackingEnabled [bool]
: true
means Latte must provide a latteBridge.windowsTracker object through latteBridge
screenEdgeMarginSupported [bool]
[0.10] : true
means this applet can handle screen gaps from floating windows on its own
latteBridge.windowsTracker
WindowTracker provides two major objects currentScreen and allScreens in order to filter windows and provide window states information.
latteBridge.windowsTracker.currentScreen <properties>
activeWindowMaximized [bool] (readonly)
: true
when there is an active and at the same time maximized window in current screen
activeWindowTouching [bool] (readonly)
: true
when there is an active window in current screen and that window is also touching the Latte dock/panel.
existsWindowActive [bool] (readonly)
: true
when there is an active window in current screen.
existsWindowMaximized [bool] (readonly)
: true
when there is a maximized window in current screen independent if it is active or not.
existsWindowTouching [bool] (readonly)
: true
where there is a window in current screen that is touching the Latte dock/panel independent if it is active or not
activeWindowScheme[SchemeColors *QtObject] (readonly)
: color scheme object for window that is touching Latte dock/panel in current screen and null
if there is none. Properties provided by scheme objects can be found at schemecolors.h
lastActiveWindow[LastActiveWindow *QtObject] (readonly)
: last active window that is still present and shown in the current screen. Properties provided from lastActiveWindow can be found at lastactivewindow.h
latteBridge.windowTracker.allScreens <properties>
activeWindowMaximized [bool] (readonly)
: true
when there is an active maximized window in any screen.
existsWindowActive [bool] (readonly)
: true
when there is an active window in any screen.
existsWindowMaximized [bool] (readonly)
: true
when there is a maximized window in any screen independent if it is active or not.
activeWindowScheme[SchemeColors *QtObject] (readonly)
: color scheme object for active window in any screen, and null
if there is none. Properties available for color scheme objects are provided through schemecolors.h
lastActiveWindow[LastActiveWindow *QtObject] (readonly)
: last active window that is still present and shown in any screen.Properties provided from lastActiveWindow can be found at lastactivewindow.h
Applet Examples
Latte Separator
Latte Spacer
Window Title Applet
Window Buttons Applet
Window AppMenu Applet
Indicators
Introduction
In Latte v0.9 every indicator style has its own standalone qml implementation that can be found in its own package, just like Plasma qml-only applets. In that way every indicator style can support its own specific user settings and also abstract its implementation from the main Latte development. Online Indicators can be found at the kde store and can be installed through Latte → Effects page without needing from the users any special actions to accomplish the task.
Package Structure
The Indicator package should have the following structure:
metadata.desktop [required] package/ui/main.qml [required] package/config/main.xml [optional] package/config/config.qml [optional]
Metadata.desktop
Every indicator needs a desktop file in order to tell Latte where to find its implementation and what its author details are. The format is as such:
[Desktop Entry] Name=Latte Comment=Latte default indicator Encoding=UTF-8 Type=Service [required] Icon=latte-dock X-Plasma-API=declarativeappletscript [required] X-KDE-ServiceTypes=Latte/Indicator [required] X-Latte-MainScript=ui/main.qml [required] X-Latte-ConfigUi=config/config.qml [optional] X-Latte-ConfigXml=config/main.xml [optional] X-KDE-PluginInfo-Author=KDE Awesome Developer [email protected] X-KDE-PluginInfo-Name=org.kde.awesome.custom X-KDE-PluginInfo-Version=0.1 X-KDE-PluginInfo-Category=Latte Indicator X-KDE-PluginInfo-License=GPL v2+ X-KDE-PluginInfo-EnabledByDefault=true
X-Plasma-API
: it is required because it defines a qml-only plugin
X-KDE-ServiceTypes
: it is required with value Latte/Indicator
otherwise the indicator can not be installed and loaded
X-Latte-MainScript
: it is required and defines the main qml file for the indicator implementation
X-Latte-ConfigXml
: defines the xml settings that are going to be used from indicator implementation and user settings. It is optional and a package may not include it
X-Latte-ConfigUI
: defines the qml settings user interface. It is optional and is provided only when the indicator has settings that the user can choose from in order to adjust the indicate apprearance and behaviour
QML Implementation
package/ui/main.qml
Every indicator's main qml file must use LatteComponents.IndicatorItem
at its root
import QtQuick 2.0 import org.kde.latte 0.2 as Latte import org.kde.latte.components 1.0 as LatteComponents LatteComponents.IndicatorItem { id: root providesFrontLayer: false providesHoveredAnimation: false ... }
The LatteComponents.IndicatorItem
provides options to inform Latte what requirements and capabilities this indicator provides in order to appear, function and behave properly. All IndicatorItem options are [optional]:
LatteComponents.IndicatorItem [properties]
needsIconColors [bool]
: true
when current icon main colors are needed. For example Unity Indicator draws its background and glow based on current icon colors.
needsMouseEventCoordinates [bool]
: true
when mouse event coordinates are needed. An example is click animation in android style from Plasma Indicator.
providesFrontLayer [bool]
: true
when a front layer is provided in order to draw contents above the current item/icon.
providesHoveredAnimation [bool]
: true
if Latte built-in hovered animation must be disabled
providesClickedAnimation [bool]
: true
if Latte built-in clicked animation must be disabled
providesInAttentionAnimation [bool]
[v0.10.4] : true
if Latte built-in inattention animation must be disabled
providesTaskLauncherAnimation [bool]
[v0.10.4] : true
if Latte built-in bouncing task launcher animation must be disabled
providesGroupedWindowAddedAnimation [bool]
[v0.10.4] : true
if Latte built-in window added in group animation must be disabled
providesGroupedWindowRemovedAnimation [bool]
[v0.10.4] : true
if Latte built-in window removed from group animation must be disabled
enabledForApplets [bool]
[v0.10.0] : true
if indicator should be drawn also for applets and false
if it should not.
extraMaskThickness [int]
: How many pixels are needed above the indicator in order to be drawn correctly. An example is the Latte indicator in reverse mode that supports glowing, but that glow is drawn externally. Latte must be informed for this in order to not visually subtract that glow.
minThicknessPadding [real]
: Minimum thickness padding that is needed from this indicator
minThicknessPadding: 0.2 // 20% of current icon size
lengthPadding [real]
[v0.10.0] : Default length padding that should be applied both for tasks and applets.
lengthPadding: 0.2 // 20% of current icon size
appletLengthPadding [real]
[v0.9.2] : If enabled then applets should use different length padding value compared to tasks.
appletLengthPadding: -1 // [disabled] use general length paddding appletLengthPadding: 0.2 // 20% of current icon size
backgroundCornerMargin [real]
[v0.10.3] : How far the indicator should be from the edge of the panel background. It is totally related to panel background roundness and specifies in percentage how much of that roundness is applied for the corner margin.
backgroundCornerMargin: 1.00 // 100% of the panel background roundness;the indicator is never drawn inside the roundness backgroundCornerMargin: 0.50 // 50% of the panel background roundness;the indicator is using only half of background roundness
svgImagePaths [Array of strings]
: Plasma::SVG files that must be loaded from Latte in order to avoid high memory consumption. An example could be:
svgImagePaths: [‘widgets/panel-background’, ‘../icons/separator.svg’]
In this example first svg icon is provided from current plasma theme and second is located relevant to package/ui
folder.
Tasks/Applets Information
As long as IndicatorItem has been set for the main qml file then the entire indicator qml implementation gains two different objects ( level
and indicator
) in order to access tasks/applets and general information.
level <properties>
isBackground [bool] (readonly)
: true
when the indicator background layer must be painted which is below the current icon/applet.
isForeground [bool] (readonly)
: true
when the indicator foreground layer needs to be painted which is above the current icon/applet
requested.iconOffsetX [int] [v0.9.2]
: adjust the icon placement for x axis in pixels
requested.iconOffsetY [int] [v0.9.2]
: adjust the icon placement for y axis in pixels
requested.iconOpacity [real] [v0.10.4]
: adjust the icon opacity
requested.iconRotation [real] [v0.10.4]
: adjust the icon rotation
requested.iconScale [real] [v0.10.4]
: adjust the icon scale value
requested.iconTransformOrigin [QML TranformOrigin] [v0.10.4]
: adjust the icon qml transform origin
level <signals>
mousePressed(int x, int y, int button)
: can be tracked when needMouseEventSignals
property has been enabled in IndicatorItem in order to get mouse x,y coordinates and which mouse button was released.
indicator <properties>
isTask [bool] (readonly)
: true
when main item is actually a task
isApplet [bool]
: true
when main item is actually an applet
isEmptySpace [bool]
[v0.9.3] : true
when the indicator has been loaded at the dock/panel background in order to trigger visual feedback for empty areas. A good example for its use is when the Plasma indicator style is creating android-like click animations for empty areas in a panel.
isLauncher [bool] (readonly)
: true
when main item is a task in launcher state
isStartup [bool] (readonly)
: true
when main item is a task in startup state
isWindow [bool] (readonly)
: true
when main item is a task in window state
isActive [bool] (readonly)
: true
when main item is active
isGroup [bool] (readonly)
: true
when main item is a group of tasks
isHovered [bool] (readonly)
: true
when main item is hovered
isMinimized [bool] (readonly)
: true
when main item is a task in minimized state
isPressed [bool] (readonly)
: true
when main item is pressed
inAttention [bool] (readonly)
: true
when main item requires attention
inRemoving [bool] (readonly)
: true
when main item is in remove stage
isSquare [bool] (readonly)
: true
when main item has a squared layout
hasActive [bool] (readonly)
: true
when a group of tasks has an active item
hasMinimized [bool] (readonly)
: true
when a group of tasks has at least one minimized window
hasShown [bool] (readonly)
: true
when a group of tasks has at least one shown (not minimimed) window
windowsCount [int] (readonly)
: how many windows exist in a grouped task
windowsMinimizedCount [int] (readonly)
: how many minimized windows exist in a grouped task
currentIconSize [int] (readonly)
: current icon size used for the entire dock or panel
maxIconSize [int] (readonly)
: maximum icon size that can occur from this dock or panel
scaleFactor [real] (readonly)
: current scale factor for this item with values from 1.0 to 2.0
1 = Item is not zoomed 1.2 = Item is zoomed by 20% 2 = Item is zoomed by 100%
panelOpacity [real] (readonly)
: current panel background opacity
shadowColor [color] (readonly)
: current shadow color used for all items
animationsEnabled [bool] (readonly)
: true
when animations are enabled
durationTime [real] (readonly)
: current duration time for animation. It is a multiplier that can be used for animations in order to respect user preference concerning animations speed
progressVisible [bool] (readonly)
[v0.9.2] : true
when task progress in active
progress [real] (readonly)
[v0.9.2] : current progress percentage
0 = 0% progress 45.2 = 45.2% progress
screenEdgeMargin [int] (readonly)
[v0.10] : used in floating docks and panels to specify how many pixels is the gap between the dock and the screen edge
iconBackgroundColor [color] (readonly)
: main background color produced from the current icon. [requires from you to have set needsIconColors to true
at main IndicatorItem]
iconGlowColor [color] (readonly)
: main glow color produced from the current icon. [requires from you to have set needsIconColors to true
at main IndicatorItem]
palette [QtObject] (readonly)
: current colors palette used. Provides backgroundColor, textColor etc. Take note that this object provides also a scheme string pointing absolute path of the current scheme file. A good example for indicator.scheme is the Window Buttons applet that forwards that information to KDecoration2 in order for plasma window buttons to be drawn. Example code:
property color backColor: indicator.palette.backgroundColor
configuration [QtObject] (readonly)
: object to access the user settings specified at the main.xml file
resources [QtObject] (readonly)
: object to access memory efficient produced resources such as plasma svgs
resources.svgs [Array] (readonly)
: object to access memory efficient produced Plasma/Svgs specified at IndicatorItem.svgImagePaths
import QtQuick 2.0 import org.kde.plasma.core 2.0 as PlasmaCore import org.kde.latte 0.2 as Latte import org.kde.latte.components 1.0 as LatteComponents LatteComponents.IndicatorItem { id: root svgImagePaths: [‘widgets/panel-background’, ‘../icons/separator.svg’] ... PlasmaCore.SvgItem { id: panelBackgroundSvgItem svg: indicator.resources.svgs[0] } ... }
User Settings Config File
If you are familiar with plasma applets settings xml files then you are going to feel right at home as indicators follow the same xml scheme.
Example of Latte indicator main.xml file:
<?xml version="1.0" encoding="UTF-8"?> <kcfg xmlns="http://www.kde.org/standards/kcfg/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.kde.org/standards/kcfg/1.0 http://www.kde.org/standards/kcfg/1.0/kcfg.xsd" > <kcfgfile name=""/> <group name="General"> <entry name="activeStyle" type="Enum"> <label>Active indicator style</label> <choices> <choice name="Line"/> <choice name="Dot"/> </choices> <default>0</default> </entry> <entry name="glowEnabled" type="Bool"> <default>false</default> </entry> <entry name="glowApplyTo" type="Enum"> <label>Glow for active indicators</label> <choices> <choice name="None"/> <choice name="OnActive"/> <choice name="All"/> </choices> <default>2</default> </entry> <entry name="glow3D" type="Bool"> <default>true</default> </entry> <entry name="glowOpacity" type="Double"> <default>0.35</default> </entry> <entry name="reversed" type="Bool"> <default>false</default> </entry> </group> </kcfg>
Configuration UI
If you want the users to be able to adjust settings from config xml file then you need to provide a qml interface which is going to be loaded in Latte → Effects page when your indicator is active. As such it is proposed to try to use QML components that dont break consistency and behavior of Latte Settings different pages. LatteComponents are used in most settings pages but nothing forbids you to choose something else. The configuration ui does not belong to any applet or task and as such it provides different options through two very important objects indicator and dialog.
indicator <properties - in configuration user interface>
latteTasksArePresent [bool] (readonly)
: true
when the dock or panel contains a Latte Tasks plasmoid.
configuration [QtObject] (readonly)
: object to access the user settings specified at the main.xml file
Important: all other properties provided by indicator object when is present in a task or applet are not provided here.
dialog <properties - in configuration user interface>
Through dialog object the Indicator's configuration user interface can adjust its layout at the settings popup window flexible design when appropriate.
inConfigureAppletsMode [bool] (readonly)
: true
when the user is inConfigureApplets edit mode in contrast to liveEditing mode.
optionsWidth [int] (readonly)
: the settings popup window current width that can be used from options.
Example from Plasma indicator:
import QtQuick 2.7 import QtQuick.Controls 1.4 import QtQuick.Layouts 1.3 import org.kde.plasma.plasmoid 2.0 import org.kde.plasma.core 2.0 as PlasmaCore import org.kde.latte 0.2 as Latte import org.kde.latte.components 1.0 as LatteComponents ColumnLayout { id: root Layout.fillWidth: true LatteComponents.CheckBoxesColumn { Layout.topMargin: 1.5 * units.smallSpacing LatteComponents.CheckBox { Layout.maximumWidth: dialog.optionsWidth text: i18n("Reverse indicator style") checked: indicator.configuration.reversed onClicked: { indicator.configuration.reversed = !indicator.configuration.reversed; } } LatteComponents.CheckBox { Layout.maximumWidth: dialog.optionsWidth text: i18n("Growing circle animation when clicked") checked: indicator.configuration.clickedAnimationEnabled onClicked: { indicator.configuration.clickedAnimationEnabled = !indicator.configuration.clickedAnimationEnabled; } } } }
Indicator Examples
Plasma Indicator
Latte Official Indicator
Unity Indicator
DashToPanel Indicator