GNOME Documentation Library

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.

gtk.gdk.Window.drag_begin

    def drag_begin(targets)

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)

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)

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)

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)

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)

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

gtk.gdk.Window.set_keep_above

    def set_keep_above(setting)

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)

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

    def get_window_type()

The get_window_type() method returns the type of the window which is one of the GDK Window Type Constants.

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)

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)

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)

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

    def reparent(new_parent, x, y)

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)

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)

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.

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)

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

    def set_user_data(user_data)

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.

gtk.gdk.Window.get_user_data

    def get_user_data()

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)

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)

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.

function should return one of the following values which is on of the GDK Filter Return Constants.

gtk.gdk.Window.scroll

    def scroll(dx, dy)

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)

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()

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

gtk.gdk.Window.is_viewable

    def 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

    def get_state()

The get_state() method returns the bitwise OR of the currently active GDK Window State Flag Constants.

gtk.gdk.Window.set_static_gravities

    def set_static_gravities(use_static)

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.set_type_hint

    def set_type_hint(hint)

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)

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)

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)

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.

gtk.gdk.Window.set_geometry_hints

    def set_geometry_hints(min_width=-1, min_height=-1, max_width=-1, max_height=-1, base_width=-1, base_height=-1, width_inc=-1, height_inc=-1, min_aspect=-1.0, max_aspect=-1.0)

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)

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)

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</