A few details about the hook system
-----------------------------------

1) Uses of hooks in PycaWM

PycaWM uses the concept of hooks (also known as callbacks) for almost everything.

For example:
* Focuses are implemented as hooks to the window manager internal functions. There is no static focuses in PycaWM. The focuses dynamically add their customizations to the window manager.
* Plugins are just a class with an initializer and a destructor. The initializer sets the hooks, the destructor removes them. All the customizations brought by the plugins use the hook system. (e.g. To show a window with the new coordinates of a window being moved, the plugin simply hooks the moving method of a client.)
* Menus are independent from PycaWM. A menu sets its hooks to be called at the right time, but the window manager has no specific functions to handle menus directly.
* etc.

2) Kinds and types of hooks

There are two kinds of hooks. Each kind of hooks is itself divided in 3 types.

The two kinds of hooks are: `normal' and instance hooks.

A normal hook can hook functions or methods. It will be called each time the hooked function/method is executed.
An instance hook can only hook methods. It will be called each time the method is executed with the same instance (self) as in the hook definition.

the 2 types of hooks are: `pre', `post' and `overriding hooks'.

A pre hook is called before the hooked function/method.
A post hook is called after the hooked function/method.
An overriding hook is called instead of the hooked function/method. If there are multiple overriding hooks for a function/method, they are all run one by one.

The hooks are called in the order they have been defined.

3) Other details

We cannot set a hook on every function or method.

To successfully set a hook, the hooked function must be decorated with the `run_hooks' decorator. The class of the hooked method must have `MetaHookable' as its metaclass. (`run_hooks' and `MetaHookable' are defined in the `hookmanager.py' file. Typing "from pycawm.hookmanager import run_hooks, MetaHookable" will import them.)

4) Further information

PycaWM has commented unit tests which describe how the hook system works.
These unit tests are in the `tests/hookmanager.test' file.
