Standard QML MouseArea components are rectangular, which often poses a challenge when designing interactive UI elements with complex shapes, such as circular buttons or organic illustrations. To achieve precise interaction where clicks are only registered on the visible parts of an image, we must extend QQuickItem in C++ to implement alpha-based hit testing.

QML Implementation

The following example demonstrates how to use a custom component, IrregularMouseRegion, to wrap an image. The visual properties like scale and opacity respond dynamically based on whether the mouse is hovering over or presssing down on the non-transparent pixels of the source image.

// The visual element reacts to custom mouse area states
Image {
    id: cloudIcon
    source: "images/cloud.png"
    anchors.centerIn: parent
    
    // Scale up when pressed, slightly transparent when idle
    scale: interactionArea.pressed ? 1.1 : 1.0
    opacity: interactionArea.containsMouse ? 1.0 : 0.7

    IrregularMouseRegion {
        id: interactionArea
        anchors.fill: parent
        alphaThreshold: 0.1
        maskSource: cloudIcon.source
    }

    Behavior on scale {
        NumberAnimation { duration: 120; easing.type: Easing.OutQuad }
    }
    Behavior on opacity {
        NumberAnimation { duration: 200 }
    }
}

The C++ Backend Logic

To support this functionality, we define a C++ class that inherits from QQuickItem. This class manages the mask image and exposes properties to QML for interaction states.

#include <QImage>
#include <QQuickItem>
#include <QUrl>

class IrregularMouseRegion : public QQuickItem {
    Q_OBJECT
    Q_PROPERTY(bool pressed READ isPressed NOTIFY pressedChanged)
    Q_PROPERTY(bool containsMouse READ containsMouse NOTIFY containsMouseChanged)
    Q_PROPERTY(QUrl maskSource READ maskSource WRITE setMaskSource NOTIFY maskSourceChanged)
    Q_PROPERTY(qreal alphaThreshold READ alphaThreshold WRITE setAlphaThreshold NOTIFY alphaThresholdChanged)

public:
    explicit IrregularMouseRegion(QQuickItem *parent = nullptr);

    // Overriding contains is crucial for custom hit testing
    bool contains(const QPointF &point) const override;

    bool isPressed() const { return m_isPressed; }
    bool containsMouse() const { return m_containsMouse; }
    QUrl maskSource() const { return m_sourceUrl; }
    void setMaskSource(const QUrl &url);
    qreal alphaThreshold() const { return m_threshold; }
    void setAlphaThreshold(qreal val);

signals:
    void pressed();
    void released();
    void clicked();
    void pressedChanged();
    void maskSourceChanged();
    void containsMouseChanged();
    void alphaThresholdChanged();

protected:
    void mousePressEvent(QMouseEvent *event) override;
    void mouseReleaseEvent(QMouseEvent *event) override;
    void hoverEnterEvent(QHoverEvent *event) override;
    void hoverLeaveEvent(QHoverEvent *event) override;

private:
    bool m_isPressed = false;
    bool m_containsMouse = false;
    qreal m_threshold = 0.0;
    QUrl m_sourceUrl;
    QImage m_maskBuffer;
};

Alpha-Based Hit Detection

The core logic resides in the contains() method. While the default implementation only checks if a point lies within the bounding box, our override checks the specific alpha value of the pixel at that coordinate.

bool IrregularMouseRegion::contains(const QPointF &point) const {
    // First check if the point is within the basic bounding rect
    if (!QQuickItem::contains(point) || m_maskBuffer.isNull()) {
        return false;
    }

    QPoint pixelPos = point.toPoint();

    // Ensure the point is within the image boundaries
    if (pixelPos.x() < 0 || pixelPos.x() >= m_maskBuffer.width() ||
        pixelPos.y() < 0 || pixelPos.y() >= m_maskBuffer.height()) {
        return false;
    }

    // Map the threshold (0.0 - 1.0) to an 8-bit alpha value (0 - 255)
    int alphaLimit = qBound(0, qRound(m_threshold * 255), 255);
    
    // Get the alpha value of the pixel and compare it with the threshold
    return qAlpha(m_maskBuffer.pixel(pixelPos)) > alphaLimit;
}

When the QML engine needs to determine if a mouse event belongs to this item, it calls contains(). By returning false for transparent areas, we allow mouse events to "pass through" to items beneath, creating a perfect irregular interaction zone that matches the visual representation of the asset.