Publish overloaded methods and signals to JavaScript

Previously, we only published the first method or signal of any given
name. We keep this behavior for the nice JavaScript notation that looks
like a normal JavaScript method call `foo.bar(...)`. When you need to
call a different overloaded method, this patch offers you to specify
the explicit signature on the JavaScript side. I.e. when we have an
object with `foo(int i)` and `foo(const QString &str, int i)`, then
on the JavaScript a call to `obj.foo(...)` will always call the first
method like before. But now you can specify the full QMetaMethod
signature and call matching methods explicitly via `obj["foo(int)"]`
or `obj["foo(QString,int)"]`.

Automatic overload resolution on the C++ side for the nice notation
cannot easily be implemented: We need to know the return value of
the called function, otherwise we cannot construct a valid
QGenericReturnArgument. Furthermore, we wouldn't be able to
differentiate between e.g. any numeric types on the C++ side, since
JavaScript only has a single `double` type internally.

[ChangeLog][QWebChannel][General] It is now possible to explicitly
call overloaded methods or connect to overloaded signals by specifying
the full method or signal signature in string form on the JavaScript
side.

Fixes: QTBUG-73010
Change-Id: I4645edee97af56fd8d126e77d70dc33ed3513deb
Reviewed-by: Arno Rehn <a.rehn@menlosystems.com>
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@qt.io>
Reviewed-by: Milian Wolff <milian.wolff@kdab.com>

1 files changed, 40 insertions, 0 deletions

diff --git a/src/webchannel/doc/src/javascript.qdoc b/src/webchannel/doc/src/javascript.qdoc
index e643034..9f8c580 100644
--- a/src/webchannel/doc/src/javascript.qdoc
+++ b/src/webchannel/doc/src/javascript.qdoc
@@ -97,4 +97,44 @@ new QWebChannel(yourTransport, function(channel) {
     console.log(foo.MyEnum.MyEnumerator);
 });
     \endcode
+
+    \section2 Overloaded methods and signals
+
+    When you publish a \c QObject that has overloaded methods or signals, then
+    only the first one is accessible directly via the pretty JavaScript notation.
+    All others are accessible through their complete \c QMetaMethod signature.
+    Assume we have the following \c QObject subclass on the C++ side:
+
+    \code
+    class Foo : public QObject
+    {
+        Q_OBJECT
+    slots:
+        void foo(int i);
+        void foo(const QString &str);
+        void foo(const QString &str, int i);
+
+    signals:
+        void bar(int i);
+        void bar(const QString &str);
+        void bar(const QString &str, int i);
+    };
+    \endcode
+
+    Then you can interact with this class on the JavaScript side like this:
+
+    \code
+    // methods
+    foo.foo(42); // will call first method named foo, i.e. foo(int i)
+    foo.foo("asdf"); // will also call foo(int i), probably not what you want
+    foo["foo(int)"](42); // explicitly call foo(int i)
+    foo["foo(QString)"]("asdf"); // explicitly call foo(const QString &str)
+    foo["foo(QString,int)"]("asdf", 42); // explicitly call foo(const QString &str, int i)
+
+    // signals
+    foo.bar.connect(...); // connect to first signal named bar, i.e. bar(int i)
+    foo["bar(int)"].connect(...); // connect explicitly to bar(int i)
+    foo["bar(QString)"].connect(...); // connect explicitly to bar(const QString &str)
+    foo["bar(QString,int)"].connect(...); // connect explicitly to bar(const QString &str, int i)
+    \endcode
 */