gtk.gdk.Window on-screen display areas in the target window system gtk.gdk.Window gtk.gdk.Drawable gtk.gdk.Window parent width height window_type event_mask wclass title None x -1 y -1 visual None colormap None cursor None wmclass_name None wmclass_class None override_redirect -1 drag_begin targets input_set_extension_events mask mode property_get property type None pdelete False property_change property type format mode data property_delete property selection_convert selection target time set_keep_above setting set_keep_below setting destroy get_window_type show hide withdraw move x y resize width height move_resize x y width height reparent new_parent x y clear clear_area x y width height clear_area_e x y width height raise_ lower focus timestamp 0L set_user_data user_data get_user_data set_override_redirect override_redirect add_filter function dataNone scroll dx dy shape_combine_mask shape_mask offset_x offset_y set_child_shapes merge_child_shapes is_visible is_viewable get_state set_static_gravities use_static get_type_hint set_type_hint hint set_modal_hint modal set_skip_taskbar_hint skips_taskbar set_skip_pager_hint skips_pager 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 begin_paint_rect rectangle begin_paint_region region end_paint set_title title set_role role set_transient_for leader set_background color set_back_pixmap pixmap parent_relative set_cursor cursor get_geometry get_position get_origin get_root_origin get_frame_extents get_pointer get_parent get_toplevel get_children get_events set_events event_mask set_icon_list pixbufs set_icon icon_window pixmap mask set_icon_name name set_group leader get_group set_decorations decorations get_decorations set_functions functions iconify deiconify stick unstick maximize unmaximize fullscreen unfullscreen register_dnd begin_resize_drag edge button root_x root_y timestamp begin_move_drag button root_x root_y timestamp invalidate_rect rect invalidate_children invalidate_region region invalidate_children get_update_area freeze_updates thaw_updates process_updates update_children set_accept_focus accept_focus enable_synchronized_configure configure_finished set_focus_on_map focus_on_map set_urgency_hint urgent move_region region dx dy shape_combine_region shape_region offset_x offset_y input_shape_combine_mask mask x y input_shape_combine_region shape_region offset_x offset_y beep set_composited composited set_opacity opacity set_startup_id startup_id remove_redirection Functions gtk.gdk.window_foreign_new anid gtk.gdk.window_foreign_new_for_display display anid gtk.gdk.get_default_root_window gtk.gdk.window_get_toplevels gtk.gdk.window_lookup anid gtk.gdk.window_lookup_for_display display anid gtk.gdk.window_process_all_updates gtk.gdk.gdk_window_set_debug_updates setting gtk.gdk.window_at_pointer +-- gobject.GObject +-- gtk.gdk.Drawable +-- gtk.gdk.Window gtk.gdk.Window is a rectangular region on the screen. It's a low-level object, used to implement high-level objects such as gtk.Widget and gtk.Window. A gtk.Window is a toplevel window, the object a user might think of as a "window" with a titlebar and so on. A gtk.Window may contain several gtk.gdk.Window objects since most widgets use a gtk.gdk.Window. 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. 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 parent width height window_type event_mask wclass title None x -1 y -1 visual None colormap None cursor None wmclass_name None wmclass_class None override_redirect -1 parent : a gtk.gdk.Window width : the width of the window in pixels height : the height of the window in pixels window_type : the window type event_mask : the bitmask of events received by the window wclass : the class of window - either gtk.gdk.INPUT_OUTPUT or gtk.gdk.INPUT_ONLY title : the window title if a toplevel window x : the x coordinate of the window position relative to parent y : the y coordinate of the window position relative to parent visual : the gtk.gdk.Visual for the window colormap : the gtk.gdk.Colormap for the window cursor : the gtk.gdk.Cursor for the window wmclass_name : don't use this - see the gtk.Window.set_wmclass() method for more information. wmclass_class : don't use this - see the gtk.Window.set_wmclass() method for more information. override_redirect : if True bypass the window manager Returns : the new gtk.gdk.Window 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 . The value of wclass must be one of the . If the optional parameters are not specified the corresponding attribute values will have default values: x 0 y 0 visual the default system visual - see the gtk.gdk.visual_get_system() function colormap either the system gtk.gdk.Colormap if using the system gtk.gdk.Visual (see the gtk.gdk.colormap_get_system() function) or a new gtk.gdk.Colormap using visual cursor use the parent window's cursor override_redirect False drag_begin targets targets : a list of offered targets Returns : a new gtk.gdk.DragContext 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. 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 . 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. 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 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. 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. 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. set_keep_above setting setting : xif True keep the window above other windows 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. set_keep_below setting setting : if True, keep the window below other windows 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. 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. get_window_type Returns : the type of window The get_window_type() method returns the type of the window which is one of the . 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. 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. 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. 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. 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. 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.) reparent new_parent x y new_parent : the new parent gtk.gdk.Window to move the window into x : the X location inside the new parent y : the Y location inside the new parent 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. clear The clear() method clears an entire the window to the background color or background pixmap. 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. 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. 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. This method is called raise() in the C API, but was renamed raise_() since raise is a reserved Python keyword. 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. 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. set_user_data user_data user_data : a gtk.Widget 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. 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. get_user_data Returns : the user data set on the window 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. 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. add_filter function dataNone function : a function data : data to pass to function 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. function should return one of the following values which is on of the . 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.) 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. 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. 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. 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. 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.) get_state Returns : the window state bitfield The get_state() method returns the bitwise OR of the currently active . 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. get_type_hint Returns : The type hint set for window. The get_type_hint() method returns the type hint set for a window. 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 . 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 set_skip_taskbar_hint modal skip_taskbar : if True skip the taskbar. 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. set_skip_pager_hint skips_pager skips_pager : if True skip the pager 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. 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 min_width : minimum width of window or -1 to use requisition min_height : minimum height of window or -1 to use requisition max_width : maximum width of window or -1 to use requisition max_height : maximum height of window or -1 to use requisition base_width : allowed window widths are base_width + width_inc * N (where N is any integer) or -1 base_height : allowed window widths are base_height + height_inc * N (where N is any integer) or -1 width_inc : width resize increment height_inc : height resize increment min_aspect : minimum width/height ratio max_aspect : maximum width/height ratio 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. 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. begin_paint_region region region : the region you intend to draw to 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. 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. 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). 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. set_transient_for leader leader : another gtk.gdk.Window 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. set_background color color : an allocated gtk.gdk.Color The set_background() method sets the background gtk.gdk.Color of the window to the value specified by color. (However, when using PyGTK, set the background of a widget with the gtk.Widget.modify_bg() method from an application - or the gtk.Style.set_background() method from a custom widget implementation.) The color must be allocated Also see the set_back_pixmap() method. set_back_pixmap pixmap parent_relative pixmap : a gtk.gdk.Pixmap, or None parent_relative : if True the tiling origin is at the origin of the window's parent 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. set_cursor cursor cursor : a gtk.gdk.Cursor or None 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. 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. 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. 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.) 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. get_frame_extents Returns : a gtk.gdk.Rectangle specifying the bounding box of the window frame 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. 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 . get_parent Returns : the parent gtk.gdk.Window of the window The get_parent() method returns the parent of the window as set when the gtk.gdk.Window was created or when the reparent() method was called. get_toplevel Returns : the toplevel gtk.gdk.Window containing the window The get_toplevel() method returns the toplevel gtk.gdk.Window that's an ancestor of the window. 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. 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. 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 . set_icon_list pixbufs pixbufs : a list (or tuple) containing pixbufs, of different sizes. 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. set_icon icon_window pixmap mask icon_window : a gtk.gdk.Window to use for the icon pixmap : a gtk.gdk.Pixmap to use as the icon mask : a 1-bit pixmap (GdkBitmap) to use as mask for pixmap The set_icon() method sets the icon of the window as a gtk.gdk.Pixmap (specified by pixmap) or gtk.gdk.Window specified by icon_window). Investigate the gtk.window_set_default_icon_list()() function first, and then the gtk.Window.set_icon_list() and gtk.Window.set_icon() methods. If those don't meet your needs, look at the set_icon_list() method. Only if all those are too high-level do you want to fall back to the set_icon(). 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. set_group leader leader : the group leader gtk.gdk.Window 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). get_group Returns : the group leader gtk.gdk.Window for the window This method is available in PyGTK 2.4 and above. The get_group() method returns the group leader gtk.gdk.Window for the window. See the set_group() method for more information. 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 . get_decorations Returns : the window decorations The get_decorations() method returns the decorations set on the window with the set_decorations method. 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 . 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. 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. 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. unstick The unstick() method reverses the effect of the stick() method. See the stick() and gtk.Window.unstick() methods for more information. 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. 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. fullscreen 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. unfullscreen 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. register_dnd The register_dnd() method registers the window as a potential drop destination. begin_resize_drag edge button root_x root_y timestamp edge : the edge or corner from which the drag is started button : the mouse 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 (use the gtk.gdk.Event.get_time() method) 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 . 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. 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. invalidate_rect rect invalidate_children rect : the rectangle to invalidate invalidate_children : if True invalidate child gtk.gdk.Window objects The invalidate_rect() method invalidates the rectangular region specified by rect. If invalidate_children is True the child gtk.gdk.Window object of the window are also invalidated. invalidate_region region invalidate_children region : a gtk.gdk.Region invalidate_children : If True also invalidate child windows 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. get_update_area Returns : a gtk.gdk.Region conatining the update area for the window 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. 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. thaw_updates The thaw_updates() method thaws a window frozen with the freeze_updates() method. 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. set_accept_focus accept_focus accept_focus : if True, the window should receive input focus 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. enable_synchronized_configure 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. On X, calling this function makes window participate in the _NET_WM_SYNC_REQUEST window manager protocol. configure_finished 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. This function can only be called if the enable_synchronized_configure() method was called previously. set_focus_on_map focus_on_map focus_on_map : if True the window should receive input focus when mapped. 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. set_urgency_hint urgent urgent : if True the window requires urgent user attention. 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. move_region region dx dy region : the gtk.gdk.Region to move dx : the distance to move horizontally dy : the distance to move vertically 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. 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 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. 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 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. 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 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. beep 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(). set_composited composited composited : True to set the window as composited 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. set_opacity opacity opacity : The opacity value. 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. For setting up per-pixel alpha, see gtk.gdk.Screen.get_rgba_colormap(). For making non-toplevel windows translucent, see gtk.gdk.Window.set_composited(). set_startup_id startup_id startup_id : A string with startup-notification identifier. This method is available in PyGTK 2.12 and above. When using GTK+, typically you should use gtk.Window.set_startup_id() instead of this low-level function. remove_redirection This method is available in PyGTK 2.14 and above. When using GTK+, typically you should use gtk.Window.set_startup_id() instead of this low-level function. 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 display anid display : a gtk.gdk.Display 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. 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.get_default_root_window Returns : the default root gtk.gdk.Window The gtk.gdk.get_default_root_window() function returns the root gtk.gdk.Window (the parent window that all other windows are inside) for the default display and screen. gtk.gdk.window_get_toplevels Returns : a list containing the toplevel gtk.gdk.Window object 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 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 display anid display : a gtk.gdk.Display anid : a native window system ID Returns : the gtk.gdk.Window wrapper for the native window or None if there is none. 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 The gtk.gdk.process_all_updates() function calls the process_updates() method for each gtk.gdk.Window in the application. 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 Returns : a 3 tuple containing the gtk.gdk.Window and the pointer location in the window or None. 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) For multi-head-aware widgets or applications use the gtk.gdk.Display.get_window_at_pointer() method instead.