WIP: book: rewrite various sections for 0.6

KDAB · Sep 22, 2023 · 4e2bcf5 · 4e2bcf5
1 parent 0cc122b
commit 4e2bcf5
Show file tree

Hide file tree

Showing 34 changed files with 657 additions and 452 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -7,28 +7,27 @@ SPDX-License-Identifier: MIT OR Apache-2.0
 
 # Summary
 
-[Introduction](./index.md)
-
----
-
+- [Introduction](./index.md)
 - [Getting Started](./getting-started/index.md)
     - [QObjects in Rust](./getting-started/1-qobjects-in-rust.md)
     - [Our first CXX-Qt module](./getting-started/2-our-first-cxx-qt-module.md)
     - [Creating the QML GUI](./getting-started/3-qml-gui.md)
     - [Building with CMake](./getting-started/4-cmake-integration.md)
     - [Building with Cargo](./getting-started/5-cargo-executable.md)
-- [QObject](./qobject/index.md)
-    - [`#[cxx_qt::bridge]` - Bridge Macro](./qobject/bridge-macro.md)
-    - [`#[qobject]` - Defining QObjects](./qobject/qobject_struct.md)
-    - [`#[qsignal]` - Signal macro](./qobject/signals.md)
-    - [`qobject::T` - The generated QObject](./qobject/generated-qobject.md)
-    - [CxxQtThread](./qobject/cxxqtthread.md)
-- [Concepts](./concepts/index.md)
-    - [Bridge](./concepts/bridge.md)
-    - [Qt](./concepts/qt.md)
-    - [Types](./concepts/types.md)
+- [Core Concepts](./concepts/index.md)
     - [Build Systems](./concepts/build_systems.md)
-    - [Threading](./concepts/threading.md)
+    - [Generated QObject](./concepts/generated_qobject.md)
+    - [Types](./concepts/types.md)
     - [Nested Objects](./concepts/nested_objects.md)
     - [Inheritance & Overriding](./concepts/inheritance.md)
-    - [Custom Constructors](./concepts/constructor.md)
+- [Reference: the bridge module](./bridge/index.md)
+    - [extern "RustQt"](./bridge/extern_rustqt.md)
+    - [extern "C++Qt"](./bridge/extern_cppqt.md)
+    - [Shared types](./bridge/shared_types.md)
+    - [Attributes](./bridge/attributes.md)
+- [Reference: traits](./traits/index.md)
+    - [CxxQtType](./traits/cxxqttype.md)
+    - [Constructor](./traits/constructor.md)
+    - [Initialize](./traits/initialize.md)
+    - [Locking](./traits/locking.md)
+    - [Threading](./traits/threading.md)
diff --git a/book/src/bridge/attributes.md b/book/src/bridge/attributes.md
@@ -0,0 +1,47 @@
+<!--
+SPDX-FileCopyrightText: 2023 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+SPDX-FileContributor: Andrew Hayzen <andrew.hayzen@kdab.com>
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+-->
+
+# Attributes
+
+## namespace
+
+The C++ namespace which to emit `extern "RustQt"` items and the namespace to find `extern "C++Qt"` items.
+
+An item will inherit the namespace specified on it's surrounding `extern` block if any,
+otherwise the namespace specified with the top level `cxx_qt::bridge` attribute, if any, will be used.
+
+```rust,ignore,noplayground
+{{#include ../../../examples/qml_features/rust/src/threading.rs:book_namespace_macro}}
+```
+
+> Note that `#[namespace = "..."]` may not work on all items,
+> we hope to improve this in future this support in the future.
+
+## cxx_name and rust_name
+
+The `#[cxx_name = "..."]` attribute replaces the name that C++ should use for this item.
+
+The `#[rust_name = "..."]` attribute replaces the name that Rust should use for this item.
+
+> Note that `#[cxx_name = "..."]` and `#[rust_name = "..."]` may not work on all items,
+> we hope to improve this in future this support in the future.
+
+If no `#[cxx_name = "..."]` or `#[rust_name = "..."]` is specified, CXX-Qt will perform an automatic conversion to function names as specified in the table below.
+
+|                  | Rust       | C++       |
+|------------------|------------|-----------|
+| `extern "C++Qt"` | -          | camelCase |
+| `extern "RustQt"`| -          | camelCase |
+
+> Note that in some cases `snake_case` conversions may occur for generated functions in Rust (eg `on_<signal>`).
+
+> Note that this table may change to the following conversions in the future.
+>
+> |                  | Rust       | C++       |
+> |------------------|------------|-----------|
+> | `extern "C++Qt"` | snake_case | -         |
+> | `extern "RustQt"`| -          | camelCase |
diff --git a/book/src/bridge/extern_cppqt.md b/book/src/bridge/extern_cppqt.md
@@ -0,0 +1,104 @@
+<!--
+SPDX-FileCopyrightText: 2023 Klarälvdalens Datakonsult AB, a KDAB Group company <info@kdab.com>
+SPDX-FileContributor: Andrew Hayzen <andrew.hayzen@kdab.com>
+
+SPDX-License-Identifier: MIT OR Apache-2.0
+-->
+
+# extern "C++Qt"
+
+- [QObjects](#qobjects)
+- [Methods](#methods)
+- [Signals](#signals)
+
+```rust,ignore,noplayground
+#[cxx_qt::bridge]
+mod ffi {
+    extern "C++Qt" {
+
+    }
+}
+```
+
+The `extern "C++Qt"` section of a CXX-Qt bridge declares Qt types and signatures to be made available to Rust,
+and gives the paths of the headers which contain the corresponding Qt declarations.
+
+A bridge module may contain zero or more `extern "C++Qt"` blocks.
+
+This complements the [`extern "C++"` CXX section](https://cxx.rs/extern-c++.html)
+but allows for declaring Qt specific features on C++ types.
+
+## QObjects
+
+Types defined in C++ that are made available to Rust, but only behind an indirection.
+
+This is the same as [CXX Opaque C++ types](https://cxx.rs/extern-c++.html#opaque-c-types).
+
+```rust,ignore,noplayground
+#[cxx_qt::bridge]
+mod ffi {
+    extern "C++Qt" {
+        include!(<QtWidgets/QPushButton>);
+        type QPushButton;
+    }
+}
+```
+
+<!--
+TODO: use a real example from qml_features once closure support lands
+-->
+
+## Methods
+
+Methods can be specified on the Qt type in the same way as [`extern "RustQt"` blocks](./extern_rustqt.md#methods).
+
+This is the same as [CXX Functions and member functions](https://cxx.rs/extern-c++.html#functions-and-member-functions).
+
+```rust,ignore,noplayground
+#[cxx_qt::bridge]
+mod ffi {
+    unsafe extern "C++" {
+        include!("cxx-qt-lib/qstring.h");
+        type QString = cxx_qt_lib::QString;
+    }
+
+    extern "C++Qt" {
+        include!(<QtWidgets/QPushButton>);
+        type QPushButton;
+
+        fn text(self: &QPushButton) -> QString;
+        fn setText(self: Pin<&mut QPushButton>, text: &QString);
+    }
+}
+```
+
+<!--
+TODO: use a real example from qml_features once closure support lands
+-->
+
+## Signals
+
+Signals can be specified on the Qt type in the same way as [`extern "RustQt"` blocks](./extern_rustqt.md#signals).
+
+```rust,ignore,noplayground
+#[cxx_qt::bridge]
+mod ffi {
+    extern "C++Qt" {
+        include!(<QtWidgets/QPushButton>);
+        type QPushButton;
+
+        #[qsignal]
+        fn clicked(self: Pin<&mut QPushButton>, checked: bool);
+    }
+}
+```
+
+This then causes CXX-Qt to generate Rust methods to connect to the `#[qsignal]` with a closure,
+in the same way as a `#[qsignal]` in a [`extern "RustQt"` block](./extern_rustqt.md#signals).
+
+> Note using `pub(self)` as the visibility of the signal
+> allows for declaring private signals
+
+<!--
+TODO: use a real example from qml_features once closure support lands
+-->