diff options
author | Kjell Ahlstedt <kjell.ahlstedt@bredband.net> | 2013-10-26 10:47:25 +0200 |
---|---|---|
committer | Kjell Ahlstedt <kjell.ahlstedt@bredband.net> | 2013-10-26 10:47:25 +0200 |
commit | 49e753a7e2d2ce85bc090da47b80c78a24c065d6 (patch) | |
tree | 4da55a80b2fa7cd70dee75e60a2004143f5ce9d3 | |
parent | cd600a31fbf8e76e25f4be4c10c0645f090a9b80 (diff) | |
download | sigc++-49e753a7e2d2ce85bc090da47b80c78a24c065d6.tar.gz |
Documentation: Mention std::function and std::bind() in more comments
* sigc++/functors/macros/functor_trait.h.m4: Mention that
SIGC_FUNCTORS_DEDUCE_RESULT_TYPE_WITH_DECLTYPE does not support functors
with overloaded operator()().
* sigc++/adaptors/macros/track_obj.h.m4:
* sigc++/functors/macros/slot.h.m4:
* sigc++/functors/slot_base.h:
* sigc++/signal_base.h: Mention std::function as an alternative to
sigc::slot.
* sigc++/macros/signal.h.m4: connect(): Describe why the result of
std::bind() can't be connected directly to a signal.
-rw-r--r-- | sigc++/adaptors/macros/track_obj.h.m4 | 6 | ||||
-rw-r--r-- | sigc++/functors/macros/functor_trait.h.m4 | 2 | ||||
-rw-r--r-- | sigc++/functors/macros/slot.h.m4 | 15 | ||||
-rw-r--r-- | sigc++/functors/slot_base.h | 13 | ||||
-rw-r--r-- | sigc++/macros/signal.h.m4 | 14 | ||||
-rw-r--r-- | sigc++/signal_base.h | 5 |
6 files changed, 45 insertions, 10 deletions
diff --git a/sigc++/adaptors/macros/track_obj.h.m4 b/sigc++/adaptors/macros/track_obj.h.m4 index f7cde4e..632b8f5 100644 --- a/sigc++/adaptors/macros/track_obj.h.m4 +++ b/sigc++/adaptors/macros/track_obj.h.m4 @@ -136,9 +136,9 @@ namespace sigc { /** @defgroup track_obj track_obj() * track_obj() tracks trackable objects, referenced from a functor. - * It can be useful when you assign a C++11 lambda expression to a slot, or connect - * it to a signal, and the lambda expression contains references to sigc::trackable - * derived objects. + * It can be useful when you assign a C++11 lambda expression or a std::function<> + * to a slot, or connect it to a signal, and the lambda expression or std::function<> + * contains references to sigc::trackable derived objects. * * The functor returned by sigc::track_obj() is formally an adaptor, but it does * not alter the signature, return type or behaviour of the supplied functor. diff --git a/sigc++/functors/macros/functor_trait.h.m4 b/sigc++/functors/macros/functor_trait.h.m4 index 915e27d..813d8d9 100644 --- a/sigc++/functors/macros/functor_trait.h.m4 +++ b/sigc++/functors/macros/functor_trait.h.m4 @@ -197,6 +197,8 @@ struct functor_trait<T_functor,false> \ * } * @endcode * + * Functors with overloaded operator()() are not supported. + * * @newin{2,2,11} * * You can't use both SIGC_FUNCTORS_HAVE_RESULT_TYPE and diff --git a/sigc++/functors/macros/slot.h.m4 b/sigc++/functors/macros/slot.h.m4 index 1a125ef..7162e63 100644 --- a/sigc++/functors/macros/slot.h.m4 +++ b/sigc++/functors/macros/slot.h.m4 @@ -28,7 +28,7 @@ define([SLOT_N],[dnl FOR(1,$1,[ * - @e T_arg%1 Argument type used in the definition of operator()(). The default @p nil means no argument.]) * - * To use simply assign the slot to the desired functor. If the functor + * To use simply assign the desired functor to the slot. If the functor * is not compatible with the parameter list defined with the template * arguments compiler errors are triggered. When called the slot * will invoke the functor with minimal copies. @@ -109,7 +109,7 @@ ifelse($1, $2,[dnl FOR(1,$1,[ * - @e T_arg%1 Argument type used in the definition of operator()(). The default @p nil means no argument.]) * - * To use, simply assign the slot to the desired functor. If the functor + * To use, simply assign the desired functor to the slot. If the functor * is not compatible with the parameter list defined with the template * arguments, compiler errors are triggered. When called, the slot * will invoke the functor with minimal copies. @@ -119,10 +119,19 @@ FOR(1,$1,[ * @par Example: * @code * void foo(int) {} - * sigc::slot<void, long> s = sigc::ptr_fun(&foo); + * sigc::slot<void, int> s = sigc::ptr_fun(&foo); * s(19); * @endcode * + * It is often possible to replace sigc::slot<> by the C++11 class std::function<>. + * + * @par Example: + * @code + * void foo(int) {} + * std::function<void(int)> f = &foo; + * f(19); + * @endcode + * * @ingroup slot */ template <LIST(class T_return, LOOP(class T_arg%1 = nil, $1))>],[dnl diff --git a/sigc++/functors/slot_base.h b/sigc++/functors/slot_base.h index 7081238..3a23f34 100644 --- a/sigc++/functors/slot_base.h +++ b/sigc++/functors/slot_base.h @@ -177,7 +177,7 @@ struct SIGC_API slot_do_unbind * Use the sigc::mem_fun() and sigc::ptr_fun() template functions to get a sigc::slot, like so: * * @code - * sigc::slot<void, int> sl = sigc::mem_fun(someobj,& SomeClass::somemethod); + * sigc::slot<void, int> sl = sigc::mem_fun(someobj, &SomeClass::somemethod); * @endcode * * or @@ -196,6 +196,17 @@ struct SIGC_API slot_do_unbind * * You can also pass slots as method parameters where you might normally pass a function pointer. * + * It is often possible to replace sigc::slot<> by the C++11 class std::function<>, for instance: + * @code + * std::function<void(int)> fn = &somefunction; + * m_Dialog.signal_response().connect(fn); + * @endcode + * + * If you connect an std::function<> instance to a signal or assign it to a slot, + * - if the return type is not void, you must use the #SIGC_FUNCTORS_DEDUCE_RESULT_TYPE_WITH_DECLTYPE macro; + * - if your function, somefunction(), contains references to sigc::trackable derived objects, + * those objects will not be tracked, unless you also use sigc::track_obj(). + * * @ingroup sigcfunctors */ diff --git a/sigc++/macros/signal.h.m4 b/sigc++/macros/signal.h.m4 index 6d33794..03deae0 100644 --- a/sigc++/macros/signal.h.m4 +++ b/sigc++/macros/signal.h.m4 @@ -319,12 +319,22 @@ public: /** Add a slot to the list of slots. * Any functor or slot may be passed into connect(). - * It will be converted into a slot implicitely. + * It will be converted into a slot implicitly. * The returned iterator may be stored for disconnection * of the slot at some later point. It stays valid until * the slot is removed from the list of slots. The iterator - * can also be implicitely converted into a sigc::connection object + * can also be implicitly converted into a sigc::connection object * that may be used safely beyond the life time of the slot. + * + * std::function<> and C++11 lambda expressions are functors. + * These are examples of functors that can be connected to a signal. + * + * %std::bind() creates a functor, but this functor typically has an + * %operator()() which is a variadic template. + * #SIGC_FUNCTORS_DEDUCE_RESULT_TYPE_WITH_DECLTYPE can't deduce the result type + * of such a functor. If you first assign the return value of %std::bind() + * to a std::function, you can connect the std::function to a signal. + * * @param slot_ The slot to add to the list of slots. * @return An iterator pointing to the new slot in the list. */ diff --git a/sigc++/signal_base.h b/sigc++/signal_base.h index 3b972ab..841f99d 100644 --- a/sigc++/signal_base.h +++ b/sigc++/signal_base.h @@ -242,9 +242,12 @@ private: * For compile time type safety a list of template arguments * must be provided for the signal template that determines the * parameter list for emission. Functors and closures are converted - * into slots implicitely on connection, triggering compiler errors + * into slots implicitly on connection, triggering compiler errors * if the given functor or closure cannot be invoked with the * parameter list of the signal to connect to. + * + * Almost any functor with the correct signature can be converted to a sigc::slot + * and connected to a signal. See @ref slot "Slots" and sigc::signal::connect(). */ /** Base class for the sigc::signal# templates. |