| Top | |
|
|
|
| CairoSurface* | create-surface | Run Last |
| void | from-embedder | Run Last |
| void | moved-to-rect | Run First |
| GdkWindow* | pick-embedded-child | Run Last |
| void | to-embedder | Run Last |
| GdkWindow | |
| enum | GdkWindowType |
| enum | GdkWindowWindowClass |
| enum | GdkWindowHints |
| struct | GdkGeometry |
| enum | GdkGravity |
| enum | GdkAnchorHints |
| enum | GdkWindowEdge |
| enum | GdkWindowTypeHint |
| struct | GdkWindowAttr |
| enum | GdkWindowAttributesType |
| enum | GdkFullscreenMode |
| enum | GdkFilterReturn |
| typedef | GdkXEvent |
| #define | GDK_PARENT_RELATIVE |
| enum | GdkModifierType |
| enum | GdkModifierIntent |
| enum | GdkWMDecoration |
| enum | GdkWMFunction |
A GdkWindow is a (usually) rectangular region on the screen. It’s a low-level object, used to implement high-level objects such as GtkWidget and GtkWindow on the GTK+ level. A GtkWindow is a toplevel window, the thing a user might think of as a “window” with a titlebar and so on; a GtkWindow may contain many GdkWindows. For example, each GtkButton has a GdkWindow associated with it.
Normally, the windowing system takes care of rendering the contents
of a child window onto its parent window. This mechanism can be
intercepted by calling gdk_window_set_composited() on the child
window. For a “composited” window it is the
responsibility of the application to render the window contents at
the right spot.
Offscreen windows are more general than composited windows, since they allow not only to modify the rendering of the child window onto its parent, but also to apply coordinate transformations.
To integrate an offscreen window into a window hierarchy, one has
to call gdk_offscreen_window_set_embedder() and handle a number of
signals. The “pick-embedded-child” signal on the embedder
window is used to select an offscreen child at given coordinates,
and the “to-embedder” and “from-embedder” signals
on the offscreen window are used to translate coordinates between
the embedder and the offscreen window.
For rendering an offscreen window onto its embedder, the contents
of the offscreen window are available as a surface, via
gdk_offscreen_window_get_surface().
GdkWindow * gdk_window_new (GdkWindow *parent,GdkWindowAttr *attributes,gint attributes_mask);
Creates a new GdkWindow using the attributes from
attributes
. See GdkWindowAttr and GdkWindowAttributesType for
more details. Note: to use this on displays other than the default
display, parent
must be specified.
[constructor]
parent |
a GdkWindow, or |
[allow-none] |
attributes |
attributes of the new window |
|
attributes_mask |
mask indicating which
fields in |
[type GdkWindowAttributesType] |
void
gdk_window_destroy (GdkWindow *window);
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.
GdkWindowType
gdk_window_get_window_type (GdkWindow *window);
Gets the type of the window. See GdkWindowType.
GdkDisplay *
gdk_window_get_display (GdkWindow *window);
Gets the GdkDisplay associated with a GdkWindow.
Since: 2.24
GdkScreen *
gdk_window_get_screen (GdkWindow *window);
Gets the GdkScreen associated with a GdkWindow.
Since: 2.24
GdkVisual *
gdk_window_get_visual (GdkWindow *window);
Gets the GdkVisual describing the pixel format of window
.
Since: 2.24
GdkWindow * gdk_window_at_pointer (gint *win_x,gint *win_y);
gdk_window_at_pointer has been deprecated since version 3.0 and should not be used in newly-written code.
Use gdk_device_get_window_at_position() instead.
Obtains the window underneath the mouse pointer, returning the
location of that window in win_x
, win_y
. Returns NULL if the
window under the mouse pointer is not known to GDK (if the window
belongs to another application and a GdkWindow 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.
void
gdk_window_show (GdkWindow *window);
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 GtkWidget, you should call this function on the widget's GdkWindow as part of the “map” method.
void
gdk_window_show_unraised (GdkWindow *window);
Shows a GdkWindow 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
XMapWindow() (it also updates some internal GDK state, which means
that you can’t really use XMapWindow() directly on a GDK window).
void
gdk_window_hide (GdkWindow *window);
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().
gboolean
gdk_window_is_destroyed (GdkWindow *window);
Check to see if a window is destroyed..
Since: 2.18
gboolean
gdk_window_is_visible (GdkWindow *window);
Checks whether the window has been mapped (with gdk_window_show() or
gdk_window_show_unraised()).
gboolean
gdk_window_is_viewable (GdkWindow *window);
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.)
gboolean
gdk_window_is_input_only (GdkWindow *window);
Determines whether or not the window is an input only window.
Since: 2.22
gboolean
gdk_window_is_shaped (GdkWindow *window);
Determines whether or not the window is shaped.
Since: 2.22
GdkWindowState
gdk_window_get_state (GdkWindow *window);
Gets the bitwise OR of the currently active window state flags, from the GdkWindowState enumeration.
void
gdk_window_withdraw (GdkWindow *window);
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.
void
gdk_window_iconify (GdkWindow *window);
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 GtkWindow widget.
This function only makes sense when window
is a toplevel window.
void
gdk_window_deiconify (GdkWindow *window);
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 GdkWindow variant. Or better yet,
you probably want to use gtk_window_present_with_time(), which raises the window, focuses it,
unminimizes it, and puts it on the current desktop.
void
gdk_window_stick (GdkWindow *window);
“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 GtkWindow, 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.
void
gdk_window_unstick (GdkWindow *window);
Reverse operation for gdk_window_stick(); see gdk_window_stick(),
and gtk_window_unstick().
void
gdk_window_maximize (GdkWindow *window);
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.
void
gdk_window_unmaximize (GdkWindow *window);
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.
void
gdk_window_fullscreen (GdkWindow *window);
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.
Since: 2.2
void gdk_window_fullscreen_on_monitor (GdkWindow *window,gint monitor);
Moves the window into fullscreen mode on the given monitor. 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.
Since: UNRELEASED
void
gdk_window_unfullscreen (GdkWindow *window);
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.
Since: 2.2
GdkFullscreenMode
gdk_window_get_fullscreen_mode (GdkWindow *window);
Obtains the GdkFullscreenMode of the window
.
Since: 3.8
void gdk_window_set_fullscreen_mode (GdkWindow *window,GdkFullscreenMode mode);
Specifies whether the window
should span over all monitors (in a multi-head
setup) or only the current monitor when in fullscreen mode.
The mode
argument is from the GdkFullscreenMode enumeration.
If GDK_FULLSCREEN_ON_ALL_MONITORS is specified, the fullscreen window
will
span over all monitors from the GdkScreen.
On X11, searches through the list of monitors from the GdkScreen the ones
which delimit the 4 edges of the entire GdkScreen and will ask the window
manager to span the window
over these monitors.
If the XINERAMA extension is not available or not usable, this function has no effect.
Not all window managers support this, so you can’t rely on the fullscreen window to span over the multiple monitors when GDK_FULLSCREEN_ON_ALL_MONITORS is specified.
Since: 3.8
void gdk_window_set_keep_above (GdkWindow *window,gboolean setting);
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.
Since: 2.4
void gdk_window_set_keep_below (GdkWindow *window,gboolean setting);
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.
Since: 2.4
void gdk_window_set_opacity (GdkWindow *window,gdouble opacity);
Set window
to render as partially transparent,
with opacity 0 being fully transparent and 1 fully opaque. (Values
of the opacity parameter are clamped to the [0,1] range.)
For toplevel windows this depends on support from the windowing system
that may not always be there. For instance, On X11, this works only on
X screens with a compositing manager running. On Wayland, there is no
per-window opacity value that the compositor would apply. Instead, use
gdk_window_set_opaque_region (window, NULL) to tell the compositor
that the entire window is (potentially) non-opaque, and draw your content
with alpha, or use gtk_widget_set_opacity() to set an overall opacity
for your widgets.
For child windows this function only works for non-native windows.
For setting up per-pixel alpha topelevels, see gdk_screen_get_rgba_visual(),
and for non-toplevels, see gdk_window_set_composited().
Support for non-toplevel windows was added in 3.8.
Since: 2.12
void gdk_window_set_composited (GdkWindow *window,gboolean composited);
gdk_window_set_composited has been deprecated since version 3.16 and should not be used in newly-written code.
Compositing is an outdated technology that only ever worked on X11.
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
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 gdk_display_supports_composite() to check if
setting a window as composited is supported before
attempting to do so.
Since: 2.12
gboolean
gdk_window_get_composited (GdkWindow *window);
gdk_window_get_composited has been deprecated since version 3.16 and should not be used in newly-written code.
Compositing is an outdated technology that only ever worked on X11.
Determines whether window
is composited.
See gdk_window_set_composited().
Since: 2.22
void gdk_window_set_pass_through (GdkWindow *window,gboolean pass_through);
Sets whether input to the window is passed through to the window below.
The default value of this is FALSE, which means that pointer
events that happen inside the window are send first to the window,
but if the event is not selected by the event mask then the event
is sent to the parent window, and so on up the hierarchy.
If pass_through
is TRUE then such pointer events happen as if the
window wasn't there at all, and thus will be sent first to any
windows below window
. This is useful if the window is used in a
transparent fashion. In the terminology of the web this would be called
"pointer-events: none".
Note that a window with pass_through
TRUE can still have a subwindow
without pass through, so you can get events on a subset of a window. And in
that cases you would get the in-between related events such as the pointer
enter/leave events on its way to the destination window.
Since: 3.18
gboolean
gdk_window_get_pass_through (GdkWindow *window);
Returns whether input to the window is passed through to the window below.
See gdk_window_set_pass_through() for details
Since: 3.18
void gdk_window_move (GdkWindow *window,gint x,gint y);
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 GtkWindow 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.
void gdk_window_resize (GdkWindow *window,gint width,gint height);
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.
void gdk_window_move_resize (GdkWindow *window,gint x,gint y,gint width,gint height);
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().)
void gdk_window_scroll (GdkWindow *window,gint dx,gint dy);
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.
void gdk_window_move_to_rect (GdkWindow *window,const GdkRectangle *rect,GdkGravity rect_anchor,GdkGravity window_anchor,GdkAnchorHints anchor_hints,gint rect_anchor_dx,gint rect_anchor_dy);
Moves window
to rect
, aligning their anchor points.
rect
is relative to the top-left corner of the window that window
is
transient for. rect_anchor
and window_anchor
determine anchor points on
rect
and window
to pin together. rect
's anchor point can optionally be
offset by rect_anchor_dx
and rect_anchor_dy
, which is equivalent to
offsetting the position of window
.
anchor_hints
determines how window
will be moved if the anchor points cause
it to move off-screen. For example, GDK_ANCHOR_FLIP_X will replace
GDK_GRAVITY_NORTH_WEST with GDK_GRAVITY_NORTH_EAST and vice versa if
window
extends beyond the left or right edges of the monitor.
Connect to the “moved-to-rect” signal to find out how it was actually positioned.
window |
the GdkWindow to move |
|
rect |
the destination GdkRectangle to align |
[not nullable] |
rect_anchor |
the point on |
|
window_anchor |
the point on |
|
anchor_hints |
positioning hints to use when limited on space |
|
rect_anchor_dx |
horizontal offset to shift |
|
rect_anchor_dy |
vertical offset to shift |
Since: 3.24
void gdk_window_move_region (GdkWindow *window,const cairo_region_t *region,gint dx,gint dy);
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 |
||
region |
The cairo_region_t to move |
|
dx |
Amount to move in the X direction |
|
dy |
Amount to move in the Y direction |
Since: 2.8
void
gdk_window_flush (GdkWindow *window);
gdk_window_flush has been deprecated since version 3.14 and should not be used in newly-written code.
This function does nothing.
Since: 2.18
gboolean
gdk_window_has_native (GdkWindow *window);
Checks whether the window has a native window or not. Note that
you can use gdk_window_ensure_native() if a native window is needed.
Since: 2.22
gboolean
gdk_window_ensure_native (GdkWindow *window);
Tries to ensure that there is a window-system native window for this
GdkWindow. This may fail in some situations, returning FALSE.
Offscreen window and children of them can never have native windows.
Some backends may not support native child windows.
Since: 2.18
void gdk_window_reparent (GdkWindow *window,GdkWindow *new_parent,gint x,gint y);
Reparents window
into the given new_parent
. The window being
reparented will be unmapped as a side effect.
void
gdk_window_raise (GdkWindow *window);
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.
void
gdk_window_lower (GdkWindow *window);
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().)