FabMenu.qml

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Pier Luigi Fiorini <pierluigi.fiorini@gmail.com>
// SPDX-License-Identifier: MPL-2.0
 
pragma ComponentBehavior: Bound
 
import QtQuick
import QtQuick.Templates as T
import QtQuick.Window
import Fluid as MD
 
T.Pane {
    id: control
 
    enum Variant {
        Primary,
        Secondary,
        Tertiary
    }
 
    enum Direction {
        Up,
        Down
    }
 
    property bool expanded: false
 
    property int variant: FabMenu.Variant.Primary
 
    property int direction: FabMenu.Direction.Up
 
    property int alignment: Qt.AlignRight
 
    property bool scrim: true
 
    property real margins: MD.Tokens.fabMenu.containerMargin
 
    property string text
 
    property string collapsedIconName: MD.SymbolNames.symbolAdd
 
    property string expandedIconName: MD.SymbolNames.symbolClose
 
    readonly property alias button: fabMenuButton
 
    readonly property color itemContainerColor: {
        switch (variant) {
        case FabMenu.Variant.Primary:
            return control.MD.Style.primaryContainerColor;
        case FabMenu.Variant.Secondary:
            return control.MD.Style.secondaryContainerColor;
        case FabMenu.Variant.Tertiary:
            return control.MD.Style.tertiaryContainerColor;
        }
    }
 
    readonly property color itemContentColor: {
        switch (variant) {
        case FabMenu.Variant.Primary:
            return control.MD.Style.onPrimaryContainerColor;
        case FabMenu.Variant.Secondary:
            return control.MD.Style.onSecondaryContainerColor;
        case FabMenu.Variant.Tertiary:
            return control.MD.Style.onTertiaryContainerColor;
        }
    }
 
    readonly property bool _alignedRight: (alignment === Qt.AlignRight) !== mirrored
 
    readonly property real _entranceDirection: direction === FabMenu.Direction.Up ? 1 : -1
 
    readonly property real _buttonMargin: margins + MD.Tokens.fabMenu.closeButtonContainerHeight + MD.Tokens.fabMenu.closeButtonBetweenSpace
 
    property Item _restoreFocusItem: null
 
    function open() {
        control.expanded = true;
    }
 
    function close() {
        control.expanded = false;
    }
 
    function toggle() {
        control.expanded = !control.expanded;
    }
 
    function _focusSequence() {
        const items = [];
        for (let index = 0; index < control.contentChildren.length; ++index) {
            const item = control.contentChildren[index];
            if (item && item.menu === control && item.enabled)
                items.push(item);
        }
        if (control.direction === FabMenu.Direction.Down)
            items.unshift(fabMenuButton);
        else
            items.push(fabMenuButton);
        return items;
    }
 
    function _focusFirstAction() {
        for (let index = 0; index < control.contentChildren.length; ++index) {
            const item = control.contentChildren[index];
            if (item && item.menu === control && item.enabled) {
                item.forceActiveFocus(Qt.PopupFocusReason);
                return;
            }
        }
        fabMenuButton.forceActiveFocus(Qt.PopupFocusReason);
    }
 
    function _moveFocus(direction) {
        const sequence = control._focusSequence();
        if (sequence.length === 0)
            return;
        let index = sequence.indexOf(Window.window ? Window.window.activeFocusItem : null);
        index = index < 0 ? (direction > 0 ? -1 : 0) : index;
        sequence[(index + direction + sequence.length) % sequence.length]
                .forceActiveFocus(Qt.TabFocusReason);
    }
 
    function _focusBoundary(last) {
        const sequence = control._focusSequence();
        if (sequence.length > 0)
            sequence[last ? sequence.length - 1 : 0].forceActiveFocus(Qt.TabFocusReason);
    }
 
    function _bindItems() {
        for (let index = 0; index < control.contentChildren.length; ++index) {
            const item = control.contentChildren[index];
            if (!item || item.menu === undefined || item.staggerIndex === undefined)
                continue;
            // Activating an item dismisses the menu, as the specification
            // requires. The connection is made only when the item is first
            // bound, so re-binding cannot connect it twice, and it lives here
            // rather than in an onClicked handler inside FabMenuItem, which a
            // caller's own onClicked would override.
            if (item.menu !== control) {
                item.menu = control;
                item.clicked.connect(control.close);
            }
            item.staggerIndex = index;
            item.x = Qt.binding(() => {
                return control._alignedRight ? Math.max(0, column.width - item.width) : 0;
            });
        }
    }
 
    implicitWidth: Math.max(fabMenuButton.implicitWidth + margins * 2, implicitContentWidth + leftPadding + rightPadding)
    implicitHeight: Math.max(fabMenuButton.implicitHeight + margins * 2, implicitContentHeight + topPadding + bottomPadding)
 
    leftInset: 0
    rightInset: 0
    topInset: 0
    bottomInset: 0
    leftPadding: margins
    rightPadding: margins
    topPadding: direction === FabMenu.Direction.Up ? margins : _buttonMargin
    bottomPadding: direction === FabMenu.Direction.Up ? _buttonMargin : margins
 
    // Only the toggle participates in normal Tab traversal. Menu actions use
    // programmatic focus while expanded, and the non-actionable pane remains
    // transparent to both keyboard traversal and the accessibility tree.
    focusPolicy: Qt.NoFocus
    Accessible.ignored: true
 
    onContentChildrenChanged: control._bindItems()
 
    // Capture focus before entering the menu, then wait until the expansion
    // state has made its animated actions visible before focusing one. Closing
    // reverses that transfer so pointer, keyboard, and programmatic openings all
    // return focus consistently.
    onExpandedChanged: {
        if (control.expanded) {
            control._restoreFocusItem = Window.window ? Window.window.activeFocusItem : null;
            Qt.callLater(control._focusFirstAction);
        } else {
            const restoreItem = control._restoreFocusItem || fabMenuButton;
            if (restoreItem)
                restoreItem.forceActiveFocus(Qt.PopupFocusReason);
            control._restoreFocusItem = null;
        }
    }
 
    Component.onCompleted: control._bindItems()
 
    // Key events from the focused toggle or action bubble to the pane. Keeping
    // the handlers here gives every item identical wrapping and dismissal rules
    // without duplicating navigation logic in FabMenuItem.
    Keys.onEscapePressed: event => {
        if (control.expanded)
            control.close();
        else
            event.accepted = false;
    }
    Keys.onUpPressed: control._moveFocus(-1)
    Keys.onDownPressed: control._moveFocus(1)
    Keys.onPressed: event => {
        if (!control.expanded) {
            event.accepted = false;
        } else if (event.key === Qt.Key_Home) {
            control._focusBoundary(false);
            event.accepted = true;
        } else if (event.key === Qt.Key_End) {
            control._focusBoundary(true);
            event.accepted = true;
        } else {
            event.accepted = false;
        }
    }
 
    contentItem: Column {
        id: column
 
        z: 1
        spacing: MD.Tokens.fabMenu.listItemBetweenSpace
 
        // The pane stretches its content item over the available area, so the
        // items are pushed down to sit next to a button placed at the bottom.
        transform: Translate {
            y: control.direction === FabMenu.Direction.Up ? Math.max(0, column.height - column.implicitHeight) : 0
        }
    }
 
    /*
        The scrim and the toggle button are declared as direct children of the
        control rather than inside a background delegate: Qt Quick Controls does
        not deliver mouse presses to items nested in a background, so a button
        placed there would never register a press. Stacking is set explicitly so
        the scrim stays behind the items and the button stays in front of them.
        Every child keeps a non-negative z: a negative z would place it behind
        the control itself, which then consumes the presses meant for it.
    */
    data: [
        Rectangle {
            objectName: "fabMenuScrim"
 
            anchors.fill: parent
            color: control.MD.Style.scrimColor
            opacity: control.expanded && control.scrim ? MD.Tokens.fabMenu.scrimOpacity : 0
            visible: opacity > 0
 
            Behavior on opacity {
                NumberAnimation {
                    duration: MD.Tokens.motion.duration.short4
                }
            }
 
            TapHandler {
                onTapped: control.close()
            }
        },
 
        MD.FabMenuButton {
            id: fabMenuButton
            objectName: "fabMenuButton"
 
            // Positioned explicitly rather than by swapping anchors: resetting an
            // anchor to undefined does not restore the implicit size it overrode,
            // which would stretch the button when the direction or alignment flips.
            x: control._alignedRight ? control.width - width - control.margins : control.margins
            y: control.direction === FabMenu.Direction.Up ? control.height - height - control.margins : control.margins
            z: 2
 
            expanded: control.expanded
            containerColor: control.itemContainerColor
            contentColor: control.itemContentColor
            text: control.text
            collapsedIconName: control.collapsedIconName
            expandedIconName: control.expandedIconName
 
            onClicked: control.toggle()
        }
    ]
}