doc/python/hooks.txt

   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 *******************************************************************************
   7
   8 hooks
   9
  10 ----
  11
  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.
  14
  15 ----
  16
  17 hooks.Hook
  18
  19 ----
  20
  21 Methods
  22
  23 ----
  24
  25 __call__(args)
  26
  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.
  31
  32         args: Any number of function arguments, which are passed on to the
  33               hook's registered functions.
  34
  35 ----
  36
  37 append(func)
  38
  39 Appends a function to the hook.
  40
  41         func: The function to add to the hook.
  42
  43 ----
  44
  45 remove(func)
  46
  47 Removes the function from the hook.
  48
  49         func: The function to remove from the hook.
  50
  51 ----
  52
  53 hooks
  54
  55 ----
  56
  57 Hooks
  58
  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.
  62
  63 ----
  64
  65 startup - function()
  66
  67 When Openbox is starting, just before it begins managing clients.
  68
  69 ----
  70
  71 shutdown - function()
  72
  73 When Openbox is shutting down, after releasing all clients.
  74
  75 ----
  76
  77 visibledesktop - function(new, old)
  78
  79 When the current desktop changes.
  80
  81         new: An integer containing the new desktop.
  82
  83         old: An integer containing the old desktop.
  84
  85 ----
  86
  87 numdesktops - function(desktops)
  88
  89 When the number of desktops changes.
  90
  91         desktops: An integer containing the number of available desktops.
  92
  93 ----
  94
  95 desktopnames - function()
  96
  97 When the desktops' names have been changed.
  98
  99 ----
 100
 101 showdesktop - function(showing)
 102
 103 When Openbox enters or leaves 'showing the desktop' mode. Called after the
 104 desktop is shown/hidden.
 105
 106         showing: True if entering 'showing the desktop' mode, False if leaving.
 107
 108 ----
 109
 110 screenconfiguration - function(size)
 111
 112 When the screen's size (ob.Openbox.physicalSize()) has changed.
 113
 114         size: The new size of the screen, as returned by
 115               ob.Openbox.physicalSize().
 116
 117 ----
 118
 119 screenarea - function()
 120
 121 When the screen's area (ob.Openbox.screenArea()) has changed.
 122
 123 ----
 124
 125 managed - function(client)
 126
 127 When a client is managed.
 128
 129         client: The Client being managed.
 130
 131 ----
 132
 133 closed - function(client)
 134
 135 When a client is being closed/destroyed/released.
 136
 137         client: The Client which has been closed.
 138
 139 ----
 140
 141 bell - function(client)
 142
 143 When the system bell is fired.
 144
 145         client: The Client the bell is associated with, or None. Clients can
 146                 only be associated with bells through the XKB extension.
 147
 148 ----
 149
 150 urgent - function(client)
 151
 152 When a window enters/leaves urgent status.
 153
 154         client: The client which has become/stopped being urgent.
 155
 156 ----
 157
 158 pointerenter - function(client)
 159
 160 When the pointer moves above a client.
 161
 162         client: The Client that the pointer has move above.
 163
 164 ----
 165
 166 pointerleave - function(client)
 167
 168 When the pointer moves off of a client.
 169
 170         client: The Client that the pointer has moved off of.
 171
 172 ----
 173
 174 focused - function(client)
 175
 176 When focus changes.
 177
 178         client: The Client which has recieved input focus, or None if no client
 179                 is focused.
 180
 181 ----
 182
 183 requestactivate - function(client)
 184
 185 When a request is made to activate a client.
 186
 187         client: The Client who has been requested to be made active.
 188
 189 ----
 190
 191 title - function(client)
 192
 193 When a client's title or icon title changes.
 194
 195         client: The Client whose title changed.
 196
 197 ----
 198
 199 desktop - function(client, new, old)
 200
 201 When a client's desktop changes.
 202
 203         client: The Client that changed desktops.
 204
 205         new: An integer containing the client's new desktop.
 206
 207         old: An integer containing the client's old desktop.
 208
 209 ----
 210
 211 iconic - function(client)
 212
 213 When a client's iconic status changes.
 214
 215         client: The Client that has been (un)iconified.
 216
 217 ----
 218
 219 shaded - function(client)
 220
 221 When a client's shaded status changes.
 222
 223         client: The Client that has been (un)shaded.
 224
 225 ----
 226
 227 maximized - function(client)
 228
 229 When a client's maximized status changes.
 230
 231         client: The Client that has been (un)maximized.
 232
 233 ----
 234
 235 fullscreen - function(client)
 236
 237 When a client's fullscreen status changes.
 238
 239         client: The Client which as been (un)fullscreened.
 240
 241 ----
 242
 243 visible - function(client)
 244
 245 When a client becomes visible or hidden, but not for desktop changes.
 246
 247         client: The Client which has been shown/hidden.
 248
 249 ----
 250
 251 configuration - function(client)
 252
 253 When a client's configuration (area/position/size) changes.
 254
 255         client: The Client which has moved or resized.