Using File Selectors with Qt Quick Controls

File selectors provide a convenient way of selecting file variants. Qt offers the platform name and the locale as built-in selectors. Qt Quick Controls extends the built-in selectors with the name (Capitalized) of the style that an application is running with.

By using file selectors, style-specific tweaks can be applied without creating a hard dependency to a style. From the available file variants, only the selected QML file is loaded by the QML engine. Each file variant can assume the context, that is, a specific style. This typically leads to some code duplication, but on the other hand, cuts the aforementioned hard dependency to the style, and leads to simpler and more efficient QML code.

The following example demonstrates a custom rounded button that has a styled drop shadow in the Material style, and looks flat in other styles. The files are organized so that the Material version of CustomButton.qml is placed into a +Material sub-directory.

:/main.qml
:/CustomButton.qml
:/+Material/CustomButton.qml

By default, main.qml will use CustomButton.qml for the CustomButton type. However, when the application is run with the Material style, the Material selector will be present and the +Material/CustomButton.qml version will be used instead.

// main.qml
import QtQuick
import QtQuick.Controls

ApplicationWindow {
    id: window
    visible: true

    CustomButton {
        text: "Button"
        anchors.centerIn: parent
    }
}

The base implementation of the custom button is a simple rounded flat button.

// CustomButton.qml
import QtQuick
import QtQuick.Controls

Button {
    id: control

    background: Rectangle {
        radius: width / 2
        implicitWidth: 36
        implicitHeight: 36
        color: control.pressed ? "#ccc" : "#eee"
    }
}

The Material style's implementation of the custom button imports the Material style, requests a dark theme to get light text, and creates a drop shadow for the background.

// +Material/CustomButton.qml
import QtQuick
import QtQuick.Effects
import QtQuick.Controls
import QtQuick.Controls.Material

Button {
    id: control

    Material.theme: Material.Dark

    background: Rectangle {
        implicitWidth: 48
        implicitHeight: 48
        color: Material.accentColor
        radius: width / 2

        layer.enabled: control.enabled
        layer.effect: MultiEffect {
            shadowEnabled: true
            shadowHorizontalOffset: 3
            shadowVerticalOffset: 3
            shadowColor: Material.dropShadowColor
            shadowBlur: control.pressed ? 0.8 : 0.4
        }
    }
}

Note: It is recommended to use QQmlApplicationEngine, which internally creates a QQmlFileSelector instance. This is all that is needed to take QML file selectors into use.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.