API improvements for solving duality of types and related changes

[ahayzen-kdab]

Problems

• How do we define signals on foreign QObjects? (eg QButton) - Add extern "Qt" - allow signals on existing Qt classes #527
• Dualility of a Rust struct + C++ type is not know to the dev
• How do we run Rust code in a C++ context in a constructor? - Have a handle_init / handle_destroy function and trait #13 `Constructor` trait to allow non-`Default` QObjects #339
• How do we define a different type for the parent param - Need to be able to choose the parent when deriving from different bases #474
• How do we define constructors with custom parameters - `Constructor` trait to allow non-`Default` QObjects #339
• Re-exporting of qobject::T causes problems when we have two bridges - Consider supporting multiple macro mod blocks #294
• Re-exporting of qobject::T casues problems for documentation - Generated qobject module has no documentation, triggering #![warn(missing_docs)] #517 Generated documentation doesn't show up on qobject::T #529
• Enums for signals don't match perfectly and create a match, when they are just normal functions this causes property_changed or inheriting of signals to be odd - Add extern "Qt" - allow signals on existing Qt classes #527
• Do we still want cxx_type as direct macros to signals would lose this Consider if cxx_type and return_cxx_type are still required #289
• CXX supports Result<T, E> and anything where impl Display for T (eg anyhow::Result<T>) as the Rust method return type, but then in the CXX bridge this is written as Result<T> they do this by writing the API differently in the extern block Support Result<T, E> as a return type from Rust -> C++ #404 https://cxx.rs/binding/result.html#returning-result-from-rust-to-c

High level solutions

• Point the Rust struct and C++ type to the same memory space (aka have one "type")
• Require the dev to be explicit about the C++ type

Combining struct and type

If the Rust struct and C++ class happened to have space matching each other they could share the same memory space.

This would mean that we wouldn't need two structs, however

• This would be tricky to figure out the size of each others memory
• We would need to prevent direct construction of the struct
• We need to inject space into either size
• What happens if a trait is implemented on the struct?

Instead of sharing the exact same memory space there could be a wrapper.

struct MyObjectInner {
  #[qproperty]
  prop: i32
}

struct MyObject {
  inner: MyObjectInner,
  space: MaybeUinit<..>
}

Then MyObject could match the C++ memory space. (is there any advantage to using a Pimpl style thing?)
We would then need to be able to pass through Default constructors on the outer type to the inner, and what would happen with other traits?

We need the dev to only ever be able to access MyObjectInner via a Pin<&mut T> for mut so that we can prevent mutating the field without calling the signal.

Require the dev to be explicit

Instead of hiding the TQt type we could instead have the dev write it themselves via a macro attribute or extern block.

extern "C++" {
  #[cxx_qt::qobject(MyObject)]
  type MyObjectCpp
}

#[cxx_qt::qobject]
struct MyObject;

or

extern "Qt" {
  #[qobject(MyObject)]
  type MyObjectCpp
}

#[cxx_qt::qobject]
struct MyObject;

or

#[cxx_qt::qobject] 
#[cxx_name = "MyObjectCpp"]
struct MyObject;

These have the advantage of being explicit about another type existing, which make it more obvious where things are coming from.

There are questions over whether the cxx_name would rename the type in C++, whether it can be the same as the Rust name, and the same for the type variant.

The extern "Qt" block idea could be combined with the new signals API design, but does extern "Qt" refer to Rust or C++ created things, or a shared block ?

Summary

So lots of open questions and possible ideas to improve things further.

Either I think we should end up with

• one struct with minimal magic and devs can impl traits and things sanely or with warnings
• two types, but it's explicit and the dev knows that there are two types living

[ahayzen-kdab]

Keeping two types seems to be the route for now.

[LeonMatthesKDAB]

New suggested API for Signals (also moves cxx_qt::inherit):

#[cxx_qt::bridge]
mod ffi {
    #[cxx_qt::qobject]
    struct MyObject {
    }

    impl qobject::MyObject {

        #[inherit]
        #[cxx_name="beginInsertRows"]
        fn super_begin_insert_rows(&self);

        #[qsignal]
        #[inherit]
        fn my_signal(&self);
    }
}

The issue with this right now is mostly that we're unsure whether declaring functions without a function body within an impl block will continue to be passed straight through to our procedural macro...

Alternatively, we could explore putting this in an extern "Qt" block, though this makes it a bit less obvious what's implemented on the qobject::T

[ahayzen-kdab]

Further problem is that Result<T, E> and something that has impl Display for T are supported in CXX.

So we maybe need to have a "header" portion of invokables, if we want to be able to support fallible2 in this example.

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        fn fallible1(depth: usize) -> Result<String>;
        fn fallible2() -> Result<()>;
    }
}

fn fallible1(depth: usize) -> anyhow::Result<String> {
    if depth == 0 {
        return Err(anyhow::Error::msg("fallible1 requires depth > 0"));
    }
    ...
}

fn fallible2() -> Result<(), io::Error> {
    ...
    Ok(())
}

[LeonMatthesKDAB]

Suggested API:

#[cxxqt::bridge]
mod qobject {
    extern "Qt" {
        type QAbstractItemModel = cxx_qt_lib::QAbstractItemModel;

        type QButton;

        type OtherObject = crate::qobject::OtherObject;

        #[qsignal]
        fn clicked(self: &QButton);
    }

    extern "RustQt" {
        #[base="QAbstractItemModel"]
        #[qml_element]
        #[qproperty(i32, member="prop")] // needs to access field .prop
        #[qproperty(i32, read="get_my_prop", write="set_my_prop")] //#[qproperty(i32, member="prop")]
        #[qproperty(QString, read="get_my_prop", write="set_my_prop")] //#[qproperty(QString, member="prop")]
        type MyObject = super::MyObject;

        #[qinvokable]
        fn my_invokable(self: Pin<&mut Self>, ..., *mut OtherObject) -> Result<()>;
    
       #[qsignal]
       #[inherit]
        fn data(self: Pin<&mut MyObject>, ...) -> ...;

        #[cxx_name = "hasChildren"]
        #[inherit]
        fn has_children_super(self: &MyObject, parent: &QModelIndex) -> bool;
    }

    impl cxx_qt::Constructor<(i32)> for MyObject {
        todo!{}
    }

    impl cxx_qt::Threading for MyObject {}
    // to disable CXXQt locking!
    impl !cxx_qt::Locking for MyObject {}
}

struct MyObject {
    pub prop: i32,

    private_stuff: MySpecialType,
}

impl qobject::MyObject {
    fn get_my_prop(&self) -> i32 {
        todo!{}
    }
    
    fn set_my_prop(self: Pin<&mut Self>, value: i32) {
        todo!{}
    }

    pub fn my_invokable(self: core::pin::Pin<&mut Self>) ->  anyhow::Result<()> {
        todo! { }
    }
}