1// Copyright (C) 2018 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtquick-bestpractices.html
6\title Best Practices for QML and Qt Quick
7\brief Lists best practices for working with QML and Qt Quick.
9\ingroup explanations-programminglanguages
11Despite all of the benefits that QML and Qt Quick offer, they can be
12challenging in certain situations. The following sections elaborate on some of
13the best practices that will help you get better results when developing
16\section1 Custom UI Controls
18A fluid and modern UI is key for any application's success in today's world, and
19that's where QML makes so much sense for a designer or developer. Qt offers the
20most basic UI controls that are necessary to create a fluid and modern-looking
21UI. It is recommended to browse this list of UI controls before creating your
24Besides these basic UI controls offered by Qt Quick itself, a rich set of UI
25controls are also available with Qt Quick Controls. They cater to the most
26common use cases without any change, and offer a lot more possibilities with their
27customization options. In particular, Qt Quick Controls provides styling
28options that align with the latest UI design trends. If these UI controls do not
29satisfy your application's needs, only then it is recommended to create a
32You can use the controls when you design UIs in Qt Design Studio. In addition,
33it provides timeline-based animations, visual effects, layouts, and a
34live-preview for prototyping applications.
36\section2 Related Information
38\li \l{Qt Quick Controls}
39\li \l{Customizing Qt Quick Controls}
41\li \l{Qt Design Studio Manual}
45\section1 Keep it Short and Simple or "KiSS"
47QML being a declarative language, a lot of the details are worked out by the underlying
48engine. So it is important for any QML application, especially one with a
49larger codebase, to have its code organized in smaller and simpler \c .qml files.
51TODO: need a few snippet or example applications that showcase this.
54\section1 Coding Conventions
56See \l{QML Coding Conventions}.
58\section1 Bundle Application Resources
60Most applications depend on resources such as images and icons to provide a
61rich user experience. It can often be a challenge to make these resources
62available to the application regardless of the target OS. Most popular OS-es
63employ stricter security policies that restrict access to the file system,
64making it harder to load these resources. As an alternative, Qt offers its own
65\l {The Qt Resource System}{resource system} that is built into the
66application binary, enabling access to the application's resources regardless
69For example, consider the following project directory structure:
80You may represent this structure as a \l{qt_add_qml_module}{CMake QML Module} in the following way:
83qt_add_qml_module(my_module
95All QML files listed under \c {QML_FILES} will automatically get compiled \l {Ahead-of-Time Compilation}{ahead of time}.
97You should keep the QML files in the same directory as the CMakeLists.txt with
98the qt_add_qml_module. Otherwise their \l{The Implicit Import}{implicit imports}
99will be different from the \l{QML Modules} they belong to. This is a frequent
102\section2 Related Information
104 \li \l{The Qt Resource System}
107\section1 Separate UI from Business Logic
109One of the key goals that most application developers want to achieve is to
110create a maintainable application. One of the ways to achieve this goal is
111to separate the user interface from the business logic. The following are a few
112reasons why an application's UI should be written in QML:
115 \li Declarative languages are strongly suited for defining UIs.
116 \li QML code is simpler to write, as it is less verbose than C++, and is not
117 strongly typed. This also results in it being an excellent language to
118 prototype in, a quality that is vital when collaborating with designers,
120 \li JavaScript can easily be used in QML to respond to events.
123Being a strongly typed language, C++ is best suited for an application's
124business logic. Typically, such code performs tasks such as complex calculations
125or data processing, which are faster in C++ than QML.
127Qt offers various approaches to integrate QML and C++ code in an application.
128A typical use case is displaying a list of data in a user interface.
129If the data set is static, simple, and/or small, a model written in QML can be
132The following snippet demonstrates examples of models written in QML:
135 model: [ "Item 1", "Item 2", "Item 3" ]
140Use \l {QAbstractItemModel Subclass}{C++} for dynamic data sets that are large
141or frequently modified.
143\section2 Exposing Data from C++ to QML
145Refactoring QML is a lot easier than refactoring C++, so in order to make
146maintenance pain-free, we should strive to keep C++ types unaware of QML as
147much as possible. This can be achieved by "pushing" references to C++ types
150This can be done by using \l {Required properties}{required properties} and
151setting them via \l QQmlApplicationEngine::setInitialProperties. It is also
152possible to create one or multiple \l {QML_SINGLETON}{singletons} which will
153return all the data the C++ side wants to provide to QML.
155With this approach, the C++ remains unchanged in the event that the QML needs
156to be refactored in the future.
158For a quick guide to choosing the correct approach to expose C++ types to QML,
159see \l {Choosing the Correct Integration Method Between C++ and QML}.
161\section2 Related Information
163\li \l{Writing QML Extensions with C++}
164 {Writing QML Extensions with C++ Tutorial}
165\li \l{Qt Quick Controls - Chat Tutorial}{Chat application tutorial}
168\section1 Using Qt Design Studio
170Qt Design Studio uses UI files that have the filename extension \e {.ui.qml}
171to separate the visual parts of the UI from the UI logic you implement in
172\e {.qml} files. You should edit UI files only in the \uicontrol {2D} view in
173Qt Design Studio. If you use some other tool to add code that Qt Design Studio
174does not support, it displays error messages. Fix the errors to enable visual
175editing of the UI files again. Typically, you should move the unsupported code
178\section2 Related Information
181 \li \l{Qt Design Studio: UI Files}
184\section1 Using Qt Quick Layouts
186Qt offers Qt Quick Layouts to arrange Qt Quick items visually in a layout.
187Unlike its alternative, the item positioners, the Qt Quick Layouts can also
188resize its children on window resize. Although Qt Quick Layouts are often
189the desired choice for most use cases, the following \e dos and \e{don'ts}
190must be considered while using them:
195 \li Use \l {Item::}{anchors} or the \l {Item::}{width} and \l {Item::}{height}
196 properties to specify the size of the layout against its non-layout parent
198 \li Use the \l Layout attached property to set the size and alignment
199 attributes of the layout's immediate children.
205 \li Do not define preferred sizes for items that provide implicitWidth and
206 implicitHeight, unless their implicit sizes are not satisfactory.
207 \li Do not use anchors on an item that is an immediate child of a layout.
208 Instead, use \c Layout.preferredWidth and \c Layout.preferredHeight:
210 \snippet qml/windowconstraints.qml rowlayout
213\note Layouts and anchors are both types of objects that take more memory and
214instantiation time. Avoid using them (especially in list and table delegates,
215and styles for controls) when simple bindings to x, y, width, and height
216properties are enough.
218\section2 Related Information
221 \li \l{Item Positioners}
222 \li \l{Qt Quick Layouts Overview}
227When declaring properties in QML, it's easy and convenient to use the "var" type:
232property var optionsMenu
235However, this approach has several disadvantages:
237 \li If a value with the wrong type is assigned, the error reported will point
238 to the location of the property declaration, as opposed to the location
239 where the property was assigned to. This slows down the development
240 process by making it more difficult to track down errors.
241 \li Static anaylsis to catch errors like the ones mentioned above is not
243 \li The actual underlying type of the property is not always immediately clear
247Instead, always use the actual type where possible:
252property MyMenu optionsMenu
257For information on performance in QML and Qt Quick,
258see \l {QML Performance Considerations And Suggestions}.
260\section1 Prefer Declarative Bindings Over Imperative Assignments
262In QML, it's possible to use imperative JavaScript code to perform tasks
263such as responding to input events, send data over a network, and so on.
264Imperative code has an important place in QML, but it's also important
265to be aware of when not to use it.
267For example, consider the following imperative assignment:
271 Component.onCompleted: color = "red"
275This has the following disadvantages:
278\li It's slow. The color property will first be evaluated with a
279 default-constructed value, and then again with "red" later on.
280\li It delays errors that could be found at build time to run time, slowing
281 down the development process.
282\li It overwrites any declarative binding that was in place. In most cases this
283 is intended, but sometimes it can be unintentional.
284 See \l {Debugging overwriting of bindings} for more information.
285\li It interferes with tooling; Qt Quick Designer, for example, doesn't support
289The code can be rewritten to be a declarative binding instead:
297\section1 Tools and Utilities
299For information on useful tools and utilies that make working with QML and
300Qt Quick easier, see \l {Qt Quick Tools and Utilities}.
304For information on Qt Quick's scene graph, see \l {Qt Quick Scene Graph}.
306\section1 Scalable User Interfaces
308As display resolutions improve, a scalable application UI becomes more and
309more important. One of the approaches to achieve this is to maintain several
310copies of the UI for different screen resolutions, and load the appropriate one
311depending on the available resolution. Although this works pretty
312well, it adds to the maintenance overhead.
314Qt offers a better solution to this problem and recommends the application
315developers to follow these tips:
318 \li Use anchors or the Qt Quick Layouts module to lay out the visual items.
319 \li Do not specify explicit width and height for a visual item.
320 \li Provide UI resources such as images and icons for each display resolution
321 that your application supports. The Qt Quick Controls gallery example
322 demonstrates this well by providing the \c qt-logo.png for \c @2x, \c @3x,
323 and \c @4x resolutions, enabling the application to cater to high
324 resolution displays. Qt automatically chooses the appropriate
325 image that is suitable for the given display, provided the high DPI scaling
326 feature is explicitly enabled.
327 \li Use SVG images for small icons. While larger SVGs can be slow to render,
328 small ones work well. Vector images avoid the need to provide several
329 versions of an image, as is necessary with bitmap images.
330 \li Use font-based icons, such as Font Awesome. These scale to any display
331 resolution, and also allow colorization. The
332 Qt Quick Controls Text Editor example demonstrates this well.
335With this in place, your application's UI should scale depending
336on the display resolution on offer.
338\image qtquickcontrols-gallery-welcome.png
340\section2 Related Information
343 \li \l{Qt Quick Controls - Gallery}{Gallery example}
344 \li \l{Qt Quick Controls - Text Editor}{Text Editor example}