Onscreen display areas in the target window system. The
gdk:window object is a usually rectangular region on the screen.
It is a low-level object, used to implement high-level objects such as
gtk:widget and
gtk:window widgets on the GTK level. A
gtk:window widget is a toplevel window, the thing a user might think of as a "window" with a titlebar and so on. A
gtk:window widget may contain many
gdk:window objects. For example, each
gtk:button widget has a
gdk:window object associated with it.
Composited Windows
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 the
gdk:window-composited function 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
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 the
gdk:offscreen-window-embedder function 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 the
gdk:offscreen-window-surface function.
Signal Details
The "create-surface" signal
lambda (window width height) :run-last
- window
- The gdk:window offscreen window on which the signal is emitted.
- width
- The integer for the width of the offscreen surface to create.
- height
- The integer for the height of the offscreen surface to create.
- Returns
- The newly created cairo:surface-t instance for the offscreen window.
The signal is emitted when an offscreen window needs its surface
(re)created, which happens either when the the window is first drawn to,
or when the window is being resized. The first signal handler that returns a non-
nil surface will stop any further signal emission, and its
surface will be used. Note that it is not possible to access the window's
previous surface from within any callback of this signal. Calling the
gdk:offscreen-window-surface function will lead to a crash.
The "from-embedder" signal
lambda (window xembedder yembedder xoffscreen yoffscreen) :run-last
- window
- The gdk:window offscreen window on which the signal is emitted.
- xembedder
- The double float for the x coordinate in the embedder window.
- yembedder
- The double float for the y coordinate in the embedder window.
- xoffscreen
- The double float return location for the x coordinate in the offscreen window.
- yoffscreen
- The double float return location for the y coordinate in the offscreen window.
The signal is emitted to translate coordinates in the embedder of an
offscreen window to the offscreen window. See also the "to-embedder"
signal.
The "moved-to-rect" signal
lambda (window flipped final xflipped yflipped) :run-first
- window
- The gdk:window object that moved.
- flipped
- The position of window after any possible flipping or nil if the backend cannot obtain it.
- final
- The final position of window or nil if the backend cannot obtain it.
- xflipped
- True if the anchors were flipped horizontally.
- yflipped
- True if the anchors were flipped vertically.
Emitted when the position of window is finalized after being moved to a destination rectangle.
window might be flipped over the destination rectangle in order to keep it on-screen, in which case
xflipped and
yflipped will be set to
true accordingly.
flipped is
the ideal position of window after any possible flipping, but before any possible sliding.
final is
flipped, but possibly translated
in the case that flipping is still ineffective in keeping window
on-screen. Since 3.22
The "pick-embedded-child" signal
lambda (window x y) :run-last
- window
- The gdk:window object on which the signal is emitted.
- x
- The double float for the x coordinate in the window.
- y
- The double float for the y coordinate in the window.
- Returns
- The gdk:window object of the embedded child at x, y, or nil.
The signal is emitted to find an embedded child at the given position.
The "to-embedder" signal
lambda (window xoffscreen yoffscreen xembedder yembedder) :run-last
- window
- The gdk:window object with the offscreen window on which the signal is emitted.
- xoffscreen
- The double float for the x coordinate in the offscreen window.
- yoffscreen
- The double float for the y coordinate in the offscreen window.
- xembedder
- The double float return location for the x coordinate in the embedder window.
- yembedder
- The double float return location for the y coordinate in the embedder window.
The signal is emitted to translate coordinates in an offscreen window to its embedder. See also the
"from-embedder" signal.