ModalNavigationRail.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
import "../internal/MotionAnimation.js" as MotionAnimation
 
T.Control {
    id: control
 
    default property alias destinations: rail.contentData
 
    property bool expanded: false
 
    property bool hideOnCollapse: false
 
    property alias currentIndex: rail.currentIndex
 
    property alias arrangement: rail.arrangement
 
    property alias header: rail.header
 
    property color containerColor: control.MD.Style.surfaceContainerColor
 
    property color scrimColor: control.MD.Style.scrimColor
 
    readonly property alias count: rail.count
 
    property Item _restoreFocusItem: null
 
    property real _dragOffset: 0
 
    property real _dragStartOffset: 0
 
    function itemAt(index) {
        return rail.itemAt(index);
    }
 
    function expand() {
        control.expanded = true;
    }
 
    function collapse() {
        control.expanded = false;
    }
 
    function toggle() {
        control.expanded = !control.expanded;
    }
 
    function _focusRail() {
        let index = control.currentIndex;
        if (index >= 0) {
            const selectedItem = rail.itemAt(index);
            if (selectedItem && selectedItem.enabled) {
                selectedItem.forceActiveFocus(Qt.PopupFocusReason);
                return;
            }
        }
        for (index = 0; index < rail.count; ++index) {
            const item = rail.itemAt(index);
            if (item && item.enabled) {
                item.forceActiveFocus(Qt.PopupFocusReason);
                return;
            }
        }
        rail.forceActiveFocus(Qt.PopupFocusReason);
    }
 
    function _focusDestination() {
        const selected = rail.itemAt(rail._tabStopIndex);
        if (selected) {
            selected.forceActiveFocus(Qt.TabFocusReason);
            return true;
        }
        return false;
    }
 
    function _moveModalTab(backward) {
        const headerItem = rail._headerFocusItem();
        const headerFocusable = headerItem !== null;
        if (headerFocusable && !headerItem.activeFocus) {
            headerItem.forceActiveFocus(backward ? Qt.BacktabFocusReason : Qt.TabFocusReason);
            return;
        }
        if (!control._focusDestination() && headerFocusable)
            headerItem.forceActiveFocus(backward ? Qt.BacktabFocusReason : Qt.TabFocusReason);
    }
 
    implicitWidth: rail.implicitWidth
    implicitHeight: rail.implicitHeight
    padding: 0
    focusPolicy: Qt.StrongFocus
    LayoutMirroring.childrenInherit: true
 
    // The page-sized host exists for input, focus trapping, and the scrim. Keep
    // it out of the accessibility tree and expose the contained tab-list instead.
    Accessible.ignored: true
 
    onExpandedChanged: {
        if (expanded) {
            // Capture the invoking control before moving focus into the modal.
            _restoreFocusItem = Window.window ? Window.window.activeFocusItem : null;
            Qt.callLater(control._focusRail);
        } else {
            _dragOffset = 0;
            // Return keyboard focus after every dismissal path: Escape, scrim,
            // drag, or an external expanded-property change.
            if (_restoreFocusItem)
                _restoreFocusItem.forceActiveFocus(Qt.PopupFocusReason);
            _restoreFocusItem = null;
        }
    }
 
    // Only consume modal-navigation keys while expanded. When collapsed, allow
    // ancestors and neighboring controls to handle normal application traversal.
    Keys.onEscapePressed: event => {
        if (control.expanded)
            control.collapse();
        else
            event.accepted = false;
    }
    Keys.onTabPressed: event => {
        if (control.expanded) {
            control._moveModalTab(false);
            event.accepted = true;
        } else {
            event.accepted = false;
        }
    }
    Keys.onBacktabPressed: event => {
        if (control.expanded) {
            control._moveModalTab(true);
            event.accepted = true;
        } else {
            event.accepted = false;
        }
    }
 
    contentItem: Item {
        clip: false
 
        Rectangle {
            id: scrim
            objectName: "modalNavigationRailScrim"
 
            anchors.fill: parent
            z: 0
            color: control.scrimColor
            opacity: control.expanded ? MD.Tokens.navigationRail.modalScrimOpacity : 0
            visible: opacity > 0
 
            Behavior on opacity {
                NumberAnimation {
                    duration: MotionAnimation.expressiveFastEffectsDuration
                    easing.type: Easing.BezierSpline
                    easing.bezierCurve: MotionAnimation.expressiveFastEffectsCurve
                }
            }
 
            TapHandler {
                onTapped: control.collapse()
            }
        }
 
        NavigationRail {
            id: rail
            objectName: "modalNavigationRailSurface"
 
            z: 1
            x: {
                const shownX = control.mirrored ? control.width - rail.width : 0;
                const hiddenX = control.mirrored ? control.width : -rail.width;
                return (control.expanded || !control.hideOnCollapse ? shownX : hiddenX)
                       + control._dragOffset;
            }
            y: 0
            width: Math.min(rail.implicitWidth, control.width)
            height: control.height
            expanded: control.hideOnCollapse || control.expanded
            containerColor: control.containerColor
            _modal: true
 
            // Forward the caller-provided name to the actual PageTabList node;
            // the ignored overlay host must not become a duplicate announcement.
            Accessible.name: control.Accessible.name
            LayoutMirroring.enabled: control.mirrored
            LayoutMirroring.childrenInherit: true
 
            Behavior on x {
                enabled: !dragHandler.active && !dragSettleAnimation.running
 
                NumberAnimation {
                    duration: MotionAnimation.expressiveFastSpatialDuration
                    easing.type: Easing.BezierSpline
                    easing.bezierCurve: MotionAnimation.expressiveFastSpatialCurve
                }
            }
 
            DragHandler {
                id: dragHandler
                objectName: "modalNavigationRailDragHandler"
 
                enabled: control.expanded
                target: null
                dragThreshold: 0
                acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad | PointerDevice.Mouse
 
                onActiveChanged: {
                    if (active) {
                        dragSettleAnimation.stop();
                        control._dragStartOffset = control._dragOffset;
                    } else {
                        const dismissalDistance = control.mirrored
                                                  ? control._dragOffset
                                                  : -control._dragOffset;
                        if (dismissalDistance >= rail.width * 0.5) {
                            control._dragOffset = 0;
                            control.collapse();
                        } else {
                            dragSettleAnimation.restart();
                        }
                    }
                }
 
                onTranslationChanged: {
                    if (!active)
                        return;
                    const logicalDistance = control.mirrored ? translation.x : -translation.x;
                    const clampedDistance = Math.max(0, Math.min(rail.width, logicalDistance));
                    control._dragOffset = control._dragStartOffset
                                          + (control.mirrored ? clampedDistance : -clampedDistance);
                }
            }
        }
    }
 
    NumberAnimation {
        id: dragSettleAnimation
        target: control
        property: "_dragOffset"
        to: 0
        duration: MotionAnimation.expressiveFastSpatialDuration
        easing.type: Easing.BezierSpline
        easing.bezierCurve: MotionAnimation.expressiveFastSpatialCurve
    }
}