From d822b16806a8a88ca8c6e3ec5617e30c1fb71ab9 Mon Sep 17 00:00:00 2001
From: Bart Janssens <bart@bartjanssens.org>
Date: Mon, 16 Oct 2023 14:54:39 +0200
Subject: [PATCH] Document using QML.jl from a Julia module

Issue Properties passed to `loadqml` makes app to crash when loaded from module #165
Issue Segfault when calling Julia functions #183
---
 docs/src/index.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/docs/src/index.md b/docs/src/index.md
index bcc465b..4af5a3c 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -30,6 +30,64 @@ Most fundamental types are converted implicitly. Mind that the default integer t
 
 We also convert `QVariantMap`, exposing the indexing operator `[]` to access element by a string key. This mostly to deal with arguments passed to the QML `append` function in list models.
 
+## Using QML.jl inside another Julia module
+
+Because of precompilation and because the QML engine gets destroyed between runs, care needs to be taken to avoid storing invalid pointers and to call all `@qmlfunction` macros again before restarting the program. An example module that takes care of this could look like this:
+
+```julia
+module QmlModuleTest
+
+using QML
+# absolute path in case working dir is overridden
+const qml_file = joinpath(dirname(@__FILE__), "qml", "frommodule.qml")
+
+# Propertymap is a pointer, so it needs to be a function and not a const value
+props() = JuliaPropertyMap(
+    "hi" => "Hi",
+)
+
+world() = " world!"
+
+# Convenience function to call all relevant function macros
+function define_funcs()
+  @qmlfunction world
+end
+
+function main()
+  define_funcs()
+  loadqml(qml_file; props=props())
+  exec()
+end
+
+end # module QmlModuleTest
+```
+
+The referred `frommodule.qml` file is expected in a subdirectory called `qml`, with the following content:
+
+```qml
+import QtQuick
+import QtQuick.Controls
+import org.julialang
+
+ApplicationWindow {
+  id: mainWin
+  title: "My Application"
+  width: 100
+  height: 100
+  visible: true
+
+  Rectangle {
+    anchors.fill: parent
+    color: "red"
+
+    Text {
+      anchors.centerIn: parent
+      text: props.hi + Julia.world()
+    }
+  }
+}
+```
+
 ## Interface
 
 ```@index