qtbridge_interfaces/

lib.rs

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only

//! # Qt Interfaces (Internal Documentation)
//!
//! This crate provides proxies for various Qt (C++) interfaces using Cxx.
//! Proxies serve as the bridge between Rust and C++ implementations of Qt
//! interfaces, allowing Rust types to implement behavior expected by C++
//! code and to access C++ functionality from Rust.
//!
//! ## The proxy
//!
//! Each Qt interface has a corresponding **proxy** in Rust. This proxy has
//! to implement the [`qtbridge_runtime::qproxies::QRustProxy`] trait and interacts mostly with
//! the [`qtbridge_runtime::QObjectHolder`] trait, that is automatically implemented for all
//! user types by the `qobject` macro.
//!
//! The demands on proxies are baked into the [`qtbridge_runtime::qproxies::QRustProxy`] trait.
//! For example, there
//! is the demand to provide a Qt static meta object, usually from the "base" this proxy
//! is derived from. Further, the proxy has to provide a marker trait called `AdapterType`
//! that is at a minimum used to store a reference to the user object as
//! `Rc<RefCell<dyn AdapterType>>`. Otherwise the proxy is mostly free in its design.
//!
//! All proxies provided in this module follow a similar architecture. The proxy works
//! together with a set of traits. The QObject proxy is very different since it is the
//! proxy that is used if only QMetaObject functionality needs to be provided but no
//! interface implementation.
//!
//! ## Traits
//!
//! 1. **User-implemented functionality**: Rust implementations of Qt virtual functions.
//! 2. **Rust access to C++ functionality**: Rust wrappers around C++ methods of the interface.
//! 3. **Internal type erasure and proxy plumbing**: Allows dynamic behavior when types
//!    are not fully known at compile time.
//!
//! These proxies rely on the following Rust traits to define functionality and structure,
//! shown on the example of `QListModel`.
//!
//! ### 1. `QListModel`
//! * **Responsibility**: Must be implemented by the user.
//! * **Purpose**: Functions in this trait are called from C++ via the proxy, providing Rust
//!   implementations of Qt virtual functions. Some modifications can be done in the functions
//!   to shape the API and to erase Qt types (e.g. QVariant and QModelIndex).
//! * **Associated Types**: Defines types (e.g., `Item`) that are part of the interface contract.
//! * **Notes**: Users implement function as expected from the Qt API. Default implementation
//!   can exist for non-pure virtual functions.
//!
//! ### 2. `QListModelBase`
//! * **Responsibility**: Default / blank implementation for all `QListModel`.
//! * **Purpose**: Provides access to C++ functions from Rust and other convenience functions
//!   that should not be overridden. Serves as a bridge between user logic and C++ functionality.
//!   Functions that should not be overridden by the user are implemented here.
//! * **Notes**: This trait forms the core Rust interface to call C++ functions for types implementing
//!   `QListModel`.
//!
//! ### 3. `QListModelAdapter` (Internal Only)
//! * **Responsibility**: Default / blank implementation for all `QListModel`.
//! * **Purpose**: Provides a type-erased interface for internal machinery. Traits with associated
//!   types (like `QListModel::Item`) cannot be used as `dyn` traits in Rust. `QListModelAdapter`
//!   erases unknown types while exposing the necessary interface internally.
//! * **Notes**: Never meant for user implementation or usage. Facilitates dynamic behavior and
//!   internal bridging without exposing associated types to user code.
//!
//! ## Memory Ownership and Lifetimes
//!
//! Every instance of a user-defined Rust struct annotated with `#[qobject]`
//! has two auxiliary parts invisible to the user:
//!
//! - **`CppProxy`** - a C++ class derived from `QObject` or `QAbstractItemModel` (or another base
//!   interface). This is the object the QML engine sees and interacts with. It is allocated with
//!   a regular `new` for Rust-created objects, or with placement `new` at a QML-engine-supplied
//!   address for QML-created elements.
//! - **[`RustProxy`](crate::genericrustproxy::GenericRustProxy)** - the Rust-side bridge,
//!   heap-allocated via [`Box::into_raw`] in
//!   [`QRustProxy::new`](qtbridge_runtime::qproxies::QRustProxy::new). It holds a pointer to
//!   `CppProxy` and, in [`RustObjAccess`], the strong `Rc<RefCell<UserStruct>>` that keeps the
//!   user struct alive.
//!
//! A user struct therefore lives exactly as long as its `QObject`, plus any user handles,
//! which are plain `Rc<RefCell<UserStruct>>`s. There is one teardown chain, no matter who
//! initiates the deletion:
//!
//! ```text
//! QObject dies (the engine, a parent, or registry::collect_garbage())
//!   → virtual ~CppProxy()
//!     → GenericRustProxy::drop_self
//!       → on_drop() (removes the registry entry)
//!       → RustProxy drops its Rc
//!         → UserStruct::drop()          (only if this was the last strong Rc)
//! ```
//!
//! Who may initiate the deletion is the registry's policy: the per-entry owner state,
//! the `CppOwnership` pin for Rust-created objects, and the collection rules live in
//! `qtbridge_runtime::registry`.

pub mod genericrustproxy;
pub use qtbridge_runtime::live_proxy_count;

pub mod qobject;

pub mod qabstract_item_model;
pub use qabstract_item_model::{QAbstractItemModel, QAbstractItemModelBase};

pub mod qlist_model;
pub use qlist_model::{QListModel, QListModelBase};

pub mod qparser_status;
pub use qparser_status::QParserStatus;

pub mod qtable_model;
pub use qtable_model::{QTableModel, QTableModelBase};

pub mod object_access;
pub use object_access::rust_object_access::RustObjAccess;