Update book and docs

Author: BenFordTytherington

book/src/SUMMARY.md

@@ -21,6 +21,7 @@ SPDX-License-Identifier: MIT OR Apache-2.0
   - [Types](./concepts/types.md)
   - [Nested Objects](./concepts/nested_objects.md)
   - [Inheritance & Overriding](./concepts/inheritance.md)
+  - [Casting](./concepts/casting.md)
 - [Reference: the bridge module](./bridge/index.md)
   - [`extern "RustQt"`](./bridge/extern_rustqt.md)
   - [`extern "C++Qt"`](./bridge/extern_cppqt.md)

book/src/bridge/extern_rustqt.md

@@ -92,7 +92,7 @@ Use the CXX `include!` macro to include the appropriate C++ header for the base
 {{#include ../../../examples/qml_features/rust/src/custom_base_class.rs:book_base_include}}
 ```
 
-For more information on inheritance and how to override methods see the [Inheritance & Overriding](../concepts/inheritance.md) page.
+For more information on inheritance and how to override methods see the [Inheritance & Overriding](../concepts/inheritance.md) page and the [Casting](../concepts/casting.md) page.
 
 [Full Example](https://github.com/KDAB/cxx-qt/blob/main/examples/qml_features/rust/src/custom_base_class.rs)
 

book/src/bridge/traits.md

@@ -26,3 +26,8 @@ For further documentation, refer to the documentation of the individual traits:
 - [Constructor](https://docs.rs/cxx-qt/latest/cxx_qt/trait.Constructor.html) - custom constructor
 - [Initialize](https://docs.rs/cxx-qt/latest/cxx_qt/trait.Initialize.html) - execute Rust code when the object is constructed
 - [Threading](https://docs.rs/cxx-qt/latest/cxx_qt/trait.Threading.html) - marker trait whether CXX-Qt threading should be enabled
+
+> ⚠️ These traits should only be implemented if you are sure you need to, they are automatically implemented for RustQt types.
+
+- [Upcast](https://docs.rs/cxx-qt/latest/cxx_qt/trait.Upcast.html) - Allows a type to access its parent class if there is one
+- [Downcast](https://docs.rs/cxx-qt/latest/cxx_qt/trait.Downcast.html) - Allows a type to access its child class if there is one

book/src/concepts/casting.md

@@ -0,0 +1,42 @@
+<!--
+SPDX-FileCopyrightText: 2025 Klarälvdalens Datakonsult AB, a KDAB Group company <[email protected]>
+SPDX-FileContributor: Ben Ford <[email protected]>
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+-->
+
+# Casting
+
+With the [base](../bridge/attributes.md) attribute, it is possible to inherit from another type.
+In order to access this parent class, we provide an API to cast up or down.
+Currently, this is only supported for objects in `extern "RustQt"` blocks, which have either a `#[qobject]` attribute,
+or a `#[base = T]` attribute. see [here](../bridge/attributes.md) for more details on these attributes.
+
+## Accessing the base class
+
+To access the methods of a base class in Rust, use the `Upcast` trait like so `use cxx_qt::Upcast;`.
+Objects with base classes can then be accessed with the following methods
+
+| Self Type        | Method         |
+|------------------|----------------|
+| `&self`          | `upcast()`     |
+| `&mut self`      | `upcast_mut()` |
+| `Pin<&mut self>` | `upcast_pin()` |
+
+This will then return a reference to the base in the same format as the self type, e.g. `upcast()` returns `&Base`, etc...
+
+## Accessing the child class
+
+This also works in the opposite direction, allowing access to the child a base class was obtained from.
+To do this, use the `Downcast` trait like so `use cxx_qt::Downcast;`.
+The child can then be accessed in the same manner, with the following methods
+
+| Self Type        | Method           |
+|------------------|------------------|
+| `&self`          | `downcast()`     |
+| `&mut self`      | `downcast_mut()` |
+| `Pin<&mut self>` | `downcast_pin()` |
+
+These will return an `Option<T>`, as it is possible that downcasting will fail,
+if the type is not actually of the given subclass,
+and these also return in the same format as the self type, e.g. `downcast()` returns `Option<&Sub>`, etc...

crates/cxx-qt/src/lib.rs

@@ -127,19 +127,30 @@ pub trait Threading: Sized {
     fn threading_drop(cxx_qt_thread: &mut CxxQtThread<Self>);
 }
 
-/// This trait is automatically implemented by CXX-Qt and should not be manually implemented
-/// Allows upcasting to either QObject or the provided base class of a type
-/// Will not be implemented if no types inherit from QObject or base.
+/// This trait is automatically implemented by CXX-Qt and you most likely do not need to manually implement it.
+/// Allows upcasting to either [QObject] or the provided base class of a type.
+/// Will not be implemented if no types inherit from [QObject] or have the `#[base = T]` attribute.
 pub trait Upcast<T> {
     #[doc(hidden)]
-    /// Internal function, Should not be implemented manually
+    /// # Safety
+    ///
+    /// Internal function, Should probably not be implemented manually unless you're absolutely sure you need it.
+    /// Automatically available for types in RustQt blocks in [cxx_qt::bridge](bridge)s.
+    /// Upcasts a pointer to `Self` to a pointer to the base class `T`.
+    /// > Note: Internal implementation uses `static_cast`.
     unsafe fn upcast_ptr(this: *const Self) -> *const T;
 
     #[doc(hidden)]
-    /// Internal function, Should not be implemented manually
+    /// # Safety
+    ///
+    /// Internal function, Should probably not be implemented manually unless you're absolutely sure you need it.
+    /// Automatically available for types in RustQt blocks in [cxx_qt::bridge](bridge)s.
+    /// Downcasts a pointer to base class `T` to a pointer to `Self`.
+    /// Return a null pointer if `Self` is not actually a child of base.
+    /// > Note: Internal implementation uses `dynamic_cast`.
     unsafe fn from_base_ptr(base: *const T) -> *const Self;
 
-    /// Upcast a reference to a reference to the base class
+    /// Upcast a reference to self to a reference to the base class
     fn upcast(&self) -> &T {
         let ptr = self as *const Self;
         unsafe {
@@ -148,7 +159,7 @@ pub trait Upcast<T> {
         }
     }
 
-    /// Upcast a mutable reference to a mutable reference to the base class
+    /// Upcast a mutable reference to sell to a mutable reference to the base class
     fn upcast_mut(&mut self) -> &mut T {
         let ptr = self as *const Self;
         unsafe {
@@ -157,7 +168,7 @@ pub trait Upcast<T> {
         }
     }
 
-    /// Upcast a pinned mutable reference to a pinned mutable reference to the base class
+    /// Upcast a pinned mutable reference to self to a pinned mutable reference to the base class
     fn upcast_pin(self: Pin<&mut Self>) -> Pin<&mut T> {
         let this = self.deref() as *const Self;
         unsafe {
@@ -167,9 +178,11 @@ pub trait Upcast<T> {
     }
 }
 
-/// Trait for downcasting to a subclass, provided the subclass implements Upcast to this type
+/// This trait is automatically implemented by CXX-Qt and you most likely do not need to manually implement it.
+/// Trait for downcasting to a subclass, provided the subclass implements [Upcast] to this type.
+/// Returns `None` in cases where `Sub` isn't a child class of `Self`.
 pub trait Downcast: Sized {
-    /// try Downcast to a subclass of this, given that the subclass upcasts to this type
+    /// Try to downcast to a subclass of this type, given that the subclass upcasts to this type
     fn downcast<Sub: Upcast<Self>>(&self) -> Option<&Sub> {
         unsafe {
             let ptr = Sub::from_base_ptr(self as *const Self);
@@ -181,7 +194,7 @@ pub trait Downcast: Sized {
         }
     }
 
-    /// try Downcast mutably to a subclass of this, given that the subclass upcasts to this type
+    /// Try to downcast mutably to a subclass of this, given that the subclass upcasts to this type
     fn downcast_mut<Sub: Upcast<Self>>(&mut self) -> Option<&mut Sub> {
         unsafe {
             let ptr = Sub::from_base_ptr(self as *const Self) as *mut Sub;
@@ -193,7 +206,7 @@ pub trait Downcast: Sized {
         }
     }
 
-    /// try Downcast a pin to a pinned subclass of this, given that the subclass upcasts to this type
+    /// Try to downcast a pin to a pinned subclass of this, given that the subclass upcasts to this type
     fn downcast_pin<Sub: Upcast<Self>>(self: Pin<&mut Self>) -> Option<Pin<&mut Sub>> {
         let this = self.deref() as *const Self;
         unsafe {
@@ -207,6 +220,7 @@ pub trait Downcast: Sized {
     }
 }
 
+/// Automatic implementation of Downcast for any applicable types
 impl<T: Sized> Downcast for T {}
 
 /// This trait can be implemented on any [CxxQtType] to define a