rename PanelBox to Background.MultiLayered

--much better name and also describes how Background
really works and draws its content

containment/package/contents/ui/VisibilityManager.qml

@@ -236,7 +236,7 @@ Item{
             var isTouchingTopScreenEdge = (latteView.y === latteView.screenGeometry.y);
             var hasTopBorder = ((latteView.effects && (latteView.effects.enabledBorders & PlasmaCore.FrameSvg.TopBorder)) > 0);
 
-            return root.isVertical && !latteView.visibility.isHidden && !isTouchingTopScreenEdge && !hasTopBorder && panelBoxBackground.isShown;
+            return root.isVertical && !latteView.visibility.isHidden && !isTouchingTopScreenEdge && !hasTopBorder && background.isShown;
         }
     }
 
@@ -251,7 +251,7 @@ Item{
 
             var hasBottomBorder = ((latteView.effects && (latteView.effects.enabledBorders & PlasmaCore.FrameSvg.BottomBorder)) > 0);
 
-            return root.isVertical && !latteView.visibility.isHidden && !isTouchingBottomScreenEdge && !hasBottomBorder && panelBoxBackground.isShown;
+            return root.isVertical && !latteView.visibility.isHidden && !isTouchingBottomScreenEdge && !hasBottomBorder && background.isShown;
         }
     }
 

containment/package/contents/ui/background/MultiLayered.qml

@@ -31,11 +31,14 @@ import org.kde.kquickcontrolsaddons 2.0
 
 import org.kde.latte.core 0.2 as LatteCore
 
-import "colorizer" as Colorizer
+import "../colorizer" as Colorizer
 
 Item{
     id:barLine
 
+    //! Layer 0: Multi-Layer container in order to provide a consistent final element that acts
+    //! as a single entity/background
+
     width: root.isHorizontal ? panelWidth : smallSize
     height: root.isVertical ? panelHeight : smallSize
 
@@ -46,10 +49,7 @@ Item{
     property int animationTime: 6*animations.speedFactor.current*animations.duration.small
 
     property int screenEdgeMargin: root.screenEdgeMarginEnabled ? metrics.margin.screenEdge - shadowsSvgItem.screenEdgeShadow : 0
-
-    property int lengthMargins: {
-        return root.isVertical ? shadowsSvgItem.marginsHeight : shadowsSvgItem.marginsWidth
-    }
+    property int lengthMargins: root.isVertical ? shadowsSvgItem.marginsHeight : shadowsSvgItem.marginsWidth
 
     property int panelWidth: {
         if (root.behaveAsPlasmaPanel && LatteCore.WindowSystem.compositingActive && !root.editMode) {
@@ -123,25 +123,9 @@ Item{
     onXChanged: solidBackground.updateEffectsArea();
     onYChanged: solidBackground.updateEffectsArea();
 
-    /// plasmoid's default panel
-    /*  BorderImage{
-            anchors.fill:parent
-            source: "../images/panel-west.png"
-            border { left:8; right:8; top:8; bottom:8 }
-
-            opacity: (!root.useThemePanel) ? 1 : 0
-
-            visible: (opacity == 0) ? false : true
-
-            horizontalTileMode: BorderImage.Stretch
-            verticalTileMode: BorderImage.Stretch
-
-            Behavior on opacity{
-                NumberAnimation { duration: 200 }
-            }
-        }*/
-
-    /// the current theme's panel
+    //! Layer 1: Shadows that are drawn around the background but always inside the View window (these are internal drawn shadows).
+    //!          When the container has chosen external shadows (these are shadows that are drawn out of the View window from the compositor)
+    //!          in such case the internal drawn shadows are NOT drawn at all.
     PlasmaCore.FrameSvgItem{
         id: shadowsSvgItem
 
@@ -293,7 +277,8 @@ Item{
             value: root.isVertical ? shadowsSvgItem.marginsHeight : shadowsSvgItem.marginsWidth
         }
 
-        //! Show a fake blurness under panel background for editMode visual feedback
+
+        //! Layer 2: Draw fake blurness under background when the user is INEDITMODE state for visual feedback
         Loader {
             anchors.fill: solidBackground
             active: editModeVisual.inEditMode && root.userShowPanelBackground && plasmoid.configuration.blurEnabled
@@ -345,7 +330,9 @@ Item{
             }
         }
 
-        //! This is used to provide real solidness
+        //! Layer 3: Provide visual solidness. Plasma themes by design may provide a panel-background svg that is not
+        //!          solid. That means that user can not gain full solidness in such cases. This layer is responsible
+        //!          to solve the previous mentioned plasma theme limitation.
         Colorizer.CustomBackground {
             id: backgroundLowestRectangle
             anchors.fill: solidBackground
@@ -368,6 +355,10 @@ Item{
             }
         }
 
+        //! Layer 4: Original Plasma Theme "panel-background" svg. It is used for calculations and also to draw
+        //!          the original background when to special settings and options exist from the user. It is also
+        //!          doing one very important job which is to calculate the Effects Rectangle which is used from
+        //!          the compositor to provide blurriness and from Mask calculations to provide the View Local Geometry
         PlasmaCore.FrameSvgItem{
             id: solidBackground
             anchors.leftMargin: LatteCore.WindowSystem.compositingActive ? shadowsSvgItem.margins.left : 0
@@ -590,6 +581,8 @@ Item{
             }
         }
 
+        //! Layer 5: Plasma theme design does not provide a way to colorize the background. This layer
+        //!          solves this by providing a custom background layer that respects the Colorizer palette
         Colorizer.CustomBackground {
             id: overlayedBackground
             anchors.fill: solidBackground
@@ -663,7 +656,9 @@ Item{
             }
         }
 
-        //! Outline drawing
+        //! Layer 6: Plasma theme design does not provide a way to draw background outline on demand. This layer
+        //!          solves this by providing a custom background layer that only draws an outline on top of all
+        //!          previous layers
         Loader{
             anchors.fill: solidBackground
             active: root.panelOutline && !(root.hasExpandedApplet && root.plasmaBackgroundForPopups)

containment/package/contents/ui/main.qml

@@ -40,6 +40,7 @@ import "colorizer" as Colorizer
 import "editmode" as EditMode
 import "indicators" as Indicators
 import "layouts" as Layouts
+import "./background" as Background
 import "../code/LayoutManager.js" as LayoutManager
 
 Item {
@@ -272,7 +273,7 @@ Item {
     property int scrollAction: plasmoid.configuration.scrollAction
 
     property bool panelOutline: plasmoid.configuration.panelOutline
-    property int panelEdgeSpacing: Math.max(panelBoxBackground.lengthMargins, 1.5*appShadowSize)
+    property int panelEdgeSpacing: Math.max(background.lengthMargins, 1.5*appShadowSize)
     property int panelTransparency: plasmoid.configuration.panelTransparency //user set
     property int currentPanelTransparency: 0 //application override
 
@@ -333,7 +334,7 @@ Item {
     property string appShadowColor: "#" + decimalToHex(appShadowOpacity) + appChosenShadowColor
     property string appShadowColorSolid: "#" + appChosenShadowColor
 
-    property int totalPanelEdgeSpacing: 0 //this is set by PanelBox
+    property int totalPanelEdgeSpacing: 0 //this is set by Background
     property int offset: {
         if (behaveAsPlasmaPanel) {
             return 0;
@@ -353,7 +354,7 @@ Item {
     property int realPanelSize: 0
     property int realPanelLength: 0
     property int realPanelThickness: 0
-    //this is set by the PanelBox
+    //this is set by the Background
     property int panelThickMarginBase: 0
     property int panelThickMarginHigh: 0
     property int panelMarginLength: 0
@@ -409,6 +410,7 @@ Item {
     property Item latteApplet
 
     readonly property alias animations: _animations
+    readonly property alias background: _background
     readonly property alias autosize: _autosize
     readonly property alias indexer: _indexer
     readonly property alias indicatorsManager: indicators
@@ -1476,11 +1478,10 @@ Item {
                                                    || (foreDropArea.dragInfo.computationsAreValid && !root.dragInfo.isPlasmoid && !root.dragInfo.onlyLaunchers))
 
         Item{
-            id: panelBox
             anchors.fill: layoutsContainer
 
-            PanelBox{
-                id: panelBoxBackground
+            Background.MultiLayered{
+                id: _background
             }
         }