554 lines
14 KiB
Text
554 lines
14 KiB
Text
|
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.
|