Qt Quick Architecture

From Qt Wiki
Jump to: navigation, search

Qt Quick is a set of QML primitives which can be combined to create graphical user interfaces. These are the primitives, not ready made components like Button, Slider, etc. These primitives should be able to construct any UI, especially fluid UIs. Since QML is designed for component reuse and extension, there can be a lot of component sets built on top of this (like QtQuick.Controls) with a prime usecase being platform-specific UI component sets (like the Symbian and Meego components of yore).


Items are elements in the visual scene. There is a tree of items (with a root node owned by a QQuickWindow) which defines an individual scene inside that window. Traversing this tree is how the window renders nodes and delivers input events. This is the C++ API for creating custom types for the visual scene; the C++ API provides standard Qt event handling and graphical rendering via the Scenegraph APIs. Note that on a purely C++ level (SG is not exposed to QML), there is another tree of graphical SG nodes used for rendering.

Functionality baked into the Item class

Inside the Item class (and so every item) we have a lot of stuff which applies to entire subtrees. Has to be here because this is the API for creating custom types

  • Transforms (including translation) which apply to the whole sub-tree
  • Opacity, sub-tree applied. clip/visible/enabled are marking sub-trees to be ignored
  • Anchors (although maybe this should move to work on any object with x/y/width/height ?). For performance reasons right now anchors are tied into the visual hierarchy, as this prevents having to calculate scene positions on items
  • Keyboard handling (mostly via attached properties). This is here because we wanted to do it via attached properties (it has no actual relation to on screen position) but it has to be Items because the events propagate through the subtree.

Visual Items

Rectangle, Canvas, Image, these elements are mostly about defining a textured quad.

Interactive Items

MouseArea, Flickable, MultiPointTouchArea, FocusScope, these are about how the scene reacts to input.

Flickable needs a lot of tuning per platform and that's currently not really possible. Either it should be decomposed into a generic viewport and scrolling behavior primitives (seems excessive) or it should gain a mechanism to tweak the motion to a greater extent.

Note that for items with a "viewport" split, like Flickable, where there is an item inside it to really contain the items, the pattern is to expose the internal item as "contentItem". The reference is needed in some situations and the consistent naming makes the concept easier to use.


Needs work. Views currently are large and monolithic, should be split into Layout-Instantiatior-Interactor sort of primitives which can then create List/Grid/Path views in QML. Like Flickable+Repeater+Column but with instantiation logic?

QAbstractItemModel is also fairly large and monolithic. It's great for complex and advanced models, but a simpler API could be used for just basic lists (a common model) which would be faster and easier to use. Also there are the QtQml.Models which combine a model with the ability to produce delegates, these could use to be cleaned up and made public once we see how they fit into new views (might play a larger role?).


Types that don't interact with the visual tree (non-visual, non-interactive, non-sub-tree-affecting). When put inside an Item the default property redirects them to be a QObject child but not part of the visual sub-tree. Because QtObject doesn't have a default property by default, users won't accidentally create sub-trees from these types and thus run into the fact that it's not an Item.

States, Transitions and Animations

For controlling properties over time. Goes with QtQuick because it's vital for fluid, animated UIs but these elements aren't strictly graphical related.

Note that the States/Transitions are UI states, not State Machine states. So these states are a delta over base properties (not just a graph node) and transitions are the animations to use when applying those deltas (not even a graph edge).


This has to be a non-item because it is the root of a visual tree. Window{} is a direct QQuickWindow with a root item and items inside it go into that sub-tree. This is necessary for controlling/creating windows in QML, and it also eases a generic QML runtime.

Informational objects

SystemPalette, Screen etc. These are just objects that expose properties we have in C++ which might be useful.

Utility Objects