merge the C branch into HEAD

1 files changed, 255 insertions, 0 deletions

diff --git a/doc/python/hooks.txt b/doc/python/hooks.txt
new file mode 100644
index 00000000..3bfc2706
--- /dev/null
+++ b/doc/python/hooks.txt
@@ -0,0 +1,255 @@
+*******************************************************************************
+*******************************************************************************
+**    CAUTION: changing any value in the hook for that value changing is     **
+**    dangerous, as this can easily lead to an infinate loop of updating!    **
+*******************************************************************************
+*******************************************************************************
+
+hooks
+
+----
+
+This document describes the 'Hook' class, exposed by Openbox's 'hooks' module
+to its python scripts, and the standard hooks exposed in the 'hooks' module.
+
+----
+
+hooks.Hook
+
+----
+
+Methods
+
+----
+
+__call__(args)
+
+Fires the hook, passing the given arguments on to all functions registered with
+the hook. Functions are called in the order in which they were added. If any
+function defined as a hook returns any value other than None, the hook will
+not fire any more functions.
+
+	args: Any number of function arguments, which are passed on to the
+	      hook's registered functions.
+
+----
+
+append(func)
+
+Appends a function to the hook.
+
+	func: The function to add to the hook.
+
+----
+
+remove(func)
+
+Removes the function from the hook.
+
+	func: The function to remove from the hook.
+
+----
+
+hooks
+
+----
+
+Hooks
+
+The following standard hooks are defined by Openbox. After each name comes the
+expected format of a function added to the hook. Adding a function of another
+format will lead to an exception when the hook is fired.
+
+----
+
+startup - function()
+
+When Openbox is starting, just before it begins managing clients.
+
+----
+
+shutdown - function()
+
+When Openbox is shutting down, after releasing all clients.
+
+----
+
+visibledesktop - function(new, old)
+
+When the current desktop changes.
+
+	new: An integer containing the new desktop.
+
+	old: An integer containing the old desktop.
+
+----
+
+numdesktops - function(desktops)
+
+When the number of desktops changes.
+
+	desktops: An integer containing the number of available desktops.
+
+----
+
+desktopnames - function()
+
+When the desktops' names have been changed.
+
+----
+
+showdesktop - function(showing)
+
+When Openbox enters or leaves 'showing the desktop' mode. Called after the
+desktop is shown/hidden.
+
+	showing: True if entering 'showing the desktop' mode, False if leaving.
+
+----
+
+screenconfiguration - function(size)
+
+When the screen's size (ob.Openbox.physicalSize()) has changed.
+
+	size: The new size of the screen, as returned by
+	      ob.Openbox.physicalSize().
+
+----
+
+screenarea - function()
+
+When the screen's area (ob.Openbox.screenArea()) has changed.
+
+----
+
+managed - function(client)
+
+When a client is managed.
+
+	client: The Client being managed.
+
+----
+
+closed - function(client)
+
+When a client is being closed/destroyed/released.
+
+	client: The Client which has been closed.
+
+----
+
+bell - function(client)
+
+When the system bell is fired.
+
+	client: The Client the bell is associated with, or None. Clients can
+		only be associated with bells through the XKB extension.
+
+----
+
+urgent - function(client)
+
+When a window enters/leaves urgent status.
+
+	client: The client which has become/stopped being urgent.
+
+----
+
+pointerenter - function(client)
+
+When the pointer moves above a client.
+
+	client: The Client that the pointer has move above.
+
+----
+
+pointerleave - function(client)
+
+When the pointer moves off of a client.
+
+	client: The Client that the pointer has moved off of.
+
+----
+
+focused - function(client)
+
+When focus changes.
+
+	client: The Client which has recieved input focus, or None if no client
+		is focused.
+
+----
+
+requestactivate - function(client)
+
+When a request is made to activate a client.
+
+	client: The Client who has been requested to be made active.
+
+----
+
+title - function(client)
+
+When a client's title or icon title changes.
+
+	client: The Client whose title changed.
+
+----
+
+desktop - function(client, new, old)
+
+When a client's desktop changes.
+
+	client: The Client that changed desktops.
+
+	new: An integer containing the client's new desktop.
+
+	old: An integer containing the client's old desktop.
+
+----
+
+iconic - function(client)
+
+When a client's iconic status changes.
+
+	client: The Client that has been (un)iconified.
+
+----
+
+shaded - function(client)
+
+When a client's shaded status changes.
+
+	client: The Client that has been (un)shaded.
+
+----
+
+maximized - function(client)
+
+When a client's maximized status changes.
+
+	client: The Client that has been (un)maximized.
+
+----
+
+fullscreen - function(client)
+
+When a client's fullscreen status changes.
+
+	client: The Client which as been (un)fullscreened.
+
+----
+
+visible - function(client)
+
+When a client becomes visible or hidden, but not for desktop changes.
+
+	client: The Client which has been shown/hidden.
+
+----
+
+configuration - function(client)
+
+When a client's configuration (area/position/size) changes.
+
+	client: The Client which has moved or resized.