add effects guide #10

soramanew · 2025-07-01T13:43:45Z

Adds a page in the guide for how to use QtQuick.Effects and also how to migrate from Qt5Compat.GraphicalEffects to the QtQuick.Effects module.

HigherOrderLogic · 2025-07-01T15:51:53Z

I dont know if there is any between specifying source: comp vs layer.effect: MultiEffect { ... } but if there is, it would be a good idea to mention it in the guide.

Also fix up intro

soramanew · 2025-07-02T03:52:50Z

I dont know if there is any between specifying source: comp vs layer.effect: MultiEffect { ... } but if there is, it would be a good idea to mention it in the guide.

I don't think there is a difference, but I've added a section in the guide for that.

outfoxxed · 2025-07-02T05:14:40Z

src/guide/effects.mdx

+Now, how do I use this you ask? Well, this guide provides a few examples for common uses of
+effects such as drop shadows, colourisation, masks and blurring.
+
+First and foremost (and arguably the most commonly used), drop shadows! To create a drop shadow,
+the [QtQuick.Effects](https://doc.qt.io/qt-6/qtquick-effects-qmlmodule.html) module provides
+two components that you can use: @@QtQuick.Effects.RectangularShadow and @@QtQuick.Effects.MultiEffect.


Write this more formally

outfoxxed · 2025-07-02T05:15:42Z

src/guide/effects.mdx

+@@QtQuick.Effects.RectangularShadow is much easier to use and more efficient than
+@@QtQuick.Effects.MultiEffect, however it can only be used for rectangular shadows (as the name implies).
+On the other hand, @@QtQuick.Effects.MultiEffect can used for most common effects, including all of
+the previously mentioned effects.


Cut the bit about shadows. We'll leave that to the headers which you can go to to learn about each thing.

outfoxxed · 2025-07-02T05:22:45Z

src/guide/effects.mdx

+The simplest way to create a rectangular drop shadow is with the @@QtQuick.Effects.RectangularShadow
+component. This component essentially creates a rectangle with blurred edges to act as a shadow. To
+use this component, you would typically create one below the source component of the shadow. To position
+a component beneath another, you can either simply create it before the other component, or use the
+@@QtQuick.Item.z property to visually position it below the other component.
+
+For example:
+
+```qml
+@@QtQuick.Rectangle {
+  id: rect
+
+  implicitWidth: 100
+  implicitHeight: 200
+  radius: 30
+}
+
+@@QtQuick.Effects.RectangularShadow {
+  anchors.fill: rect  // Fill the source rect
+  radius: rect.radius  // Have the same rounding as the source rect
+  blur: 15  // The blur/radius of the shadow
+  spread: 2  // The number of pixels from the edges of the rect the shadow extends from
+  color: "#000000"  // The colour of the shadow
+  z: -1  // Visually positions the shadow behind the source rect
+}
+```


Formulate the example to have the shadow above the rectangle and don't use z index. You can still mention thats an option though.

outfoxxed · 2025-07-02T05:23:32Z

src/guide/effects.mdx

+For more complex shapes, you can use the @@QtQuick.Effects.MultiEffect with the
+@@QtQuick.Effects.MultiEffect.shadowEnabled property set to `true`. You can then use the
+@@QtQuick.Effects.MultiEffect.shadowBlur, @@QtQuick.Effects.MultiEffect.shadowScale,
+@@QtQuick.Effects.MultiEffect.blurMax, @@QtQuick.Effects.MultiEffect.blurMultiplier,
+@@QtQuick.Effects.MultiEffect.shadowHorizontalOffset, @@QtQuick.Effects.MultiEffect.shadowVerticalOffset,
+@@QtQuick.Effects.MultiEffect.shadowOpacity and @@QtQuick.Effects.MultiEffect.shadowColor properties to
+tweak the drop shadow looks to your liking.


This should probably be a bullet list with an explanation of what each property does inline

outfoxxed · 2025-07-02T05:25:00Z

src/guide/effects.mdx

+> [!NOTE]
+> @@QtQuick.Effects.MultiEffect renders a new visual item alongside the source component,
+> meaning displaying the source component as well as the @@QtQuick.Effects.MultiEffect is unecessary
+> and wastes CPU cycles. To avoid this, you should either set `visible: false` or `opacity: 0` on
+> the source component. The first will prevent it from receiving mouse events while the second won't.
+
+```qml
+@@QtQuick.Rectangle {
+  id: rect
+
+  implicitWidth: 100
+  implicitHeight: 200
+  radius: 100
+  visible: false
+}
+
+@@QtQuick.Effects.MultiEffect {
+  anchors.fill: rect
+  source: rect
+  shadowEnabled: true  // This must be true for the shadow work
+  blurMax: 32  // This affects the radius of the shadow (this is also affected by `shadowBlur` and `blurMultiplier`)
+  shadowScale: 1  // This is essentially the same as `RectangularShadow#spread` but as a multiplier of the source's size
+  shadowColor: "#000000"  // The colour of the shadow
+}
+```


You should use layer.effect, its easier to understand and unloads when enabled is false. Do mention that you can use it without layer.effect as you do here, but with is preferred.

outfoxxed · 2025-07-02T05:31:48Z

src/guide/effects.mdx

+### Simple effects
+
+For simple effects like colourisation, brightness, contrast and saturation, @@QtQuick.Effects.MultiEffect
+provides them as easily animatable props.


"properties that can be easily animated"

outfoxxed · 2025-07-02T05:32:29Z

src/guide/effects.mdx

+Blurring is also done using the @@QtQuick.Effects.MultiEffect component. It is done similarly
+to shadows, however instead of setting the @@QtQuick.Effects.MultiEffect.shadowEnabled
+property to `true`, you set the @@QtQuick.Effects.MultiEffect.blurEnabled property to `true`.
+The blur effect can be customised with the @@QtQuick.Effects.MultiEffect.blur,
+@@QtQuick.Effects.MultiEffect.blurMax and @@QtQuick.Effects.MultiEffect.blurMultiplier properties.


Should probably be a bullet list, as above

outfoxxed · 2025-07-02T05:32:59Z

src/guide/effects.mdx

+
+### Stacking effects
+
+The advantage of using a @@QtQuick.Effects.MultiEffect is that you can apply multiple effects


We haven't mentioned qt5compat yet so no "advantage" at this point

outfoxxed · 2025-07-02T05:33:51Z

src/guide/effects.mdx

+The @@QtQuick.Effects.MultiEffect component can also be used as a layer effect instead of a
+separate visual item. For example, you can replicate the previous using a layer effect:
+
+> [!NOTE]
+> The source component should be visible and have @@QtQuick.Item.layer.enabled set to `true`.
+> Additionally, the @@QtQuick.Effects.MultiEffect does not need to have a size or the
+> @@QtQuick.Effects.MultiEffect.source property set.
+
+```qml
+@@QtQuick.Image {
+  id: img
+
+  source: "/path/to/img"
+
+  layer.enabled: true
+  layer.effect: @@QtQuick.Effects.MultiEffect {
+    // Apply colourisation
+    colorization: 1
+    colorizationColor: "#abc4d3"
+
+    // Apply shadow
+    shadowEnabled: true
+    shadowBlur: 1
+    shadowColor: "#000000"
+
+    // Apply blur (`blurMax` also affects shadow)
+    blurEnabled: true
+    blur: 1
+    blurMax: 32
+  }
+}
+```


Ok you did touch on this, but you should swap how its done throughout the guide page. Layer.effect is the preferred method, and I'd mention the alternative around here.

Use layer.effect by default Other sentence/wording changes Fix prop listing

add effects guide

7f63f76

add use as layer effect section to effects guide

6f4b997

Also fix up intro

outfoxxed requested changes Jul 2, 2025

View reviewed changes

fix effects guide for foxxed review

fd9a1bb

Use layer.effect by default Other sentence/wording changes Fix prop listing

soramanew requested a review from outfoxxed July 10, 2025 05:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

add effects guide #10

add effects guide #10

Uh oh!

soramanew commented Jul 1, 2025

Uh oh!

HigherOrderLogic commented Jul 1, 2025

Uh oh!

soramanew commented Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

outfoxxed Jul 2, 2025

Uh oh!

Uh oh!


		### Stacking effects

		The advantage of using a @@QtQuick.Effects.MultiEffect is that you can apply multiple effects

add effects guide #10

Are you sure you want to change the base?

add effects guide #10

Uh oh!

Conversation

soramanew commented Jul 1, 2025

Uh oh!

HigherOrderLogic commented Jul 1, 2025

Uh oh!

soramanew commented Jul 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!