[glibmm/wip/dboles/Binding-2.62: 2/4] Binding: Move SlotTypeTransform up and document it

[Daniel Boles <dboles src gnome org>]

commit 2303ca804b7c01b040d0c060955608cd251406fa
Author: Daniel Boles <dboles src gmail com>
Date:   Sat Nov 9 13:26:19 2019 +0000

    Binding: Move SlotTypeTransform up and document it
    
    This is more maintainable than all the arguments to all the overloads of
    bind_property() manually repeating the signature in their documentation,
    plus more user-friendly as we document it, users can use the typedef, &c

 glib/src/binding.hg | 48 +++++++++++++++++++++++++++---------------------
 1 file changed, 27 insertions(+), 21 deletions(-)
---
diff --git a/glib/src/binding.hg b/glib/src/binding.hg
index b6bdfaf5..221554aa 100644
--- a/glib/src/binding.hg
+++ b/glib/src/binding.hg
@@ -113,6 +113,19 @@ public:
    */
   using SlotTransform = sigc::slot<bool, const GValue*, GValue*>;
 
+  /** A slot to be called to transform values in a binding created by
+   * bind_property().
+   *
+   * For instance:
+   * @code
+   *   bool on_transform_to(const Glib::ustring& from_string, int& to_int);
+   * @endcode
+   *
+   * @return <tt>true</tt> if the transformation was successful, and <tt>false</tt> otherwise.
+   */
+  template <typename T_from, typename T_to>
+  using SlotTypedTransform = sigc::slot<bool, const T_from&, T_to&>;
+
   /** Creates a binding between @a source_property and @a target_property,
    * allowing you to set the transformation functions to be used by the binding.
    *
@@ -187,8 +200,7 @@ public:
    * @tparam T_target Type of the target property. Must be a type that can be
    *         stored in a Glib::Value<T_target> object.
    * @tparam T_functor_to Type of functor that translates from the source to the target.
-   *         Must be convertible to<br>
-   *         sigc::slot<bool, const T_source&, T_target&>.
+   *         Must be convertible to SlotTypedTransform<T_source, T_target>.
    *
    * @see bind_property_value()
    *
@@ -201,7 +213,7 @@ public:
     BindingFlags flags,
     const T_functor_to& transform_to)
   {
-    sigc::slot<bool, const T_source&, T_target&> slot_transform_to = transform_to;
+    SlotTypedTransform<T_source, T_target> slot_transform_to = transform_to;
 
     return bind_property_value(source_property, target_property, flags,
       slot_transform_to.empty() ? SlotTransform() : TransformProp<T_source, T_target>(slot_transform_to));
@@ -223,8 +235,7 @@ public:
    * @tparam T_target Type of the target property. Must be a type that can be
    *         stored in a Glib::Value<T_target> object.
    * @tparam T_functor_to Type of functor that translates from the source to the target.
-   *         Must be convertible to<br>
-   *         sigc::slot<bool, const T_source&, T_target&>.
+   *         Must be convertible to SlotTypedTransform<T_source, T_target>.
    *
    * @see bind_property_value()
    *
@@ -237,7 +248,7 @@ public:
     BindingFlags flags,
     const T_functor_to& transform_to)
   {
-    sigc::slot<bool, const T_source&, T_target&> slot_transform_to = transform_to;
+    SlotTypedTransform<T_source, T_target> slot_transform_to = transform_to;
 
     return bind_property_value(source_property, target_property, flags,
       slot_transform_to.empty() ? SlotTransform() : TransformProp<T_source, T_target>(slot_transform_to));
@@ -259,8 +270,7 @@ public:
    * @tparam T_target Type of the target property. Must be a type that can be
    *         stored in a Glib::Value<T_target> object.
    * @tparam T_functor_to Type of functor that translates from the source to the target.
-   *         Must be convertible to<br>
-   *         sigc::slot<bool, const T_source&, T_target&>.
+   *         Must be convertible to SlotTypedTransform<T_source, T_target>.
    *
    * @see bind_property_value()
    *
@@ -273,7 +283,7 @@ public:
     BindingFlags flags,
     const T_functor_to& transform_to)
   {
-    sigc::slot<bool, const T_source&, T_target&> slot_transform_to = transform_to;
+    SlotTypedTransform<T_source, T_target> slot_transform_to = transform_to;
 
     return bind_property_value(source_property, target_property, flags,
       slot_transform_to.empty() ? SlotTransform() : TransformProp<T_source, T_target>(slot_transform_to));
@@ -295,8 +305,7 @@ public:
    * @tparam T_target Type of the target property. Must be a type that can be
    *         stored in a Glib::Value<T_target> object.
    * @tparam T_functor_to Type of functor that translates from the source to the target.
-   *         Must be convertible to<br>
-   *         sigc::slot<bool, const T_source&, T_target&>.
+   *         Must be convertible to SlotTypedTransform<T_source, T_target>.
    *
    * @see bind_property_value()
    *
@@ -309,7 +318,7 @@ public:
     BindingFlags flags,
     const T_functor_to& transform_to)
   {
-    sigc::slot<bool, const T_source&, T_target&> slot_transform_to = transform_to;
+    SlotTypedTransform<T_source, T_target> slot_transform_to = transform_to;
 
     return bind_property_value(source_property, target_property, flags,
       slot_transform_to.empty() ? SlotTransform() : TransformProp<T_source, T_target>(slot_transform_to));
@@ -333,11 +342,9 @@ public:
    * @tparam T_target Type of the target property. Must be a type that can be
    *         stored in a Glib::Value<T_target> object.
    * @tparam T_functor_to Type of functor that translates from the source to the target.
-   *         Must be convertible to<br>
-   *         sigc::slot<bool, const T_source&, T_target&>.
+   *         Must be convertible to SlotTypedTransform<T_source, T_target>.
    * @tparam T_functor_from Type of functor that translates from the target to the source.
-   *         Must be convertible to<br>
-   *         sigc::slot<bool, const T_target&, T_source&>.
+   *         Must be convertible to SlotTypedTransform<T_target, T_source>.
    *
    * @see bind_property_value()
    *
@@ -351,8 +358,8 @@ public:
     const T_functor_to& transform_to,
     const T_functor_from& transform_from)
   {
-    sigc::slot<bool, const T_source&, T_target&> slot_transform_to = transform_to;
-    sigc::slot<bool, const T_target&, T_source&> slot_transform_from = transform_from;
+    SlotTypedTransform<T_source, T_target> slot_transform_to = transform_to;
+    SlotTypedTransform<T_target, T_source> slot_transform_from = transform_from;
 
     return bind_property_value(source_property, target_property, flags,
       slot_transform_to.empty() ? SlotTransform() : TransformProp<T_source, T_target>(slot_transform_to),
@@ -400,9 +407,8 @@ private:
   {
   public:
     using result_type = bool;
-    using SlotTypedTransform = sigc::slot<bool, const T_from&, T_to&>;
 
-    TransformProp(const SlotTypedTransform& slot) : typed_transform(slot) {}
+    TransformProp(const SlotTypedTransform<T_from, T_to>& slot) : typed_transform(slot) {}
 
     bool operator()(const GValue* from_value, GValue* to_value)
     {
@@ -419,7 +425,7 @@ private:
     }
 
   private:
-    SlotTypedTransform typed_transform;
+    SlotTypedTransform<T_from, T_to> typed_transform;
   };
 };