From 2d2a5bc1a76d0a1df4b1d0421a45f5ebdaab4eed Mon Sep 17 00:00:00 2001
From: Tatiana Borisova <tatiana.borisova@qt.io>
Date: Fri, 10 Jan 2025 18:26:03 +0100
Subject: [PATCH] [ProtobufQuick] Clashing of Quick Components and Protobuf QML
 messages

- add an instruction how to handle contradictions of Protobuf types
and QML types in qml-files.

Task-number: QTBUG-132125
Change-Id: Icf5338cd35e8024872d8df90d830416357c13024
Reviewed-by: Dennis Oberst <dennis.oberst@qt.io>
---
 src/protobuf/doc/src/qtprotobuf.qdoc | 63 ++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/src/protobuf/doc/src/qtprotobuf.qdoc b/src/protobuf/doc/src/qtprotobuf.qdoc
index f6b821b1..2af94637 100644
--- a/src/protobuf/doc/src/qtprotobuf.qdoc
+++ b/src/protobuf/doc/src/qtprotobuf.qdoc
@@ -427,6 +427,69 @@
     \endcode
     \note The usage of duplicates will trigger a warning at compilation time.
 
+    \section1 QML types duplicates
+    If your application uses protobuf messages with names that
+    are already reserved in QML as QML types, then the correct behavior
+    cannot be guaranteed, and \c {Element is not creatable} error
+    would be triggered. To prevent an overlapping of QML Types,
+    use a <Qualifier> for QML module import, see
+    \l{Module (Namespace) Imports}.
+    For example, the following protobuf messages would be clashing
+    with the \l Text and \l Item QML types when imported into the
+    global namespace:
+    \badcode
+        syntax = "proto3";
+        package test.example;
+
+        message Text {
+            string text = 1;
+        }
+
+        message Item {
+            sint32 width = 1;
+            sint32 height = 2;
+        }
+    \endcode
+    Use the \l qt_add_protobuf macro with the \c QML option to
+    enable QML types generation from the above protobuf messages.
+    See the example below:
+    \badcode
+        qt_add_protobuf(example
+            PROTO_FILES
+                test.proto
+            QML
+            QML_URI
+                test.example
+        )
+    \endcode
+    Clashes with the QML types will be triggered if protobuf
+    messages are imported into a global namespace after the QtQuick
+    import. See the example below:
+    \badcode
+        import QtQuick
+        import test.example
+
+        Item {
+           id: root
+           ...
+           property ProtobufMessages.item itemData
+       }
+    \endcode
+    To avoid clashes with the QML types, use a \c <Qualifier>
+    to import the generated QML module into a local namespace.
+    See the example below:
+    \badcode
+        // No qualifier - global namespace
+        import QtQuick
+        // ProtobufMessages - a qualifier of local namespace.
+        import test.example as ProtobufMessages
+
+        Item {
+            id: root
+            ...
+            property ProtobufMessages.item itemData
+        }
+    \endcode
     \section2 QML keywords handling
     Pay attention to the keywords that are reserved in QML or
     JavaScript context, but not reserved in *.proto context.