diff options
| -rw-r--r-- | src/quick/doc/src/concepts/input/mouse.qdoc | 25 | ||||
| -rw-r--r-- | src/quick/doc/src/concepts/input/topic.qdoc | 30 | ||||
| -rw-r--r-- | src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc (renamed from src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers-index.qdoc) | 41 | ||||
| -rw-r--r-- | src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers.qdoc | 44 | ||||
| -rw-r--r-- | src/quick/handlers/qquickdraghandler.cpp | 4 | ||||
| -rw-r--r-- | src/quick/handlers/qquickhandlerpoint.cpp | 3 | ||||
| -rw-r--r-- | src/quick/handlers/qquickhoverhandler.cpp | 2 | ||||
| -rw-r--r-- | src/quick/handlers/qquickmultipointhandler.cpp | 3 | ||||
| -rw-r--r-- | src/quick/handlers/qquickpinchhandler.cpp | 4 | ||||
| -rw-r--r-- | src/quick/handlers/qquickpointerdevicehandler.cpp | 3 | ||||
| -rw-r--r-- | src/quick/handlers/qquickpointerhandler.cpp | 3 | ||||
| -rw-r--r-- | src/quick/handlers/qquickpointhandler.cpp | 4 | ||||
| -rw-r--r-- | src/quick/handlers/qquicksinglepointhandler.cpp | 3 | ||||
| -rw-r--r-- | src/quick/handlers/qquicktaphandler.cpp | 4 | ||||
| -rw-r--r-- | src/quick/items/qquickitem.cpp | 4 |
15 files changed, 61 insertions, 116 deletions
diff --git a/src/quick/doc/src/concepts/input/mouse.qdoc b/src/quick/doc/src/concepts/input/mouse.qdoc index 422c326898..cb506cb99a 100644 --- a/src/quick/doc/src/concepts/input/mouse.qdoc +++ b/src/quick/doc/src/concepts/input/mouse.qdoc @@ -33,6 +33,13 @@ \tableofcontents +A more modern way of handling events from all pointing devices, including +mouse and touchscreen, is via \l {Qt Quick Input Handlers}{Input Handlers}. +This page describes the original Qt Quick \l MouseArea type, which was +initially designed to handle mouse input, and later began handling single-touch +events (in the form of synthetic mouse events) in simple touch-oriented user +interfaces. + \section1 Mouse Types \list @@ -44,8 +51,8 @@ QML uses \l{qtqml-syntax-signals.html}{signals and handlers} to deliver mouse interactions. Specifically, Qt Quick provides the \l MouseArea -and \l MouseEvent types which allow developers to define signal handlers which -accept mouse events within a defined area. +and \l MouseEvent types that allow developers to define JavaScript callbacks +(also called signal handlers), which accept mouse events within a defined area. \section1 Defining a Mouse Area @@ -59,8 +66,8 @@ definable. \section1 Receiving Events -The MouseArea type provides -\l{qtqml-syntax-signals.html}{signals and handlers} to detect different +The MouseArea type emits +\l{qtqml-syntax-signals.html}{signals} in response to different mouse events. The \l MouseArea type documentation describes these gestures in greater detail: @@ -76,8 +83,8 @@ gestures in greater detail: \li released \endlist -These signals have signal handlers that are invoked when the signals are emitted. -\snippet qml/mousearea/mousearea-snippet.qml mouse handlers +These signals can have callbacks that are invoked when the signals are emitted. +\snippet qml/mousearea/mousearea-snippet.qml signal handlers \section1 Enabling Gestures Some mouse gestures and button clicks need to be enabled before they send or @@ -101,9 +108,9 @@ Additionally, to disable the whole mouse area, set the MouseArea \section1 MouseEvent Object -Signals and their handlers receive a \l MouseEvent object as a parameter. The -\c mouse object contain information about the mouse event. For example, the -mouse button that started the event is queried through the +Signals and their callbacks receive a \l MouseEvent object as a parameter. +The \c mouse object contains information about the mouse event. For example, +the mouse button that started the event is queried through the \l {MouseEvent::button}{mouse.button} property. The \c MouseEvent object can also ignore a mouse event using its \c accepted diff --git a/src/quick/doc/src/concepts/input/topic.qdoc b/src/quick/doc/src/concepts/input/topic.qdoc index c23654cadb..95f4732f46 100644 --- a/src/quick/doc/src/concepts/input/topic.qdoc +++ b/src/quick/doc/src/concepts/input/topic.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2018 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -35,30 +35,20 @@ design. Depending on the use-case that an application solves, and the form-factor of the device that the application runs on, the best way to receive user-input may be different. -\section1 Touch +\section1 Input from Pointing Devices Allowing users to physically touch a screen to interact with an application is a popular user-interface paradigm on portable devices like smartphones and -tablets. +tablets. In desktop applications, detecting and reacting to clicks and presses +according to the mouse cursor position is a fundamental concept in +user-interface design. -Qt Quick was designed specifically with touch-driven user-interfaces in mind, -and thus touch events are supported in various visual object types, from -\l{Flickable} lists to the generic \l{MultiPointTouchArea} type, as well as -in the \l{MouseArea} type (which will be documented thoroughly in a proceeding -section). +Touch-driven and mouse-driven user interfaces are supported by various +\l{Qt Quick Input Handlers}{input handler} types, and visual object types +such as \l{Flickable} and \l{MouseArea}. - -\section1 Mouse - -Mouse input is another important user input for user interfaces. Detecting -and reacting to clicks and presses according to the mouse cursor position is a fundamental -concept in user-interface design. - -Qt Quick provides the MouseArea visual object type which automatically receives -mouse events (including clicks and wheel events) which allows developers to -create custom user-interface objects to handle mouse input. Please see the -documentation about \l{qtquick-input-mouseevents.html} -{mouse events in Qt Quick} for more information on the topic. +See also the documentation about +\l{qtquick-input-mouseevents.html} {mouse events in Qt Quick}. \section1 Keyboard Input and Keyboard Focus diff --git a/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers-index.qdoc b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc index fc1fd5fbc1..2ac9860e6f 100644 --- a/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers-index.qdoc +++ b/src/quick/doc/src/concepts/inputhandlers/qtquickhandlers-index.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2018 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. @@ -27,35 +27,34 @@ /*! \page qtquickhandlers-index.html - \title Qt Quick Pointer Handlers - \brief A module with a set of QML elements that handle events from pointing devices in a user interface. + \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 Pointer Handlers are a set of QML types used to handle events from - touch, mouse, and stylus devices in a UI. In contrast to event-handling - Items, such as \l MouseArea, Pointer Handlers require less memory and are - intended to be used in greater numbers: one handler per type of - interaction. Each Pointer Handler handles events on behalf of its \c parent - Item. One Item can have multiple Pointer Handlers. + 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 + behavioral concerns are better separated, and the behavior is built up by + finer-grained composition. - The module is introduced in Qt 5.10. + 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. - \section1 Pointer Handlers + \section1 Input Handlers - \annotatedlist pointerhandlers - - \section1 Getting Started - - The QML types can be imported into your application using the following import statement in your \c {.qml} file. - - \code - import Qt.labs.handlers 1.0 - \endcode + \annotatedlist qtquick-input-handlers \section1 Key Features Some of the key features are: \list + \li Handle keystrokes within the focused Item \li Handle gestures such as tapping or dragging regardless which device it comes from \li Handle gestures from different classes of devices in different ways \li Each Item can have unlimited Handlers @@ -67,7 +66,5 @@ \list \li \l{Qt Quick} - \li \l{Qt Quick Pointer Handlers} - \li \l{Qt Quick Pointer Handlers QML Types}{Qt Quick Pointer Handlers QML Types} \endlist */ diff --git a/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers.qdoc b/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers.qdoc deleted file mode 100644 index cf87c75e8c..0000000000 --- a/src/quick/doc/src/concepts/pointerhandlers/qtquickhandlers.qdoc +++ /dev/null @@ -1,44 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \qmlmodule Qt.labs.handlers 1.0 - \title Qt Quick Pointer Handlers QML Types - \ingroup qmlmodules - \brief Provides QML types for handling events from pointing devices in a user interface. - - The \l{Qt Quick Pointer Handlers} module provides QML types for handling - events from pointing devices in a UI. These QML types work in conjunction - with \l{Qt Quick}. - - The QML types can be imported into your application using the - following import statement in your .qml file. - - \code - import Qt.labs.handlers 1.0 - \endcode -*/ diff --git a/src/quick/handlers/qquickdraghandler.cpp b/src/quick/handlers/qquickdraghandler.cpp index 707b247f72..7c175b472b 100644 --- a/src/quick/handlers/qquickdraghandler.cpp +++ b/src/quick/handlers/qquickdraghandler.cpp @@ -51,8 +51,8 @@ Q_LOGGING_CATEGORY(lcDragHandler, "qt.quick.handler.drag") \qmltype DragHandler \instantiates QQuickDragHandler \inherits SinglePointHandler - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick + \ingroup qtquick-input-handlers \brief Handler for dragging. DragHandler is a handler that is used to interactively move an Item. diff --git a/src/quick/handlers/qquickhandlerpoint.cpp b/src/quick/handlers/qquickhandlerpoint.cpp index 663fd23287..be9bad7bea 100644 --- a/src/quick/handlers/qquickhandlerpoint.cpp +++ b/src/quick/handlers/qquickhandlerpoint.cpp @@ -46,8 +46,7 @@ Q_DECLARE_LOGGING_CATEGORY(DBG_TOUCH_TARGET) /*! \qmltype HandlerPoint \instantiates QQuickHandlerPoint - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick \brief An event point. A QML representation of a QQuickEventPoint. diff --git a/src/quick/handlers/qquickhoverhandler.cpp b/src/quick/handlers/qquickhoverhandler.cpp index 430722bd93..817c1348e6 100644 --- a/src/quick/handlers/qquickhoverhandler.cpp +++ b/src/quick/handlers/qquickhoverhandler.cpp @@ -47,7 +47,7 @@ Q_LOGGING_CATEGORY(lcHoverHandler, "qt.quick.handler.hover") \qmltype HoverHandler \instantiates QQuickHoverHandler \inqmlmodule QtQuick - \ingroup qtquick-handlers + \ingroup qtquick-input-handlers \brief Handler for mouse and tablet hover HoverHandler detects a hovering cursor. Since touchscreens don't generally diff --git a/src/quick/handlers/qquickmultipointhandler.cpp b/src/quick/handlers/qquickmultipointhandler.cpp index 4e633276ab..98321e134a 100644 --- a/src/quick/handlers/qquickmultipointhandler.cpp +++ b/src/quick/handlers/qquickmultipointhandler.cpp @@ -51,8 +51,7 @@ QT_BEGIN_NAMESPACE \preliminary \instantiates QQuickMultiPointHandler \inherits PointerDeviceHandler - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick \brief Abstract handler for multi-point Pointer Events. An intermediate class (not registered as a QML type) diff --git a/src/quick/handlers/qquickpinchhandler.cpp b/src/quick/handlers/qquickpinchhandler.cpp index e0b798b638..d6e1a183bb 100644 --- a/src/quick/handlers/qquickpinchhandler.cpp +++ b/src/quick/handlers/qquickpinchhandler.cpp @@ -56,8 +56,8 @@ Q_LOGGING_CATEGORY(lcPinchHandler, "qt.quick.handler.pinch") \qmltype PinchHandler \instantiates QQuickPinchHandler \inherits MultiPointHandler - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick + \ingroup qtquick-input-handlers \brief Handler for pinch gestures. PinchHandler is a handler that interprets a multi-finger gesture to diff --git a/src/quick/handlers/qquickpointerdevicehandler.cpp b/src/quick/handlers/qquickpointerdevicehandler.cpp index 7b9f6839b1..dfea3ec02d 100644 --- a/src/quick/handlers/qquickpointerdevicehandler.cpp +++ b/src/quick/handlers/qquickpointerdevicehandler.cpp @@ -51,8 +51,7 @@ QT_BEGIN_NAMESPACE \preliminary \instantiates QQuickPointerDeviceHandler \inherits PointerHandler - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick \brief Abstract handler for pointer events with device-specific constraints. An intermediate class (not registered as a QML type) for handlers which diff --git a/src/quick/handlers/qquickpointerhandler.cpp b/src/quick/handlers/qquickpointerhandler.cpp index 5f8106af3e..91349a6ad7 100644 --- a/src/quick/handlers/qquickpointerhandler.cpp +++ b/src/quick/handlers/qquickpointerhandler.cpp @@ -53,8 +53,7 @@ Q_LOGGING_CATEGORY(lcPointerHandlerActive, "qt.quick.handler.active") \since 5.10 \preliminary \instantiates QQuickPointerHandler - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick \brief Abstract handler for pointer events. PointerHandler is the base class Input Handler (not registered as a QML type) for diff --git a/src/quick/handlers/qquickpointhandler.cpp b/src/quick/handlers/qquickpointhandler.cpp index 7cf37969cc..65a7fd7b79 100644 --- a/src/quick/handlers/qquickpointhandler.cpp +++ b/src/quick/handlers/qquickpointhandler.cpp @@ -47,8 +47,8 @@ QT_BEGIN_NAMESPACE \qmltype PointHandler \instantiates QQuickPointHandler \inherits SinglePointHandler - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick + \ingroup qtquick-input-handlers \brief Handler for reacting to a single touchpoint. PointHandler can be used to show feedback about a touchpoint or the mouse diff --git a/src/quick/handlers/qquicksinglepointhandler.cpp b/src/quick/handlers/qquicksinglepointhandler.cpp index 71c05891d4..0f8fc58bc1 100644 --- a/src/quick/handlers/qquicksinglepointhandler.cpp +++ b/src/quick/handlers/qquicksinglepointhandler.cpp @@ -48,8 +48,7 @@ Q_DECLARE_LOGGING_CATEGORY(DBG_TOUCH_TARGET) \preliminary \instantiates QQuickSinglePointHandler \inherits PointerDeviceHandler - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick \brief Abstract handler for single-point Pointer Events. An intermediate class (not registered as a QML type) diff --git a/src/quick/handlers/qquicktaphandler.cpp b/src/quick/handlers/qquicktaphandler.cpp index d565e16e2d..1d3375314f 100644 --- a/src/quick/handlers/qquicktaphandler.cpp +++ b/src/quick/handlers/qquicktaphandler.cpp @@ -55,8 +55,8 @@ int QQuickTapHandler::m_touchMultiTapDistanceSquared(-1); \qmltype TapHandler \instantiates QQuickTapHandler \inherits SinglePointHandler - \inqmlmodule Qt.labs.handlers - \ingroup qtquick-handlers + \inqmlmodule QtQuick + \ingroup qtquick-input-handlers \brief Handler for taps and clicks. TapHandler is a handler for taps on a touchscreen or clicks on a mouse. diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp index c1e625ef95..c23aca622e 100644 --- a/src/quick/items/qquickitem.cpp +++ b/src/quick/items/qquickitem.cpp @@ -357,7 +357,7 @@ void QQuickItemKeyFilter::componentComplete() \qmltype KeyNavigation \instantiates QQuickKeyNavigationAttached \inqmlmodule QtQuick - \ingroup qtquick-input + \ingroup qtquick-input-handlers \brief Supports key navigation by arrow keys. Key-based user interfaces commonly allow the use of arrow keys to navigate between @@ -816,7 +816,7 @@ bool QQuickKeysAttached::isConnected(const char *signalName) const \qmltype Keys \instantiates QQuickKeysAttached \inqmlmodule QtQuick - \ingroup qtquick-input + \ingroup qtquick-input-handlers \brief Provides key handling to Items. All visual primitives support key handling via the Keys |