LatteDock

Purpose of this page

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 APIs are provided since Latte [v0.9.0] and if a new property or function is added then in that case there will be a tag mentioning when it was introduced 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 QtObject 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 QtObject latteBridge: null
        //!
    }
}

After adding latteBridge property it is straightforward to identify when your applet is inside a Latte panel/dock OR in a Plasma panel with:

readonly property bool inLatte: latteBridge !== null

Can a plasma applet behave properly with parabolic effect?

Parabolic effect is not working at present 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 QtObject 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 Object has been set from Latte you can access the following.

latteBrige <properties>

version[int] (readonly): latteBridge Version whhich is based on Latte 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.makeVersion(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 behaves as a Plasma Panel concerning external shadow rendering, transparency levels, etc.

parabolicEffectEnabled[bool] (readonly): true when Latte Parabolid Effect is enabled.

iconSize[int] (readonly): the current icon size used for all appletsin the containment this applet is present

maxZoomFactor[real] (readonly): the current zoom factor with values from 1.0 to 2.0

1 – no zoom
1.2 – zoom for 20%
2 – zoom for 100%

actions [QtObject] (readonly): you can use it to pass information to Latte concerning your applet requirements. This is explained in detail in the latteBridge.actions section

pallete [SchemeColors *QtObject] (readonly): the current Latte color scheme palette used. Properties available for color scheme object are provided through <a href="https://phabricator.kde.org/source/latte-dock/browse/master/app/wm/schemecolors.h">https://phabricator.kde.org/source/latte-dock/browse/master/app/wm/schemecolors.h</a>

windowsTracker [QtObject] (readonly): all windows tracking information that can be used from applets to update their contents. It is explained in detail in the latteBridge.windowsTracker section. Important: You need to enable windowsTrackingEnabled first though latteBridge.actions object.

LatteBridge <signals>

broadcasted(string action, variant value)

Applets in Latte can create their own protocols in order to communicate with other applets. When such signal is received it means that some applet is requesting from you to make “action” with parameter “value” . A good example for this 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 only to the correct receivers. How applets are sending such actions through latteBridge.actions is explained better at the relevant section. If you want to track this signal you can use:

import QtQuick 2.0

Item {
    id: root

    //! Latte Connection
    property QtObject 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>

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 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);