Revision control
++ // Copyright (C) 2023 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++ /*!
++ \example filesystemexplorer
++ \examplecategory {Application Examples}
++ \meta tags {quickcontrols, layout, styling, treeview}
++ \title File System Explorer
++ \ingroup qtquickcontrols-examples
++ \brief A desktop QML app utilizing customized Qt Quick Controls to display
++ text files from a filesystem.
++
++ \image {qtquickcontrols-filesystemexplorer.webp} {A file system explorer UI}
++
++ The File System Explorer example uses a modern layout that consists of
++ three major components: an icon-based \e {Sidebar} to the left, a resizable
++ \l TreeView displaying the file system from a \l QFileSystemModel, and the
++ \l TextArea displaying the selected text files. Customized quick controls and
++ frameless windows, with specialized window decorations, ensure a common look
++ and feel across all operating systems. When launching this application from
++ the command-line, you can provide an initial directory as a parameter. This
++ initial directory will be used by the \l TreeView to set the starting point for
++ displaying the directory structure.
++
++ \include examples-run.qdocinc
++
++ \section1 Modern layout and structure
++
++ To begin with, the example provides the colors throughout a singleton QML
++ object. This is to ensure structured control over the application's
++ appearance.
++
++ \quotefromfile filesystemexplorer/qml/Colors.qml
++ \skipto pragma
++ \printuntil }
++
++ The example uses the \c FramelessWindowHint flag inside the
++ \l ApplicationWindow to create a customized decoration, as opposed to relying
++ on the operating system's window decoration. In order to achieve an
++ equivalent interaction with the window, the example overrides the
++ \c contentItem property of the customized \l MenuBar and displays information
++ text and interaction possibilities for dragging or closing the application.
++ \l {Inline Components} simplify this process.
++
++ \quotefromfile filesystemexplorer/qml/MyMenuBar.qml
++ \skipto component InteractionButton
++ \printuntil id: maximize
++ \dots
++
++ The \e {Sidebar} on the left includes checkable navigation buttons on top
++ and one-shot buttons on the bottom. A \l ButtonGroup and a container are used
++ to ensure that only one entry is active at any given time. It is then
++ possible to provide different views using a property alias for the current
++ position, along with a \l StackLayout.
++
++ This technique lets you extend the functionality by adding
++ another button and the corresponding element inside the \l StackLayout.
++
++ \quotefromfile filesystemexplorer/Main.qml
++ \skipto StackLayout {
++ \printuntil /^\s{16}\}$/
++
++ The \l StackLayout includes, besides some information text, the \e
++ {FileSystemView}. This custom component displays files and folders and
++ populates it with data from a \l {Using C++ Models with Qt Quick Views}{C++
++ model}. You can then select the files and read them accordingly.
++
++ \quotefromfile filesystemexplorer/filesystemmodel.cpp
++ \skipto readFile
++ \printuntil /^\s{0}\}$/
++
++ Right-clicking a folder in the \l TreeView opens a popup \c Menu,
++ which allows control over the \c rootIndex property of the \l TreeView.
++
++ \quotefromfile filesystemexplorer/qml/FileSystemView.qml
++ \skipto MyMenu
++ \printuntil /^\s{8}\}$/
++
++ \l SplitView lets you dynamically share the space between the \l StackLayout
++ and the editor. The editor contains the \l TextArea that displays the opened
++ file and provides all the functionality needed to edit text files.
++ Additionally, the editor provides line numbers, which can be toggled on
++ and off in the \c Menu.
++
++ \quotefromfile filesystemexplorer/Main.qml
++ \skipto Editor {
++ \printuntil /^\s{12}\}$/
++
++ \section1 Custom components
++
++ For a better understanding of the customization process, investigate the
++ \l {Customizing a Control} article first. This example uses reusable and
++ customized components.
++
++ For instance, the \c MyMenu component customizes Menu's \c background
++ property, its delegate's \c contentItem, and the \c background properties.
++
++ \quotefile filesystemexplorer/qml/MyMenu.qml
++
++ Another example is the customization of the \l ScrollIndicator inside the
++ \c {FileSystemView}, which uses customized animations. Here, the example
++ overrides the \c contentItem.
++
++ \quotefromfile filesystemexplorer/qml/FileSystemView.qml
++ \skipto ScrollIndicator.vertical
++ \printuntil /^\s{8}\}$/
++
++ \section1 Python version
++
++ If you're interested in the Python version of this example, you can find it
++ {here}. This showcases the usage of Qt for Python and demonstrates how it
++ can be used to create the same application.
++
++ Additionally, there is a detailed
++ {tutorial} available that provides step-by-step instructions on how to
++ extend this example with additional features. This tutorial can be helpful
++ if you want to explore and learn more about building upon the existing
++ functionality of the File System Explorer.
++
++ \section1 Source files
++
++ \sa {All Qt Examples}, {Qt Quick Controls Examples}
++ */
++