Next: , Previous: Cursors, Up: Top


17 Windows

Onscreen display areas in the target window system

17.1 Overview

A <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> on the GTK+ level. A <gtk-window> is a toplevel window, the thing a user might think of as a "window" with a titlebar and so on; a <gtk-window> may contain many <gdk-window>. For example, each <gtk-button> has a <gdk-window> associated with it.

17.2 Usage

— Function: gdk-window-destroy (self <gdk-window>)
— Method: destroy

Destroys the window system resources associated with window and decrements window's reference count. The window system resources for all children of window are also destroyed, but the children's reference counts are not decremented.

Note that a window will not be destroyed automatically when its reference count reaches zero. You must call this function yourself before that happens.

window
a <gdk-window>
— Function: gdk-window-get-window-type (self <gdk-window>) ⇒  (ret <gdk-window-type>)
— Method: get-window-type

Gets the type of the window. See <gdk-window-type>.

window
a <gdk-window>
ret
type of window
— Function: gdk-window-at-pointer ⇒  (ret <gdk-window>) (win_x int) (win_y int)

Obtains the window underneath the mouse pointer, returning the location of that window in win-x, win-y. Returns ‘#f’ if the window under the mouse pointer is not known to GDK (if the window belongs to another application and a <gdk-window> hasn't been created for it with gdk-window-foreign-new)

NOTE: For multihead-aware widgets or applications use gdk-display-get-window-at-pointer instead.

win-x
return location for origin of the window under the pointer
win-y
return location for origin of the window under the pointer
ret
window under the mouse pointer
— Function: gdk-window-show (self <gdk-window>)
— Method: show

Like gdk-window-show-unraised, but also raises the window to the top of the window stack (moves the window to the front of the Z-order).

This function maps a window so it's visible onscreen. Its opposite is gdk-window-hide.

When implementing a <gtk-widget>, you should call this function on the widget's <gdk-window> as part of the "map" method.

window
a <gdk-window>
— Function: gdk-window-show-unraised (self <gdk-window>)
— Method: show-unraised

Shows a <gdk-window> onscreen, but does not modify its stacking order. In contrast, gdk-window-show will raise the window to the top of the window stack.

On the X11 platform, in Xlib terms, this function calls x-map-window (it also updates some internal GDK state, which means that you can't really use x-map-window directly on a GDK window).

window
a <gdk-window>
— Function: gdk-window-hide (self <gdk-window>)
— Method: hide

For toplevel windows, withdraws them, so they will no longer be known to the window manager; for all windows, unmaps them, so they won't be displayed. Normally done automatically as part of gtk-widget-hide.

window
a <gdk-window>
— Function: gdk-window-is-visible (self <gdk-window>) ⇒  (ret bool)
— Method: is-visible

Checks whether the window has been mapped (with gdk-window-show or gdk-window-show-unraised).

window
a <gdk-window>
ret
#t’ if the window is mapped
— Function: gdk-window-is-viewable (self <gdk-window>) ⇒  (ret bool)
— Method: is-viewable

Check if the window and all ancestors of the window are mapped. (This is not necessarily "viewable" in the X sense, since we only check as far as we have GDK window parents, not to the root window.)

window
a <gdk-window>
ret
#t’ if the window is viewable
— Function: gdk-window-get-state (self <gdk-window>) ⇒  (ret <gdk-window-state>)
— Method: get-state

Gets the bitwise OR of the currently active window state flags, from the <gdk-window-state> enumeration.

window
a <gdk-window>
ret
window state bitfield
— Function: gdk-window-withdraw (self <gdk-window>)
— Method: withdraw

Withdraws a window (unmaps it and asks the window manager to forget about it). This function is not really useful as gdk-window-hide automatically withdraws toplevel windows before hiding them.

window
a toplevel <gdk-window>
— Function: gdk-window-iconify (self <gdk-window>)
— Method: iconify

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

This function only makes sense when window is a toplevel window.

window
a toplevel <gdk-window>
— Function: gdk-window-deiconify (self <gdk-window>)
— Method: deiconify

Attempt to deiconify (unminimize) window. On X11 the window manager may choose to ignore the request to deiconify. When using GTK+, use gtk-window-deiconify instead of the <gdk-window> variant. Or better yet, you probably want to use gtk-window-present, which raises the window, focuses it, unminimizes it, and puts it on the current desktop.

window
a toplevel <gdk-window>
— Function: gdk-window-stick (self <gdk-window>)
— Method: stick

"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 <gtk-window>, gtk-window-stick may be more useful.)

On the X11 platform, this function depends on window manager support, so may have no effect with many window managers. However, GDK 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.

window
a toplevel <gdk-window>
— Function: gdk-window-unstick (self <gdk-window>)
— Method: unstick

Reverse operation for gdk-window-stick; see gdk-window-stick, and gtk-window-unstick.

window
a toplevel <gdk-window>
— Function: gdk-window-maximize (self <gdk-window>)
— Method: maximize

Maximizes the window. If the window was already maximized, then this function does nothing.

On X11, asks the window manager to maximize 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, and GDK makes a best effort to get it to happen.

On Windows, reliably maximizes the window.

window
a toplevel <gdk-window>
— Function: gdk-window-unmaximize (self <gdk-window>)
— Method: unmaximize

Unmaximizes the window. If the window wasn't maximized, then this function does nothing.

On X11, asks the window manager to unmaximize 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, and GDK makes a best effort to get it to happen.

On Windows, reliably unmaximizes the window.

window
a toplevel <gdk-window>
— Function: gdk-window-fullscreen (self <gdk-window>)
— Method: fullscreen

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 function does nothing.

On X11, asks the window manager to put 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"; so you can't rely on the fullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

window
a toplevel <gdk-window>

Since 2.2

— Function: gdk-window-unfullscreen (self <gdk-window>)
— Method: unfullscreen

Moves the window out of fullscreen mode. If the window was not fullscreen, does nothing.

On X11, asks the window manager to move 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"; so you can't rely on the unfullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

window
a toplevel <gdk-window>

Since 2.2

— Function: gdk-window-set-keep-above (self <gdk-window>) (setting bool)
— Method: set-keep-above

Set if window must be kept above other windows. If the window was already above, then this function does nothing.

On X11, asks the window manager to keep 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"; so you can't rely on the window being kept above. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

window
a toplevel <gdk-window>
setting
whether to keep window above other windows

Since 2.4

— Function: gdk-window-set-keep-below (self <gdk-window>) (setting bool)
— Method: set-keep-below

Set if window must be kept below other windows. If the window was already below, then this function does nothing.

On X11, asks the window manager to keep 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"; so you can't rely on the window being kept below. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

window
a toplevel <gdk-window>
setting
whether to keep window below other windows

Since 2.4

— Function: gdk-window-move (self <gdk-window>) (int) (int)
— Method: move

Repositions a window relative to its parent window. For toplevel windows, window managers may ignore or modify the move; you should probably use gtk-window-move on a <gtk-window> widget anyway, instead of using GDK functions. For child windows, the move will reliably succeed.

If you're also planning to resize the window, use gdk-window-move-resize to both move and resize simultaneously, for a nicer visual effect.

window
a <gdk-window>
x
X coordinate relative to window's parent
y
Y coordinate relative to window's parent
— Function: gdk-window-resize (self <gdk-window>) (width int) (height int)
— Method: resize

Resizes window; for toplevel windows, asks the window manager to resize the window. The window manager may not allow the resize. When using GTK+, use gtk-window-resize instead of this low-level GDK function.

Windows may not be resized below 1x1.

If you're also planning to move the window, use gdk-window-move-resize to both move and resize simultaneously, for a nicer visual effect.

window
a <gdk-window>
width
new width of the window
height
new height of the window
— Function: gdk-window-move-resize (self <gdk-window>) (int) (int) (width int) (height int)
— Method: move-resize

Equivalent to calling gdk-window-move and gdk-window-resize, 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 gdk-window-move-resize.)

window
a <gdk-window>
x
new X position relative to window's parent
y
new Y position relative to window's parent
width
new width
height
new height
— Function: gdk-window-scroll (self <gdk-window>) (dx int) (dy int)
— Method: scroll

Scroll the contents of window, both pixels and children, by the given amount. window itself does not move. Portions of the window that the scroll operation brings in from offscreen 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.)

window
a <gdk-window>
dx
Amount to scroll in the X direction
dy
Amount to scroll in the Y direction
— Function: gdk-window-move-region (self <gdk-window>) (region <gdk-region>) (dx int) (dy int)
— Method: move-region

Move the part of window indicated by region by dy pixels in the Y direction and dx pixels in the X direction. The portions of region that not covered by the new position of region are invalidated.

Child windows are not moved.

window
a <gdk-window>
region
The <gdk-region> to move
dx
Amount to move in the X direction
dy
Amount to move in the Y direction

Since 2.8

— Function: gdk-window-reparent (self <gdk-window>) (new_parent <gdk-window>) (int) (int)
— Method: reparent

Reparents window into the given new-parent. The window being reparented will be unmapped as a side effect.

window
a <gdk-window>
new-parent
new parent to move window into
x
X location inside the new parent
y
Y location inside the new parent
— Function: gdk-window-clear (self <gdk-window>)
— Method: clear

Clears an entire window to the background color or background pixmap.

window
a <gdk-window>
— Function: gdk-window-clear-area (self <gdk-window>) (int) (int) (width int) (height int)
— Method: clear-area

Clears an area of window to the background color or background pixmap.

window
a <gdk-window>
x
x coordinate of rectangle to clear
y
y coordinate of rectangle to clear
width
width of rectangle to clear
height
height of rectangle to clear
— Function: gdk-window-clear-area-e (self <gdk-window>) (int) (int) (width int) (height int)
— Method: clear-area-e

Like gdk-window-clear-area, but also generates an expose event for the cleared area.

This function has a stupid name because it dates back to the mists time, pre-GDK-1.0.

window
a <gdk-window>
x
x coordinate of rectangle to clear
y
y coordinate of rectangle to clear
width
width of rectangle to clear
height
height of rectangle to clear
— Function: gdk-window-raise (self <gdk-window>)
— Method: raise

Raises window to the top of the Z-order (stacking order), so that other windows with the same parent window appear below window. This is true whether or not the windows are visible.

If window is a toplevel, the window manager may choose to deny the request to move the window in the Z-order, gdk-window-raise only requests the restack, does not guarantee it.

window
a <gdk-window>
— Function: gdk-window-lower (self <gdk-window>)
— Method: lower

Lowers window to the bottom of the Z-order (stacking order), so that other windows with the same parent window appear above window. This is true whether or not the other windows are visible.

If window is a toplevel, the window manager may choose to deny the request to move the window in the Z-order, gdk-window-lower only requests the restack, does not guarantee it.

Note that gdk-window-show raises the window again, so don't call this function before gdk-window-show. (Try gdk-window-show-unraised.)

window
a <gdk-window>
— Function: gdk-window-focus (self <gdk-window>) (timestamp unsigned-int32)
— Method: focus

Sets keyboard focus to window. In most cases, gtk-window-present should be used on a <gtk-window>, rather than calling this function.

window
a <gdk-window>
timestamp
timestamp of the event triggering the window focus
— Function: gdk-window-register-dnd (self <gdk-window>)
— Method: register-dnd

Registers a window as a potential drop destination.

window
a <gdk-window>.
— Function: gdk-window-begin-resize-drag (self <gdk-window>) (edge <gdk-window-edge>) (button int) (root_x int) (root_y int) (timestamp unsigned-int32)
— Method: begin-resize-drag

Begins a window resize operation (for a toplevel window). You might use this function to implement a "window resize grip," for example; in fact <gtk-statusbar> uses it. The function works best with window managers that support the Extended Window Manager Hints, but has a fallback implementation for other window managers.

window
a toplevel <gdk-window>
edge
the edge or corner from which the drag is started
button
the button being used to drag
root-x
root window X coordinate of mouse click that began the drag
root-y
root window Y coordinate of mouse click that began the drag
timestamp
timestamp of mouse click that began the drag (use gdk-event-get-time)
— Function: gdk-window-begin-move-drag (self <gdk-window>) (button int) (root_x int) (root_y int) (timestamp unsigned-int32)
— Method: begin-move-drag

Begins a window move operation (for a toplevel window). You might use this function to implement a "window move grip," for example. The function works best with window managers that support the Extended Window Manager Hints, but has a fallback implementation for other window managers.

window
a toplevel <gdk-window>
button
the button being used to drag
root-x
root window X coordinate of mouse click that began the drag
root-y
root window Y coordinate of mouse click that began the drag
timestamp
timestamp of mouse click that began the drag
— Function: gdk-window-begin-paint-rect (self <gdk-window>) (rectangle <gdk-rectangle>)
— Method: begin-paint-rect

A convenience wrapper around gdk-window-begin-paint-region which creates a rectangular region for you. See gdk-window-begin-paint-region for details.

window
a <gdk-window>
rectangle
rectangle you intend to draw to
— Function: gdk-window-begin-paint-region (self <gdk-window>) (region <gdk-region>)
— Method: begin-paint-region

Indicates that you are beginning the process of redrawing region. A backing store (offscreen buffer) large enough to contain region will be created. The backing store will be initialized with the background color or background pixmap for window. Then, all drawing operations performed on window will be diverted to the backing store. When you call gdk-window-end-paint, the backing store will be copied to window, making it visible onscreen. Only the part of 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 gdk-window-end-paint. If you draw to window directly without calling gdk-window-begin-paint-region, the user may see flicker as individual drawing operations are performed in sequence. The clipping and background-initializing features of gdk-window-begin-paint-region are conveniences for the programmer, so you can avoid doing that work yourself.

When using GTK+, the widget system automatically places calls to gdk-window-begin-paint-region and gdk-window-end-paint 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 <gdk-event-expose> 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 gdk-window-begin-paint-region. (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 function multiple times before calling the matching gdk-window-end-paint, the backing stores are pushed onto a stack. gdk-window-end-paint copies the topmost backing store onscreen, 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 gdk-window-end-paint is required for each call to gdk-window-begin-paint-region.

window
a <gdk-window>
region
region you intend to draw to
— Function: gdk-window-end-paint (self <gdk-window>)
— Method: end-paint

Indicates that the backing store created by the most recent call to gdk-window-begin-paint-region should be copied onscreen and deleted, leaving the next-most-recent backing store or no backing store at all as the active paint region. See gdk-window-begin-paint-region for full details. It is an error to call this function without a matching gdk-window-begin-paint-region first.

window
a <gdk-window>
— Function: gdk-window-invalidate-rect (self <gdk-window>) (rect <gdk-rectangle>) (invalidate_children bool)
— Method: invalidate-rect

A convenience wrapper around gdk-window-invalidate-region which invalidates a rectangular region. See gdk-window-invalidate-region for details.

window
a <gdk-window>
rect
rectangle to invalidate
invalidate-children
whether to also invalidate child windows
— Function: gdk-window-invalidate-region (self <gdk-window>) (region <gdk-region>) (invalidate_children bool)
— Method: invalidate-region

Adds region to the update area for window. The update area is the region that needs to be redrawn, or "dirty region." The call gdk-window-process-updates sends one or more expose events to the window, which together cover the entire update area. An application would normally redraw the contents of window in response to those expose events.

GDK will call gdk-window-process-all-updates 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 ‘#f’, then the update area for child windows will remain unaffected. See gdk_window_invalidate_maybe_recurse if you need fine grained control over which children are invalidated.

window
a <gdk-window>
region
a <gdk-region>
invalidate-children
#t’ to also invalidate child windows
— Function: gdk-window-get-update-area (self <gdk-window>) ⇒  (ret <gdk-region>)
— Method: get-update-area

Transfers ownership of the update area from window to the caller of the function. That is, after calling this function, window will no longer have an invalid/dirty region; the update area is removed from window and handed to you. If a window has no update area, gdk-window-get-update-area returns ‘#f’. You are responsible for calling gdk-region-destroy on the returned region if it's non-‘#f’.

window
a <gdk-window>
ret
the update area for window
— Function: gdk-window-freeze-updates (self <gdk-window>)
— Method: freeze-updates

Temporarily freezes a window such that it won't receive expose events. The window will begin receiving expose events again when gdk-window-thaw-updates is called. If gdk-window-freeze-updates has been called more than once, gdk-window-thaw-updates must be called an equal number of times to begin processing exposes.

window
a <gdk-window>
— Function: gdk-window-thaw-updates (self <gdk-window>)
— Method: thaw-updates

Thaws a window frozen with gdk-window-freeze-updates.

window
a <gdk-window>
— Function: gdk-window-process-all-updates

Calls gdk-window-process-updates for all windows (see <gdk-window>) in the application.

— Function: gdk-window-process-updates (self <gdk-window>) (update_children bool)
— Method: process-updates

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

window
a <gdk-window>
update-children
whether to also process updates for child windows
— Function: gdk-window-set-debug-updates (setting bool)

With update debugging enabled, calls to gdk-window-invalidate-region clear the invalidated region of the screen to a noticeable color, and GDK pauses for a short time before sending exposes to windows during gdk-window-process-updates. 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 GTK 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 GTK+ programs enables this debug option at application startup time. That's usually more useful than calling gdk-window-set-debug-updates yourself, though you might want to use this function to enable updates sometime after application startup time.

setting
#t’ to turn on update debugging
— Function: gdk-window-configure-finished (self <gdk-window>)
— Method: configure-finished

Signal to the window system that the application has finished handling 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 gdk-window-enable-synchronized-configure was called previously.

window
a toplevel <gdk-window>

Since 2.6

— Function: gdk-window-set-override-redirect (self <gdk-window>) (override_redirect bool)
— Method: set-override-redirect

An override redirect 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.

window
a toplevel <gdk-window>
override-redirect
#t’ if window should be override redirect
— Function: gdk-window-set-accept-focus (self <gdk-window>) (accept_focus bool)
— Method: set-accept-focus

Setting accept-focus to ‘#f’ hints 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.

window
a toplevel <gdk-window>
accept-focus
#t’ if the window should receive input focus

Since 2.4

— Function: gdk-window-set-focus-on-map (self <gdk-window>) (focus_on_map bool)
— Method: set-focus-on-map

Setting focus-on-map to ‘#f’ hints the desktop environment that the window doesn't want to receive input focus when it is mapped. focus_on_map should be turned off for windows that aren't triggered interactively (such as popups from network activity).

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.

window
a toplevel <gdk-window>
focus-on-map
#t’ if the window should receive input focus when mapped

Since 2.6

— Function: gdk-window-shape-combine-mask (self <gdk-window>) (mask <gdk-drawable>) (int) (int)
— Method: shape-combine-mask

Applies a shape mask to window. Pixels in window corresponding to set bits in the mask will be visible; pixels in window corresponding to unset bits in the mask will be transparent. This gives a non-rectangular window.

If mask is ‘#f’, 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.

On the Win32 platform the functionality is always present.

This function works on both toplevel and child windows.

window
a <gdk-window>
mask
shape mask
x
X position of shape mask with respect to window
y
Y position of shape mask with respect to window
— Function: gdk-window-shape-combine-region (self <gdk-window>) (shape_region <gdk-region>) (offset_x int) (offset_y int)
— Method: shape-combine-region

Makes pixels in window outside shape-region be transparent, so that the window may be nonrectangular. See also gdk-window-shape-combine-mask to use a bitmap as the mask.

If shape-region is ‘#f’, the shape will be unset, so the whole window will be opaque again. offset-x and offset-y are ignored if shape-region is ‘#f’.

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.

On the Win32 platform, this functionality is always present.

This function works on both toplevel and child windows.

window
a <gdk-window>
shape-region
region of window to be non-transparent
offset-x
X position of shape-region in window coordinates
offset-y
Y position of shape-region in window coordinates
— Function: gdk-window-set-child-shapes (self <gdk-window>)
— Method: set-child-shapes

Sets the shape mask of window to the union of shape masks for all children of window, ignoring the shape mask of window itself. Contrast with gdk-window-merge-child-shapes which includes the shape mask of window in the masks to be merged.

window
a <gdk-window>
— Function: gdk-window-merge-child-shapes (self <gdk-window>)
— Method: merge-child-shapes

Merges the shape masks for any child windows into the shape mask for window. i.e. the union of all masks for window and its children will become the new mask for window. See gdk-window-shape-combine-mask.

This function is distinct from gdk-window-set-child-shapes because it includes window's shape mask in the set of shapes to be merged.

window
a <gdk-window>
— Function: gdk-window-input-shape-combine-mask (self <gdk-window>) (mask <gdk-drawable>) (int) (int)
— Method: input-shape-combine-mask

Like gdk-window-shape-combine-mask, 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 on the window below 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.

On the Win32 platform, this functionality is not present and the function does nothing.

window
a <gdk-window>
mask
shape mask
x
X position of shape mask with respect to window
y
Y position of shape mask with respect to window

Since 2.10

— Function: gdk-window-set-child-input-shapes (self <gdk-window>)
— Method: set-child-input-shapes

Sets the input shape mask of window to the union of input shape masks for all children of window, ignoring the input shape mask of window itself. Contrast with gdk-window-merge-child-input-shapes which includes the input shape mask of window in the masks to be merged.

window
a <gdk-window>

Since 2.10

— Function: gdk-window-merge-child-input-shapes (self <gdk-window>)
— Method: merge-child-input-shapes

Merges the input shape masks for any child windows into the input shape mask for window. i.e. the union of all input masks for window and its children will become the new input mask for window. See gdk-window-input-shape-combine-mask.

This function is distinct from gdk-window-set-child-input-shapes because it includes window's input shape mask in the set of shapes to be merged.

window
a <gdk-window>

Since 2.10

— Function: gdk-window-set-static-gravities (self <gdk-window>) (use_static bool) ⇒  (ret bool)
— Method: set-static-gravities

Set the bit gravity of the given window to static, and flag it so all children get static subwindow gravity. This is used if you are implementing scary features that involve deep knowledge of the windowing system. Don't worry about it unless you have to.

window
a <gdk-window>
use-static
#t’ to turn on static gravity
ret
#t’ if the server supports static gravity
— Function: gdk-window-set-hints (self <gdk-window>) (int) (int) (min_width int) (min_height int) (max_width int) (max_height int) (flags int)
— Method: set-hints

gdk_window_set_hints’ is deprecated and should not be used in newly-written code.

This function is broken and useless and you should ignore it. If using GTK+, use functions such as gtk-window-resize, gtk-window-set-size-request, gtk-window-move, gtk-window-parse-geometry, and gtk-window-set-geometry-hints, depending on what you're trying to do.

If using GDK directly, use gdk-window-set-geometry-hints.

window
a <gdk-window>
x
ignored field, does not matter
y
ignored field, does not matter
min-width
minimum width hint
min-height
minimum height hint
max-width
max width hint
max-height
max height hint
flags
logical OR of GDK_HINT_POS, GDK_HINT_MIN_SIZE, and/or GDK_HINT_MAX_SIZE
— Function: gdk-window-set-title (self <gdk-window>) (title mchars)
— Method: set-title

Sets the title of a toplevel window, to be displayed in the titlebar. If you haven't explicitly set the icon name for the window (using gdk-window-set-icon-name), the icon name will be set to title as well. title must be in UTF-8 encoding (as with all user-readable strings in GDK/GTK+). title may not be ‘#f’.

window
a toplevel <gdk-window>
title
title of window
— Function: gdk-window-set-background (self <gdk-window>) (color <gdk-color>)
— Method: set-background

Sets the background color of window. (However, when using GTK+, set the background of a widget with gtk-widget-modify-bg - if you're an application - or gtk-style-set-background - if you're implementing a custom widget.)

The color must be allocated; gdk-rgb-find-color is the best way to allocate a color.

See also gdk-window-set-back-pixmap.

window
a <gdk-window>
color
an allocated <gdk-color>
— Function: gdk-window-set-back-pixmap (self <gdk-window>) (pixmap <gdk-pixmap>) (parent_relative bool)
— Method: set-back-pixmap

Sets the background pixmap of window. May also be used to set a background of "None" on window, by setting a background pixmap of ‘#f’. A background pixmap will be tiled, positioning the first tile at the origin of window, or if parent-relative is ‘#t’, 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).

A background pixmap of ‘#f’ means that the window will have no background. A window with no background 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 gdk-window-clear.

window
a <gdk-window>
pixmap
a <gdk-pixmap>, or ‘#f
parent-relative
whether the tiling origin is at the origin of window's parent
— Function: gdk-window-set-cursor (self <gdk-window>) (cursor <gdk-cursor>)
— Method: set-cursor

Sets the mouse pointer for a <gdk-window>. Use gdk-cursor-new or gdk-cursor-new-from-pixmap to create the cursor. To make the cursor invisible, use gdk-cursor-new-from-pixmap to create a cursor with no pixels in it. Passing ‘#f’ for the cursor argument to gdk-window-set-cursor means that window will use the cursor of its parent window. Most windows should use this default.

window
a <gdk-window>
cursor
a cursor
— Function: gdk-window-get-geometry (self <gdk-window>) ⇒  (int) (int) (width int) (height int) (depth int)
— Method: get-geometry

Any of the return location arguments to this function may be ‘#f’, if you aren't interested in getting the value of that field.

The X and Y coordinates returned are relative to the parent window of 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 window; this may be out-of-sync with the position of window delivered in the most-recently-processed <gdk-event-configure>. gdk-window-get-position in contrast gets the position from the most recent configure event.

If window is not a toplevel, it is much better to call gdk-window-get-position and gdk-drawable-get-size instead, because it avoids the roundtrip to the X server and because gdk-drawable-get-size supports the full 32-bit coordinate space, whereas gdk-window-get-geometry is restricted to the 16-bit coordinates of X11.

window
a <gdk-window>
x
return location for X coordinate of window (relative to its parent)
y
return location for Y coordinate of window (relative to its parent)
width
return location for width of window
height
return location for height of window
depth
return location for bit depth of window
— Function: gdk-window-set-icon-list (self <gdk-window>) (pixbufs glist-of)
— Method: set-icon-list

Sets a list of icons for the window. 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.

window
The <gdk-window> toplevel window to set the icon of.
pixbufs
A list of pixbufs, of different sizes.
— Function: gdk-window-set-modal-hint (self <gdk-window>) (modal bool)
— Method: set-modal-hint

The application can use this hint to tell the window manager that a certain window has modal behaviour. The window manager can use this information to handle modal windows in a special way.

You should only use this on windows for which you have previously called gdk-window-set-transient-for

window
A toplevel <gdk-window>
modal
#t’ if the window is modal, ‘#f’ otherwise.
— Function: gdk-window-set-type-hint (self <gdk-window>) (hint <gdk-window-type-hint>)
— Method: set-type-hint

The application can use this call to provide a hint to the window manager about the functionality of a window. The window manager can use this information when determining the decoration and behaviour of the window.

The hint must be set before the window is mapped.

window
A toplevel <gdk-window>
hint
A hint of the function this window will have
— Function: gdk-window-get-type-hint (self <gdk-window>) ⇒  (ret <gdk-window-type-hint>)
— Method: get-type-hint

This function returns the type hint set for a window.

window
A toplevel <gdk-window>
ret
The type hint set for window

Since 2.10

— Function: gdk-window-set-skip-taskbar-hint (self <gdk-window>) (skips_taskbar bool)
— Method: set-skip-taskbar-hint

Toggles whether a window should appear in a task list or window list. If a window's semantic type as specified with gdk-window-set-type-hint already fully describes the window, this function should not be called in addition, instead you should allow the window to be treated according to standard policy for its semantic type.

window
a toplevel <gdk-window>
skips-taskbar
#t’ to skip the taskbar

Since 2.2

— Function: gdk-window-set-skip-pager-hint (self <gdk-window>) (skips_pager bool)
— Method: set-skip-pager-hint

Toggles whether a window should appear in a pager (workspace switcher, or other desktop utility program that displays a small thumbnail representation of the windows on the desktop). If a window's semantic type as specified with gdk-window-set-type-hint already fully describes the window, this function should not be called in addition, instead you should allow the window to be treated according to standard policy for its semantic type.

window
a toplevel <gdk-window>
skips-pager
#t’ to skip the pager

Since 2.2

— Function: gdk-window-set-urgency-hint (self <gdk-window>) (urgent bool)
— Method: set-urgency-hint

Toggles whether a window needs the user's urgent attention.

window
a toplevel <gdk-window>
urgent
#t’ if the window is urgent

Since 2.8

— Function: gdk-window-get-position (self <gdk-window>) ⇒  (int) (int)
— Method: get-position

Obtains the position of the window as reported in the most-recently-processed <gdk-event-configure>. Contrast with gdk-window-get-geometry which queries the X server for the current window position, regardless of which events have been received or processed.

The position coordinates are relative to the window's parent window.

window
a <gdk-window>
x
X coordinate of window
y
Y coordinate of window
— Function: gdk-window-get-root-origin (self <gdk-window>) ⇒  (int) (int)
— Method: get-root-origin

Obtains the top-left corner of the window manager frame in root window coordinates.

window
a toplevel <gdk-window>
x
return location for X position of window frame
y
return location for Y position of window frame
— Function: gdk-window-get-origin (self <gdk-window>) ⇒  (ret int) (int) (int)
— Method: get-origin

Obtains the position of a window in root window coordinates. (Compare with gdk-window-get-position and gdk-window-get-geometry which return the position of a window relative to its parent window.)

window
a <gdk-window>
x
return location for X coordinate
y
return location for Y coordinate
ret
not meaningful, ignore
— Function: gdk-window-get-deskrelative-origin (self <gdk-window>) ⇒  (ret bool) (int) (int)
— Method: get-deskrelative-origin

gdk_window_get_deskrelative_origin’ is deprecated and should not be used in newly-written code.

This gets the origin of a <gdk-window> relative to an Enlightenment-window-manager desktop. As long as you don't assume that the user's desktop/workspace covers the entire root window (i.e. you don't assume that the desktop begins at root window coordinate 0,0) this function is not necessary. It's deprecated for that reason.

window
a toplevel <gdk-window>
x
return location for X coordinate
y
return location for Y coordinate
ret
not meaningful
— Function: gdk-window-get-parent (self <gdk-window>) ⇒  (ret <gdk-window>)
— Method: get-parent

Obtains the parent of window, as known to GDK. Does not query the X server; thus this returns the parent as passed to gdk-window-new, not the actual parent. This should never matter unless you're using Xlib calls mixed with GDK calls on the X11 platform. It may also matter for toplevel windows, because the window manager may choose to reparent them.

window
a <gdk-window>
ret
parent of window
— Function: gdk-window-get-toplevel (self <gdk-window>) ⇒  (ret <gdk-window>)
— Method: get-toplevel

Gets the toplevel window that's an ancestor of window.

window
a <gdk-window>
ret
the toplevel window containing window
— Function: gdk-window-get-children (self <gdk-window>) ⇒  (ret glist-of)
— Method: get-children

Gets the list of children of window known to GDK. This function only returns children created via GDK, so for example it's useless when used with the root window; it only returns windows an application created itself.

The returned list must be freed, but the elements in the list need not be.

window
a <gdk-window>
ret
list of child windows inside window
— Function: gdk-window-get-events (self <gdk-window>) ⇒  (ret <gdk-event-mask>)
— Method: get-events

Gets the event mask for window. See gdk-window-set-events.

window
a <gdk-window>
ret
event mask for window
— Function: gdk-window-set-events (self <gdk-window>) (event_mask <gdk-event-mask>)
— Method: set-events

The event mask for a window determines which events will be reported for that window. For example, an event mask including <gdk-button-press-mask> means the window should report button press events. The event mask is the bitwise OR of values from the <gdk-event-mask> enumeration.

window
a <gdk-window>
event-mask
event mask for window
— Function: gdk-window-set-icon (self <gdk-window>) (icon_window <gdk-window>) (pixmap <gdk-pixmap>) (mask <gdk-drawable>)
— Method: set-icon

Sets the icon of window as a pixmap or window. If using GTK+, investigate gtk-window-set-default-icon-list first, and then gtk-window-set-icon-list and gtk-window-set-icon. If those don't meet your needs, look at gdk-window-set-icon-list. Only if all those are too high-level do you want to fall back to gdk-window-set-icon.

window
a toplevel <gdk-window>
icon-window
a <gdk-window> to use for the icon, or ‘#f’ to unset
pixmap
a <gdk-pixmap> to use as the icon, or ‘#f’ to unset
mask
a 1-bit pixmap (<gdk-bitmap>) to use as mask for pixmap, or ‘#f’ to have none
— Function: gdk-window-set-icon-name (self <gdk-window>) (name mchars)
— Method: set-icon-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 function, if you like.

window
a toplevel <gdk-window>
name
name of window while iconified (minimized)
— Function: gdk-window-set-transient-for (self <gdk-window>) (parent <gdk-window>)
— Method: set-transient-for

Indicates to the window manager that window is a transient dialog associated with the application window parent. This allows the window manager to do things like center window on parent and keep window above parent.

See gtk-window-set-transient-for if you're using <gtk-window> or <gtk-dialog>.

window
a toplevel <gdk-window>
parent
another toplevel <gdk-window>
— Function: gdk-window-set-role (self <gdk-window>) (role mchars)
— Method: set-role

When using GTK+, typically you should use gtk-window-set-role 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.

window
a toplevel <gdk-window>
role
a string indicating its role
— Function: gdk-window-set-group (self <gdk-window>) (leader <gdk-window>)
— Method: set-group

Sets the group leader window for window. By default, GDK sets the group leader for all toplevel windows to a global window implicitly created by GDK. With this function 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/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.

window
a toplevel <gdk-window>
leader
group leader window, or ‘#f’ to restore the default group leader window
— Function: gdk-window-get-group (self <gdk-window>) ⇒  (ret <gdk-window>)
— Method: get-group

Returns the group leader window for window. See gdk-window-set-group.

window
a toplevel <gdk-window>
ret
the group leader window for window

Since 2.4

— Function: gdk-window-set-decorations (self <gdk-window>) (decorations <gdk-wm-decoration>)
— Method: set-decorations

"Decorations" are the features the window manager adds to a toplevel <gdk-window>. This function 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 gtk-window-set-decorated on a <gtk-window> instead of using the GDK function directly.

The decorations argument is the logical OR of the fields in the <gdk-wm-decoration> enumeration. If <gdk-decor-all> is included in the mask, the other bits indicate which decorations should be turned off. If <gdk-decor-all> is not included, then the other bits indicate which decorations should be turned on.

Most window managers honor a decorations hint of 0 to disable all decorations, but very few honor all possible combinations of bits.

window
a toplevel <gdk-window>
decorations
decoration hint mask
— Function: gdk-window-set-functions (self <gdk-window>) (functions <gdk-wm-function>)
— Method: set-functions

Sets hints about the window management functions to make available via buttons on the window frame.

On the X backend, this function sets the traditional Motif window manager hint for this purpose. However, few window managers do anything reliable or interesting with this hint. Many ignore it entirely.

The functions argument is the logical OR of values from the <gdk-wm-function> enumeration. If the bitmask includes <gdk-func-all>, then the other bits indicate which functions to disable; if it doesn't include <gdk-func-all>, it indicates which functions to enable.

window
a toplevel <gdk-window>
functions
bitmask of operations to allow on window
— Function: gdk-window-get-toplevels ⇒  (ret glist-of)

Obtains a list of all toplevel windows known to GDK on the default screen (see gdk-screen-get-toplevel-windows). A toplevel window is a child of the root window (see gdk-get-default-root-window).

The returned list should be freed with g-list-free, but its elements need not be freed.

ret
list of toplevel windows, free with g-list-free
— Function: gdk-get-default-root-window ⇒  (ret <gdk-window>)

Obtains the root window (parent all other windows are inside) for the default display and screen.

ret
the default root window