1 *******************************************************************************
2 *******************************************************************************
3 ** CAUTION: changing any value in the hook for that value changing is **
4 ** dangerous, as this can easily lead to an infinate loop of updating! **
5 *******************************************************************************
6 *******************************************************************************
12 This document describes the 'Hook' class, exposed by Openbox's 'hooks' module
13 to its python scripts, and the standard hooks exposed in the 'hooks' module.
27 Fires the hook, passing the given arguments on to all functions registered with
28 the hook. Functions are called in the order in which they were added. If any
29 function defined as a hook returns any value other than None, the hook will
30 not fire any more functions.
32 args: Any number of function arguments, which are passed on to the
33 hook's registered functions.
39 Appends a function to the hook.
41 func: The function to add to the hook.
47 Removes the function from the hook.
49 func: The function to remove from the hook.
59 The following standard hooks are defined by Openbox. After each name comes the
60 expected format of a function added to the hook. Adding a function of another
61 format will lead to an exception when the hook is fired.
67 When Openbox is starting, just before it begins managing clients.
73 When Openbox is shutting down, after releasing all clients.
77 visibledesktop - function(new, old)
79 When the current desktop changes.
81 new: An integer containing the new desktop.
83 old: An integer containing the old desktop.
87 numdesktops - function(desktops)
89 When the number of desktops changes.
91 desktops: An integer containing the number of available desktops.
95 desktopnames - function()
97 When the desktops' names have been changed.
101 showdesktop - function(showing)
103 When Openbox enters or leaves 'showing the desktop' mode. Called after the
104 desktop is shown/hidden.
106 showing: True if entering 'showing the desktop' mode, False if leaving.
110 screenconfiguration - function(size)
112 When the screen's size (ob.Openbox.physicalSize()) has changed.
114 size: The new size of the screen, as returned by
115 ob.Openbox.physicalSize().
119 screenarea - function()
121 When the screen's area (ob.Openbox.screenArea()) has changed.
125 managed - function(client)
127 When a client is managed.
129 client: The Client being managed.
133 closed - function(client)
135 When a client is being closed/destroyed/released.
137 client: The Client which has been closed.
141 bell - function(client)
143 When the system bell is fired.
145 client: The Client the bell is associated with, or None. Clients can
146 only be associated with bells through the XKB extension.
150 urgent - function(client)
152 When a window enters/leaves urgent status.
154 client: The client which has become/stopped being urgent.
158 pointerenter - function(client)
160 When the pointer moves above a client.
162 client: The Client that the pointer has move above.
166 pointerleave - function(client)
168 When the pointer moves off of a client.
170 client: The Client that the pointer has moved off of.
174 focused - function(client)
178 client: The Client which has recieved input focus, or None if no client
183 requestactivate - function(client)
185 When a request is made to activate a client.
187 client: The Client who has been requested to be made active.
191 title - function(client)
193 When a client's title or icon title changes.
195 client: The Client whose title changed.
199 desktop - function(client, new, old)
201 When a client's desktop changes.
203 client: The Client that changed desktops.
205 new: An integer containing the client's new desktop.
207 old: An integer containing the client's old desktop.
211 iconic - function(client)
213 When a client's iconic status changes.
215 client: The Client that has been (un)iconified.
219 shaded - function(client)
221 When a client's shaded status changes.
223 client: The Client that has been (un)shaded.
227 maximized - function(client)
229 When a client's maximized status changes.
231 client: The Client that has been (un)maximized.
235 fullscreen - function(client)
237 When a client's fullscreen status changes.
239 client: The Client which as been (un)fullscreened.
243 visible - function(client)
245 When a client becomes visible or hidden, but not for desktop changes.
247 client: The Client which has been shown/hidden.
251 configuration - function(client)
253 When a client's configuration (area/position/size) changes.
255 client: The Client which has moved or resized.