BoundaryRule QML Type | Qt Quick | Qt 6.10.3
Description: Defines a restriction on the range of values that can be set on a numeric property.

- Qt 6.10
- Qt Quick
- QML Types
- Qt.labs.animation
- BoundaryRule
- Qt 6.10.3 Reference Documentation

# BoundaryRule QML Type

Defines a restriction on the range of values that can be set on a numeric property. More...

Import Statement: | `import Qt.labs.animation`

- List of all members, including inherited members

## Properties

- currentOvershoot : real
- easing : enumeration
- enabled : bool
- maximum : real
- maximumOvershoot : real
- minimum : real
- minimumOvershoot : real
- overshootFilter : enumeration
- overshootScale : real
- peakOvershoot : real
- returnDuration : int

## Signals

- returnedToBounds()

## Methods

- bool returnToBounds()

## Detailed Description

A BoundaryRule defines the range of values that a particular property is allowed to have. When an out-of-range value would otherwise be set, it applies "resistance" via an easing curve.

For example, the following BoundaryRule prevents DragHandler from dragging the Rectangle too far:

     import QtQuick
     import Qt.labs.animation

     Rectangle {
         id: root
         width: 170; height: 120
         color: "green"

         DragHandler {
             id: dragHandler
             yAxis.minimum: -1000
             xAxis.minimum: -1000
             onActiveChanged: if (!active) xbr.returnToBounds();
         }

         BoundaryRule on x {
             id: xbr
             minimum: -50
             maximum: 100
             minimumOvershoot: 40
             maximumOvershoot: 40
         }
     }

Note that a property cannot have more than one assigned BoundaryRule.

See also Animation and Transitions in Qt Quick, Behavior example, Qt Qml, and Qt Quick Examples - Pointer Handlers.

## Property Documentation

currentOvershoot : real

This property holds the amount by which the most recently set value of the intercepted property exceeds maximum or is less than minimum.

It is positive if the property value exceeds maximum, negative if the property value is less than minimum, or 0 if the property value is within both boundaries.

easing : enumeration

This property holds the easing curve to be applied in overshoot mode (whenever the minimum or maximum constraint is violated, while the value is still within the respective overshoot range).

The default easing curve is QEasingCurve::OutQuad.

enabled : bool

This property holds whether the rule will be enforced when the tracked property changes value.

By default a BoundaryRule is enabled.

maximum : real

This property holds the largest unconstrained value that the property is allowed to have. If the property is set to a larger value, it will be constrained by easing and maximumOvershoot.

The default is `1`.

maximumOvershoot : real

This property holds the amount that the property is allowed to be more than maximum. Whenever the value is greater than maximum and less than `maximum + maximumOvershoot`, it is constrained by the easing curve. When the value attempts to exceed `maximum + maximumOvershoot` there is a hard stop.

The default is 0.

minimum : real

This property holds the smallest unconstrained value that the property is allowed to have. If the property is set to a smaller value, it will be constrained by easing and minimumOvershoot.

The default is `0`.

minimumOvershoot : real

This property holds the amount that the property is allowed to be less than minimum. Whenever the value is less than minimum and greater than `minimum - minimumOvershoot`, it is constrained by the easing curve. When the value attempts to go under `minimum - minimumOvershoots` there is a hard stop.

The default is `0`.

overshootFilter : enumeration

This property specifies the aggregation function that will be applied to the intercepted property value.

If this is set to `BoundaryRule.None` (the default), the intercepted property will hold a value whose overshoot is limited to currentOvershoot. If this is set to `BoundaryRule.Peak`, the intercepted property will hold a value whose overshoot is limited to peakOvershoot.

overshootScale : real

This property holds the amount by which the easing is scaled during the overshoot condition. For example if an Item is restricted from moving more than 100 pixels beyond some limit, and the user (by means of some Input Handler) is trying to drag it 100 pixels past the limit, if overshootScale is set to 1, the user will succeed: the only effect of the easing curve is to change the rate at which the item moves from overshoot 0 to overshoot 100. But if it is set to 0.5, the BoundaryRule provides resistance such that when the user tries to move 100 pixels, the Item will only move 50 pixels; and the easing curve modulates the rate of movement such that it may move in sync with the user's attempted movement at the beginning, and then slows down, depending on the shape of the easing curve.

The default is 0.5.

peakOvershoot : real

This property holds the most-positive or most-negative value of currentOvershoot that has been seen, until returnToBounds() is called.

This can be useful when the intercepted property value is known to fluctuate, and you want to find and react to the maximum amount of overshoot rather than to the fluctuations.

See also overshootFilter.

returnDuration : int

This property holds the amount of time in milliseconds that returnToBounds() will take to return the target property to the nearest bound. If it is set to 0, returnToBounds() will set the property immediately rather than creating an animation job.

The default is 100 ms.

## Signal Documentation

returnedToBounds()

This signal is emitted when currentOvershoot returns to `0` again, after the maximum or minimum constraint has been violated. If the return is animated, the signal is emitted when the animation completes.

Note: The corresponding handler is `onReturnedToBounds`.

See also returnDuration and returnToBounds().

## Method Documentation

bool returnToBounds()

Returns the intercepted property to a value between minimum and maximum, such that currentOvershoot and peakOvershoot are both zero. This will be animated if returnDuration is greater than zero.

Returns true if the value needed to be adjusted, or false if it was already within bounds.

See also returnedToBounds.