Revision control
Copy as Markdown
// 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}
*/