// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page quick-user-interaction-methods.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-design-qtquick-components

    \title Add interaction to UIs

    You can create instances of preset basic components to add interaction
    methods to UIs, such as performing actions by using a pointing device or
    the keyboard, or flicking the visible area of the screen horizontally or
    vertically. They are availabe in \uicontrol Components >
    \uicontrol {Default Components} > \uicontrol Basic.

    In addition, you can create instances of preset \l{Insert UI controls}
    {UI controls} to inform users about the progress of the application or to
    collect input from users.

    The following basic components are available for user interaction:

    \list
        \li \l {Create mouse areas}{Mouse Area}
        \li \l {Set focus scope}{Focus Scope}
        \li \l {Create flickable components}{Flickable}
        \li \l {Summary of the basic interaction methods}
    \endlist

    You can specify values for the properties of component instances in the
    \uicontrol {Properties} view.

    \section1 Create mouse areas

    Signals and handlers are used to deliver mouse interactions. Specifically,
    you can use a \uicontrol {Mouse Area} component to define JavaScript
    callbacks (also called signal handlers), which accept mouse events within
    a defined area.

    One quick way to define a mouse area is to select a component and then
    select \uicontrol {Add Mouse Area} in the context menu. This
    \l{Set anchors and margins}{anchors} the mouse area to its parent's area.
    If the parent is a \l {Rectangle} (or any component that is derived from an
    \l {basic-item}{Item}), the mouse area fills the area defined by the parent's
    dimensions.

    You can also define an area smaller or larger than the parent. Several
    controls, such as \l {Button}{buttons}, contain a mouse area.

    \section2 Predefined signals

    A mouse area emits \l{Connect components to signals}{signals} in response
    to different mouse events:

    \list
        \li \c canceled()
        \li \c clicked()
        \li \c doubleClicked()
        \li \c entered()
        \li \c exited()
        \li \c positionChanged()
        \li \c pressAndHold()
        \li \c pressed()
        \li \c released()
    \endlist

    \section2 Enable a mouse area

    A \uicontrol {Mouse Area} is an invisible component that you typically use
    in conjunction with a visible component in order to provide mouse handling
    for that component. By effectively acting as a proxy, the logic for mouse
    handling can be contained within a \uicontrol {Mouse Area} component.

    To create a mouse area:

    \list
        \li Select a component in the \uicontrol Navigator or \uicontrol 2D view,
            and then select \uicontrol {Add Mouse Area} in the context menu.
        \li Drag the \uicontrol {Mouse Area} component from \uicontrol Components:
            \list 1
                \li Go to \uicontrol Components > \uicontrol {Default Components} >
                    \uicontrol Basic.
                \li Drag a \uicontrol {Mouse Area} component to another component in the
                    \uicontrol Navigator or \uicontrol 2D view.
            \endlist
    \endlist

    In \uicontrol Properties, in the \uicontrol {Mouse Area} section,
    \uicontrol Area enables mouse handling for the proxied component.

    \image {qtquick-properties-mouse-area.png} {Mouse Area properties.}

    \section2 Set hovering

    By default, \uicontrol {Mouse Area} components only report mouse
    clicks and not changes to the position of the mouse cursor. Select
    \uicontrol Hover to ensure that the appropriate handlers are used and
    the values of other properties are updated as necessary even when no
    mouse buttons are pressed.

    \section2 Make mouse areas transparent to mouse events

    Even though \uicontrol {Mouse Area} is an invisible component, it has a
    \uicontrol Visible property. Clear \uicontrol Visible in
    the \uicontrol Visibility section to make the mouse area transparent to
    mouse events.

    \section2 Respond to mouse buttons

    In the \uicontrol {Mouse Area} section, \uicontrol {Accepted buttons} field,
    select the mouse button that the mouse area reacts to.

    Select \uicontrol AllButtons to have the mouse area react to all mouse buttons.

    You can add support for more buttons in the \uicontrol {Code} view,
    \uicontrol Edit mode, or \uicontrol {Binding Editor} by combining the
    values with the OR operator (|). For more information about the available
    values, see \l {MouseArea::acceptedButtons}.

    \image {qtquick-properties-mouse-area-accepted-buttons.webp} {Adding accepted buttons in Binding Editor.}

    \section2 Set cursor shape

    In the \uicontrol {Cursor shape} field, select the cursor shape for this
    mouse area. On platforms that do not display a mouse cursor, this value
    may have no effect.

    \section2 Set signal hold interval

    In the \uicontrol {Hold interval} field, specify a value to override the
    elapsed time in milliseconds before the \c pressAndHold() signal is emitted.
    If you do not explicitly set the value or it is reset, it follows the
    globally set application style hint. Set this value if you need particular
    intervals for particular \uicontrol {Mouse Area} instances.

    \section2 Respond to scroll gestures

    Select \uicontrol {Scroll gesture} to respond to scroll
    gestures from non-mouse devices, such as the 2-finger flick gesture on
    a trackpad. If the checkbox is not selected, the wheel signal is emitted
    only when the wheel event comes from an actual mouse with a wheel, while
    scroll gesture events will pass through to any other component that will
    handle them.

    For example, the user might perform a flick gesture while the
    cursor is over a component containing a \uicontrol {Mouse Area} instance,
    intending to interact with a \uicontrol Flickable component which is
    underneath. Setting this property to \c false will allow the \l PinchArea
    component to handle the mouse wheel or the pinch gesture, while the
    \uicontrol Flickable handles the flick gesture.

    \section2 Propagate events

    Information about the mouse position and button clicks are provided via
    signals for which event handler properties are defined. If a mouse area
    overlaps with the area of other instances of the \uicontrol {Mouse Area}
    components, you can propagate \c clicked(), \c doubleClicked(), and
    \c pressAndHold() events to these other components by selecting
    \uicontrol {Propagate events}. Each event is propagated to the
    next enabled \uicontrol {Mouse Area} beneath it in the stacking order,
    propagating down this visual hierarchy until a \uicontrol {Mouse Area}
    accepts the event.

    \section2 Prevent stealing

    You can place a \uicontrol {Mouse Area} instance within a component that
    filters child mouse events, such as \uicontrol Flickable. However, the
    mouse events might get stolen from the \uicontrol {Mouse Area} if a gesture,
    such as a flick, is recognized by the parent component.

    Select \uicontrol {Prevent stealing} to stop mouse events from
    being stolen from the \uicontrol {Mouse Area} instance. This value will take
    no effect until the next \c press() event if it is set once a component has
    started stealing events.

    For more information, see \l {MouseArea}.

    \section2 Set drag properties

    Specify properties for dragging components in the \uicontrol Drag
    section. Select the component to drag in the \uicontrol Target field.
    Keep in mind that anchored components cannot be dragged.

    \image {qtquick-properties-mouse-area-drag.png} {Mouse Area Drag properties.}

    In the \uicontrol Axis field, specify whether dragging can be done
    horizontally, vertically, or both.

    In the \uicontrol Threshold field, set the threshold in pixels of when the
    drag operation should start. By default, this value is bound to a platform
    dependent value.

    Select \uicontrol {Filter children} to enable dragging to
    override descendant \uicontrol {Mouse Area} instances. This enables a
    parent \uicontrol {Mouse Area} instance to handle drags, for example, while
    the descendant areas handle clicks.

    Select \uicontrol Smoothed to move the target component only
    after the drag operation has started. If this checkbox is not selected, the
    target component is moved straight to the current mouse position.

    \section1 Set focus scope

    When a key is pressed or released, a key event is generated and delivered
    to the focused component. If no component has active focus, the key event
    is ignored. If the component with active focus accepts the key event,
    propagation stops. Otherwise the event is sent to the component's parent
    until the event is accepted, or the root component is reached and the event
    is ignored.

    A component has focus when the \uicontrol Focus property in the
    \uicontrol Advanced section is set to \c true. However, for reusable
    or imported components, this is not sufficient, and you should use
    a \uicontrol {Focus Scope} component.

    To create an instance of a \uicontrol {Focus Scope} component, go to
    \uicontrol Components > \uicontrol {Default Components} > \uicontrol Basic.

    Within each focus scope, one object may have focus enabled. If more
    than one component have it enabled, the last component to enable it
    will have the focus and the others are unset, similarly to when there
    are no focus scopes.

    When a focus scope receives active focus, the contained component with
    focus set (if any) also gets the active focus. If this component is
    also a focus scope, both the focus scope and the sub-focused component
    will have active focus.

    The \uicontrol {Focus Scope} component is not a visual component and
    therefore the properties of its children need to be exposed to the parent
    component of the focus scope. \l{Use layouts}{Layouts} and
    \l{Make layouts scalable}{positioners} will use these visual and styling
    properties to create the layout.

    For more information, see \l {Keyboard Focus in Qt Quick}.

    \section1 Create flickable components

    A \uicontrol Flickable component places its children on a surface that users
    can drag and flick, causing the view onto the child components to scroll.
    This behavior forms the basis of components that show large
    numbers of child components, such as \uicontrol {List View} and
    \uicontrol {Grid View}. For more information, see \l{List Views and Grid Views}.

    In traditional user interfaces, users can scroll views using standard
    controls, such as scroll bars and arrow buttons. Sometimes, they can
    drag the view directly by pressing and holding a mouse button while
    moving the cursor. In touch-based user interfaces, this dragging action
    is often complemented with a flicking action, where
    scrolling continues after the user has stopped touching the view.

    \section2 Clipping flickable components

    The contents of a \uicontrol Flickable component are not automatically
    clipped. If the component is not used as a full-screen component, consider
    selecting \uicontrol Clip in the \uicontrol Visibility
    section.

    \section2 Enable flicking

    To create a flickable component:

    \list 1
        \li Go to \uicontrol Components > \uicontrol {Default Components} >
            \uicontrol Basic.
        \li Drag a \uicontrol Flickable component to the \uicontrol Navigator or
            \uicontrol 2D view.
        \li In the \uicontrol Flickable section, set \uicontrol Interactive to
            \c true.
            \image {qtquick-designer-flickable-properties.png} {Flickable properties.}
    \endlist

    Set \uicontrol Interactive to \c false to temporarily disable
    flicking. This enables special interaction with the component's children.
    For example, you might want to freeze a flickable map while scrolling
    through a pop-up that is a child of the \uicontrol Flickable component.

    \section2 Set flick direction

    In the \uicontrol Flickable section, set \uicontrol {Flick direction} to
    determine whether users can flick the view horizontally or vertically.

    Select \uicontrol AutoFlickDirection
    to enable flicking vertically if the content height is not equal to height
    of the flickable and horizontally if the content width is not equal
    to the width of the flickable.

    Select \uicontrol AutoFlickIfNeeded if
    the content height or width is greater than that of the flickable.

    \section2 Set flick velocity

    In the \uicontrol Flickable section, set the maximum velocity for flicking
    the view in pixels per second in the \uicontrol {Max. velocity} field.

    Set the rate at which a flick will decelerate in the \uicontrol Deceleration
    field.

    \section2 Set movement

    In the \uicontrol Flickable section, set the value of the \uicontrol Movement
    field to determine whether the flickable makes the edges of the view seem
    soft, rather than a hard physical boundary.

    Select \uicontrol StopAtBounds for custom edge effects
    where the contents do not follow drags or flicks beyond the bounds of the
    flickable.

    Select \uicontrol FollowBoundsBehavior to have the contents
    follow drags or flicks beyond the bounds of the flickable depending on the
    value of the \uicontrol Behavior field.

    In the \uicontrol {Press delay} field, specify the time in milliseconds
    to delay delivering a press to children of a flickable. This can be useful
    when reacting to a press before a flicking action has undesirable effects.
    If users drag or flick the flickable before the delay times out,
    the press event is not delivered. If the button is released
    within the timeout, both the press and release are delivered.

    \note For nested flickables with press delay set, the press delay of
    outer flickables is overridden by the innermost flickable. If the drag
    exceeds the platform drag threshold, the press event will be delivered
    regardless of this property.

    \uicontrol {Pixel aligned} sets the unit of alignment set in
    the \uicontrol Content \uicontrol X and \uicontrol Y fields to pixels
    (\c true) or subpixels (\c false). Set it to \c true to optimize for still
    content or moving content with high constrast edges, such as one-pixel-wide
    lines, text, or vector graphics. Set it to \c false when optimizing for
    animation quality.

    If \uicontrol {Synchronous drag} is set to \c true, then when the mouse or
    touchpoint moves far enough to begin dragging the content, the content will
    jump, so that the content pixel which was under the cursor or touchpoint
    when pressed remains under that point. The default is \c false, which
    provides a smoother experience (no jump) at the cost of losing some of the
    drag distance at the beginning.

    \section2 Set Flickable geometry

    In the \uicontrol {Flickable Geometry} section, the \uicontrol {Content size}
    field specifies the dimensions of the surface controlled by a flickable.
    Typically, you set the values of the
    \uicontrol W and \uicontrol H fields to the combined size of the components
    placed in the flickable. You can set additional margins around the
    content in the \uicontrol {Left margin}, \uicontrol {Right margin},
    \uicontrol {Top margin}, and \uicontrol {Bottom margin} fields.

    \image {qtquick-designer-flickable-geometry.png} {Flickable geometry properties.}

    The \uicontrol Origin field specifies the origin of the content. It
    refers to the top-left position of the content regardless of layout
    direction. Usually, the \uicontrol X and \uicontrol Y values are set to 0.
    However, a \l{ListView}{List View} and \l {GridView}{Grid View}
    may have an arbitrary origin due to delegate size variation, or component
    insertion or removal outside the visible region.

    \section1 Summary of the basic interaction methods

    The following table lists the components that you can use to add basic
    interaction methods to UIs with links to their developer documentation.
    They are availabe in \uicontrol Components >
    \uicontrol {Default Components} > \uicontrol Basic. The \e {MCU support} column
    indicates which components are supported on MCUs.

    \table
    \header
        \li Icon
        \li Name
        \li MCU support
        \li Purpose
    \row
        \li \imageflickableicon16
        \li \l [QML]{Flickable}
        \li Yes
        \li Enables flicking components horizontally or vertically.
    \row
        \li \imagefocusscopeicon16
        \li \l{FocusScope}{Focus Scope}
        \li No
        \li Assists in keyboard focus handling when building reusable
            components.
    \row
        \li \imagemouseareaicon16
        \li \l [QtQuick]{MouseArea}{Mouse Area}
        \li Yes
        \li Enables simple mouse handling.
    \endtable

    \sa {Use UI components}{How to: Use UI components}, {Qt Quick UI design},
    {Designing Qt Quick UIs}
*/
