A gtk.gdk.Window
object interacts with the native window system for input and events. Some
gtk.Widget
objects do not have an associated gtk.gdk.Window and
therefore cannot receive events. To receive events on behalf of these
"windowless" widgets a gtk.EventBox must
be used.

A gtk.gdk.Window Composited Windows example

import gtk
import cairo
'''
The expose event handler for the event box.
This function simply draws a transparency onto a widget on the area
for which it receives expose events. This is intended to give the
event box a "transparent" background.
In order for this to work properly, the widget must have an RGBA
colourmap. The widget should also be set as app-paintable since it
doesn't make sense for GTK+ to draw a background if we are drawing it
(and because GTK+ might actually replace our transparency with its
default background colour).
'''
def transparent_expose(widget, event):
cr = widget.window.cairo_create()
cr.set_operator(cairo.OPERATOR_CLEAR)
# Ugly but we don't have event.region
region = gtk.gdk.region_rectangle(event.area)
cr.region(region)
cr.fill()
return False
'''
The expose event handler for the window.
This function performs the actual compositing of the event box onto
the already-existing background of the window at 50% normal opacity.
In this case we do not want app-paintable to be set on the widget
since we want it to draw its own (red) background. Because of this,
however, we must ensure that we use g_signal_register_after so that
this handler is called after the red has been drawn. If it was
called before then GTK would just blindly paint over our work.
Note: if the child window has children, then you need a cairo 1.16
feature to make this work correctly.
'''
def window_expose_event(widget, event):
#get our child (in this case, the event box)
child = widget.get_child()
#create a cairo context to draw to the window
cr = widget.window.cairo_create()
#the source data is the (composited) event box
cr.set_source_pixmap (child.window,
child.allocation.x,
child.allocation.y)
#draw no more than our expose event intersects our child
region = gtk.gdk.region_rectangle(child.allocation)
r = gtk.gdk.region_rectangle(event.area)
region.intersect(r)
cr.region (region)
cr.clip()
#composite, with a 50% opacity
cr.set_operator(cairo.OPERATOR_OVER)
cr.paint_with_alpha(0.5)
return False
# Make the widgets
w = gtk.Window()
b = gtk.Button("A Button")
e = gtk.EventBox()
# Put a red background on the window
red = gtk.gdk.color_parse("red")
w.modify_bg(gtk.STATE_NORMAL, red)
# Set the colourmap for the event box.
# Must be done before the event box is realised.
screen = e.get_screen()
rgba = screen.get_rgba_colormap()
e.set_colormap(rgba)
# Set our event box to have a fully-transparent background
# drawn on it. Currently there is no way to simply tell GTK+
# that "transparency" is the background colour for a widget.
e.set_app_paintable(True)
e.connect("expose-event", transparent_expose)
# Put them inside one another
w.set_border_width(10)
w.add(e)
e.add(b)
# Realise and show everything
w.show_all()
# Set the event box GdkWindow to be composited.
# Obviously must be performed after event box is realised.
e.window.set_composited(True)
# Set up the compositing handler.
# Note that we do _after_ so that the normal (red) background is drawn
# by gtk before our compositing occurs.
w.connect_after("expose-event", window_expose_event)
gtk.main()

In this example a button is placed inside of an event box inside of a window.
The event box is set as composited and therefore is no longer automatically
drawn to the screen.

When the contents of the event box change, an expose event is generated on its
parent window (which, in this case, belongs to the toplevel
gtk.Window). The expose
handler for this widget is responsible for merging the changes back on the screen
in the way that it wishes.

In our case, we merge the contents with a 50% transparency. We also set the background
colour of the window to red. The effect is that the background shows through the button.

Creates a new gtk.gdk.Window of
the type and class specified by window_type and
wclass. The window will be a child of the specified
parent and will have the specified
width and height.
event_mask is a bitfield specifying the events that
the window will receive - see the set_events()
method for more information. The value of window_type
must be one of the GDK Window Type Constants.

Methods

gtk.gdk.Window.drag_begin

The drag_begin() method starts a drag
operation and returns the new gtk.gdk.DragContext
created for it. The list of targets (integer values) supported by the drag
source are specified by targets.

gtk.gdk.Window.input_set_extension_events

def input_set_extension_events(mask, mode)

mask :

the event mask to be used

mode :

the set of extension events to
receive

The input_set_extension_events() method
enables or disables the extension events specified by
mode for the window when using the event mask
specified by mask. The value of
mode must be one of the GDK Extension Mode Constants

gtk.gdk.Window.property_get

def property_get(property, type=0, pdelete=False)

property :

the property to get

type :

the type of property to get or not specified if
any type of property data is acceptable.

pdelete :

if True, delete the property
after retrieving the data.

Returns :

a tuple containing the actual property type,
the data format and the data

The property_get() method returns a
tuple containing the actual property type (as a gtk.gdk.Atom), the
format and the data of the specified property with
the specified type. The value of
type may not be be specified in which case it will be
0 to match any type of property. the returned data will be a string if the
data format is 8; a list of integers if the data format is 16; or, a list of
gtk.gdk.Atom
objects or integers if the data format is 32. If
property cannot be found None is
returned. property and type
(if specified) must be a string or a gtk.gdk.Atom.

gtk.gdk.Window.property_change

def property_change(property, type, format, mode, data)

property :

the property to change

type :

the new type of the property. If
mode is gtk.gdk.PROP_MODE_PREPEND
or gtk.gdk.PROP_MODE_APPEND, then this must match the
existing type or an error will occur.

format :

the new format for the property. If
mode is gtk.gdk.PROP_MODE_PREPEND
or gtk.gdk.PROP_MODE_APPEND, then this must match the
existing format or an error will occur.

mode :

a value describing how the new data is to be
combined with the current data.

data :

the data for the property

The property_change() method changes
the contents of the specified property to the
specified data with the specified
type and format. The value of
mode must be one of the GDK Property Mode Constants which describes how the
new data is to be combined with the existing property data.The value of
format must be 8, 16 or
32. property and type must be
a string or a gtk.gdk.Atom.

gtk.gdk.Window.property_delete

def property_delete(property)

property :

the property to delete

The property_delete() method deletes
the specified property from the window.
property must be a string or a gtk.gdk.Atom.

gtk.gdk.Window.selection_convert

def selection_convert(selection, target, time)

selection :

the selection to retrieve

target :

the target form of
selection

time :

the timestamp to use when retrieving
selection. The selection owner may refuse the request
if it did not own the selection at the time indicated by the
timestamp.

The selection_convert() method converts
the specified selection to the specified
form.

gtk.gdk.Window.set_keep_above

def set_keep_above(setting)

setting :

xif True keep the window
above other windows

Note

This method is available in PyGTK 2.4 and above.

The set_keep_above() method sets the
"keep-above" setting to the value of setting. If
setting is True the window must be
kept above other windows. If the window is already above, then this method
does nothing.

On X11, asks the window manager to keep the window above, if the
window manager supports this operation. Not all window managers support
this, and some deliberately ignore it or don't have a concept of "keep
above", but most standard window managers do.

gtk.gdk.Window.set_keep_below

def set_keep_below(setting)

setting :

if True, keep the window
below other windows

Note

This method is available in PyGTK 2.4 and above.

The set_keep_below() method sets the
"keep-below" setting to the value of setting. If
setting is True the window must be
kept below other windows. If the window was already below, then this
method does nothing.

On X11, asks the window manager to keep the window below, if the
window manager supports this operation. Not all window managers support
this, and some deliberately ignore it or don't have a concept of "keep
below" but most standard window managers do.

gtk.gdk.Window.destroy

def destroy()

The destroy() method destroys the
window (destroys the server-side resource associated with the window). All
children of the window are also destroyed. There's normally no need to use
this method since windows are automatically destroyed when their reference
count reaches 0.

gtk.gdk.Window.get_window_type

gtk.gdk.Window.show

def show()

The show() method maps the window so
it's visible on-screen and also raises it to the top of the window stack
(moves the window to the front of the Z-order). This method is opposite to
the hide()
method. When implementing a gtk.Widget, you
should call this method on the widget's gtk.gdk.Window as
part of the "map" method.

gtk.gdk.Window.hide

def hide()

The hide() method withdraws toplevel
windows, so they will no longer be known to the window manager and for all
windows, unmaps them, so they won't be displayed. This is normally done
automatically as part of the gtk.Widget.hide()
method.

gtk.gdk.Window.withdraw

def withdraw()

The withdraw() method withdraws the
window (unmaps it and asks the window manager to forget about it). This is
normally done automatically by the gtk.Widget.hide()
method called on a gtk.Window.

gtk.gdk.Window.move

def move(x, y)

x :

the X coordinate relative to the window's
parent

y :

the Y coordinate relative to the window's
parent

The move() method repositions the
window to the location specified by x and
y relative to its parent window. For toplevel
windows, window managers may ignore or modify the move. You should probably
use the gtk.Window.move()
method on a gtk.Window widget
anyway, instead of using this method. For child windows, the move will
reliably succeed. If you're also planning to resize the window, use the
move_resize()
method to both move and resize simultaneously, for a nicer visual
effect.

gtk.gdk.Window.resize

def resize(width, height)

width :

the new width of the
window

height :

the new height of the
window

The resize() method resizes the window
to the specified width and
height. For toplevel windows, this method asks the
window manager to resize the window. However, the window manager may not
allow the resize. You should use the gtk.Window.resize()
method instead of this low-level method. Windows may not be resized smaller
than 1x1. If you're also planning to move the window, use the move_resize()
method to both move and resize simultaneously, for a nicer visual
effect.

gtk.gdk.Window.move_resize

def move_resize(x, y, width, height)

x :

the new X position relative to the window's
parent

y :

the new Y position relative to the window's
parent

width :

the new width

height :

the new height

The move_resize() method repositions
the window to the location specified by x and
y with the size specified by
width and height. This method
is equivalent to calling the move() and
resize()
methods, except that both operations are performed at once, avoiding strange
visual effects. (i.e. the user may be able to see the window first move,
then resize, if you don't use the move_resize()
method.)

gtk.gdk.Window.reparent

The reparent() method reparents the
window into the gtk.gdk.Window
specified new_parent. The window being reparented
will be unmapped as a side effect.

gtk.gdk.Window.clear

def clear()

The clear() method clears an entire the
window to the background color or background pixmap.

gtk.gdk.Window.clear_area

def clear_area(x, y, width, height)

x :

the X coordinate of the rectangle to
clear

y :

the Y coordinate of the rectangle to
clear

width :

the width of the rectangle to
clear

height :

the height of the rectangle to
clear

The clear_area() method clears the area
(specified by x, y,
width and height) of the
window to the background color or background pixmap.

gtk.gdk.Window.clear_area_e

def clear_area_e(x, y, width, height)

x :

the X coordinate of the rectangle to
clear

y :

the Y coordinate of the rectangle to
clear

width :

the width of the rectangle to
clear

height :

the height of the rectangle to
clear

The clear_area_e() method is like the
clear_area(),
but also generates an expose event for the cleared area.

gtk.gdk.Window.raise_

def raise_()

The raise_() method raises the window to
the top of the Z-order (stacking order), so that other windows with the same
parent window appear below the window. If the window is a toplevel, the
window manager may choose to deny the request to move the window in the
Z-order. Therefore, the raise_()
method only requests the restack, it does not guarantee it.

Note

This method is called raise() in
the C API, but was renamed raise_()
since raise is a reserved Python keyword.

gtk.gdk.Window.lower

def lower()

The lower() method lowers the window to the bottom of the
Z-order (stacking order), so that other windows with the same parent window
appear above the window. If the window is a toplevel, the window manager may
choose to deny the request to move the window in the Z-order. Therefore, the
lower()
only requests the restack, it does not guarantee it. Note that the show()
method raises the window again, so don't call this method before calling the
show()
method to avoid duplication.

gtk.gdk.Window.focus

def focus(timestamp=0L)

timestamp :

the timestamp of the event triggering the
window focus

The focus() method sets keyboard focus
to the window. If the window is not on-screen this will not work. In most
cases, the gtk.Window.present()
method should be used on a gtk.Window, rather
than calling this method.

gtk.gdk.Window.set_user_data

Note

This method is available in PyGTK 2.4 and above.

The set_user_data() method stores the
underlying GTK+ widget of the PyGTK widget that is specified by
user_data as the user data of the window. In general
GTK+ stores the widget that owns a gtk.gdk.Window as
user data on a gtk.Window. So,
custom widget implementations in PyGTK should use this
method to provide that capability. If GTK+ receives an
event for a gtk.gdk.Window, and
the user data for the window is set, GTK+ will assume the
user data is a gtk.Widget, and
forward the event to that widget.

In PyGTK 2.4 and above this method will raise the TypeError
exception if user_data is not a gtk.Widget.

Note

This method is deprecated for any use other than the above. To
set other user data on a gtk.gdk.Window use
the gobject.GObject.set_data()
method instead.

gtk.gdk.Window.get_user_data

def get_user_data()

Returns :

the user data set on the
window

Note

This method is available in PyGTK 2.4 and above.

The get_user_data() method returns the
PyGTK widget that was set as the user data of the window using the set_user_data()
method. This method raises the ValueError exception if the user data is not
set or is not a PyGTK object.

gtk.gdk.Window.set_override_redirect

def set_override_redirect(override_redirect)

override_redirect :

if True the window should be
override redirect

The set_override_redirect() method sets
the "override redirect" attribute on the window to the value specified by
override_redirect. If
override_redirect is True the
window is not under the control of the window manager. This means it won't
have a titlebar, won't be minimizable, etc. - it will be entirely under the
control of the application. The window manager can't see the override
redirect window at all. Override redirect should only be used for
short-lived temporary windows, such as popup menus. gtk.Menu uses an
override redirect window in its implementation, for example. This method
does not work on MS Windows.

gtk.gdk.Window.add_filter

def add_filter(function, data=None)

function :

a function

data :

data to pass to
function

Note

This method is available in PyGTK 2.2 and above.

The add_filter() method adds an event
filter function specified by function to the window,
allowing you to intercept events before they reach GDK. This is a low-level
operation and makes it easy to break GDK and/or GTK+, so you have to know
what you're doing. Once added there is no way to remove a filter
function. The function signature is:

def function(event, user_data)

where event is a gtk.gdk.Event and
user_data is data. If
data is not specified then
user_data is not passed to
function.

gtk.gdk.Window.scroll

def scroll(dx, dy)

dx :

the amount to scroll in the X
direction

dy :

the amount to scroll in the Y
direction

The scroll() method scrolls the
contents of the window, both pixels and children, by the horizontal and
vertical amounts specified by dx and
dy respectively. The window itself does not move.
Portions of the window that the scroll operation brings in from off-screen
areas are invalidated. The invalidated region may be bigger than what would
strictly be necessary. (For X11, a minimum area will be invalidated if the
window has no subwindows, or if the edges of the window's parent do not
extend beyond the edges of the window. In other cases, a multi-step process
is used to scroll the window which may produce temporary visual artifacts
and unnecessary invalidations.)

gtk.gdk.Window.shape_combine_mask

def shape_combine_mask(shape_mask, offset_x, offset_y)

shape_mask :

the shape bitmap mask

offset_x :

the X position of shape mask with respect to
the window

offset_y :

the Y position of shape mask with respect to
the window

The shape_combine_mask() method applies
the bitmap mask specified by shape_mask to the window
at the location specified by x and
y. Pixels in the window corresponding to set bits in
the shape_mask will be visible; pixels in the window
corresponding to unset bits in the shape_mask will be
transparent. This method provides a non-rectangular window. If
shape_mask is None, the shape mask
will be unset, and the x/y
parameters are not used.

On the X11 platform, this uses an X server extension which is
widely available on most common platforms, but not available on very old X
servers, and occasionally the implementation will be buggy. On servers
without the shape extension, this function will do nothing.

gtk.gdk.Window.set_child_shapes

def set_child_shapes()

The set_child_shapes() method sets the
shape mask of the window to the union of shape masks for all children of the
window, ignoring the shape mask of the window itself. Contrast this method
with the merge_child_shapes()
method that includes the shape mask of the window in the masks to be
merged.

gtk.gdk.Window.merge_child_shapes

def merge_child_shapes()

The merge_child_shapes() method merges
the shape masks for any child windows into the shape mask for the window.
i.e. the union of all masks for the window and its children will become the
new mask for the window. See the shape_combine_mask()
method. This method is distinct from the set_child_shapes()
method because it includes the window's shape mask in the set of shapes to
be merged.

gtk.gdk.Window.is_visible

def is_visible()

Returns :

True if the window is
mapped

The is_visible() method returns
True if the window has been mapped (with the show()
method.

gtk.gdk.Window.is_viewable

def is_viewable()

Returns :

True if the window is
viewable

The is_viewable() method returns
True if the window and all its ancestors are mapped.
(This is not necessarily "viewable" in the X sense, since we only check as
far as we have gtk.gdk.Window
parents, not to the root window.)

gtk.gdk.Window.get_state

gtk.gdk.Window.set_static_gravities

def set_static_gravities(use_static)

use_static :

if True turn on static
gravity

Returns :

True if the server supports
static gravity

The set_static_gravities() method sets
the bit gravity of the given window to the value specified by
use_static. If use_static is
True the window uses static gravity and all children get
static subwindow gravity as well. This method returns
True if the window system server supports static
gravity.

gtk.gdk.Window.get_type_hint

def get_type_hint()

Returns :

The type hint set for window.

The get_type_hint() method returns the
type hint set for a window.

gtk.gdk.Window.set_type_hint

def set_type_hint(hint)

hint :

a hint of the function this window will
have

The set_type_hint() method provides the
specified hint to the window manager about the
functionality of a window. The window manager can use this information when
determining the decoration and behavior of the window. The hint must be set
before the window is mapped. The value of hint must be one of the GDK Window Type Hint Constants.

gtk.gdk.Window.set_modal_hint

def set_modal_hint(modal)

modal :

if True the window is
modal.

The set_modal_hint() method sets the
window's modal hint to the value specified by modal.
If modal is True the window is
modal. The window manager can use this information to handle modal windows
in a special way which usually means that the window gets all the input for
the application effectively blocking input to other windows in the
application. . You should only use this on windows for which you have
previously called the set_transient_for()
method

gtk.gdk.Window.set_skip_taskbar_hint

def set_skip_taskbar_hint(modal)

skip_taskbar :

if True skip the
taskbar.

Note

This method is available in PyGTK 2.2 and above.

The set_skip_taskbar_hint() method sets
the "skip_taskbar" setting to the value specified by
skips_taskbar. If
skips_taskbar is True the window
should not appear in a task list or window
list. If the window's semantic type as specified with the set_type_hint()
method already fully describes the window, this method should not be called in addition; instead you should allow
the window to be treated according to standard policy for its semantic
type.

gtk.gdk.Window.set_skip_pager_hint

def set_skip_pager_hint(skips_pager)

skips_pager :

if True skip the pager

Note

This method is available in PyGTK 2.2 and above.

The set_skip_pager_hint() method sets
the "skip_pager" setting to the value of skips_pager. If skips_pager is True
the window should not appear in a pager (a
workspace switcher, or other desktop utility program that displays a small
thumbnail representation of the windows on the desktop). If the window's
semantic type as specified with set_type_hint()
already fully describes the window, this method should not be called in addition, instead you should allow
the window to be treated according to standard policy for its semantic
type.

Note

This method is available in PyGTK 2.2 and above.

The set_geometry_hints() method sets
the geometry hints for the window.

This method provides hints to the windowing system about
acceptable sizes for a toplevel window. The purpose of this is to constrain
user resizing, but the windowing system will typically (but is not required
to) also constrain the current size of the window to the provided values and
constrain programmatic resizing via gdk_window_resize() or
gdk_window_move_resize().

Note that on X11, this effect has no effect on windows of type
GDK_WINDOW_TEMP or windows where override_redirect has been turned on via
the set_override_redirect()
method since these windows are not resizable by the user.

gtk.gdk.Window.begin_paint_rect

def begin_paint_rect(rectangle)

rectangle :

the rectangle you intend to draw
to

The begin_paint_rect() method indicates
that you are beginning the process of redrawing the area specified by
rectangle. A backing store (off-screen buffer) large
enough to contain rectangle will be created. The
backing store will be initialized with the background color or background
pixmap for window. Then, all drawing operations performed on the window will
be diverted to the backing store. When you call the end_paint()
method, the backing store will be copied to the window, making it visible
on-screen. Only the part of window contained in region will be modified; that
is, drawing operations are clipped to rectangle. The
net result of all this is to remove flicker, because the user sees the
finished product appear all at once when you call the end_paint()
method. If you draw to window directly without calling the
begin_paint_rect() method, the user may see flicker
as individual drawing operations are performed in sequence. The clipping and
background initializing features of the
begin_paint_rect() are conveniences for the
programmer, so you can avoid doing that work yourself.

gtk.gdk.Window.begin_paint_region

def begin_paint_region(region)

region :

the region you intend to draw to

Note

This method is available in PyGTK 2.10 and above.

The begin_paint_region() method
indicates that you are beginning the process of redrawing the gtk.gdk.Region
specified by region. A backing store
(off-screen buffer) large enough to contain
region will be created. The backing store will
be initialized with the background color or background pixmap for the
window. Then, all drawing operations performed on the window will be
diverted to the backing store. When you call the end_paint()
method, the backing store will be copied to the window, making it
visible on-screen. Only the part of the window contained in
region will be modified; that is, drawing
operations are clipped to region.

The net result of all this is to remove flicker, because the
user sees the finished product appear all at once when you call the
end_paint()
method. If you draw to the window directly without calling the begin_paint_region()
method, the user may see flicker as individual drawing operations are
performed in sequence. The clipping and background initializing
features of the begin_paint_region()
method are conveniences for the programmer, so you can avoid doing
that work yourself.

The widget system automatically places calls to the begin_paint_region()
and end_paint()
methods around emissions of the "expose_event" signal. That is, if
you're writing an expose event handler, you can assume that the
exposed area in a gtk.gdk.EXPOSE type gtk.gdk.Event
has already been cleared to the window background, is already set as
the clip region, and already has a backing store. Therefore in most
cases, application code need not call the begin_paint_region()
method. (You can disable the automatic calls around expose events on a
widget-by-widget basis by calling gtk.Widget.set_double_buffered().)

If you call this method multiple times before calling the
matching the end_paint()
method, the backing stores are pushed onto a stack. The end_paint()
method copies the topmost backing store on-screen, subtracts the
topmost region from all other regions in the stack, and pops the
stack. All drawing operations affect only the topmost backing store in
the stack. One matching call to the end_paint()
method is required for each call to the begin_paint_region()
method.

gtk.gdk.Window.end_paint

def end_paint()

The end_paint() method indicates that
the backing store created by the most recent call to the begin_paint_rect()
method should be copied on-screen and deleted, leaving the next-most-recent
backing store or no backing store at all as the active paint region. It is
an error to call this function without a matching call to the begin_paint_rect()
method first.

gtk.gdk.Window.set_title

def set_title(title)

title :

the new title of the
window

The set_title() method sets the title
of a toplevel window, to the string specified by
title. If you haven't explicitly set the icon name
for the window (using the set_icon_name()
method), the icon name will be set to title as well.
title must be in UTF-8 encoding (as with all
user-readable strings in PyGTK).

gtk.gdk.Window.set_role

def set_role(role)

role :

a string indicating its
role

The set_role() method sets the string
specified by role as the window's role. When using
PyGTK, you should generally use the gtk.Window.set_role()
method instead of this low-level function. The window manager and session
manager use a window's role to distinguish it from other kinds of window in
the same application. When an application is restarted after being saved in
a previous session, all windows with the same title and role are treated as
interchangeable. So if you have two windows with the same title that should
be distinguished for session management purposes, you should set the role on
those windows. It doesn't matter what string you use for the role, as long
as you have a different role for each non-interchangeable kind of
window.

gtk.gdk.Window.set_transient_for

The set_transient_for() method
indicates to the window manager that the window is a transient dialog
associated with the application window leader. This
allows the window manager to do things like center the window on
leader and keep the window above
leader. See the gtk.Window.set_transient_for()
method if you're using a gtk.Window or gtk.Dialog.

gtk.gdk.Window.set_back_pixmap

The set_back_pixmap() method sets the
background pixmap of the window to the value specified by
pixmap A background pixmap will be tiled, positioning
the first tile at the origin of the window, or if
parent_relative is True, the
tiling will be done based on the origin of the parent window (useful to
align tiles in a parent with tiles in a child). If
pixmap is None the window will
have no background which means it will never have its background filled by
the windowing system. Instead the window will contain whatever pixels were
already in the corresponding area of the display. The windowing system will
normally fill a window with its background when the window is obscured then
exposed, and when you call the clear()
method.

gtk.gdk.Window.set_cursor

The set_cursor() method sets the mouse
pointer for a gtk.gdk.Window. Use
either the gtk.gdk.Cursor() or
gtk.gdk.Cursor() constructors
to create the cursor. To make the cursor invisible, use the gtk.gdk.Cursor() constructor to
create a cursor with no pixels in it. Passing None for
the cursor argument to the
set_cursor() method means that the window will use
the cursor of its parent window. Most windows should use this
default.

gtk.gdk.Window.get_geometry

def get_geometry()

Returns :

a 5-tuple containing the X and Y coordinate of
the location of the window relative to its parent and the width and height
of the window and the bit depth of the window.

The get_geometry() method returns a
5-tuple containing the window's location and size (x, y, width, height) and
the bit depth of the window. The X and Y coordinates returned are relative
to the parent window of the window, which for toplevels usually means
relative to the window decorations (titlebar, etc.) rather than relative to
the root window (screen-size background window).

On the X11 platform, the geometry is obtained from the X server, so reflects
the latest position of the window; this may be out-of-sync with the position
of the window delivered in the most-recently-processed
GdkEventConfigure. the get_position()
method in contrast gets the position from the most recent configure
event.

gtk.gdk.Window.get_position

def get_position()

Returns :

a 2-tuple containing the X and Y coordinates of
the window location.

The get_position() returns a 2-tuple
containing the position of the window as reported in the
most-recently-processed GdkEventConfigure. By comparison
with the get_geometry()
method that queries the X server for the current window position, regardless
of what events have been received or processed. The position coordinates are
relative to the window's parent window.

gtk.gdk.Window.get_origin

def get_origin()

Returns :

a 2-tuple containing the X and Y coordinates of
the window

The get_origin() method returns a
2-tuple containing the x and y coordinates of the position of a window in
root window coordinates. (Compare this method with the get_position()
and get_geometry()
methods that return the position of a window relative to its parent
window.)

gtk.gdk.Window.get_root_origin

def get_root_origin()

Returns :

a 2-tuple containing the X and Y coordinates of
the window frame position

The get_root_origin() method returns a
2-tuple containing the top-left corner of the window manager frame in root
window coordinates.

gtk.gdk.Window.get_frame_extents

The get_frame_extents() method returns
a gtk.gdk.Rectangle
specifying the bounding box of the window, including window manager
titlebar/borders if any. The frame position is given in root window
coordinates. To get the position of the window itself (rather than the
frame) in root window coordinates, use the get_origin()
method.

gtk.gdk.Window.get_pointer

def get_pointer()

Returns :

a 3-tuple containing the X and Y coordinates of
the mouse pointer and the modifier mask

The get_pointer() method returns a
3-tuple containing the coordinates of the mouse pointer location relative to
the window and the modifier state. The modifier state is a combination of
the GDK Modifier Constants.

gtk.gdk.Window.get_toplevel

The get_toplevel() method returns the
toplevel gtk.gdk.Window
that's an ancestor of the window.

gtk.gdk.Window.get_children

def get_children()

Returns :

the list of child windows inside the
window

The get_children() method returns the
list of children gtk.gdk.Window
objects of the window. This method only returns children created via
PyGTK, so for example it's useless when used with the
root window; it only returns windows an application created itself.

gtk.gdk.Window.get_events

def get_events()

Returns :

the event mask for the
window

The get_events() method returns the
event mask for the window. See the set_events()
method for more detail.

gtk.gdk.Window.set_events

def set_events(event_mask)

event_mask :

the event mask for the
window

The set_events() method sets the event
mask to the value specified by event_mask for the window. The event mask
determines which events will be reported for the window. For example, an
event mask including gtk.gdk.BUTTON_PRESS_MASK means the
window should report button press events. The event mask is the bitwise OR
of the GDK Event Mask Flag Constants.

gtk.gdk.Window.set_icon_list

def set_icon_list(pixbufs)

pixbufs :

a list (or tuple) containing pixbufs, of
different sizes.

Note

This method is available in PyGTK 2.2 and above.

The set_icon_list() method sets the
list of icons for the window. pixbufs is a list or tuple containing gtk.gdk.Pixbuf
objects to be used as the icon images. One of these will be used to
represent the window when it has been iconified. The icon is usually shown
in an icon box or some sort of task bar. Which icon size is shown depends on
the window manager. The window manager can scale the icon but setting
several size icons can give better image quality since the window manager
may only need to scale the icon by a small amount or not at all.

gtk.gdk.Window.set_icon_name

def set_icon_name(name)

name :

the name of the window while iconified
(minimized)

The set_icon_name() method sets the
name of the window when it is iconified to the value of
name. Windows may have a name used while minimized,
distinct from the name they display in their titlebar. Most of the time this
is a bad idea from a user interface standpoint. But you can set such a name
with this method, if you like.

gtk.gdk.Window.set_group

The set_group() method sets the group
leader for the window to the gtk.gdk.Window
specified by leader. By default, the group leader
for all toplevel windows is set to a global window implicitly created by
PyGTK. With this method you can override this default.
The group leader window allows the window manager to distinguish all windows
that belong to a single application. It may for example allow users to
minimize or unminimize all windows belonging to an application at once. You
should only set a non-default group window if your application pretends to
be multiple applications. The group leader window may not be changed after a
window has been mapped (with the show()
method for example).

gtk.gdk.Window.get_group

Note

The get_group() method returns the
group leader gtk.gdk.Window for
the window. See the set_group()
method for more information.

gtk.gdk.Window.set_decorations

def set_decorations(decorations)

decorations :

the decoration hint mask

The set_decorations() method sets the
specified decorations for the window. "Decorations" are the features the
window manager adds to a toplevel gtk.gdk.Window. This
method sets the traditional Motif window manager hints that tell the window
manager which decorations you would like your window to have. Usually you
should use the gtk.Window.set_decorated()
method on a gtk.Window instead
of using this method directly. The value of
decorations is the logical OR of the GDK WM Decoration Constants.

gtk.gdk.Window.get_decorations

def get_decorations()

Returns :

the window decorations

The get_decorations() method returns
the decorations set on the window with the set_decorations
method.

gtk.gdk.Window.set_functions

def set_functions(functions)

functions :

the bitmask of operations to allow on the
window

The set_functions() method sets the
traditional Motif window manager hint for which operations the window
manager should allow on a toplevel window. However, few window managers do
anything reliable or interesting with this hint. Many ignore it
entirely. The functions argument is the logical OR of
the GDK WM Function Constants.

gtk.gdk.Window.iconify

def iconify()

The iconify() method asks the window
manager to iconify (minimize) the window. The window manager may choose to
ignore the request, but normally will honor it. Using the gtk.Window.iconify()
method is preferred, if you have a gtk.Window
widget.

gtk.gdk.Window.deiconify

def deiconify()

The deiconify() method asks the window
manager to deiconify (unminimize) the window. On X11 the window manager may
choose to ignore the request to deiconify. Using the gtk.Window.deiconify()
method is preferred. Or better yet, use the gtk.Window.present(),
which raises the window, focuses it, unminimizes it, and puts it on the
current desktop.

gtk.gdk.Window.stick

def stick()

The stick() method "pins" a window such
that it's on all workspaces and does not scroll with viewports, for window
managers that have scrollable viewports. (When using a gtk.Window, the
gtk.Window.stick()
method may be more useful.) On the X11 platform, this method depends on
window manager support, so may have no effect with many window managers.
However, PyGTK will do the best it can to convince the
window manager to stick the window. For window managers that don't support
this operation, there's nothing you can do to force it to happen.

gtk.gdk.Window.unstick

gtk.gdk.Window.maximize

def maximize()

The maximize() method asks the window
manager to maximize the window, if the window manager supports this
operation. Not all window managers support this, and some deliberately
ignore it or don't have a concept of "maximized"; so you can't rely on the
maximization actually happening. But it will happen with most standard
window managers. If the window was already maximized, then this method does
nothing.

gtk.gdk.Window.unmaximize

def unmaximize()

The unmaximize() method asks the window
manager to unmaximize the window, if the window manager supports this
operation. Not all window managers support this, and some deliberately
ignore it or don't have a concept of "maximized"; so you can't rely on the
unmaximization actually happening. But it will happen with most standard
window managers. If the window wasn't maximized, then this method does
nothing.

gtk.gdk.Window.fullscreen

def fullscreen()

Note

This method is available in PyGTK 2.2 and above.

The fullscreen() method moves the window
into fullscreen mode. This means the window covers the entire screen and is
above any panels or task bars.

If the window was already fullscreen, then this method does
nothing.

On X11, asks the window manager to put the window in a
fullscreen state, if the window manager supports this operation. Not all
window managers support this, and some deliberately ignore it or don't have
a concept of "fullscreen" but most standard window managers do.

gtk.gdk.Window.unfullscreen

def unfullscreen()

Note

This method is available in PyGTK 2.2 and above.

The unfullscreen() method moves the
window out of fullscreen mode. If the window was not fullscreen, does
nothing.

On X11, asks the window manager to move the window out of the
fullscreen state, if the window manager supports this operation. Not all
window managers support this, and some deliberately ignore it or don't have
a concept of "fullscreen" but most standard window managers do.

gtk.gdk.Window.register_dnd

def register_dnd()

The register_dnd() method registers the
window as a potential drop destination.

The begin_resize_drag() method begins a
window resize operation (for a toplevel gtk.gdk.Window) from
the specified edge using the specified
button starting at the location specified by
root_x and root_y. The value
of edge must be one of the GDK Window Edge Constants.

You might use this
method to implement a "window resize grip," for example; in fact the gtk.Statusbar
uses it. The method works best with window managers that support the
Extended Window Manager Hints spec (see http://www.freedesktop.org),
but has a fallback implementation for other window managers.

gtk.gdk.Window.begin_move_drag

def begin_move_drag(button, root_x, root_y, timestamp)

button :

the button being used to
drag

root_x :

the root window X coordinate of the mouse click
that began the drag

root_y :

the root window Y coordinate of the mouse click
that began the drag

timestamp :

the timestamp of the mouse click that began the
drag

The begin_move_drag() method begins a
window move operation (for a toplevel window) using the specified
button starting at the location specified by
root_x and root_y. You might
use this method to implement a "window move grip," for example. The method
works best with window managers that support the Extended Window Manager
Hints spec (see http://www.freedesktop.org),
but has a fallback implementation for other window managers.

gtk.gdk.Window.invalidate_region

Note

This method is available in PyGTK 2.10 and above.

The invalidate_region() method adds the
gtk.gdk.Region
specified by region to the update area for the
window. The update area is the region that needs to be redrawn, or the
"dirty region." The call to the process_updates()
method sends one or more expose events to the window, which together
cover the entire update area. An application would normally redraw the
contents of the window in response to those expose events.

PyGTK will call the gtk.gdk.window_process_all_updates()
method on your behalf whenever your program returns to the main loop
and becomes idle, so normally there's no need to do that manually, you
just need to invalidate regions that you know should be
redrawn.

The invalidate_children parameter
controls whether the region of each child window that intersects
region will also be invalidated. If
False, then the update area for child windows will
remain unaffected.

gtk.gdk.Window.get_update_area

Note

This method is available in PyGTK 2.10 and above.

The get_update_area() method returns a
gtk.gdk.Region
containing the update area and transfers ownership of the update area from
the window to the caller of the method. That is, after calling this
method, the window will no longer have an invalid/dirty region; the update
area is removed from the window and passed in the returned gtk.gdk.Region. If
a window has no update area, the get_update_area()
method returns None.

gtk.gdk.Window.freeze_updates

def freeze_updates()

The freeze_updates() method temporarily
freezes the window such that it won't receive expose events. The window will
begin receiving expose events again when the thaw_updates()
method is called. If the freeze_updates() method
has been called more than once, the thaw_updates()
method must be called an equal number of times to begin processing
exposes.

gtk.gdk.Window.thaw_updates

def thaw_updates()

The thaw_updates() method thaws a
window frozen with the freeze_updates()
method.

gtk.gdk.Window.process_updates

def process_updates(update_children)

update_children :

if True process updates for
child windows

The process_updates() method sends one
or more expose events to the window. The areas in each expose event will
cover the entire update area for the window (see the invalidate_rect()
method for details). Normally PyGTK calls the gtk.gdk.window_process_all_updates()
function on your behalf, so there's no need to call this method unless you
want to force expose events to be delivered immediately and synchronously
(vs. the usual case, where PyGTK delivers them in an idle
handler). Occasionally this is useful to produce nicer scrolling behavior,
for example.

gtk.gdk.Window.set_accept_focus

def set_accept_focus(accept_focus)

accept_focus :

if True, the window should
receive input focus

Note

This method is available in PyGTK 2.4 and above.

The set_accept_focus() method sets the
"accept_focus setting to the value of
accept_focus. If accept_focus
is True the window will accept focus; if
False hints to the desktop environment that the window
doesn't want to receive input focus.

On X, it is the responsibility of the window manager to
interpret this hint. ICCCM-compliant window manager usually respect
it.

gtk.gdk.Window.enable_synchronized_configure

def enable_synchronized_configure()

Note

This method is available in PyGTK 2.6 and above.

The enable_synchronized_configure()
method indicates that the application will cooperate with the window system
in synchronizing the window repaint with the window manager during resizing
operations. After an application calls this method, it must call the configure_finished()
method every time it has finished all processing associated with a set of
Configure events. Toplevel GTK+ windows automatically use this
protocol.

gtk.gdk.Window.configure_finished

def configure_finished()

Note

This method is available in PyGTK 2.6 and above.

The configure_finished() method signals
to the window system that the application has finished handling all the
Configure events it has received. Window Managers can use this to better
synchronize the frame repaint with the application. GTK+ applications will
automatically call this function when appropriate.

gtk.gdk.Window.set_focus_on_map

def set_focus_on_map(focus_on_map)

focus_on_map :

if True the window should
receive input focus when mapped.

Note

This method is available in PyGTK 2.6 and above.

The set_focus_on_map() method sets the
a hint for the desktop environment to the value specified by
focus_on_map. If focus_on_map
is True the window sets a hint for the desktop
environment indicating that it would like to receive input focus when
mapped.

On X, it is the responsibility of the window manager to
interpret this hint. Window managers following the freedesktop.org window manager
extension specification should respect it.

gtk.gdk.Window.set_urgency_hint

def set_urgency_hint(urgent)

urgent :

if True the window requires
urgent user attention.

Note

This method is available in PyGTK 2.10 and above.

The set_urgency_hint() method sets the
a hint for the desktop environment to the value specified by
urgent. If urgent is
True the window sets a hint for the desktop environment
indicating that it needs urgent user attention.

gtk.gdk.Window.move_region

Note

This method is available in PyGTK 2.10 and above.

The move_region() method moves the part
of window indicated by the gtk.gdk.Region
specified by region by
dy pixels in the Y direction and
dx pixels in the X direction. The portions of
region that are not covered by the new position
of region are invalidated.

gtk.gdk.Window.shape_combine_region

def shape_combine_region(shape_region, offset_x, offset_y)

shape_region :

the region of the window to leave
opaque

offset_x :

X position of shape_region
in window coordinates

offset_y :

Y position of shape_region
in window coordinates

Note

This method is available in PyGTK 2.10 and above.

The shape_combine_region() method makes
pixels in the window outside of the gtk.gdk.Region
specified by shape_region transparent, so
that the window may be nonrectangular. See the shape_combine_mask()
method to use a bitmap as the mask.

If shape_region is
None, the shape will be unset, so the whole window
will be opaque again. offset_x and
offset_y are ignored if
shape_region is None.

This method works on both toplevel and child windows.

On the X11 platform, this uses an X server extension which is
widely available on most common platforms, but not available on very
old X servers, and occasionally the implementation will be buggy. On
servers without the shape extension, this method will do
nothing.

gtk.gdk.Window.input_shape_combine_mask

def input_shape_combine_mask(mask, x, y)

mask :

the shape bitmap mask

x :

the X position of shape mask with respect to
the window

y :

the Y position of shape mask with respect to
the window

Note

This method is available in PyGTK 2.10 and above.

The input_shape_combine_mask() method
is similar to the shape_combine_mask()
method but the shape applies only to event handling. Mouse events
which happen while the pointer position corresponds to an unset bit in
the mask will be passed onto the window below this window.

An input shape is typically used with RGBA windows. The alpha
channel of the window defines which pixels are invisible and allows
for nicely antialiased borders, and the input shape controls where the
window is "clickable".

On the X11 platform, this requires version 1.1 of the shape
extension.

gtk.gdk.Window.input_shape_combine_region

def input_shape_combine_region(shape_region, offset_x, offset_y)

shape_region :

the region of the window to leave
opaque

offset_x :

X position of shape_region
in window coordinates

offset_y :

Y position of shape_region
in window coordinates

Note

This method is available in PyGTK 2.10 and above.

The input_shape_combine_region() method
is similar to the shape_combine_region()
method, but the shape applies only to event handling. Mouse events
which happen while the pointer position corresponds to an unset bit in
shape_region will be passed onto the window
below this window.

An input shape is typically used with RGBA windows. The alpha
channel of the window defines which pixels are invisible and allows
for nicely antialiased borders, and the input shape controls where the
window is "clickable".

On the X11 platform, this requires version 1.1 of the shape
extension.

gtk.gdk.Window.beep

def beep()

Note

This method is available in PyGTK 2.12 and above.

Emits a short beep associated to window in the appropriate display,
if supported. Otherwise, emits a short beep on the display just as
gtk.gdk.Display.beep().

gtk.gdk.Window.set_composited

def set_composited(composited)

composited :

True to set the window as composited

Note

This method is available in PyGTK 2.12 and above.

Sets a GdkWindow as composited, or unsets it. Composited windows do
not automatically have their contents drawn to the screen. Drawing is
redirected to an offscreen buffer and an expose event is emitted on
the parent of the composited window. It is the responsibility of the
parent's expose handler to manually merge the off-screen content onto
the screen in whatever way it sees fit.

It only makes sense for child windows to be composited; see
gtk.gdk.Window.set_opacity()
if you need translucent toplevel windows.

An additional effect of this call is that the area of this window is no longer
clipped from regions marked for invalidation on its parent. Draws done on the
parent window are also no longer clipped by the child.

This call is only supported on some systems (currently, only X11 with
new enough Xcomposite and Xdamage extensions). You must call
gtk.gdk.Display.supports_composite()
to check if setting a window as composited is supported before attempting to do so.

gtk.gdk.Window.set_opacity

def set_opacity(opacity)

opacity :

The opacity value.

Note

This method is available in PyGTK 2.12 and above.

Request the windowing system to make window partially transparent, with
opacity 0 being fully transparent and 1 fully opaque.
Values of the opacity parameter are clamped to the [0,1] range.)

On X11, this works only on X screens with a compositing manager running.

gtk.gdk.Window.remove_redirection

Note

Functions

gtk.gdk.window_foreign_new

def gtk.gdk.window_foreign_new(anid)

anid :

a native window system ID

Returns :

the new gtk.gdk.Window
wrapper for the native window or None if the window has
been destroyed.

The gtk.gdk.window_foreign_new() function
wraps a native window specified by anid for the default display in a gtk.gdk.Window. This
may fail if the window has been destroyed. For example in the X Window
System backend, a native window handle is an Xlib
XID.

gtk.gdk.window_foreign_new_for_display

the new gtk.gdk.Window
wrapper for the native window or None if the window has
been destroyed.

Note

This function is available in PyGTK 2.2 and above.

The
gtk.gdk.window_foreign_new_for_display() function wraps
a native window specified by anid for the gtk.gdk.Display
specified by display in a gtk.gdk.Window. This
may fail if the window has been destroyed. For example in the X Window
System backend, a native window handle is an Xlib
XID.

gtk.gdk.window_get_toplevels

The gtk.gdk.window_get_toplevels() function
returns a list of all toplevel windows known to PyGTK on
the default screen. A toplevel window is a child of the root window (see the
gtk.gdk.get_default_root_window()
function).

gtk.gdk.window_lookup

def gtk.gdk.window_lookup(anid)

anid :

a native window system ID

Returns :

the gtk.gdk.Window
wrapper for the native window or None if there is
none.

The gtk.gdk.window_lookup() function looks
up the gtk.gdk.Window that
wraps the native window handle specified by anid. For
example in the X Window System backend, a native window handle is an Xlib
XID.

gtk.gdk.window_lookup_for_display

the gtk.gdk.Window
wrapper for the native window or None if there is
none.

Note

This function is available in PyGTK 2.2 and above.

The gtk.gdk.window_lookup_for_display()
function looks up the gtk.gdk.Window that
wraps the native window handle specified by anid for
the gtk.gdk.Display
specified by display. For example in the X Window
System backend, a native window handle is an Xlib
XID.

gtk.gdk.window_process_all_updates

gtk.gdk.gdk_window_set_debug_updates

def gtk.gdk.gdk_window_set_debug_updates(setting)

setting :

if True enable update
debugging

The gtk.gdk.gdk_set_debug_updates() function
sets the update debugging flag to the value of
setting. If setting is
True, update debugging is enabled. With update debugging
enabled, calls to the invalidate_rect()
method clear the invalidated rectangle of the screen to a noticeable color,
and PyGTK pauses for a short time before sending exposes
to windows during the process_updates()
method. The net effect is that you can see the invalid region for each
window and watch redraws as they occur. This allows you to diagnose
inefficiencies in your application.In essence, because the
GDK rendering model prevents all flicker, if you are
redrawing the same region 400 times you may never notice, aside from
noticing a speed problem. Enabling update debugging causes
PyGTK to flicker slowly and noticeably, so you can see
exactly what's being redrawn when, in what order.

The --gtk-debug=updates command line option
passed to PyGTK programs enables this debug option at
application startup time. That's usually more useful than calling
gtk.gdk.gdk_set_debug_updates() yourself, though you might
want to use this function to enable updates sometime after application
startup time.

gtk.gdk.window_at_pointer

def gtk.gdk.window_at_pointer()

Returns :

a 3 tuple containing the gtk.gdk.Window
and the pointer location in the window or
None.

Note

This function is available in PyGTK 2.4 and above.

The gtk.gdk.window_at_pointer() function
returns a 3-tuple containing the gtk.gdk.Window
underneath the mouse pointer, and the location of the pointer in the
window. This function returns None if the window under
the mouse pointer is not known to GDK (if the window belongs to another
application and a gtk.gdk.Window
hasn't been created for it with the gtk.gdk.window_foreign_new()
function)