Struct qt_core::QPtr

pub struct QPtr<T: StaticUpcast<QObject>> { /* fields omitted */ }

A smart pointer that automatically resets when the object is deleted.

QPtr exposes functionality provided by the QPointer<T> C++ class. QPtr can only contain a pointer to a QObject-based object. When that object is deleted, QPtr automatically becomes a null pointer.

Note that dereferencing a null QPtr will panic, so if it's known that the object may already have been deleted, you should use is_null(), as_ref(), or a similar method to check if the object is still alive before calling its methods.

QPtr is not an owning pointer, similar to cpp_core::Ptr. If you actually own the object, you should convert it to QBox (it will delete the object when dropped if it has no parent) or CppBox (it will always delete the object when dropped). QPtr provides into_qbox and to_box helpers for that.

Safety

While QPtr is much safer than cpp_core::Ptr and prevents use-after-free in common cases, it is unsafe to use in Rust terms. QPtr::new must receive a valid pointer or a null pointer, otherwise the behavior is undefined. You should not store pointers of other types (e.g. Ptr, Ref, or raw pointers) produced by QPtr because, unlike QPtr, these pointers will not become null pointers when the object is deleted.

It's still possible to cause use-after-free by calling a method through QPtr. Even in a single threaded program, the accessed object can be deleted by a nested call while one of its methods is still running. In multithreaded context, the object can be deleted in another thread between the null check and the method call, also resulting in undefined behavior.

Methods

impl<T: StaticUpcast<QObject>> QPtr<T>

pub unsafe fn new(target: impl CastInto<Ptr<T>>) -> Self

Creates a QPtr from a Ptr.

Safety

target must be either a valid pointer to an object or a null pointer. See type level documentation.

pub unsafe fn from_raw(target: *const T) -> Self

Creates a QPtr from a raw pointer.

Safety

target must be either a valid pointer to an object or a null pointer. See type level documentation.

pub unsafe fn null() -> Self

Creates a null pointer.

Note that you can also use NullPtr to specify a null pointer to a function accepting impl CastInto<Ptr<_>>. Unlike Ptr, NullPtr is not a generic type, so it will not cause type inference issues.

Note that accessing the content of a null QPtr through Deref will result in a panic.

Safety

Null pointers must not be dereferenced. See type level documentation.

pub unsafe fn is_null(&self) -> bool

Returns true if the pointer is null.

pub unsafe fn as_ptr(&self) -> Ptr<T>

Returns the content as a const Ptr.

Safety

See type level documentation.

pub unsafe fn as_raw_ptr(&self) -> *const T

Returns the content as a raw const pointer.

Safety

See type level documentation.

pub unsafe fn as_ref(&self) -> Option<Ref<T>>

Returns the content as a const Ref. Returns None if self is a null pointer.

Safety

See type level documentation.

pub unsafe fn static_upcast<U>(&self) -> QPtr<U> where
    T: StaticUpcast<U>,
    U: StaticUpcast<QObject>, 

Converts the pointer to the base class type U.

Safety

This operation is safe as long as self is valid or null. See type level documentation.

pub unsafe fn static_downcast<U>(&self) -> QPtr<U> where
    T: StaticDowncast<U>,
    U: StaticUpcast<QObject>, 

Converts the pointer to the derived class type U.

It's recommended to use dynamic_cast instead because it performs a checked conversion.

Safety

This operation is safe as long as self is valid and it's type is U or inherits from U, of if self is a null pointer. See type level documentation.

pub unsafe fn dynamic_cast<U>(&self) -> QPtr<U> where
    T: DynamicCast<U>,
    U: StaticUpcast<QObject>, 

Converts the pointer to the derived class type U. Returns None if the object's type is not U and doesn't inherit U.

Safety

This operation is safe as long as self is valid or null. See type level documentation.

Trait Implementations

impl<'a, T: StaticUpcast<QObject>> AsReceiver for &'a QPtr<T> where
    T: AsReceiver, 

type Arguments = <T as AsReceiver>::Arguments

fn as_receiver(&self) -> Receiver<Self::Arguments>

impl<'a, T, U> CastFrom<&'a QPtr<U>> for Ptr<T> where
    U: StaticUpcast<T> + StaticUpcast<QObject>, 

unsafe fn cast_from(value: &'a QPtr<U>) -> Self

Performs the conversion.

impl<T, U> CastFrom<QPtr<U>> for Ptr<T> where
    U: StaticUpcast<T> + StaticUpcast<QObject>, 

unsafe fn cast_from(value: QPtr<U>) -> Self

Performs the conversion.

impl<T: StaticUpcast<QObject>> Clone for QPtr<T>

Creates another pointer to the same object.

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: StaticUpcast<QObject>> Debug for QPtr<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: StaticUpcast<QObject>> Deref for QPtr<T>

Allows to call member functions of T and its base classes directly on the pointer.

Panics if the pointer is null.

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.