diff options
Diffstat (limited to 'examples/quickcontrols/filesystemexplorer/doc/src')
-rw-r--r-- | examples/quickcontrols/filesystemexplorer/doc/src/qtquickcontrols-filesystemexplorer.qdoc | 123 |
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. +*/ + |