diff options
Diffstat (limited to 'src/quick/doc/src/concepts')
7 files changed, 74 insertions, 30 deletions
diff --git a/src/quick/doc/src/concepts/effects/particles.qdoc b/src/quick/doc/src/concepts/effects/particles.qdoc index abe721c5ab..aa89450439 100644 --- a/src/quick/doc/src/concepts/effects/particles.qdoc +++ b/src/quick/doc/src/concepts/effects/particles.qdoc @@ -26,7 +26,7 @@ ****************************************************************************/ /*! - \qmlmodule QtQuick.Particles 2.\QtMinorVersion + \qmlmodule QtQuick.Particles \title Qt Quick Particles QML Types \ingroup qmlmodules \brief Provides QML types for particle effects diff --git a/src/quick/doc/src/concepts/input/focus.qdoc b/src/quick/doc/src/concepts/input/focus.qdoc index 9862489f42..6dd5a4b4bc 100644 --- a/src/quick/doc/src/concepts/input/focus.qdoc +++ b/src/quick/doc/src/concepts/input/focus.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -76,8 +76,9 @@ type whose text is determined by whether or not it has active focus. An \l Item requests focus by setting the \c focus property to \c true. For very simple cases simply setting the \c focus property is sometimes -sufficient. If we run the following example with \l{qtquick-qmlscene.html} -{qmlscene}, we see that the \c {keyHandler} type has active focus and +sufficient. If we run the following example with the +\l {Prototyping with the QML Runtime Tool}{qml tool}, +we see that the \c {keyHandler} type has active focus and pressing the \c A, \c B, or \c C keys modifies the text appropriately. \snippet qml/focus/basicwidget.qml focus true @@ -196,7 +197,7 @@ property. As the \l ListView is a focus scope, this doesn't affect the rest of the application. However, if the \l ListView itself has active focus this causes the delegate itself to receive active focus. In this example, the root type of the delegate is also a focus scope, -which in turn gives active focus to the \c {Text} type that actually performs +which in turn gives active focus to the \l {TextInput} type that actually performs the work of handling the \c {Return} key. All of the QML view classes, such as \l PathView and \l GridView, behave diff --git a/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc index 2ac9860e6f..7a05583a82 100644 --- a/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc +++ b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2018 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -30,20 +30,23 @@ \title Qt Quick Input Handlers \brief A module with a set of QML elements that handle events from input devices in a user interface. - Qt Quick Input Handlers are a set of QML types used to handle events from - keyboard, touch, mouse, and stylus devices in a UI. In contrast to event-handling - items, such as \l MouseArea and \l Flickable, input handlers are explicitly non-visual, - require less memory and are intended to be used in greater numbers: one - handler instance per aspect of interaction. Each input handler instance - handles certain events on behalf of its \c parent Item. Thus the visual and + Qt Quick Input Handlers are a set of QML types used to handle + \l {QInputEvent}{events} from keyboard, touch, mouse, and stylus + \l {QInputDevice}{devices} in a UI. In contrast to event-handling + items, such as \l MouseArea and \l Flickable, input handlers are explicitly + non-visual, require less memory and are intended to be used in greater + numbers: one handler instance per aspect of interaction. Each input handler + instance handles certain events on behalf of its + \l {QQuickPointerHandler::parent()}{parent} Item. Thus the visual and behavioral concerns are better separated, and the behavior is built up by finer-grained composition. - In Qt 5.10, these handlers were introduced in a separate Qt.labs.handlers module. - Now they are included with Qt Quick since 5.12. The pre-existing - \l Keys attached property is similar in concept, so we refer to the - pointing-device-oriented handlers plus \c Keys together as the set of Input Handlers. - We expect to offer more attached-property use cases in future versions of Qt. + The \l {Pointer Handlers Example} demonstrates some use cases for these. + + The pre-existing \l Keys attached property is similar in concept, so we + refer to the pointing-device-oriented handlers plus \c Keys together as the + set of Input Handlers. We expect to offer more attached-property use cases + in future versions of Qt. \section1 Input Handlers @@ -60,7 +63,45 @@ \li Each Item can have unlimited Handlers \endlist - \omit TODO actual overview with snippets and stuff \endomit + \section1 Handlers Manipulating Items + + Some Handlers add interactivity simply by being declared inside an Item: + + \snippet pointerHandlers/dragHandler.qml 0 + + \section1 Handler Properties and Signals + + All Handlers have properties that can be used in bindings, and signals that + can be handled to react to input: + + \snippet pointerHandlers/hoverTapKeyButton.qml 0 + + \section1 Pointer Grab + + An important concept with Pointer Handlers is the type of grabs that they + perform. The only kind of grab an Item can take is the exclusive grab: for + example if you call \l QPointerEvent::setExclusiveGrabber(), the following + mouse moves and mouse release event will be sent only to that object. (As a + workaround to this exclusivity, see \l QQuickItem::setFiltersChildMouseEvents() + and \l QQuickItem::childMouseEventFilter().) However Pointer Handlers have + an additional mechanism available: the + \l {QPointerEvent::addPassiveGrabber()} {passive grab}. Mouse and touch + \l {QEventPoint::state()}{press} events are delivered by visiting all the + Items in top-down Z order: first each Item's child Handlers, and then the + \l {QQuickItem::event()}{Item} itself. At the time a press event is + delivered, a Handler can take either a passive or an exclusive grab + depending on its needs. If it takes a passive grab, it is guaranteed to + receive the updates and the release, even if other Items or Handlers in the + scene take any kind of grab, passive or exclusve. Some Handlers (such as + PointHandler) can work only with passive grabs; others require exclusive + grabs; and others can "lurk" with passive grabs until they detect that a + gesture is being performed, and then make the transition from passive to + exclusive grab. TapHandler's grabbing behavior is + \l {TapHandler::gesturePolicy}{configurable}. + + When a grab transition is requested, \l PointerHandler::grabPermissions, + \l QQuickItem::keepMouseGrab() and \l QQuickItem::keepTouchGrab() control + whether the transition will be allowed. \section1 Related Information diff --git a/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc b/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc index 369c2f4444..429bd6e854 100644 --- a/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc +++ b/src/quick/doc/src/concepts/layouts/qtquicklayouts-overview.qdoc @@ -103,9 +103,16 @@ \l{Layout::minimumWidth}{minimum}, \l{Layout::preferredWidth}{preferred}, and \l{Layout::maximumWidth}{maximum} sizes of all items where \l{Layout::fillWidth}{Layout.fillWidth} or \l{Layout::fillHeight}{Layout.fillHeight} is set to \c true. + + The \l{Layout::preferredWidth}{preferred} width and height is the \e actual width and + height of an item if the layout is not bound to a specific size itself. If the layout is set + to a specific size, it will distribute additional space based on the ratio of preferred sizes + of its items (taking minimum and maximum sizes into account). + For instance, the following will produce a layout with two rectangles lying side-by-side that stretches horizontally. The azure rectangle can be resized from 50x150 to 300x150, and the plum - rectangle can be resized from 100x100 to ∞x100. + rectangle can be resized from 100x100 to ∞x100. As long as the minimum and maximum width of each + item is not reached, the plum rectangle will have two times the width of the azure one. \snippet qml/windowconstraints.qml rowlayout diff --git a/src/quick/doc/src/concepts/layouts/qtquicklayouts.qdoc b/src/quick/doc/src/concepts/layouts/qtquicklayouts.qdoc index 9ea8759318..0df832cca9 100644 --- a/src/quick/doc/src/concepts/layouts/qtquicklayouts.qdoc +++ b/src/quick/doc/src/concepts/layouts/qtquicklayouts.qdoc @@ -26,7 +26,7 @@ ****************************************************************************/ /*! - \qmlmodule QtQuick.Layouts 1.\QtMinorVersion + \qmlmodule QtQuick.Layouts \title Qt Quick Layouts QML Types \ingroup qmlmodules \brief Provides QML types for arranging QML items in a user interface. diff --git a/src/quick/doc/src/concepts/positioning/righttoleft.qdoc b/src/quick/doc/src/concepts/positioning/righttoleft.qdoc index 1f3602cde1..574dfcb58f 100644 --- a/src/quick/doc/src/concepts/positioning/righttoleft.qdoc +++ b/src/quick/doc/src/concepts/positioning/righttoleft.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -175,17 +175,11 @@ You can test that the layout direction works as expected by running your Qt Quic the compiled translation file: \code -qmlscene myapp.qml -translation myapp.qm +qml myapp.qml -translation myapp.qm \endcode -You can test your application in right-to-left layout direction simply by executing qmlscene with a -command-line parameter "-reverse": - -\code -qmlscene myapp.qml -reverse -\endcode - -The layout direction can also be set from C++ by calling the static function \l QGuiApplication::setLayoutDirection(): +You can test your application in right-to-left layout direction by calling the +static function \l QGuiApplication::setLayoutDirection(): \code QGuiApplication app(argc, argv); diff --git a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc index faec8df7e4..b0a66cfb5f 100644 --- a/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc +++ b/src/quick/doc/src/concepts/visualcanvas/scenegraph.qdoc @@ -194,6 +194,7 @@ throttling, use the \c basic render loop instead by setting \c {QSG_RENDER_LOOP=basic} in the environment. \section2 Threaded Render Loop ('threaded') +\target threaded_render_loop On many configurations, the scene graph rendering will happen on a dedicated render thread. This is done to increase parallelism of |