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()
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
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.
30 Returns: True or False for if the Client instance is valid.
36 Returns the client's title.
38 Returns: A string containing the client's title.
44 Change the client's title to the given string. This change will be overwritten
45 if/when the client changes its title.
47 title: A string containing the new title for the client.
53 Returns's the client's icon title. The icon title is the title to be displayed
54 when the client is iconified.
56 Returns: A string containing the client's icon title.
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.
65 title: A string containing the new icon title for the client.
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.
75 Returns: An integer containing the client's desktop,
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.
85 desktop: The desktop on which to place the client.
91 Returns the resouce name of the client. The resource name is meant to provide
92 an instance name for the client.
94 Returns: A string containing the client's resource name.
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',
103 Returns: A string containing the client's resource class.
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.
112 Returns: A string containing the client window's role.
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().
122 Returns: True or False for if the client is a transient window.
128 Returns the client for which this client is a transient. See transient() for
129 a description of transience.
131 Returns: A Client containing the client which this client is transient
132 for. None if such a client does not exist.
138 Returns a tuple containing all the Clients which are transients of this window.
139 See transient() for a description of transience.
141 Returns: A tuple containing Clients which are transients for this
142 client. The tuple may be empty.
148 Returns the logical type of the window. This is one of the ClientType
149 constants. See also normal().
151 Returns: The type of the window.
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.
164 Returns: True or False declaring the client as 'normal' or not.
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().
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).
180 setArea(area, [final])
182 Sets the client's area, moving and resizing it as specified (or as close as can
185 area: The new area for the client, in a tuple. The tuple should be of
186 the format (x, y, width, height).
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.
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().
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).
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.
216 area: The new area for the client. in a tuple. The tuple should be of
217 the format (x, y, width, height).
223 Returns the size of the decorations around the client window.
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).
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.
237 Returns: A tuple containing the application's strut. The tuple has the
238 format (left, top, right, bottom).
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.
249 Returns: A tuple containing the client's logical size. The tuple has
250 the format (width, height).
256 Returns True or False for if the client can be focused.
258 Returns: True or False for if the client can recieve input focus.
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.
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.
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.
281 Returns True or False for if the client has the input focus.
283 Returns: True or False for if the client has the input focus.
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.
292 Returns: True or False for if the client is visible.
298 Shows or hides the client. This has no effect if its current visible() state
301 show: True or False specifying if the client should be hidden or shown.
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
312 Returns: True or False for if the client is a modal window.
318 Make the client window modal or non-modal.
320 mdal: True or False to make the client modal or not respectively.
326 Returns True or False for if the client is shaded. Shaded windows have only
327 their titlebar decorations showing.
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.
336 shade: True or False to make the client shaded or not respectively.
342 Returns True or False for if the window is iconified. Iconified windows are not
343 visible on any desktops.
345 Returns: True or False for if the client is iconified.
349 setIconic(iconify, [current])
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.
355 iconify: True or False to iconify or deiconify the client repectively.
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).
367 Returns whether the client is maximized in the horizontal direction.
369 Returns: True if the client is maximized horizontally; False if it is
374 setMaximizedHorz(max)
376 Maximizes or restores a client horizontally.
378 max: True or False for if the client should be maximized or
379 unmaximized in the horizontal direction.
385 Returns whether the client is maximized in the vertical direction.
387 Returns: True if the client is maximized vertically; False if it is
392 setMaximizedVert(max)
394 Maximizes or restores a client vertically.
396 max: True or False for if the client should be maximized or
397 unmaximized in the vertical direction.
403 Returns whether the client is maximized in the horizontal or vertical
406 Returns: True if the client is maximized horizontally or vertically;
413 Maximizes or restores a client vertically and horzontally.
415 max: True or False for if the client should be maximized or
416 unmaximized in the vertical and horizontal direction.
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.
425 Returns: True or False for if the client is fullscreen.
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.
434 full: True or False to set the client into or out of fullscreen mode
441 Returns if the client will be stacked above/below other clients in the same
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.
453 Set how the client will be stacked according to other clients in its layer.
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.
464 Raises the window to the top of its stacking layer.
470 Lowers the window to the bottom of its stacking layer.
476 Returns if the client has requested to be skipped (not displayed) by pagers.
478 Returns: True or False for if the client has requested to be skiped by
485 Set whether the client should be skipped (not displayed) by pagers.
487 skip: True or False to make the client be skipped or not skipped by
494 Returns if the client has requested to be skipped (not displayed) by taskbars.
496 Returns: True or False for if the client has requested to be skiped by
503 Set whether the client should be skipped (not displayed) by taskbars.
505 skip: True or False to make the client be skipped or not skipped by
510 disableDecorations(titlebar, handle, border)
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
517 titlebar: True to disable, or False to enable (if possible) the
520 handle: True to disable, or False to enable (if possible) the
523 border: True to disable, or False to enable (if possible) the
530 Requests the client to close its window.
536 Returns the client's window id. This is the id by which the X server knows the
539 Returns: An integer containing the client's window id.
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
553 ClientType.Splash: a splash screen window.