Struct qt_widgets::QScroller

#[repr(C)]pub struct QScroller { /* fields omitted */ }

The QScroller class enables kinetic scrolling for any scrolling widget or graphics item.

C++ class: QScroller.

C++ documentation:

The QScroller class enables kinetic scrolling for any scrolling widget or graphics item.

With kinetic scrolling, the user can push the widget in a given direction and it will continue to scroll in this direction until it is stopped either by the user or by friction. Aspects of inertia, friction and other physical concepts can be changed in order to fine-tune an intuitive user experience.

The QScroller object is the object that stores the current position and scrolling speed and takes care of updates. QScroller can be triggered by a flick gesture

QWidget *w = ...;
QScroller::grabGesture(w, QScroller::LeftMouseButtonGesture);

or directly like this:

QWidget w = ...;
QScroller scroller = QScroller::scroller(w);
scroller->scrollTo(QPointF(100, 100));

The scrolled QObjects receive a QScrollPrepareEvent whenever the scroller needs to update its geometry information and a QScrollEvent whenever the content of the object should actually be scrolled.

The scroller uses the global QAbstractAnimation timer to generate its QScrollEvents. This can be changed with QScrollerProperties::FrameRate on a per-QScroller basis.

Several examples in the scroller examples directory show how QScroller, QScrollEvent and the scroller gesture can be used.

Even though this kinetic scroller has a large number of settings available via QScrollerProperties, we recommend that you leave them all at their default, platform optimized values. Before changing them you can experiment with the plot example in the scroller examples directory.

Methods

impl QScroller

pub fn slot_set_scroller_properties(
    &self
) -> Receiver<(*const QScrollerProperties,)>

This property holds the scroller properties of this scroller. The properties are used by the QScroller to determine its scrolling behavior.

Returns a built-in Qt slot QScroller::setScrollerProperties that can be passed to qt_core::Signal::connect.

C++ documentation:

This property holds the scroller properties of this scroller. The properties are used by the QScroller to determine its scrolling behavior.

Access functions:

QScrollerProperties	scrollerProperties() const
void	setScrollerProperties(const QScrollerProperties &prop)

Notifier signal:

void	scrollerPropertiesChanged(const QScrollerProperties &newProperties)

pub fn slot_scroll_to(&self) -> Receiver<(*const QPointF,)>

Starts scrolling the widget so that point pos is at the top-left position in the viewport.

Returns a built-in Qt slot QScroller::scrollTo that can be passed to qt_core::Signal::connect.

C++ documentation:

Starts scrolling the widget so that point pos is at the top-left position in the viewport.

The behaviour when scrolling outside the valid scroll area is undefined. In this case the scroller might or might not overshoot.

The scrolling speed will be calculated so that the given position will be reached after a platform-defined time span.

pos is given in viewport coordinates.

See also ensureVisible().

pub fn slot_scroll_to2(&self) -> Receiver<(*const QPointF, c_int)>

This is an overloaded function.

Returns a built-in Qt slot QScroller::scrollTo that can be passed to qt_core::Signal::connect.

C++ documentation:

This is an overloaded function.

This version will reach its destination position in scrollTime milliseconds.

pub fn slot_ensure_visible(
    &self
) -> Receiver<(*const QRectF, c_double, c_double)>

Starts scrolling so that the rectangle rect is visible inside the viewport with additional margins specified in pixels by xmargin and ymargin around the rect.

Returns a built-in Qt slot QScroller::ensureVisible that can be passed to qt_core::Signal::connect.

C++ documentation:

Starts scrolling so that the rectangle rect is visible inside the viewport with additional margins specified in pixels by xmargin and ymargin around the rect.

In cases where it is not possible to fit the rect plus margins inside the viewport the contents are scrolled so that as much as possible is visible from rect.

The scrolling speed is calculated so that the given position is reached after a platform-defined time span.

This function performs the actual scrolling by calling scrollTo().

See also scrollTo().

pub fn slot_ensure_visible2(
    &self
) -> Receiver<(*const QRectF, c_double, c_double, c_int)>

This is an overloaded function.

Returns a built-in Qt slot QScroller::ensureVisible that can be passed to qt_core::Signal::connect.

C++ documentation:

This is an overloaded function.

This version will reach its destination position in scrollTime milliseconds.

pub fn slot_resend_prepare_event(&self) -> Receiver<()>

This function resends the QScrollPrepareEvent. Calling resendPrepareEvent triggers a QScrollPrepareEvent from the scroller. This allows the receiver to re-set content position and content size while scrolling. Calling this function while in the Inactive state is useless as the prepare event is sent again before scrolling starts.

Returns a built-in Qt slot QScroller::resendPrepareEvent that can be passed to qt_core::Signal::connect.

C++ documentation:

This function resends the QScrollPrepareEvent. Calling resendPrepareEvent triggers a QScrollPrepareEvent from the scroller. This allows the receiver to re-set content position and content size while scrolling. Calling this function while in the Inactive state is useless as the prepare event is sent again before scrolling starts.

pub fn state_changed(&self) -> Signal<(State,)>

QScroller emits this signal whenever the state changes. newState is the new State.

Returns a built-in Qt signal QScroller::stateChanged that can be passed to qt_core::Signal::connect.

C++ documentation:

QScroller emits this signal whenever the state changes. newState is the new State.

Note: Notifier signal for property state.

See also state.

pub fn scroller_properties_changed(
    &self
) -> Signal<(*const QScrollerProperties,)>

QScroller emits this signal whenever its scroller properties change. newProperties are the new scroller properties.

Returns a built-in Qt signal QScroller::scrollerPropertiesChanged that can be passed to qt_core::Signal::connect.

C++ documentation:

QScroller emits this signal whenever its scroller properties change. newProperties are the new scroller properties.

Note: Notifier signal for property scrollerProperties.

See also scrollerProperties.

pub unsafe fn active_scrollers() -> CppBox<QListOfQScroller>

Returns an application wide list of currently active QScroller objects. Active QScroller objects are in a state() that is not QScroller::Inactive. This function is useful when writing your own gesture recognizer.

Calls C++ function: static QList<QScroller*> QScroller::activeScrollers().

C++ documentation:

Returns an application wide list of currently active QScroller objects. Active QScroller objects are in a state() that is not QScroller::Inactive. This function is useful when writing your own gesture recognizer.

pub unsafe fn ensure_visible_3a(
    &self,
    rect: impl CastInto<Ref<QRectF>>,
    xmargin: c_double,
    ymargin: c_double
)

Starts scrolling so that the rectangle rect is visible inside the viewport with additional margins specified in pixels by xmargin and ymargin around the rect.

Calls C++ function: [slot] void QScroller::ensureVisible(const QRectF& rect, double xmargin, double ymargin).

C++ documentation:

Starts scrolling so that the rectangle rect is visible inside the viewport with additional margins specified in pixels by xmargin and ymargin around the rect.

In cases where it is not possible to fit the rect plus margins inside the viewport the contents are scrolled so that as much as possible is visible from rect.

The scrolling speed is calculated so that the given position is reached after a platform-defined time span.

This function performs the actual scrolling by calling scrollTo().

See also scrollTo().

pub unsafe fn ensure_visible_4a(
    &self,
    rect: impl CastInto<Ref<QRectF>>,
    xmargin: c_double,
    ymargin: c_double,
    scroll_time: c_int
)

This is an overloaded function.

Calls C++ function: [slot] void QScroller::ensureVisible(const QRectF& rect, double xmargin, double ymargin, int scrollTime).

C++ documentation:

This is an overloaded function.

This version will reach its destination position in scrollTime milliseconds.

pub unsafe fn final_position(&self) -> CppBox<QPointF>

Returns the estimated final position for the current scroll movement. Returns the current position if the scroller state is not Scrolling. The result is undefined when the scroller state is Inactive.

Calls C++ function: QPointF QScroller::finalPosition() const.

C++ documentation:

Returns the estimated final position for the current scroll movement. Returns the current position if the scroller state is not Scrolling. The result is undefined when the scroller state is Inactive.

The target position is in pixel.

See also pixelPerMeter() and scrollTo().

pub unsafe fn grab_gesture_2a(
    target: impl CastInto<Ptr<QObject>>,
    gesture_type: ScrollerGestureType
) -> GestureType

Registers a custom scroll gesture recognizer, grabs it for the target and returns the resulting gesture type. If scrollGestureType is set to TouchGesture the gesture triggers on touch events. If it is set to one of LeftMouseButtonGesture, RightMouseButtonGesture or MiddleMouseButtonGesture it triggers on mouse events of the corresponding button.

Calls C++ function: static Qt::GestureType QScroller::grabGesture(QObject* target, QScroller::ScrollerGestureType gestureType = …).

C++ documentation:

Registers a custom scroll gesture recognizer, grabs it for the target and returns the resulting gesture type. If scrollGestureType is set to TouchGesture the gesture triggers on touch events. If it is set to one of LeftMouseButtonGesture, RightMouseButtonGesture or MiddleMouseButtonGesture it triggers on mouse events of the corresponding button.

Only one scroll gesture can be active on a single object at the same time. If you call this function twice on the same object, it will ungrab the existing gesture before grabbing the new one.

Note: To avoid unwanted side-effects, mouse events are consumed while the gesture is triggered. Since the initial mouse press event is not consumed, the gesture sends a fake mouse release event at the global position (INT_MIN, INT_MIN). This ensures that internal states of the widget that received the original mouse press are consistent.

See also ungrabGesture() and grabbedGesture().

pub unsafe fn grab_gesture_1a(
    target: impl CastInto<Ptr<QObject>>
) -> GestureType

Registers a custom scroll gesture recognizer, grabs it for the target and returns the resulting gesture type. If scrollGestureType is set to TouchGesture the gesture triggers on touch events. If it is set to one of LeftMouseButtonGesture, RightMouseButtonGesture or MiddleMouseButtonGesture it triggers on mouse events of the corresponding button.

Calls C++ function: static Qt::GestureType QScroller::grabGesture(QObject* target).

C++ documentation:

Registers a custom scroll gesture recognizer, grabs it for the target and returns the resulting gesture type. If scrollGestureType is set to TouchGesture the gesture triggers on touch events. If it is set to one of LeftMouseButtonGesture, RightMouseButtonGesture or MiddleMouseButtonGesture it triggers on mouse events of the corresponding button.

Only one scroll gesture can be active on a single object at the same time. If you call this function twice on the same object, it will ungrab the existing gesture before grabbing the new one.

Note: To avoid unwanted side-effects, mouse events are consumed while the gesture is triggered. Since the initial mouse press event is not consumed, the gesture sends a fake mouse release event at the global position (INT_MIN, INT_MIN). This ensures that internal states of the widget that received the original mouse press are consistent.

See also ungrabGesture() and grabbedGesture().

pub unsafe fn grabbed_gesture(
    target: impl CastInto<Ptr<QObject>>
) -> GestureType

Returns the gesture type currently grabbed for the target or 0 if no gesture is grabbed.

Calls C++ function: static Qt::GestureType QScroller::grabbedGesture(QObject* target).

C++ documentation:

Returns the gesture type currently grabbed for the target or 0 if no gesture is grabbed.

See also grabGesture() and ungrabGesture().

pub unsafe fn handle_input_3a(
    &self,
    input: Input,
    position: impl CastInto<Ref<QPointF>>,
    timestamp: i64
) -> bool

This function is used by gesture recognizers to inform the scroller about a new input event. The scroller changes its internal state() according to the input event and its attached scroller properties. The scroller doesn't distinguish between the kind of input device the event came from. Therefore the event needs to be split into the input type, a position and a milli-second timestamp. The position needs to be in the target's coordinate system.

Calls C++ function: bool QScroller::handleInput(QScroller::Input input, const QPointF& position, qint64 timestamp = …).

C++ documentation:

This function is used by gesture recognizers to inform the scroller about a new input event. The scroller changes its internal state() according to the input event and its attached scroller properties. The scroller doesn't distinguish between the kind of input device the event came from. Therefore the event needs to be split into the input type, a position and a milli-second timestamp. The position needs to be in the target's coordinate system.

The return value is true if the event should be consumed by the calling filter or false if the event should be forwarded to the control.

Note: Using grabGesture() should be sufficient for most use cases.

pub unsafe fn handle_input_2a(
    &self,
    input: Input,
    position: impl CastInto<Ref<QPointF>>
) -> bool

This function is used by gesture recognizers to inform the scroller about a new input event. The scroller changes its internal state() according to the input event and its attached scroller properties. The scroller doesn't distinguish between the kind of input device the event came from. Therefore the event needs to be split into the input type, a position and a milli-second timestamp. The position needs to be in the target's coordinate system.

Calls C++ function: bool QScroller::handleInput(QScroller::Input input, const QPointF& position).

C++ documentation:

This function is used by gesture recognizers to inform the scroller about a new input event. The scroller changes its internal state() according to the input event and its attached scroller properties. The scroller doesn't distinguish between the kind of input device the event came from. Therefore the event needs to be split into the input type, a position and a milli-second timestamp. The position needs to be in the target's coordinate system.

The return value is true if the event should be consumed by the calling filter or false if the event should be forwarded to the control.

Note: Using grabGesture() should be sufficient for most use cases.

pub unsafe fn has_scroller(target: impl CastInto<Ptr<QObject>>) -> bool

Returns true if a QScroller object was already created for target; false otherwise.

Calls C++ function: static bool QScroller::hasScroller(QObject* target).

C++ documentation:

Returns true if a QScroller object was already created for target; false otherwise.

See also scroller().

pub unsafe fn meta_object(&self) -> Ptr<QMetaObject>

Calls C++ function: virtual const QMetaObject* QScroller::metaObject() const.

pub unsafe fn pixel_per_meter(&self) -> CppBox<QPointF>

Returns the pixel per meter metric for the scrolled widget.

Calls C++ function: QPointF QScroller::pixelPerMeter() const.

C++ documentation:

Returns the pixel per meter metric for the scrolled widget.

The value is reported for both the x and y axis separately by using a QPointF.

Note: Please note that this value should be physically correct. The actual DPI settings that Qt returns for the display may be reported wrongly on purpose by the underlying windowing system, for example on macOS.

pub unsafe fn qt_metacall(
    &self,
    arg1: Call,
    arg2: c_int,
    arg3: *mut *mut c_void
) -> c_int

Calls C++ function: virtual int QScroller::qt_metacall(QMetaObject::Call arg1, int arg2, void** arg3).

pub unsafe fn qt_metacast(&self, arg1: *const c_char) -> *mut c_void

Calls C++ function: virtual void* QScroller::qt_metacast(const char* arg1).

pub unsafe fn resend_prepare_event(&self)

This function resends the QScrollPrepareEvent. Calling resendPrepareEvent triggers a QScrollPrepareEvent from the scroller. This allows the receiver to re-set content position and content size while scrolling. Calling this function while in the Inactive state is useless as the prepare event is sent again before scrolling starts.

Calls C++ function: [slot] void QScroller::resendPrepareEvent().

C++ documentation:

This function resends the QScrollPrepareEvent. Calling resendPrepareEvent triggers a QScrollPrepareEvent from the scroller. This allows the receiver to re-set content position and content size while scrolling. Calling this function while in the Inactive state is useless as the prepare event is sent again before scrolling starts.

pub unsafe fn scroll_to_1a(&self, pos: impl CastInto<Ref<QPointF>>)

Starts scrolling the widget so that point pos is at the top-left position in the viewport.

Calls C++ function: [slot] void QScroller::scrollTo(const QPointF& pos).

C++ documentation:

Starts scrolling the widget so that point pos is at the top-left position in the viewport.

The behaviour when scrolling outside the valid scroll area is undefined. In this case the scroller might or might not overshoot.

The scrolling speed will be calculated so that the given position will be reached after a platform-defined time span.

pos is given in viewport coordinates.

See also ensureVisible().

pub unsafe fn scroll_to_2a(
    &self,
    pos: impl CastInto<Ref<QPointF>>,
    scroll_time: c_int
)

This is an overloaded function.

Calls C++ function: [slot] void QScroller::scrollTo(const QPointF& pos, int scrollTime).

C++ documentation:

This is an overloaded function.

This version will reach its destination position in scrollTime milliseconds.

pub unsafe fn scroller_q_object(
    target: impl CastInto<Ptr<QObject>>
) -> QPtr<QScroller>

Returns the scroller for the given target. As long as the object exists this function will always return the same QScroller instance. If no QScroller exists for the target, one will implicitly be created. At no point more than one QScroller will be active on an object.

Calls C++ function: static QScroller* QScroller::scroller(QObject* target).

C++ documentation:

Returns the scroller for the given target. As long as the object exists this function will always return the same QScroller instance. If no QScroller exists for the target, one will implicitly be created. At no point more than one QScroller will be active on an object.

See also hasScroller() and target().

pub unsafe fn scroller_q_object2(
    target: impl CastInto<Ptr<QObject>>
) -> QPtr<QScroller>

This is an overloaded function.

Calls C++ function: static const QScroller* QScroller::scroller(const QObject* target).

C++ documentation:

This is an overloaded function.

This is the const version of scroller().

pub unsafe fn scroller_properties(&self) -> CppBox<QScrollerProperties>

This property holds the scroller properties of this scroller. The properties are used by the QScroller to determine its scrolling behavior.

Calls C++ function: QScrollerProperties QScroller::scrollerProperties() const.

C++ documentation:

This property holds the scroller properties of this scroller. The properties are used by the QScroller to determine its scrolling behavior.

Access functions:

QScrollerProperties	scrollerProperties() const
void	setScrollerProperties(const QScrollerProperties &prop)

Notifier signal:

void	scrollerPropertiesChanged(const QScrollerProperties &newProperties)

pub unsafe fn set_scroller_properties(
    &self,
    prop: impl CastInto<Ref<QScrollerProperties>>
)

This property holds the scroller properties of this scroller. The properties are used by the QScroller to determine its scrolling behavior.

Calls C++ function: [slot] void QScroller::setScrollerProperties(const QScrollerProperties& prop).

C++ documentation:

This property holds the scroller properties of this scroller. The properties are used by the QScroller to determine its scrolling behavior.

Access functions:

QScrollerProperties	scrollerProperties() const
void	setScrollerProperties(const QScrollerProperties &prop)

Notifier signal:

void	scrollerPropertiesChanged(const QScrollerProperties &newProperties)

pub unsafe fn set_snap_positions_x_1a(
    &self,
    positions: impl CastInto<Ref<QListOfDouble>>
)

Set the snap positions for the horizontal axis to a list of positions. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an empty list of positions.

Calls C++ function: void QScroller::setSnapPositionsX(const QList<double>& positions).

C++ documentation:

Set the snap positions for the horizontal axis to a list of positions. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an empty list of positions.

pub unsafe fn set_snap_positions_x_2a(
    &self,
    first: c_double,
    interval: c_double
)

Set the snap positions for the horizontal axis to regular spaced intervals. The first snap position is at first. The next at first + interval. This can be used to implement a list header. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an interval of 0.0

Calls C++ function: void QScroller::setSnapPositionsX(double first, double interval).

C++ documentation:

Set the snap positions for the horizontal axis to regular spaced intervals. The first snap position is at first. The next at first + interval. This can be used to implement a list header. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an interval of 0.0

pub unsafe fn set_snap_positions_y_1a(
    &self,
    positions: impl CastInto<Ref<QListOfDouble>>
)

Set the snap positions for the vertical axis to a list of positions. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an empty list of positions.

Calls C++ function: void QScroller::setSnapPositionsY(const QList<double>& positions).

C++ documentation:

Set the snap positions for the vertical axis to a list of positions. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an empty list of positions.

pub unsafe fn set_snap_positions_y_2a(
    &self,
    first: c_double,
    interval: c_double
)

Set the snap positions for the vertical axis to regular spaced intervals. The first snap position is at first. The next at first + interval. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an interval of 0.0

Calls C++ function: void QScroller::setSnapPositionsY(double first, double interval).

C++ documentation:

Set the snap positions for the vertical axis to regular spaced intervals. The first snap position is at first. The next at first + interval. This overwrites all previously set snap positions and also a previously set snapping interval. Snapping can be deactivated by setting an interval of 0.0

pub unsafe fn state(&self) -> State

This property holds the state of the scroller

Calls C++ function: QScroller::State QScroller::state() const.

C++ documentation:

This property holds the state of the scroller

Access functions:

State

state() const

Notifier signal:

void	stateChanged(QScroller::State newState)

See also QScroller::State.

pub unsafe fn static_meta_object() -> Ref<QMetaObject>

Returns a reference to the staticMetaObject field.

pub unsafe fn stop(&self)

Stops the scroller and resets its state back to Inactive.

Calls C++ function: void QScroller::stop().

C++ documentation:

Stops the scroller and resets its state back to Inactive.

pub unsafe fn target(&self) -> QPtr<QObject>

Returns the target object of this scroller.

Calls C++ function: QObject* QScroller::target() const.

C++ documentation:

Returns the target object of this scroller.

See also hasScroller() and scroller().

pub unsafe fn tr(
    s: *const c_char,
    c: *const c_char,
    n: c_int
) -> CppBox<QString>

Calls C++ function: static QString QScroller::tr(const char* s, const char* c, int n).

pub unsafe fn tr_utf8(
    s: *const c_char,
    c: *const c_char,
    n: c_int
) -> CppBox<QString>

Calls C++ function: static QString QScroller::trUtf8(const char* s, const char* c, int n).

pub unsafe fn ungrab_gesture(target: impl CastInto<Ptr<QObject>>)

Ungrabs the gesture for the target. Does nothing if no gesture is grabbed.

Calls C++ function: static void QScroller::ungrabGesture(QObject* target).

C++ documentation:

Ungrabs the gesture for the target. Does nothing if no gesture is grabbed.

See also grabGesture() and grabbedGesture().

pub unsafe fn velocity(&self) -> CppBox<QPointF>

Returns the current scrolling velocity in meter per second when the state is Scrolling or Dragging. Returns a zero velocity otherwise.

Calls C++ function: QPointF QScroller::velocity() const.

C++ documentation:

Returns the current scrolling velocity in meter per second when the state is Scrolling or Dragging. Returns a zero velocity otherwise.

The velocity is reported for both the x and y axis separately by using a QPointF.

See also pixelPerMeter().

Trait Implementations

impl Deref for QScroller

type Target = QObject

The resulting type after dereferencing.

fn deref(&self) -> &QObject

Calls C++ function: QObject* static_cast<QObject*>(QScroller* ptr).

impl DynamicCast<QScroller> for QObject

unsafe fn dynamic_cast(ptr: Ptr<QObject>) -> Ptr<QScroller>

Calls C++ function: QScroller* dynamic_cast<QScroller*>(QObject* ptr).

impl StaticDowncast<QScroller> for QObject

unsafe fn static_downcast(ptr: Ptr<QObject>) -> Ptr<QScroller>

Calls C++ function: QScroller* static_cast<QScroller*>(QObject* ptr).

impl StaticUpcast<QObject> for QScroller

unsafe fn static_upcast(ptr: Ptr<QScroller>) -> Ptr<QObject>

Calls C++ function: QObject* static_cast<QObject*>(QScroller* ptr).