benn/lumiera_
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

WLink: fill in some documentation

Browse source
This commit is contained in:
Fischlurch 2018-08-16 02:34:47 +02:00
parent a15951b036
commit 22cdfbff2c
1 changed files with 22 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
src/gui/model/w-link.hpp
View file

@ -23,12 +23,23 @@
/** @file w-link.hpp /** @file w-link.hpp
** A smart link to an GTK widget with automatic disconnection. ** A smart link to an GTK widget with automatic disconnection.
** Allows to hold a connection to a `sigc::trackable` without ownership. ** Allows to hold a connection to a [trackable] without taking ownership.
** The is statefull, can be reconnected, and automatically transitions into disconnected ** The link is statefull, can be reconnected, and automatically transitions
** state when the target dies. ** into disconnected state when the target dies.
** **
** @warning this class is not threadsafe, because lib SigC++ is not either, ** @warning this class is not threadsafe, because lib SigC++ is not either,
** and it can only be used reliably from within the GUI thread. ** and it can only be used reliably from within the GUI thread.
** @remarks the lib SigC++ is used in GTKmm for handling "Signals" and invoking
** "Slots" (i.e. functors) as result of such a signal. Such is dangerous
** within the context of an interactive UI, since widgets might go away
** and be destroyed due to user interaction. To deal with this problem,
** GTKmm derives all widgets from [trackable], which offers an auto
** deregistration callback, when the object is destroyed, so any
** remaining signal connections can be dropped to avoid calling
** a dead functor. We make use of the same mechanism here to
** install a callback to invalidate this smart-handle.
**
** [trackable]: https://developer.gnome.org/libsigc++/stable/structsigc_1_1trackable.html#details "`sigc::trackable`"
** **
** @see \ref WLink_test ** @see \ref WLink_test
** @see \ref NotificationHub (usage example) ** @see \ref NotificationHub (usage example)
@ -59,6 +70,8 @@ namespace model {
/** /**
* Managed link to a `sigc::trackable` UI widget, without taking ownership. * Managed link to a `sigc::trackable` UI widget, without taking ownership.
* Automatically installs a callback to switch this link into detached state
* when the target (widget) is destroyed.
* @warning _not_ threadsafe * @warning _not_ threadsafe
*/ */
template<class TAR> template<class TAR>
@ -67,7 +80,6 @@ namespace model {
static_assert (std::is_base_of<sigc::trackable, TAR>() static_assert (std::is_base_of<sigc::trackable, TAR>()
,"target type required to be sigc::trackable"); ,"target type required to be sigc::trackable");
//mutable
TAR* widget_; TAR* widget_;
@ -108,6 +120,7 @@ namespace model {
} }
/** detach and deactivate this link */
void void
clear() clear()
{ {
@ -116,6 +129,8 @@ namespace model {
widget_ = nullptr; widget_ = nullptr;
} }
/** (re)connect this smart link to the given target.
* Any previously existing link is detached beforehand */
void void
connect (TAR& otherTarget) connect (TAR& otherTarget)
{ {
@ -133,6 +148,9 @@ namespace model {
, LERR_(BOTTOM_VALUE)); , LERR_(BOTTOM_VALUE));
} }
/** @internal installs the necessary callback
* to detach this link in case the target is destroyed
*/
TAR* TAR*
attachTo (TAR& target) attachTo (TAR& target)
{ {
@ -149,10 +167,5 @@ namespace model {
}; };
/** c */
}} // namespace gui::model }} // namespace gui::model
#endif /*GUI_MODEL_W_LINK_H*/ #endif /*GUI_MODEL_W_LINK_H*/