9 files changed, 1345 insertions, 0 deletions
diff --git a/doc/python/client.txt b/doc/python/client.txt
new file mode 100644
index 00000000..fbb57006
--- /dev/null
+++ b/doc/python/client.txt
@@ -0,0 +1,553 @@
+ob.Client
+
+----
+
+This document describes the 'ob.Client' class, exposed by Openbox to its python
+scripts. The 'Client' class cannot be instantiated, and can only be
+retrieved by catching events from Openbox, or from the ob.Openbox.clientList()
+method.
+
+A Client instance is associated with a single client window which Openbox is
+managing. When the client window is closed/destroyed/released, the Client
+instance will be marked as invalid (see valid()). Any methods of Client, with
+the exception of valid(), will raise a ReferenceError exception if they are
+called on a non-valid Client instance. For this reason, it is not encouraged to
+keep references to Client instances between events, unless you are tracking the
+hooks.closed hook or check valid() before attempting to reuse a Client
+instance.
+
+----
+
+Methods
+
+----
+
+valid()
+
+Returns if the Client instance is still valid. Client instances are marked as
+invalid when the Client they are associated is closed/destroyed/released.
+
+	Returns: True or False for if the Client instance is valid.
+
+----
+
+title()
+
+Returns the client's title.
+
+	Returns: A string containing the client's title.
+
+----
+
+setTitle(title)
+
+Change the client's title to the given string. This change will be overwritten
+if/when the client changes its title.
+
+	title: A string containing the new title for the client.
+
+----
+
+iconTitle()
+
+Returns's the client's icon title. The icon title is the title to be displayed
+when the client is iconified.
+
+	Returns: A string containing the client's icon title.
+
+----
+
+setIconTitle(title)
+
+Change the client's icon title to the given string. This change will be
+overwritten if/when the client changes its icon title.
+
+	title: A string containing the new icon title for the client.
+
+----
+
+desktop()
+
+Returns the desktop on which the client is visible. This value will always be
+in the range [0, ob.Openbox.numDesktops()), unless it is 0xffffffff. A value of
+0xffffffff indicates the client is visible on all desktops.
+
+	Returns: An integer containing the client's desktop,
+
+----
+
+setDesktop(desktop)
+
+Moves the client to the specified desktop. The desktop must be in the range
+[0, ob.Openbox.numDesktops()), unless it is 0xffffffff. A value of 0xffffffff
+indicates the client is visible on all desktops.
+
+	desktop: The desktop on which to place the client.
+
+----
+
+resName()
+
+Returns the resouce name of the client. The resource name is meant to provide
+an instance name for the client.
+
+	Returns: A string containing the client's resource name.
+
+----
+resClass()
+
+Returns the resouce class of the client. The resource class is meant to provide
+the genereal class of the application. e.g. 'Emacs', 'Xterm', 'XClock',
+'XLoad', and so on.
+
+	Returns: A string containing the client's resource class.
+
+----
+
+role()
+
+Returns the client's role. The role is meant to distinguish between different
+windows of an application. Each window should have a unique role.
+
+	Returns: A string containing the client window's role.
+
+----
+
+transient()
+
+Returns True or False describing if the client is a transient window. Transient
+windows are 'temporary' windows, such as preference dialogs, and usually have
+a parent window, which can be found from transientFor().
+
+	Returns: True or False for if the client is a transient window.
+
+----
+
+transientFor()
+
+Returns the client for which this client is a transient. See transient() for
+a description of transience.
+
+	Returns: A Client containing the client which this client is transient
+		 for. None if such a client does not exist.
+
+----
+
+transients()
+
+Returns a tuple containing all the Clients which are transients of this window.
+See transient() for a description of transience.
+
+	Returns: A tuple containing Clients which are transients for this
+		 client. The tuple may be empty.
+
+----
+
+type()
+
+Returns the logical type of the window. This is one of the ClientType
+constants. See also normal().
+
+	Returns: The type of the window.
+
+----
+
+normal()
+
+Returns True or False for if the client is a 'normal' window. Normal windows
+make up most applications. Non-normal windows have special rules applied to
+them at times such as for focus handling. An example of a non-normal window
+is 'gnome-panel'. This value is determined from the client's type(), but does
+not imply that the window is ClientType.Normal. Rather this is a more generic
+definition of 'normal' windows, and includes dialogs and others.
+
+	Returns: True or False declaring the client as 'normal' or not.
+
+----
+
+area()
+
+Returns the area of the screen which the client occupies. It may be important
+to note that this is the position and size of the client *with* its
+decorations. If you want the underlying position and size of the client
+itself, you should use clientArea(). See also logicalSize().
+
+	Returns: A tuple containing the area of the client and decorations on
+		 the screen. The tuple is in the format (x, y, width, height).
+
+----
+
+setArea(area, [final])
+
+Sets the client's area, moving and resizing it as specified (or as close as can
+be accomidated).
+
+	area: The new area for the client, in a tuple. The tuple should be of
+	      the format (x, y, width, height).
+
+	final: Optional True or False for if this is a final change. This
+	       should be set to False if the change is only part of a
+	       move/resize. Otherwise, it should be set to True. If it is not
+	       specified, it will default to True.
+
+----
+
+clientArea()
+
+Returns the area of the screen which the client considers itself to be
+occupying. This value is not what you see and should not be used for most
+things (it should, for example, be used for persisting a client's dimentions
+across sessions). See also area().
+
+	Returns: A tuple containing the area the client considers itself to be
+		 occupying. The tuple is in the format (x, y, width, height).
+
+----
+
+setClientArea(area)
+
+Sets the area of the screen which the client considers itself to be occupying.
+This is not the on-screen visible position and size, and should be used with
+care. You probably want to use setArea() to adjust the client. This should be
+used if you want the client window (inside the decorations) to be a specific
+size. Adjusting the client's position with this function is probably always a
+bad idea, because of window gravity.
+
+	area: The new area for the client. in a tuple. The tuple should be of
+	      the format (x, y, width, height).
+
+----
+
+frameSize()
+
+Returns the size of the decorations around the client window.
+
+	Returns: A tuple containing the size of the decorations on each side
+		 of the client window. The tuple has the format
+		 (left, top, right, bottom).
+
+----
+
+strut()
+
+Returns the application's specified strut. The strut is the amount of space
+that should be reserved for the application on each side of the screen.
+
+
+	Returns: A tuple containing the application's strut. The tuple has the
+		 format (left, top, right, bottom).
+
+----
+
+logicalSize()
+
+Returns the client's logical size. The logical size is the client's size in
+more user friendly terms. For many apps this is simply the size of the client
+in pixels, however for some apps this will differ (e.g. terminal emulators).
+This value should be used when displaying an applications size to the user.
+
+	Returns: A tuple containing the client's logical size. The tuple has
+		 the format (width, height).
+
+----
+
+canFocus()
+
+Returns True or False for if the client can be focused.
+
+	Returns: True or False for if the client can recieve input focus.
+
+----
+
+focus([focus])
+
+Focuses (or unfocuses) the client window. Windows which return False for
+canFocus() or visible() cannot be focused. When this function returns, the
+client's focused() state will not be changed yet. This only sends the request
+through the X server. You should wait for the hooks.focused hook to fire, and
+not assume the client has been focused.
+
+	focus: Optional. If True, the window will be focused. If False, and
+	       focused() is True, it will lose its focus. If the argument is
+	       not passed, it will default to True.
+
+	Returns: True if the client could be focused, and focus has been sent
+		 to the window. False if the client could not be focused.
+
+----
+
+focused()
+
+Returns True or False for if the client has the input focus.
+
+	Returns: True or False for if the client has the input focus.
+
+----
+
+visible()
+
+Returns True or False for if the client is visible. A client is not visible if
+it is iconic() or if its desktop() is not visible.
+
+	Returns: True or False for if the client is visible.
+
+----
+
+setVisible(show)
+
+Shows or hides the client. This has no effect if its current visible() state
+is requested.
+
+	show: True or False specifying if the client should be hidden or shown.
+
+----
+
+modal()
+
+Returns True or False for if the client is a modal window. Modal windows
+indicate that they must be dealt with before the program can continue. When
+a modal window is a transient(), its transientFor() client cannot be focused or
+raised above it.
+
+	Returns: True or False for if the client is a modal window.
+
+----
+
+setModal(modal)
+
+Make the client window modal or non-modal.
+
+	mdal: True or False to make the client modal or not respectively.
+
+----
+
+shaded()
+
+Returns True or False for if the client is shaded. Shaded windows have only
+their titlebar decorations showing.
+
+----
+
+setShaded(shade)
+
+Shade or unshade the client. Shaded windows have only their titlebar
+decorations showing. Windows which do not have a titlebar cannot be shaded.
+
+	shade: True or False to make the client shaded or not respectively.
+
+----
+
+iconic()
+
+Returns True or False for if the window is iconified. Iconified windows are not
+visible on any desktops.
+
+	Returns: True or False for if the client is iconified.
+
+----
+
+setIconic(iconify, [current])
+
+Iconifies or restores the client window. Iconified windows are not visible on
+any desktops. Iconified windows can be restored to the currently visible
+desktop or to their original (native) desktop.
+
+	iconify: True or False to iconify or deiconify the client repectively.
+
+	current: Optional True or False to specify if the client should be
+		 restored to the currently visible desktop or to the desktop
+		 from which it was iconified. This does not apply to windows
+		 who's desktop() is 0xffffffff. If this is not specified, it
+		 defaults to True (the current desktop).
+
+----
+
+maximizedHorz()
+
+Returns whether the client is maximized in the horizontal direction.
+
+	Returns: True if the client is maximized horizontally; False if it is
+		 not.
+
+----
+
+setMaximizedHorz(max)
+
+Maximizes or restores a client horizontally.
+
+	max: True or False for if the client should be maximized or
+	     unmaximized in the horizontal direction.
+
+----
+
+maximizedVert()
+
+Returns whether the client is maximized in the vertical direction.
+
+	Returns: True if the client is maximized vertically; False if it is
+		 not.
+
+----
+
+setMaximizedVert(max)
+
+Maximizes or restores a client vertically.
+
+	max: True or False for if the client should be maximized or
+	     unmaximized in the vertical direction.
+
+----
+
+maximized()
+
+Returns whether the client is maximized in the horizontal or vertical
+direction.
+
+	Returns: True if the client is maximized horizontally or vertically;
+		 False if it is not.
+
+----
+
+setMaximized(max)
+
+Maximizes or restores a client vertically and horzontally.
+
+	max: True or False for if the client should be maximized or
+	     unmaximized in the vertical and horizontal direction.
+-
+---
+
+fullscreen()
+
+Returns if the client is in fullscreen mode. Fullscreen windows are kept above
+all other windows and are stretched to fill the entire physical display.
+
+	Returns: True or False for if the client is fullscreen.
+
+----
+
+setFullscreen(full)
+
+Set a client into or out of fullscreen mode. Fullscreen windows are kept above
+all other windows and are stretched to fill the entire physical display.
+
+	full: True or False to set the client into or out of fullscreen mode
+	      respectively.
+
+----
+
+stacking()
+
+Returns if the client will be stacked above/below other clients in the same
+layer.
+
+	Returns: An integer > 0 if the client will be stacked above other
+		 clients in its layer. An integer < 0 if it will be stacked
+		 below other clients. 0 will be returned if the client is
+		 stacked as normal amongst other clients in its layer.
+
+----
+
+setStacking(stack)
+
+Set how the client will be stacked according to other clients in its layer.
+
+	stack: An integer > 0 if the client should be stacked above other
+	       clients in its layer. An integer < 0 if it should be stacked
+	       below other clients. Exactly 0 if the client should be stacked
+	       as normal amongst other clients in its layer.
+
+----
+
+raiseWindow()
+
+Raises the window to the top of its stacking layer.
+
+----
+
+lowerWindow()
+
+Lowers the window to the bottom of its stacking layer.
+
+----
+
+skipPager()
+
+Returns if the client has requested to be skipped (not displayed) by pagers.
+
+	Returns: True or False for if the client has requested to be skiped by
+		 pagers.
+
+----
+
+setSkipPager(skip)
+
+Set whether the client should be skipped (not displayed) by pagers.
+
+	skip: True or False to make the client be skipped or not skipped by
+	      pagers.
+
+----
+
+skipTaskbar()
+
+Returns if the client has requested to be skipped (not displayed) by taskbars.
+
+	Returns: True or False for if the client has requested to be skiped by
+		 taskbars.
+
+----
+
+setSkipTaskbar(skip)
+
+Set whether the client should be skipped (not displayed) by taskbars.
+
+	skip: True or False to make the client be skipped or not skipped by
+	      taskbars.
+
+----
+
+disableDecorations(titlebar, handle, border)
+
+Choose which decorations to disable on the client. Note that decorations can
+only be disabled, and decorations that would normally not be shown cannot be
+added. These values may have slightly different meanings in different theme
+engines.
+
+	titlebar: True to disable, or False to enable (if possible) the
+		  client's titlebar.
+
+	handle: True to disable, or False to enable (if possible) the
+		client's handle.
+
+	border: True to disable, or False to enable (if possible) the
+		client's border.
+
+----
+
+close()
+
+Requests the client to close its window.
+
+----
+
+window()
+
+Returns the client's window id. This is the id by which the X server knows the
+client.
+
+	Returns: An integer containing the client's window id.
+
+----
+
+ob.ClientType
+
+ClientType.Normal: a normal application window.
+ClientType.Dialog: a dialog window (usually a transient()).
+ClientType.Desktop: a desktop (bottom-most) window.
+ClientType.Dock: a dock or panel window.
+ClientType.Toolbar: a toolbar "torn off" from an application.
+ClientType.Menu: a pinnable menu "torn off" from an application.
+ClientType.Utility: a small persistent utility window such as a
+		    palette or toolbox.
+ClientType.Splash: a splash screen window.
diff --git a/doc/python/config.txt b/doc/python/config.txt
new file mode 100644
index 00000000..0362fde1
--- /dev/null
+++ b/doc/python/config.txt
@@ -0,0 +1,13 @@
+config.Config
+
+----
+
+This document describes the 'Config' class, exposed by Openbox's 'config'
+module to its python scripts.
+
+----
+
+Methods
+
+----
+
diff --git a/doc/python/helpers.txt b/doc/python/helpers.txt
new file mode 100644
index 00000000..6a11e405
--- /dev/null
+++ b/doc/python/helpers.txt
@@ -0,0 +1,25 @@
+helpers
+
+----
+
+This document describes the 'helpers' module. The 'helpers' module provides
+methods to make writing python scripts easier.
+
+----
+
+Methods
+
+----
+
+execute(path)
+
+Forks and executes a process.
+
+	path: The executable to execute. The $PATH is searched so the full
+	      path to the executable is not generally needed.
+
+Example:
+	execute("xterm")
+
+----
+
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.
diff --git a/doc/python/keyboard.txt b/doc/python/keyboard.txt
new file mode 100644
index 00000000..0cb2caa4
--- /dev/null
+++ b/doc/python/keyboard.txt
@@ -0,0 +1,59 @@
+input.Keyboard
+
+----
+
+This document describes the 'Keyboard' class, exposed by Openbox's 'input'
+module to its python scripts.
+
+All keyboard events which will be generated because of the Keyboard class can
+be caught from the hooks.keyboard hook.
+
+----
+
+Methods
+
+----
+
+bind(keychain, func)
+
+Binds a key-chain to a function. The keychain is a tuple of strings which
+define a chain of key presses. Each member of the tuple has the format
+[Modifier-]...[Key]. Modifiers can be 'mod1', 'mod2', 'mod3', 'mod4', 'mod5',
+'control', and 'shift'. The keys on your keyboard that are bound to each of
+these modifiers can be found by running 'xmodmap'. The Key can be any valid
+key definition. Key definitions can be found by running 'xev', pressing the
+key while its window is focused, and watching its output. Here are some
+examples of valid keychains: ('a'), ('F7'), ('control-a', 'd'),
+('control-mod1-x', 'control-mod4-g'), ('F1', 'space').
+The func must have a definition similar to 'def func(keydata, client)'. The
+arguments passed to the function are a KeyboardData object and a Client object.
+A keychain cannot be bound to more than one function.
+
+	keychain: A tuple containing strings defining a chain of key presses.
+
+	func: A function to bind to the keychain.
+
+----
+
+clearBinds()
+
+Removes all bindings that were previously made by bind().
+
+----
+
+grab(func)
+
+Grabs the entire keyboard, causing all possible keyboard events to be passed
+to the given function. CAUTION: Be sure when you grab() that you also have an
+ungrab() that will execute, or you will not be able to type until you restart
+Openbox. The func must have a definition similar to 'def func(keydata)'. The
+argument passed to the function is a KeyboardData object. The keyboard cannot
+be grabbed if it is already grabbed.
+
+	func: A function to receive all the grabbed keyboard events.
+
+----
+
+ungrab()
+
+Ungrabs the keyboard. The keyboard cannot be ungrabbed if it is not grabbed.
diff --git a/doc/python/keyboarddata.txt b/doc/python/keyboarddata.txt
new file mode 100644
index 00000000..4be55884
--- /dev/null
+++ b/doc/python/keyboarddata.txt
@@ -0,0 +1,35 @@
+KeyboardData
+
+----
+
+This document describes the 'KeyboardData' class, passed to functions bound to
+keyboard events.
+
+----
+
+Attributes
+
+----
+
+keychain
+
+The keychain (in the format that input.Keyboard.bind() expects them) that
+was pressed.
+
+----
+
+state
+
+An integer bitmask of the modifiers pressed down when the key was pressed.
+
+----
+
+keycode
+
+An integer containing the keycode for the key that was pressed.
+
+----
+
+press
+
+True or False for if the event was a key press or a key release
diff --git a/doc/python/openbox.txt b/doc/python/openbox.txt
new file mode 100644
index 00000000..b18c8d3f
--- /dev/null
+++ b/doc/python/openbox.txt
@@ -0,0 +1,208 @@
+ob.Openbox
+
+----
+
+This document describes the 'Openbox' class, exposed by Openbox's 'ob' module
+to its python scripts.
+
+----
+
+Methods
+
+----
+
+shutdown()
+
+Causes Openbox to shutdown and exit.
+
+
+----
+
+restart([path])
+
+Causes Openbox to shutdown and restart. If path is specified, Openbox will
+shutdown and attempt to run the specified executable instead of restarting
+itself. If that fails, however, it will restart itself.
+
+	path: Optional path to replacement executable.
+
+----
+
+state()
+
+Returns Openbox's current state, this will be one of the State constants.
+
+	Returns: One of the State values representing the internal state
+		 of Openbox.
+
+----
+
+desktop()
+
+Returns the number of the currently visible desktop. This will be in the range
+of [0, numDesktops()).
+
+	Returns: The currently visible desktop.
+
+----
+
+setDesktop(desktop)
+
+Sets the specified desktop as the visible desktop.
+
+	desktop: The desktop to make visible. Must be in the range of
+		 [0, numDesktops()) or a ValueError exception will be raised.
+
+----
+
+setNextDesktop([wrap])
+
+Sets the visible desktop to the next desktop, optionally wrapping around when
+reaching the last.
+
+	wrap: An optional argument which, when True will cause the function to
+	      wrap to the first desktop when going past the last. If it is not
+	      specified, it defaults to true.
+
+----
+
+setPreviousDesktop([wrap])
+
+Sets the visible desktop to the previous desktop, optionally wrapping around
+when reaching the first.
+
+	wrap: An optional argument which, when True will cause the function to
+	      wrap to the last desktop when going past the first. If it is not
+	      specified, it defaults to true.
+
+----
+
+numDesktops()
+
+Returns the number of desktops available.
+
+	Returns: The number of available desktops.
+
+----
+
+setNumDesktops(num)
+
+Sets the number of desktops available.
+
+	num: The new number of available desktops. This must be greater than 0.
+
+----
+
+desktopNames()
+
+Returns a tuple of names, containing a name for each desktop. The tuple may
+have a length greater than numDesktops() if more names have been specified.
+
+	Returns: A tuple of names.
+
+----
+
+setDesktopNames(names)
+
+Sets the names for the desktops.
+
+	names: An iterable list of names to apply to the desktops. Can contain
+	       more or less names than numDesktops(). If it contains fewer
+	       names, then Openbox will give the remaining desktops a
+	       placeholder name.
+
+----
+
+showingDesktop()
+
+Returns True or False, depicting if Openbox is in 'showing the desktop' mode.
+In 'showing the desktop' mode, all normal clients are hidden and the desktop
+is given focus if possible.
+
+	Returns: True or False describing if Openbox is in 'showing the
+		 desktop' mode.
+
+----
+
+setShowingDesktop(show)
+
+Enters or leaves 'showing the desktop' mode. See showingDesktop() for a
+description of this mode.
+
+	show: True or False to enter or leave 'showing the desktop' mode
+	      respectively.
+
+----
+
+screenArea(desktop)
+
+Returns the on-screen available area. This is the area not reserved by
+applications' struts. Windows should be placed within this area, not within
+the physicalSize().
+
+	desktop: The desktop for which to get the available area. 0xffffffff to
+		 get the combined area for all desktops (combined
+		 subtractively).
+
+	Returns: A tuple of form (x, y, width, height) containing the
+		 dimensions of the available on-screen area for the desktop.
+
+
+----
+
+screenStrut(desktop)
+
+Returns the combined strut which has been reserved by all applications on the
+desktops.
+
+	desktop: The desktop for which to get the strut. 0xffffffff to get the
+		 combined strut for all desktops (combined additively).
+
+	Returns: A tuple of form (left, top, right, bottom) containing the
+		 size of the reserved strut space for the desktop.
+
+----
+
+physicalSize()
+
+Returns the physical size of the display device (in pixels).
+
+	Returns: A tuple of the form (width, height) containing the size of
+		 the display device's area.
+
+----
+
+screenNumber()
+
+Returns the number of the screen on which Openbox is running.
+
+	Returns: An integer specifying the screen on which this instance of
+		 Openbox is running.
+
+----
+
+rootWindow()
+
+Return the window id of the root window.
+
+	Returns: An integer containing the window id of the root window.
+
+----
+
+clientList()
+
+Returns a all clients currently being managed by Openbox. This list is updated
+as clients are managed and closed/destroyed/released.
+
+	Returns: A list of Clients containing all the clients managed by
+		 Openbox.
+
+----
+
+ob.State
+
+State.Starting: Openbox is starting up and has not yet reached its
+		main event loop.
+State.Running:  Openbox is running normally.
+State.Exiting:  Openbox has left its main event loop and is shutting
+		down.
diff --git a/doc/python/pointer.txt b/doc/python/pointer.txt
new file mode 100644
index 00000000..b2049241
--- /dev/null
+++ b/doc/python/pointer.txt
@@ -0,0 +1,130 @@
+input.Pointer
+
+----
+
+This document describes the 'Pointer' class, exposed by Openbox's 'input'
+module to its python scripts.
+
+All pointer events which will be generated because of the Pointer class can
+be caught from the hooks.pointer hook.
+
+----
+
+Terminology
+
+----
+
+Context -- A context is a string describing a part of a window or screen in
+	   which an event can occur. Contexts are used for grabbing and
+	   tracking pointer events. A list of possible contexts are exposed by
+	   the engine through the contexts() method. The standard list of
+	   contexts are:
+	   * "none" - no context associated.
+	   * "root" - the root window.
+	   * "frame" - the client's entire frame. Note: when a button is
+		       grabbed in the "frame" context, it will not get passed
+		       through to the client.
+	   * "client" - client's window.
+	   * "titlebar" - a client's titlebar.
+	   * "handle" - a client's handle.
+	   * "tlcorner" - the top-left corner of a client's decorations.
+	   * "trcorner" - the top-right corner of a client's decorations.
+	   * "blcorner" - the bottom-left corner of a client's decorations.
+	   * "brcorner" - the bottom-right corner of a client's decorations.
+	   * "maximize" - the maximize button in the titlebar.
+	   * "close" - the close button in the titlebar.
+	   * "iconify" - the iconify button in the titlebar.
+	   * "alldesktops" - the all-desktops button in the titlebar.
+	   * "icon" - the window icon in the titlebar.
+
+	   An engine may add to this list as it sees fit (most engines will
+	   include "close", "maximize", etc. contexts for titlebar buttons).
+
+----
+
+Methods
+
+----
+
+bind(button, context, action, func)
+
+Binds a pointer button for a context and action to a function. See the
+Terminology section for a decription and list of common contexts. The button is
+a string which defines a modifier and button combination with the format
+[Modifier-]...[Button]. Modifiers can be 'mod1', 'mod2', 'mod3', 'mod4',
+'mod5', 'control', and 'shift'. The keys on your keyboard that are bound to
+each of these modifiers can be found by running 'xmodmap'. The button is the
+number of the button. Button numbers can be found by running 'xev', pressing
+the button with the pointer over its window, and watching its output. Here
+are some examples of valid buttons: 'control-1', '2', 'mod1-shift-5'. The 
+action is one of the Action_* constants. The func must have a definition
+similar to 'def func(ptrdata, client)'. The arguments passed to the function
+are a PointerData object and a Client object (or None). A button and context
+may be bound to more than one function.
+
+	button: A string defining the modifiers and button to for which events
+		should be generated.
+
+	context: The context in which the button events should be generated.
+
+	action: One of the Action_* constants specifying the action to bind
+		the function to.
+
+	func: A function to bind to the button/context.
+
+----
+
+clearBinds()
+
+Removes all bindings that were previously made by bind().
+
+----
+
+grab(func)
+
+Grabs the pointer device, causing all possible pointer events to be sent to
+the given function. CAUTION: Be sure when you grab() that you also have an
+ungrab() that will execute, or you will not be able to use the pointer device
+until you restart Openbox. The func must have a definition similar to
+'def func(data)'. The argument passed to the function is a PointerData object.
+The pointer cannot be grabbed if it is already grabbed. When a grab is active,
+no pointer bindings will fire, everything is sent only to the specified func.
+
+	func: A function to receive all the grabbed pointer events.
+
+----
+
+ungrab()
+
+Ungrabs the pointer. The pointer cannot be ungrabbed if it is not grabbed.
+
+----
+
+Constants
+
+----
+
+Action_Press		a pointer button press
+Action_Release		a pointer button release
+Action_Click		a pointer button click (press-release)
+Action_DoubleClick	a pointer button double-click
+Action_Motion		a pointer drag
+
+----
+
+Configuration options (through the config module)
+
+----
+
+double_click_rate
+
+An integer containing the number of milliseconds in which 2 clicks must be
+received to cause a double-click event.
+
+----
+
+drag_threshold
+
+An integer containing the number of pixels a drag must go before motion events
+start getting generated. Once a drag has begun, the button release will not
+count as a click event.
diff --git a/doc/python/pointerdata.txt b/doc/python/pointerdata.txt
new file mode 100644
index 00000000..8db7f0af
--- /dev/null
+++ b/doc/python/pointerdata.txt
@@ -0,0 +1,67 @@
+PointerData
+
+----
+
+This document describes the 'PointerData' class, passed to functions bound to
+pointer events.
+
+----
+
+Attributes
+
+----
+
+action
+
+The type of event. One of the input.Pointer.Action_* constants.
+
+----
+
+button
+
+The button (in the format that input.Pointer.bind() expects them) that caused
+the event. This will be 'None' if there was no button associated with the
+event. (This can only happen during a pointer grab.)
+
+----
+
+context
+
+A string containing the context of the event. See the Terminology section in
+the Pointer documentation for a decription and list of common contexts.
+
+----
+
+state
+
+An integer bitmask of the modifiers pressed down when the event occured.
+
+----
+
+buttonnum
+
+An integer containing the number of the pointer button associated with the
+event.
+
+----
+
+pos
+
+A tuple containing the current position of the cursor. The tuple has the format
+(x, y). This is only valid when 'action' is 'Action_Motion'.
+
+-----
+
+presspos
+
+A tuple containing the position of the cursor when the drag started. The tuple
+has the format (x, y). This is only valid when 'action' is 'Action_Motion'.
+
+----
+
+pressclientarea
+
+A tuple containing the area of the client when the drag started. The tuple has
+the format (x, y, width, height). This will be None if there is no client
+associated with the event (during a pointer grab, or a drag on the root
+window). This is only valid when 'action' is 'Action_Motion'.