User Interaction Methods

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 Library > Components > Default Components > Basic.

In addition, you can create instances of preset UI Controls to inform users about the progress of the application or to gather input from users.

The following basic components are available for user interaction:

You can specify values for the properties of component instances in the Properties view.

Mouse Area

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

A mouse area receives events within a defined area. One quick way to define this area is to anchor the mouse area to its parent's area. If the parent is a Rectangle (or any component that is derived from an Item), the mouse area will fill the area defined by the parent's dimensions. Alternatively, you can define an area smaller or larger than the parent. Several controls, such as buttons, contain a mouse area.

A mouse area emits signals in response to different mouse events:

  • canceled()
  • clicked()
  • doubleClicked()
  • entered()
  • exited()
  • positionChanged()
  • pressAndHold()
  • pressed()
  • released()

A more modern way of handling events from all pointing devices, including mouse and touchscreen, is via Qt Quick Input Handlers.

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 Focus property in the Advanced tab is set to true. However, for reusable or imported components, this is not sufficient, and you should use a Focus Scope component.

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 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. Layouts and positioners will use these visual and styling properties to create the layout.

For more information, see Keyboard Focus in Qt Quick.

Flickable

Flickable places its children on a surface that can be dragged and flicked, causing the view onto the child components to scroll. This behavior forms the basis of components that are designed to show large numbers of child components, such as List View and Grid View. For more information, see List and Grid Views.

In traditional user interfaces, views can be scrolled using standard controls, such as scroll bars and arrow buttons. In some situations, it is also possible to 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.

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

"Flickable properties"

Users can interact with a flickable component if the Interactive property is set to true. Set it to 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 Flickable.

The Flick direction field determines whether the view can be flicked horizontally or vertically. Select 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 AutoFlickIfNeeded if the content height or width is greater than that of the flickable.

Specify the maximum velocity for flicking the view in pixels per second in the Max. velocity field. Specify the rate at which a flick will decelerate in the Decelerate field.

The Bounds movement property determines whether the flickable will give a feeling that the edges of the view are soft, rather than a hard physical boundary. Select StopAtBounds for custom edge effects where the contents do not follow drags or flicks beyond the bounds of the flickable. Select FollowBoundsBehavior to have the contents follow drags or flicks beyond the bounds of the flickable depending on the value of the Behavior field.

In the 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 the flickable is dragged or flicked before the delay times out, the press event will not be delivered. If the button is released within the timeout, both the press and release will be 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.

The Pixel aligned property sets the alignment of Content X and Content Y to pixels (true) or subpixels (false). Enable it to optimize for still content or moving content with high constrast edges, such as one-pixel-wide lines, text, or vector graphics. Disable this property when optimizing for animation quality.

If Synchronous drag is set to 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 false, which provides a smoother experience (no jump) at the cost of losing some of the drag distance at the beginning.

The Content size field specifies the dimensions of the surface controlled by a flickable. Typically, set the values of the W and H fields to the combined size of the components placed in the flickable. You can set additional margins around the content in the Margins field.

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

Summary of 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 Library > Components > Default Components > Basic. The MCU column indicates which components are supported on MCUs.

IconNameMCUPurpose
FlickableItems can be flicked horizontally or vertically.
Focus ScopeAssists in keyboard focus handling when building reusable components.
Mouse AreaEnables simple mouse handling.