minx.core.hooks.short_circuit Class Reference

An exception for cutting short the execution of a chain of hooks. More...

Public Member Functions
def	__init__
	Create a short_circuit exception with the specified return value. More...

Detailed Description

An exception for cutting short the execution of a chain of hooks.

This class allows an end-user hook function to have Minx stop excecuting the remaining hooks in its chain of hooks.

Note

In addition to being a customization mechanism available to end-users, Minx also uses hooks internally for various purposes. All hooks, internal and external, are stored in a single hook map maintained by the main window manager object. This design allows for a very powerful way of customizing the window manager because it gives you access to even the low-level X event processing...

However, with great power comes great responsibilty! In general, it would be unwise to short-circuit Minx's internal hooks. That is, just because you can, doesn't mean you should. As a rule of thumb, use short-circuting only when you're absolutely sure it won't have an adverse effect.

For example, the manage_hook is expected to return True or False depending on whether it wants a particular window managed or not. While it would be unusual to have more than one manage_hook (because one hook can perform multiple checks on window properties for all window types), if you do have more than one manage_hook, the one that returns a False can short-circuit the rest because Minx will only manage a window if all the manage hooks return True. Thus, if even one returns False, there's no point executing the remaining hooks; that one can simply short-circuit the rest of the manage_hook chain.

Constructor & Destructor Documentation

def minx.core.hooks.short_circuit.__init__	(		self,
			ret = None
	)

Create a short_circuit exception with the specified return value.

Parameters

ret	The hook's return value (default = None).

If a function raises an exception, it cannot also communicate a return value to its caller using the usual function return mechanism. Instead, we allow the short-circuiting hook to stuff its return value into the short_circuit exception. The hooks.trigger() function will extract the return value from its short_circuit exception handler and also stop executing the remaining hooks in the short-circuiting hook's chain.

Here is an example of an end-user hook short-circuiting its chain of hooks and returning a value:

             #!/usr/bin/env python
 
             import minx
             from minx.core.hooks import short_circuit
 
             def my_manage_hook(w):
                 prop = w.properties()
                 if prop['class'].lower() == 'gkrellm':
                    raise short_circuit(False)
                 return True
 
             wm = minx.core.wm()
             wm.hooks.add('manage_hook', my_manage_hook)
             wm.start()

Note

The return value can be anything the hook function wants to return. The exception and hooks classes don't care about it; they simply pass it back to the Minx function that triggered the hooks.