doc/python/client.txt

   1 ob.Client
   2
   3 ----
   4
   5 This document describes the 'ob.Client' class, exposed by Openbox to its python
   6 scripts. The 'Client' class cannot be instantiated, and can only be
   7 retrieved by catching events from Openbox, or from the ob.Openbox.clientList()
   8 method.
   9
  10 A Client instance is associated with a single client window which Openbox is
  11 managing. When the client window is closed/destroyed/released, the Client
  12 instance will be marked as invalid (see valid()). Any methods of Client, with
  13 the exception of valid(), will raise a ReferenceError exception if they are
  14 called on a non-valid Client instance. For this reason, it is not encouraged to
  15 keep references to Client instances between events, unless you are tracking the
  16 hooks.closed hook or check valid() before attempting to reuse a Client
  17 instance.
  18
  19 ----
  20
  21 Methods
  22
  23 ----
  24
  25 valid()
  26
  27 Returns if the Client instance is still valid. Client instances are marked as
  28 invalid when the Client they are associated is closed/destroyed/released.
  29
  30         Returns: True or False for if the Client instance is valid.
  31
  32 ----
  33
  34 title()
  35
  36 Returns the client's title.
  37
  38         Returns: A string containing the client's title.
  39
  40 ----
  41
  42 setTitle(title)
  43
  44 Change the client's title to the given string. This change will be overwritten
  45 if/when the client changes its title.
  46
  47         title: A string containing the new title for the client.
  48
  49 ----
  50
  51 iconTitle()
  52
  53 Returns's the client's icon title. The icon title is the title to be displayed
  54 when the client is iconified.
  55
  56         Returns: A string containing the client's icon title.
  57
  58 ----
  59
  60 setIconTitle(title)
  61
  62 Change the client's icon title to the given string. This change will be
  63 overwritten if/when the client changes its icon title.
  64
  65         title: A string containing the new icon title for the client.
  66
  67 ----
  68
  69 desktop()
  70
  71 Returns the desktop on which the client is visible. This value will always be
  72 in the range [0, ob.Openbox.numDesktops()), unless it is 0xffffffff. A value of
  73 0xffffffff indicates the client is visible on all desktops.
  74
  75         Returns: An integer containing the client's desktop,
  76
  77 ----
  78
  79 setDesktop(desktop)
  80
  81 Moves the client to the specified desktop. The desktop must be in the range
  82 [0, ob.Openbox.numDesktops()), unless it is 0xffffffff. A value of 0xffffffff
  83 indicates the client is visible on all desktops.
  84
  85         desktop: The desktop on which to place the client.
  86
  87 ----
  88
  89 resName()
  90
  91 Returns the resouce name of the client. The resource name is meant to provide
  92 an instance name for the client.
  93
  94         Returns: A string containing the client's resource name.
  95
  96 ----
  97 resClass()
  98
  99 Returns the resouce class of the client. The resource class is meant to provide
 100 the genereal class of the application. e.g. 'Emacs', 'Xterm', 'XClock',
 101 'XLoad', and so on.
 102
 103         Returns: A string containing the client's resource class.
 104
 105 ----
 106
 107 role()
 108
 109 Returns the client's role. The role is meant to distinguish between different
 110 windows of an application. Each window should have a unique role.
 111
 112         Returns: A string containing the client window's role.
 113
 114 ----
 115
 116 transient()
 117
 118 Returns True or False describing if the client is a transient window. Transient
 119 windows are 'temporary' windows, such as preference dialogs, and usually have
 120 a parent window, which can be found from transientFor().
 121
 122         Returns: True or False for if the client is a transient window.
 123
 124 ----
 125
 126 transientFor()
 127
 128 Returns the client for which this client is a transient. See transient() for
 129 a description of transience.
 130
 131         Returns: A Client containing the client which this client is transient
 132                  for. None if such a client does not exist.
 133
 134 ----
 135
 136 transients()
 137
 138 Returns a tuple containing all the Clients which are transients of this window.
 139 See transient() for a description of transience.
 140
 141         Returns: A tuple containing Clients which are transients for this
 142                  client. The tuple may be empty.
 143
 144 ----
 145
 146 type()
 147
 148 Returns the logical type of the window. This is one of the ClientType
 149 constants. See also normal().
 150
 151         Returns: The type of the window.
 152
 153 ----
 154
 155 normal()
 156
 157 Returns True or False for if the client is a 'normal' window. Normal windows
 158 make up most applications. Non-normal windows have special rules applied to
 159 them at times such as for focus handling. An example of a non-normal window
 160 is 'gnome-panel'. This value is determined from the client's type(), but does
 161 not imply that the window is ClientType.Normal. Rather this is a more generic
 162 definition of 'normal' windows, and includes dialogs and others.
 163
 164         Returns: True or False declaring the client as 'normal' or not.
 165
 166 ----
 167
 168 area()
 169
 170 Returns the area of the screen which the client occupies. It may be important
 171 to note that this is the position and size of the client *with* its
 172 decorations. If you want the underlying position and size of the client
 173 itself, you should use clientArea(). See also logicalSize().
 174
 175         Returns: A tuple containing the area of the client and decorations on
 176                  the screen. The tuple is in the format (x, y, width, height).
 177
 178 ----
 179
 180 setArea(area, [final])
 181
 182 Sets the client's area, moving and resizing it as specified (or as close as can
 183 be accomidated).
 184
 185         area: The new area for the client, in a tuple. The tuple should be of
 186               the format (x, y, width, height).
 187
 188         final: Optional True or False for if this is a final change. This
 189                should be set to False if the change is only part of a
 190                move/resize. Otherwise, it should be set to True. If it is not
 191                specified, it will default to True.
 192
 193 ----
 194
 195 clientArea()
 196
 197 Returns the area of the screen which the client considers itself to be
 198 occupying. This value is not what you see and should not be used for most
 199 things (it should, for example, be used for persisting a client's dimentions
 200 across sessions). See also area().
 201
 202         Returns: A tuple containing the area the client considers itself to be
 203                  occupying. The tuple is in the format (x, y, width, height).
 204
 205 ----
 206
 207 setClientArea(area)
 208
 209 Sets the area of the screen which the client considers itself to be occupying.
 210 This is not the on-screen visible position and size, and should be used with
 211 care. You probably want to use setArea() to adjust the client. This should be
 212 used if you want the client window (inside the decorations) to be a specific
 213 size. Adjusting the client's position with this function is probably always a
 214 bad idea, because of window gravity.
 215
 216         area: The new area for the client. in a tuple. The tuple should be of
 217               the format (x, y, width, height).
 218
 219 ----
 220
 221 frameSize()
 222
 223 Returns the size of the decorations around the client window.
 224
 225         Returns: A tuple containing the size of the decorations on each side
 226                  of the client window. The tuple has the format
 227                  (left, top, right, bottom).
 228
 229 ----
 230
 231 strut()
 232
 233 Returns the application's specified strut. The strut is the amount of space
 234 that should be reserved for the application on each side of the screen.
 235
 236
 237         Returns: A tuple containing the application's strut. The tuple has the
 238                  format (left, top, right, bottom).
 239
 240 ----
 241
 242 logicalSize()
 243
 244 Returns the client's logical size. The logical size is the client's size in
 245 more user friendly terms. For many apps this is simply the size of the client
 246 in pixels, however for some apps this will differ (e.g. terminal emulators).
 247 This value should be used when displaying an applications size to the user.
 248
 249         Returns: A tuple containing the client's logical size. The tuple has
 250                  the format (width, height).
 251
 252 ----
 253
 254 canFocus()
 255
 256 Returns True or False for if the client can be focused.
 257
 258         Returns: True or False for if the client can recieve input focus.
 259
 260 ----
 261
 262 focus([focus])
 263
 264 Focuses (or unfocuses) the client window. Windows which return False for
 265 canFocus() or visible() cannot be focused. When this function returns, the
 266 client's focused() state will not be changed yet. This only sends the request
 267 through the X server. You should wait for the hooks.focused hook to fire, and
 268 not assume the client has been focused.
 269
 270         focus: Optional. If True, the window will be focused. If False, and
 271                focused() is True, it will lose its focus. If the argument is
 272                not passed, it will default to True.
 273
 274         Returns: True if the client could be focused, and focus has been sent
 275                  to the window. False if the client could not be focused.
 276
 277 ----
 278
 279 focused()
 280
 281 Returns True or False for if the client has the input focus.
 282
 283         Returns: True or False for if the client has the input focus.
 284
 285 ----
 286
 287 visible()
 288
 289 Returns True or False for if the client is visible. A client is not visible if
 290 it is iconic() or if its desktop() is not visible.
 291
 292         Returns: True or False for if the client is visible.
 293
 294 ----
 295
 296 setVisible(show)
 297
 298 Shows or hides the client. This has no effect if its current visible() state
 299 is requested.
 300
 301         show: True or False specifying if the client should be hidden or shown.
 302
 303 ----
 304
 305 modal()
 306
 307 Returns True or False for if the client is a modal window. Modal windows
 308 indicate that they must be dealt with before the program can continue. When
 309 a modal window is a transient(), its transientFor() client cannot be focused or
 310 raised above it.
 311
 312         Returns: True or False for if the client is a modal window.
 313
 314 ----
 315
 316 setModal(modal)
 317
 318 Make the client window modal or non-modal.
 319
 320         mdal: True or False to make the client modal or not respectively.
 321
 322 ----
 323
 324 shaded()
 325
 326 Returns True or False for if the client is shaded. Shaded windows have only
 327 their titlebar decorations showing.
 328
 329 ----
 330
 331 setShaded(shade)
 332
 333 Shade or unshade the client. Shaded windows have only their titlebar
 334 decorations showing. Windows which do not have a titlebar cannot be shaded.
 335
 336         shade: True or False to make the client shaded or not respectively.
 337
 338 ----
 339
 340 iconic()
 341
 342 Returns True or False for if the window is iconified. Iconified windows are not
 343 visible on any desktops.
 344
 345         Returns: True or False for if the client is iconified.
 346
 347 ----
 348
 349 setIconic(iconify, [current])
 350
 351 Iconifies or restores the client window. Iconified windows are not visible on
 352 any desktops. Iconified windows can be restored to the currently visible
 353 desktop or to their original (native) desktop.
 354
 355         iconify: True or False to iconify or deiconify the client repectively.
 356
 357         current: Optional True or False to specify if the client should be
 358                  restored to the currently visible desktop or to the desktop
 359                  from which it was iconified. This does not apply to windows
 360                  who's desktop() is 0xffffffff. If this is not specified, it
 361                  defaults to True (the current desktop).
 362
 363 ----
 364
 365 maximizedHorz()
 366
 367 Returns whether the client is maximized in the horizontal direction.
 368
 369         Returns: True if the client is maximized horizontally; False if it is
 370                  not.
 371
 372 ----
 373
 374 setMaximizedHorz(max)
 375
 376 Maximizes or restores a client horizontally.
 377
 378         max: True or False for if the client should be maximized or
 379              unmaximized in the horizontal direction.
 380
 381 ----
 382
 383 maximizedVert()
 384
 385 Returns whether the client is maximized in the vertical direction.
 386
 387         Returns: True if the client is maximized vertically; False if it is
 388                  not.
 389
 390 ----
 391
 392 setMaximizedVert(max)
 393
 394 Maximizes or restores a client vertically.
 395
 396         max: True or False for if the client should be maximized or
 397              unmaximized in the vertical direction.
 398
 399 ----
 400
 401 maximized()
 402
 403 Returns whether the client is maximized in the horizontal or vertical
 404 direction.
 405
 406         Returns: True if the client is maximized horizontally or vertically;
 407                  False if it is not.
 408
 409 ----
 410
 411 setMaximized(max)
 412
 413 Maximizes or restores a client vertically and horzontally.
 414
 415         max: True or False for if the client should be maximized or
 416              unmaximized in the vertical and horizontal direction.
 417 -
 418 ---
 419
 420 fullscreen()
 421
 422 Returns if the client is in fullscreen mode. Fullscreen windows are kept above
 423 all other windows and are stretched to fill the entire physical display.
 424
 425         Returns: True or False for if the client is fullscreen.
 426
 427 ----
 428
 429 setFullscreen(full)
 430
 431 Set a client into or out of fullscreen mode. Fullscreen windows are kept above
 432 all other windows and are stretched to fill the entire physical display.
 433
 434         full: True or False to set the client into or out of fullscreen mode
 435               respectively.
 436
 437 ----
 438
 439 stacking()
 440
 441 Returns if the client will be stacked above/below other clients in the same
 442 layer.
 443
 444         Returns: An integer > 0 if the client will be stacked above other
 445                  clients in its layer. An integer < 0 if it will be stacked
 446                  below other clients. 0 will be returned if the client is
 447                  stacked as normal amongst other clients in its layer.
 448
 449 ----
 450
 451 setStacking(stack)
 452
 453 Set how the client will be stacked according to other clients in its layer.
 454
 455         stack: An integer > 0 if the client should be stacked above other
 456                clients in its layer. An integer < 0 if it should be stacked
 457                below other clients. Exactly 0 if the client should be stacked
 458                as normal amongst other clients in its layer.
 459
 460 ----
 461
 462 raiseWindow()
 463
 464 Raises the window to the top of its stacking layer.
 465
 466 ----
 467
 468 lowerWindow()
 469
 470 Lowers the window to the bottom of its stacking layer.
 471
 472 ----
 473
 474 skipPager()
 475
 476 Returns if the client has requested to be skipped (not displayed) by pagers.
 477
 478         Returns: True or False for if the client has requested to be skiped by
 479                  pagers.
 480
 481 ----
 482
 483 setSkipPager(skip)
 484
 485 Set whether the client should be skipped (not displayed) by pagers.
 486
 487         skip: True or False to make the client be skipped or not skipped by
 488               pagers.
 489
 490 ----
 491
 492 skipTaskbar()
 493
 494 Returns if the client has requested to be skipped (not displayed) by taskbars.
 495
 496         Returns: True or False for if the client has requested to be skiped by
 497                  taskbars.
 498
 499 ----
 500
 501 setSkipTaskbar(skip)
 502
 503 Set whether the client should be skipped (not displayed) by taskbars.
 504
 505         skip: True or False to make the client be skipped or not skipped by
 506               taskbars.
 507
 508 ----
 509
 510 disableDecorations(titlebar, handle, border)
 511
 512 Choose which decorations to disable on the client. Note that decorations can
 513 only be disabled, and decorations that would normally not be shown cannot be
 514 added. These values may have slightly different meanings in different theme
 515 engines.
 516
 517         titlebar: True to disable, or False to enable (if possible) the
 518                   client's titlebar.
 519
 520         handle: True to disable, or False to enable (if possible) the
 521                 client's handle.
 522
 523         border: True to disable, or False to enable (if possible) the
 524                 client's border.
 525
 526 ----
 527
 528 close()
 529
 530 Requests the client to close its window.
 531
 532 ----
 533
 534 window()
 535
 536 Returns the client's window id. This is the id by which the X server knows the
 537 client.
 538
 539         Returns: An integer containing the client's window id.
 540
 541 ----
 542
 543 ob.ClientType
 544
 545 ClientType.Normal: a normal application window.
 546 ClientType.Dialog: a dialog window (usually a transient()).
 547 ClientType.Desktop: a desktop (bottom-most) window.
 548 ClientType.Dock: a dock or panel window.
 549 ClientType.Toolbar: a toolbar "torn off" from an application.
 550 ClientType.Menu: a pinnable menu "torn off" from an application.
 551 ClientType.Utility: a small persistent utility window such as a
 552                     palette or toolbox.
 553 ClientType.Splash: a splash screen window.