1 files changed, 123 insertions, 0 deletions
diff --git a/examples/quickcontrols/filesystemexplorer/doc/src/qtquickcontrols-filesystemexplorer.qdoc b/examples/quickcontrols/filesystemexplorer/doc/src/qtquickcontrols-filesystemexplorer.qdoc
new file mode 100644
index 0000000000..686c2ab48a
--- /dev/null
+++ b/examples/quickcontrols/filesystemexplorer/doc/src/qtquickcontrols-filesystemexplorer.qdoc
@@ -0,0 +1,123 @@
+// 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.
+
+    In this example, a modern layout is used that consists of three major
+    components. There is an icon-based \e {Sidebar} to the left, followed by a
+    resizable TreeView displaying the file system from a QFileSystemModel, and
+    finally the TextArea displaying the selected text files. There is a common
+    look and feel across all operating systems. We accomplish this by using
+    customized quick controls and frameless windows, with our own window
+    decorations. When launching this application from the command-line, you
+    have the option to provide an initial directory as a parameter. This
+    initial directory will be used by the TreeView to set the starting point
+    for displaying the directory structure.
+
+    \image qtquickcontrols-filesystemexplorer.webp
+
+    \include examples-run.qdocinc
+
+    \section1 Modern layout and structure
+
+    To begin with, we are providing the colors throughout a singleton QML
+    object. In this way, we can provide more structured control over the
+    appearance of the application.
+
+    \quotefromfile filesystemexplorer/qml/Colors.qml
+    \skipto pragma
+    \printuntil }
+
+    Since we do not want to rely on the operating system's window decoration
+    and instead want to provide our own, we use the \c FramelessWindowHint flag
+    inside the ApplicationWindow. In order to achieve an equivalent interaction
+    with the window, we override the \c contentItem property of our customized
+    MenuBar and display some information text as well as interaction
+    possibilities for dragging or closing the application. \l {Inline
+    Components} have been used to 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 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 StackLayout.
+
+    This technique allows us to simply extend the functionality by adding
+    another button and the corresponding element inside the StackLayout.
+
+    \quotefromfile filesystemexplorer/Main.qml
+    \skipto StackLayout {
+    \printuntil /^\s{16}\}$/
+
+    The 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}. We can then select the files and read them accordingly.
+
+    \quotefromfile filesystemexplorer/filesystemmodel.cpp
+    \skipto readFile
+    \printuntil /^\s{0}\}$/
+
+    By right-clicking on a folder in the TreeView, a popup Menu is opened,
+    which allows control over the \c rootIndex property of the TreeView.
+
+    \quotefromfile filesystemexplorer/qml/FileSystemView.qml
+    \skipto MyMenu
+    \printuntil /^\s{8}\}$/
+
+    By using a SplitView, we are able to dynamically share the space between
+    the StackLayout and the Editor. Our Editor contains the TextArea that
+    displays the opened file and provides us with all the functionality needed
+    to edit text files. Additionally, we provide a visualization of the line
+    numbers, which can be toggled on and off in the Menu.
+
+    \quotefromfile filesystemexplorer/Main.qml
+    \skipto Editor {
+    \printuntil /^\s{12}\}$/
+
+    \section1 Custom components
+
+    For a better understanding of the customization process, investigate
+    \l {Customizing a Control} {this} article first. We are using reusable and
+    customized components throughout this example.
+
+    For instance, the \e {MyMenu} component customizes Menu's \c background
+    property as well as its delegates' \c contentItem and \c background
+    properties.
+
+    \quotefile filesystemexplorer/qml/MyMenu.qml
+
+    Another example is the customization of the ScrollIndicator inside the \e
+    {FileSystemView}, which additionally uses customized animations. Here we
+    also override 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
+    \l{https://doc.qt.io/qtforpython-6/examples/example_quickcontrols_filesystemexplorer.html}
+    {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
+    \l {https://doc.qt.io/qtforpython-6/tutorials/extendedexplorer/extendedexplorer.html}
+    {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 filesystem explorer.
+*/
+