qthelper: introduce new convenience functions

(Why the heck is the C++ helper not in a separate repository?)

DOCS/client-api-changes.rst

@@ -48,6 +48,9 @@ API changes
           In future mpv releases, the conflicting deprecated options/properties
           will be removed, and mpv_set_option() will internally translate API
           calls to mpv_set_property().
+        - qthelper.hpp: deprecate get_property_variant, set_property_variant,
+          mpv_set_option, command_variant, and replace them with get_property,
+          set_property, command.
  --- mpv 0.19.0 ---
  1.22   - add stream_cb API for custom protocols
  --- mpv 0.18.1 ---

libmpv/qthelper.hpp

@@ -29,6 +29,7 @@
 #include <QList>
 #include <QHash>
 #include <QSharedPointer>
+#include <QMetaType>
 
 #include <mpv/client.h>
 
@@ -227,6 +228,8 @@ struct node_autofree {
  * Return the given property as mpv_node converted to QVariant, or QVariant()
  * on error.
  *
+ * @deprecated use get_property() instead
+ *
  * @param name the property name
  */
 static inline QVariant get_property_variant(mpv_handle *ctx, const QString &name)
@@ -240,6 +243,8 @@ static inline QVariant get_property_variant(mpv_handle *ctx, const QString &name
 
 /**
  * Set the given property as mpv_node converted from the QVariant argument.
+
+ * @deprecated use set_property() instead
  */
 static inline int set_property_variant(mpv_handle *ctx, const QString &name,
                                        const QVariant &v)
@@ -250,6 +255,8 @@ static inline int set_property_variant(mpv_handle *ctx, const QString &name,
 
 /**
  * Set the given option as mpv_node converted from the QVariant argument.
+ *
+ * @deprecated use set_property() instead
  */
 static inline int set_option_variant(mpv_handle *ctx, const QString &name,
                                      const QVariant &v)
@@ -261,6 +268,8 @@ static inline int set_option_variant(mpv_handle *ctx, const QString &name,
 /**
  * mpv_command_node() equivalent. Returns QVariant() on error (and
  * unfortunately, the same on success).
+ *
+ * @deprecated use command() instead
  */
 static inline QVariant command_variant(mpv_handle *ctx, const QVariant &args)
 {
@@ -272,7 +281,94 @@ static inline QVariant command_variant(mpv_handle *ctx, const QVariant &args)
     return node_to_variant(&res);
 }
 
+/**
+ * This is used to return error codes wrapped in QVariant for functions which
+ * return QVariant.
+ *
+ * You can use get_error() or is_error() to extract the error status from a
+ * QVariant value.
+ */
+struct ErrorReturn
+{
+    /**
+     * enum mpv_error value (or a value outside of it if ABI was extended)
+     */
+    int error;
+
+    ErrorReturn() : error(0) {}
+    explicit ErrorReturn(int err) : error(err) {}
+};
+
+/**
+ * Return the mpv error code packed into a QVariant, or 0 (success) if it's not
+ * an error value.
+ *
+ * @return error code (<0) or success (>=0)
+ */
+static inline int get_error(const QVariant &v)
+{
+    if (!v.canConvert<ErrorReturn>())
+        return 0;
+    return v.value<ErrorReturn>().error;
+}
+
+/**
+ * Return whether the QVariant carries a mpv error code.
+ */
+static inline bool is_error(const QVariant &v)
+{
+    return get_error(v) < 0;
+}
+
+/**
+ * Return the given property as mpv_node converted to QVariant, or QVariant()
+ * on error.
+ *
+ * @param name the property name
+ * @return the property value, or an ErrorReturn with the error code
+ */
+static inline QVariant get_property(mpv_handle *ctx, const QString &name)
+{
+    mpv_node node;
+    int err = mpv_get_property(ctx, name.toUtf8().data(), MPV_FORMAT_NODE, &node);
+    if (err < 0)
+        return QVariant::fromValue(ErrorReturn(err));
+    node_autofree f(&node);
+    return node_to_variant(&node);
+}
+
+/**
+ * Set the given property as mpv_node converted from the QVariant argument.
+ *
+ * @return mpv error code (<0 on error, >= 0 on success)
+ */
+static inline int set_property(mpv_handle *ctx, const QString &name,
+                                       const QVariant &v)
+{
+    node_builder node(v);
+    return mpv_set_property(ctx, name.toUtf8().data(), MPV_FORMAT_NODE, node.node());
+}
+
+/**
+ * mpv_command_node() equivalent.
+ *
+ * @param args command arguments, with args[0] being the command name as string
+ * @return the property value, or an ErrorReturn with the error code
+ */
+static inline QVariant command(mpv_handle *ctx, const QVariant &args)
+{
+    node_builder node(args);
+    mpv_node res;
+    int err = mpv_command_node(ctx, node.node(), &res);
+    if (err < 0)
+        return QVariant::fromValue(ErrorReturn(err));
+    node_autofree f(&res);
+    return node_to_variant(&res);
+}
+
 }
 }
 
+Q_DECLARE_METATYPE(mpv::qt::ErrorReturn)
+
 #endif