Permalink
Browse files

Recommend the usage of the with statement for freeze_notify and handl…

…er_block
  • Loading branch information...
sebp committed Oct 27, 2012
1 parent 33e83ac commit 6fe1b678a828f93078e6230f478018f35b2a6327
Showing with 36 additions and 0 deletions.
  1. +36 −0 source/objects.txt
View
@@ -249,10 +249,46 @@ API
emitted when any property is changed) until the :meth:`thaw_notify` method is
called.
+ It recommended to use the *with* statement when calling :meth:`freeze_notify`,
+ that way it is ensured that :meth:`that_notify` is called implicitly at
+ the end of the block::
+
+ with an_object.freeze_notify():
+ # Do your work here
+ ...
+
.. method:: thaw_notify()
Thaw all the "notify::" signals which were thawed by :meth:`freeze_notify`.
+ It is recommended to not call :meth:`thaw_notify` explicitly but use
+ :meth:`freeze_notify` together with the *with* statement.
+
+ .. method:: handler_block(handler_id)
+
+ Blocks a handler of an instance so it will not be called during any signal
+ emissions unless :meth:`handler_unblock` is called for that *handler_id*.
+ Thus "blocking" a signal handler means to temporarily deactivate it, a
+ signal handler has to be unblocked exactly the same amount of times it
+ has been blocked before to become active again.
+
+ It is recommended to use :meth:`handler_block` in conjunction with the
+ *with* statement which will call :meth:`handler_unblock` implicitly at
+ the end of the block::
+
+ with an_object.handler_block(handler_id):
+ # Do your work here
+ ...
+
+ .. method:: handler_unblock(handler_id)
+
+ Undoes the effect of :meth:`handler_block`. A blocked handler is skipped
+ during signal emissions and will not be invoked until it has been unblocked
+ exactly the amount of times it has been blocked before.
+
+ It is recommended to not call :meth:`handler_unblock` explicitly but use
+ :meth:`handler_block` together with the *with* statement.
+
.. attribute:: __gsignals__
A dictionary where inherited class can define new signals.

0 comments on commit 6fe1b67

Please sign in to comment.