Surfaces

Surfaces — Onscreen display areas in the target window system

Functions

GdkSurface * gdk_surface_new_toplevel ()
GdkSurface * gdk_surface_new_temp ()
GdkSurface * gdk_surface_new_popup ()
GdkSurface * gdk_surface_get_parent ()
void gdk_surface_destroy ()
GdkSurfaceType gdk_surface_get_surface_type ()
GdkDisplay * gdk_surface_get_display ()
void gdk_surface_show ()
void gdk_surface_show_unraised ()
void gdk_surface_hide ()
gboolean gdk_surface_is_destroyed ()
gboolean gdk_surface_is_visible ()
gboolean gdk_surface_is_viewable ()
GdkSurfaceState gdk_surface_get_state ()
void gdk_surface_minimize ()
void gdk_surface_unminimize ()
void gdk_surface_stick ()
void gdk_surface_unstick ()
void gdk_surface_maximize ()
void gdk_surface_unmaximize ()
void gdk_surface_fullscreen ()
void gdk_surface_fullscreen_on_monitor ()
void gdk_surface_unfullscreen ()
GdkFullscreenMode gdk_surface_get_fullscreen_mode ()
void gdk_surface_set_fullscreen_mode ()
void gdk_surface_set_keep_above ()
void gdk_surface_set_keep_below ()
void gdk_surface_set_opacity ()
void gdk_surface_resize ()
void gdk_surface_move_to_rect ()
void gdk_surface_raise ()
void gdk_surface_lower ()
void gdk_surface_restack ()
void gdk_surface_focus ()
void gdk_surface_register_dnd ()
void gdk_surface_begin_resize_drag ()
void gdk_surface_begin_resize_drag_for_device ()
void gdk_surface_begin_move_drag ()
void gdk_surface_begin_move_drag_for_device ()
gboolean gdk_surface_show_window_menu ()
void gdk_surface_constrain_size ()
void gdk_surface_beep ()
gint gdk_surface_get_scale_factor ()
void gdk_surface_set_opaque_region ()
GdkGLContext * gdk_surface_create_gl_context ()
GdkVulkanContext * gdk_surface_create_vulkan_context ()
GdkCairoContext * gdk_surface_create_cairo_context ()
void gdk_surface_queue_expose ()
void gdk_surface_freeze_updates ()
void gdk_surface_thaw_updates ()
GdkFrameClock * gdk_surface_get_frame_clock ()
void gdk_surface_set_accept_focus ()
gboolean gdk_surface_get_accept_focus ()
void gdk_surface_set_focus_on_map ()
gboolean gdk_surface_get_focus_on_map ()
void gdk_surface_input_shape_combine_region ()
void gdk_surface_set_title ()
void gdk_surface_set_cursor ()
GdkCursor * gdk_surface_get_cursor ()
void gdk_surface_set_geometry_hints ()
int gdk_surface_get_width ()
int gdk_surface_get_height ()
void gdk_surface_set_icon_list ()
void gdk_surface_set_modal_hint ()
gboolean gdk_surface_get_modal_hint ()
void gdk_surface_set_type_hint ()
GdkSurfaceTypeHint gdk_surface_get_type_hint ()
void gdk_surface_set_shadow_width ()
void gdk_surface_get_position ()
void gdk_surface_get_device_position ()
void gdk_surface_set_icon_name ()
void gdk_surface_set_transient_for ()
void gdk_surface_set_startup_id ()
void gdk_surface_set_decorations ()
gboolean gdk_surface_get_decorations ()
void gdk_surface_set_functions ()
gboolean gdk_surface_get_support_multidevice ()
void gdk_surface_set_support_multidevice ()
GdkCursor * gdk_surface_get_device_cursor ()
void gdk_surface_set_device_cursor ()

Properties

gboolean autohide Read / Write / Construct Only
GdkCursor * cursor Read / Write
GdkDisplay * display Read / Write / Construct Only
GdkFrameClock * frame-clock Read / Write / Construct Only
gboolean mapped Read
GdkSurface * parent Read / Write / Construct Only
GdkSurfaceState state Read
GdkSurfaceType surface-type Read / Write / Construct Only

Signals

gboolean event Run Last
void moved-to-rect Run First
gboolean render Run Last
void size-changed Run First

Types and Values

  GdkSurface
enum GdkSurfaceType
enum GdkSurfaceHints
struct GdkGeometry
enum GdkGravity
enum GdkAnchorHints
enum GdkSurfaceEdge
enum GdkSurfaceTypeHint
enum GdkSurfaceState
enum GdkFullscreenMode
#define GDK_PARENT_RELATIVE
enum GdkModifierType
enum GdkModifierIntent
enum GdkWMDecoration
enum GdkWMFunction

Object Hierarchy

    GObject
    ╰── GdkSurface

Includes

#include <gdk/gdk.h>

Description

A GdkSurface is a (usually) rectangular region on the screen. It’s a low-level object, used to implement high-level objects such as GtkWindow on the GTK level.

Functions

gdk_surface_new_toplevel ()

GdkSurface *
gdk_surface_new_toplevel (GdkDisplay *display,
                          int width,
                          int height);

Creates a new toplevel surface.

[constructor]

Parameters

display

the display to create the surface on

 

width

width of new surface

 

height

height of new surface

 

Returns

the new GdkSurface.

[transfer full]


gdk_surface_new_temp ()

GdkSurface *
gdk_surface_new_temp (GdkDisplay *display,
                      const GdkRectangle *position);

Creates a new temporary surface. The surface will bypass surface management.

[constructor]

Parameters

display

the display to create the surface on

 

position

position of the surface on screen

 

Returns

the new GdkSurface.

[transfer full]


gdk_surface_new_popup ()

GdkSurface *
gdk_surface_new_popup (GdkDisplay *display,
                       GdkSurface *parent,
                       gboolean autohide);

Create a new popup surface.

The surface will be attached to parent and can be positioned relative to it using gdk_surface_move_to_rect().

[constructor]

Parameters

display

the display to create the surface on

 

parent

the parent surface to attach the surface to

 

autohide

whether to hide the surface on outside clicks

 

Returns

a new GdkSurface.

[transfer full]


gdk_surface_get_parent ()

GdkSurface *
gdk_surface_get_parent (GdkSurface *surface);

Returns the parent surface of a surface, or NULL if the surface does not have a parent.

Only popup surfaces have parents.

Parameters

surface

a GtkSurface

 

Returns

the parent of surface , or NULL.

[transfer none][nullable]


gdk_surface_destroy ()

void
gdk_surface_destroy (GdkSurface *surface);

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

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

Parameters

surface

a GdkSurface

 

gdk_surface_get_surface_type ()

GdkSurfaceType
gdk_surface_get_surface_type (GdkSurface *surface);

Gets the type of the surface. See GdkSurfaceType.

Parameters

surface

a GdkSurface

 

Returns

type of surface


gdk_surface_get_display ()

GdkDisplay *
gdk_surface_get_display (GdkSurface *surface);

Gets the GdkDisplay associated with a GdkSurface.

Parameters

surface

a GdkSurface

 

Returns

the GdkDisplay associated with surface .

[transfer none]


gdk_surface_show ()

void
gdk_surface_show (GdkSurface *surface);

Like gdk_surface_show_unraised(), but also raises the surface to the top of the surface stack (moves the surface to the front of the Z-order).

This function maps a surface so it’s visible onscreen. Its opposite is gdk_surface_hide().

When implementing a GtkWidget, you should call this function on the widget's GdkSurface as part of the “map” method.

Parameters

surface

a GdkSurface

 

gdk_surface_show_unraised ()

void
gdk_surface_show_unraised (GdkSurface *surface);

Shows a GdkSurface onscreen, but does not modify its stacking order. In contrast, gdk_surface_show() will raise the surface to the top of the surface 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 surface).

Parameters

surface

a GdkSurface

 

gdk_surface_hide ()

void
gdk_surface_hide (GdkSurface *surface);

For toplevel surfaces, withdraws them, so they will no longer be known to the window manager; for all surfaces, unmaps them, so they won’t be displayed. Normally done automatically as part of gtk_widget_hide().

Parameters

surface

a GdkSurface

 

gdk_surface_is_destroyed ()

gboolean
gdk_surface_is_destroyed (GdkSurface *surface);

Check to see if a surface is destroyed..

Parameters

surface

a GdkSurface

 

Returns

TRUE if the surface is destroyed


gdk_surface_is_visible ()

gboolean
gdk_surface_is_visible (GdkSurface *surface);

Checks whether the surface has been mapped (with gdk_surface_show() or gdk_surface_show_unraised()).

Parameters

surface

a GdkSurface

 

Returns

TRUE if the surface is mapped


gdk_surface_is_viewable ()

gboolean
gdk_surface_is_viewable (GdkSurface *surface);

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

Parameters

surface

a GdkSurface

 

Returns

TRUE if the surface is viewable


gdk_surface_get_state ()

GdkSurfaceState
gdk_surface_get_state (GdkSurface *surface);

Gets the bitwise OR of the currently active surface state flags, from the GdkSurfaceState enumeration.

Parameters

surface

a GdkSurface

 

Returns

surface state bitfield


gdk_surface_minimize ()

void
gdk_surface_minimize (GdkSurface *surface);

Asks to minimize the surface .

The windowing system may choose to ignore the request.

You can track the result of this request by using the “state” property.

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

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_unminimize ()

void
gdk_surface_unminimize (GdkSurface *surface);

Asks to unminimize the surface .

The windowing system may choose to ignore the request.

You can track the result of this request by using the “state” property.

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

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_stick ()

void
gdk_surface_stick (GdkSurface *surface);

“Pins” a surface 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 surface. For window managers that don’t support this operation, there’s nothing you can do to force it to happen.

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_unstick ()

void
gdk_surface_unstick (GdkSurface *surface);

Reverse operation for gdk_surface_stick(); see gdk_surface_stick(), and gtk_window_unstick().

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_maximize ()

void
gdk_surface_maximize (GdkSurface *surface);

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

On X11, asks the window manager to maximize surface , 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 surface.

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_unmaximize ()

void
gdk_surface_unmaximize (GdkSurface *surface);

Unmaximizes the surface. If the surface wasn’t maximized, then this function does nothing.

On X11, asks the window manager to unmaximize surface , 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 surface.

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_fullscreen ()

void
gdk_surface_fullscreen (GdkSurface *surface);

Moves the surface into fullscreen mode. This means the surface covers the entire screen and is above any panels or task bars.

If the surface was already fullscreen, then this function does nothing.

On X11, asks the window manager to put surface 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.

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_fullscreen_on_monitor ()

void
gdk_surface_fullscreen_on_monitor (GdkSurface *surface,
                                   GdkMonitor *monitor);

Moves the surface into fullscreen mode on the given monitor. This means the surface covers the entire screen and is above any panels or task bars.

If the surface was already fullscreen, then this function does nothing.

Parameters

surface

a toplevel GdkSurface

 

monitor

Which monitor to display fullscreen on.

 

gdk_surface_unfullscreen ()

void
gdk_surface_unfullscreen (GdkSurface *surface);

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

On X11, asks the window manager to move surface 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.

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_get_fullscreen_mode ()

GdkFullscreenMode
gdk_surface_get_fullscreen_mode (GdkSurface *surface);

Obtains the GdkFullscreenMode of the surface .

Parameters

surface

a toplevel GdkSurface

 

Returns

The GdkFullscreenMode applied to the surface when fullscreen.


gdk_surface_set_fullscreen_mode ()

void
gdk_surface_set_fullscreen_mode (GdkSurface *surface,
                                 GdkFullscreenMode mode);

Specifies whether the surface 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 surface will span over all monitors of the display.

On X11, searches through the list of monitors display the ones which delimit the 4 edges of the entire display and will ask the window manager to span the surface 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 surface to span over the multiple monitors when GDK_FULLSCREEN_ON_ALL_MONITORS is specified.

Parameters

surface

a toplevel GdkSurface

 

mode

fullscreen mode

 

gdk_surface_set_keep_above ()

void
gdk_surface_set_keep_above (GdkSurface *surface,
                            gboolean setting);

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

On X11, asks the window manager to keep surface 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 surface being kept above. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

Parameters

surface

a toplevel GdkSurface

 

setting

whether to keep surface above other surfaces

 

gdk_surface_set_keep_below ()

void
gdk_surface_set_keep_below (GdkSurface *surface,
                            gboolean setting);

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

On X11, asks the window manager to keep surface 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 surface being kept below. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

Parameters

surface

a toplevel GdkSurface

 

setting

whether to keep surface below other surfaces

 

gdk_surface_set_opacity ()

void
gdk_surface_set_opacity (GdkSurface *surface,
                         gdouble opacity);

Set surface 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 surfaces 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-surface opacity value that the compositor would apply. Instead, use gdk_surface_set_opaque_region (surface, NULL) to tell the compositor that the entire surface is (potentially) non-opaque, and draw your content with alpha, or use gtk_widget_set_opacity() to set an overall opacity for your widgets.

Support for non-toplevel surfaces was added in 3.8.

Parameters

surface

a top-level or non-native GdkSurface

 

opacity

opacity

 

gdk_surface_resize ()

void
gdk_surface_resize (GdkSurface *surface,
                    gint width,
                    gint height);

Resizes surface ; for toplevel surfaces, asks the window manager to resize the surface. The window manager may not allow the resize. When using GTK, use gtk_window_resize() instead of this low-level GDK function.

Surfaces may not be resized below 1x1.

Parameters

surface

a GdkSurface

 

width

new width of the surface

 

height

new height of the surface

 

gdk_surface_move_to_rect ()

void
gdk_surface_move_to_rect (GdkSurface *surface,
                          const GdkRectangle *rect,
                          GdkGravity rect_anchor,
                          GdkGravity surface_anchor,
                          GdkAnchorHints anchor_hints,
                          gint rect_anchor_dx,
                          gint rect_anchor_dy);

Moves surface to rect , aligning their anchor points.

rect is relative to the top-left corner of the surface that surface is transient for. rect_anchor and surface_anchor determine anchor points on rect and surface 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 surface .

anchor_hints determines how surface 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 surface 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.

Parameters

surface

the GdkSurface to move

 

rect

the destination GdkRectangle to align surface with.

[not nullable]

rect_anchor

the point on rect to align with surface 's anchor point

 

surface_anchor

the point on surface to align with rect 's anchor point

 

anchor_hints

positioning hints to use when limited on space

 

rect_anchor_dx

horizontal offset to shift surface , i.e. rect 's anchor point

 

rect_anchor_dy

vertical offset to shift surface , i.e. rect 's anchor point

 

gdk_surface_raise ()

void
gdk_surface_raise (GdkSurface *surface);

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

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

Parameters

surface

a GdkSurface

 

gdk_surface_lower ()

void
gdk_surface_lower (GdkSurface *surface);

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

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

Note that gdk_surface_show() raises the surface again, so don’t call this function before gdk_surface_show(). (Try gdk_surface_show_unraised().)

Parameters

surface

a GdkSurface

 

gdk_surface_restack ()

void
gdk_surface_restack (GdkSurface *surface,
                     GdkSurface *sibling,
                     gboolean above);

Changes the position of surface in the Z-order (stacking order), so that it is above sibling (if above is TRUE) or below sibling (if above is FALSE).

If sibling is NULL, then this either raises (if above is TRUE) or lowers the surface.

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

Parameters

surface

a GdkSurface

 

sibling

a GdkSurface that is a sibling of surface , or NULL.

[allow-none]

above

a boolean

 

gdk_surface_focus ()

void
gdk_surface_focus (GdkSurface *surface,
                   guint32 timestamp);

Sets keyboard focus to surface . In most cases, gtk_window_present_with_time() should be used on a GtkWindow, rather than calling this function.

Parameters

surface

a GdkSurface

 

timestamp

timestamp of the event triggering the surface focus

 

gdk_surface_register_dnd ()

void
gdk_surface_register_dnd (GdkSurface *surface);

Registers a surface as a potential drop destination.

Parameters

surface

a GdkSurface.

 

gdk_surface_begin_resize_drag ()

void
gdk_surface_begin_resize_drag (GdkSurface *surface,
                               GdkSurfaceEdge edge,
                               gint button,
                               gint x,
                               gint y,
                               guint32 timestamp);

Begins a surface resize operation (for a toplevel surface).

This function assumes that the drag is controlled by the client pointer device, use gdk_surface_begin_resize_drag_for_device() to begin a drag with a different device.

Parameters

surface

a toplevel GdkSurface

 

edge

the edge or corner from which the drag is started

 

button

the button being used to drag, or 0 for a keyboard-initiated drag

 

x

surface X coordinate of mouse click that began the drag

 

y

surface Y coordinate of mouse click that began the drag

 

timestamp

timestamp of mouse click that began the drag (use gdk_event_get_time())

 

gdk_surface_begin_resize_drag_for_device ()

void
gdk_surface_begin_resize_drag_for_device
                               (GdkSurface *surface,
                                GdkSurfaceEdge edge,
                                GdkDevice *device,
                                gint button,
                                gint x,
                                gint y,
                                guint32 timestamp);

Begins a surface resize operation (for a toplevel surface). You might use this function to implement a “window resize grip,”

Parameters

surface

a toplevel GdkSurface

 

edge

the edge or corner from which the drag is started

 

device

the device used for the operation

 

button

the button being used to drag, or 0 for a keyboard-initiated drag

 

x

surface X coordinate of mouse click that began the drag

 

y

surface Y coordinate of mouse click that began the drag

 

timestamp

timestamp of mouse click that began the drag (use gdk_event_get_time())

 

gdk_surface_begin_move_drag ()

void
gdk_surface_begin_move_drag (GdkSurface *surface,
                             gint button,
                             gint x,
                             gint y,
                             guint32 timestamp);

Begins a surface move operation (for a toplevel surface).

This function assumes that the drag is controlled by the client pointer device, use gdk_surface_begin_move_drag_for_device() to begin a drag with a different device.

Parameters

surface

a toplevel GdkSurface

 

button

the button being used to drag, or 0 for a keyboard-initiated drag

 

x

surface X coordinate of mouse click that began the drag

 

y

surface Y coordinate of mouse click that began the drag

 

timestamp

timestamp of mouse click that began the drag

 

gdk_surface_begin_move_drag_for_device ()

void
gdk_surface_begin_move_drag_for_device
                               (GdkSurface *surface,
                                GdkDevice *device,
                                gint button,
                                gint x,
                                gint y,
                                guint32 timestamp);

Begins a surface move operation (for a toplevel surface).

Parameters

surface

a toplevel GdkSurface

 

device

the device used for the operation

 

button

the button being used to drag, or 0 for a keyboard-initiated drag

 

x

surface X coordinate of mouse click that began the drag

 

y

surface Y coordinate of mouse click that began the drag

 

timestamp

timestamp of mouse click that began the drag

 

gdk_surface_show_window_menu ()

gboolean
gdk_surface_show_window_menu (GdkSurface *surface,
                              GdkEvent *event);

Asks the windowing system to show the window menu. The window menu is the menu shown when right-clicking the titlebar on traditional windows managed by the window manager. This is useful for windows using client-side decorations, activating it with a right-click on the window decorations.

Parameters

surface

a GdkSurface

 

event

a GdkEvent to show the menu for

 

Returns

TRUE if the window menu was shown and FALSE otherwise.


gdk_surface_constrain_size ()

void
gdk_surface_constrain_size (GdkGeometry *geometry,
                            GdkSurfaceHints flags,
                            gint width,
                            gint height,
                            gint *new_width,
                            gint *new_height);

Constrains a desired width and height according to a set of geometry hints (such as minimum and maximum size).

Parameters

geometry

a GdkGeometry structure

 

flags

a mask indicating what portions of geometry are set

 

width

desired width of surface

 

height

desired height of the surface

 

new_width

location to store resulting width.

[out]

new_height

location to store resulting height.

[out]

gdk_surface_beep ()

void
gdk_surface_beep (GdkSurface *surface);

Emits a short beep associated to surface in the appropriate display, if supported. Otherwise, emits a short beep on the display just as gdk_display_beep().

Parameters

surface

a toplevel GdkSurface

 

gdk_surface_get_scale_factor ()

gint
gdk_surface_get_scale_factor (GdkSurface *surface);

Returns the internal scale factor that maps from surface coordiantes to the actual device pixels. On traditional systems this is 1, but on very high density outputs this can be a higher value (often 2).

A higher value means that drawing is automatically scaled up to a higher resolution, so any code doing drawing will automatically look nicer. However, if you are supplying pixel-based data the scale value can be used to determine whether to use a pixel resource with higher resolution data.

The scale of a surface may change during runtime, if this happens a configure event will be sent to the toplevel surface.

Parameters

surface

surface to get scale factor for

 

Returns

the scale factor


gdk_surface_set_opaque_region ()

void
gdk_surface_set_opaque_region (GdkSurface *surface,
                               cairo_region_t *region);

For optimisation purposes, compositing window managers may like to not draw obscured regions of surfaces, or turn off blending during for these regions. With RGB windows with no transparency, this is just the shape of the window, but with ARGB32 windows, the compositor does not know what regions of the window are transparent or not.

This function only works for toplevel surfaces.

GTK will update this property automatically if the surface background is opaque, as we know where the opaque regions are. If your surface background is not opaque, please update this property in your “css-changed” handler.

Parameters

surface

a top-level or non-native GdkSurface

 

region

a region, or NULL.

[allow-none]

gdk_surface_create_gl_context ()

GdkGLContext *
gdk_surface_create_gl_context (GdkSurface *surface,
                               GError **error);

Creates a new GdkGLContext matching the framebuffer format to the visual of the GdkSurface. The context is disconnected from any particular surface or surface.

If the creation of the GdkGLContext failed, error will be set.

Before using the returned GdkGLContext, you will need to call gdk_gl_context_make_current() or gdk_gl_context_realize().

Parameters

surface

a GdkSurface

 

error

return location for an error

 

Returns

the newly created GdkGLContext, or NULL on error.

[transfer full]


gdk_surface_create_vulkan_context ()

GdkVulkanContext *
gdk_surface_create_vulkan_context (GdkSurface *surface,
                                   GError **error);

Creates a new GdkVulkanContext for rendering on surface .

If the creation of the GdkVulkanContext failed, error will be set.

Parameters

surface

a GdkSurface

 

error

return location for an error

 

Returns

the newly created GdkVulkanContext, or NULL on error.

[transfer full]


gdk_surface_create_cairo_context ()

GdkCairoContext *
gdk_surface_create_cairo_context (GdkSurface *surface);

Creates a new GdkCairoContext for rendering on surface .

Parameters

surface

a GdkSurface

 

Returns

the newly created GdkCairoContext.

[transfer full]


gdk_surface_queue_expose ()

void
gdk_surface_queue_expose (GdkSurface *surface);

Forces an expose event for surface to be scheduled.

If the invalid area of surface is empty, an expose event will still be emitted. Its invalid region will be empty.

This function is useful for implementations that track invalid regions on their own.

Parameters

surface

a GdkSurface

 

gdk_surface_freeze_updates ()

void
gdk_surface_freeze_updates (GdkSurface *surface);

Temporarily freezes a surface such that it won’t receive expose events. The surface will begin receiving expose events again when gdk_surface_thaw_updates() is called. If gdk_surface_freeze_updates() has been called more than once, gdk_surface_thaw_updates() must be called an equal number of times to begin processing exposes.

Parameters

surface

a GdkSurface

 

gdk_surface_thaw_updates ()

void
gdk_surface_thaw_updates (GdkSurface *surface);

Thaws a surface frozen with gdk_surface_freeze_updates(). Note that this will not necessarily schedule updates if the surface freeze count reaches zero.

Parameters

surface

a GdkSurface

 

gdk_surface_get_frame_clock ()

GdkFrameClock *
gdk_surface_get_frame_clock (GdkSurface *surface);

Gets the frame clock for the surface. The frame clock for a surface never changes unless the surface is reparented to a new toplevel surface.

Parameters

surface

surface to get frame clock for

 

Returns

the frame clock.

[transfer none]


gdk_surface_set_accept_focus ()

void
gdk_surface_set_accept_focus (GdkSurface *surface,
                              gboolean accept_focus);

Setting accept_focus to FALSE hints the desktop environment that the surface 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.

Parameters

surface

a toplevel GdkSurface

 

accept_focus

TRUE if the surface should receive input focus

 

gdk_surface_get_accept_focus ()

gboolean
gdk_surface_get_accept_focus (GdkSurface *surface);

Determines whether or not the desktop environment shuld be hinted that the surface does not want to receive input focus.

Parameters

surface

a toplevel GdkSurface.

 

Returns

whether or not the surface should receive input focus.


gdk_surface_set_focus_on_map ()

void
gdk_surface_set_focus_on_map (GdkSurface *surface,
                              gboolean focus_on_map);

Setting focus_on_map to FALSE hints the desktop environment that the surface doesn’t want to receive input focus when it is mapped. focus_on_map should be turned off for surfaces 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.

Parameters

surface

a toplevel GdkSurface

 

focus_on_map

TRUE if the surface should receive input focus when mapped

 

gdk_surface_get_focus_on_map ()

gboolean
gdk_surface_get_focus_on_map (GdkSurface *surface);

Determines whether or not the desktop environment should be hinted that the surface does not want to receive input focus when it is mapped.

Parameters

surface

a toplevel GdkSurface.

 

Returns

whether or not the surface wants to receive input focus when it is mapped.


gdk_surface_input_shape_combine_region ()

void
gdk_surface_input_shape_combine_region
                               (GdkSurface *surface,
                                const cairo_region_t *shape_region,
                                gint offset_x,
                                gint offset_y);

Apply the region to the surface for the purpose of event handling. Mouse events which happen while the pointer position corresponds to an unset bit in the mask will be passed on the surface below surface .

An input shape is typically used with RGBA surfaces. The alpha channel of the surface defines which pixels are invisible and allows for nicely antialiased borders, and the input shape controls where the surface 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.

Parameters

surface

a GdkSurface

 

shape_region

region of surface to be non-transparent

 

offset_x

X position of shape_region in surface coordinates

 

offset_y

Y position of shape_region in surface coordinates

 

gdk_surface_set_title ()

void
gdk_surface_set_title (GdkSurface *surface,
                       const gchar *title);

Sets the title of a toplevel surface, to be displayed in the titlebar. If you haven’t explicitly set the icon name for the surface (using gdk_surface_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 and GTK). title may not be NULL.

Parameters

surface

a toplevel GdkSurface

 

title

title of surface

 

gdk_surface_set_cursor ()

void
gdk_surface_set_cursor (GdkSurface *surface,
                        GdkCursor *cursor);

Sets the default mouse pointer for a GdkSurface.

Note that cursor must be for the same display as surface .

Use gdk_cursor_new_from_name() or gdk_cursor_new_from_texture() to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR. Passing NULL for the cursor argument to gdk_surface_set_cursor() means that surface will use the cursor of its parent surface. Most surfaces should use this default.

Parameters

surface

a GdkSurface

 

cursor

a cursor.

[allow-none]

gdk_surface_get_cursor ()

GdkCursor *
gdk_surface_get_cursor (GdkSurface *surface);

Retrieves a GdkCursor pointer for the cursor currently set on the specified GdkSurface, or NULL. If the return value is NULL then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface.

Parameters

surface

a GdkSurface

 

Returns

a GdkCursor, or NULL. The returned object is owned by the GdkSurface and should not be unreferenced directly. Use gdk_surface_set_cursor() to unset the cursor of the surface.

[nullable][transfer none]


gdk_surface_set_geometry_hints ()

void
gdk_surface_set_geometry_hints (GdkSurface *surface,
                                const GdkGeometry *geometry,
                                GdkSurfaceHints geom_mask);

Sets the geometry hints for surface . Hints flagged in geom_mask are set, hints not flagged in geom_mask are unset. To unset all hints, use a geom_mask of 0 and a geometry of NULL.

This function provides hints to the surfaceing system about acceptable sizes for a toplevel surface. 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 surface to the provided values and constrain programatic resizing via gdk_surface_resize().

Note that on X11, this effect has no effect on surfaces of type GDK_SURFACE_TEMP since these surfaces are not resizable by the user.

Since you can’t count on the windowing system doing the constraints for programmatic resizes, you should generally call gdk_surface_constrain_size() yourself to determine appropriate sizes.

Parameters

surface

a toplevel GdkSurface

 

geometry

geometry hints

 

geom_mask

bitmask indicating fields of geometry to pay attention to

 

gdk_surface_get_width ()

int
gdk_surface_get_width (GdkSurface *surface);

Returns the width of the given surface .

On the X11 platform the returned size is the size reported in the most-recently-processed configure event, rather than the current size on the X server.

Parameters

surface

a GdkSurface

 

Returns

The width of surface


gdk_surface_get_height ()

int
gdk_surface_get_height (GdkSurface *surface);

Returns the height of the given surface .

On the X11 platform the returned size is the size reported in the most-recently-processed configure event, rather than the current size on the X server.

Parameters

surface

a GdkSurface

 

Returns

The height of surface


gdk_surface_set_icon_list ()

void
gdk_surface_set_icon_list (GdkSurface *surface,
                           GList *surfaces);

Sets a list of icons for the surface. One of these will be used to represent the surface 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.

Note that some platforms don't support surface icons.

Parameters

surface

The GdkSurface toplevel surface to set the icon of.

 

surfaces

A list of image surfaces, of different sizes.

[transfer none][element-type GdkTexture]

gdk_surface_set_modal_hint ()

void
gdk_surface_set_modal_hint (GdkSurface *surface,
                            gboolean modal);

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

You should only use this on surfaces for which you have previously called gdk_surface_set_transient_for()

Parameters

surface

A toplevel GdkSurface

 

modal

TRUE if the surface is modal, FALSE otherwise.

 

gdk_surface_get_modal_hint ()

gboolean
gdk_surface_get_modal_hint (GdkSurface *surface);

Determines whether or not the window manager is hinted that surface has modal behaviour.

Parameters

surface

A toplevel GdkSurface.

 

Returns

whether or not the surface has the modal hint set.


gdk_surface_set_type_hint ()

void
gdk_surface_set_type_hint (GdkSurface *surface,
                           GdkSurfaceTypeHint hint);

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

The hint must be set before the surface is mapped.

Parameters

surface

A toplevel GdkSurface

 

hint

A hint of the function this surface will have

 

gdk_surface_get_type_hint ()

GdkSurfaceTypeHint
gdk_surface_get_type_hint (GdkSurface *surface);

This function returns the type hint set for a surface.

Parameters

surface

A toplevel GdkSurface

 

Returns

The type hint set for surface


gdk_surface_set_shadow_width ()

void
gdk_surface_set_shadow_width (GdkSurface *surface,
                              gint left,
                              gint right,
                              gint top,
                              gint bottom);

Newer GTK windows using client-side decorations use extra geometry around their frames for effects like shadows and invisible borders. Window managers that want to maximize windows or snap to edges need to know where the extents of the actual frame lie, so that users don’t feel like windows are snapping against random invisible edges.

Note that this property is automatically updated by GTK, so this function should only be used by applications which do not use GTK to create toplevel surfaces.

Parameters

surface

a GdkSurface

 

left

The left extent

 

right

The right extent

 

top

The top extent

 

bottom

The bottom extent

 

gdk_surface_get_position ()

void
gdk_surface_get_position (GdkSurface *surface,
                          gint *x,
                          gint *y);

Obtains the position of the surface relative to its parent.

Parameters

surface

a GdkSurface

 

x

X coordinate of surface.

[out]

y

Y coordinate of surface.

[out]

gdk_surface_get_device_position ()

void
gdk_surface_get_device_position (GdkSurface *surface,
                                 GdkDevice *device,
                                 double *x,
                                 double *y,
                                 GdkModifierType *mask);

Obtains the current device position in doubles and modifier state. The position is given in coordinates relative to the upper left corner of surface .

Parameters

surface

a GdkSurface.

 

device

pointer GdkDevice to query to.

 

x

return location for the X coordinate of device , or NULL.

[out][allow-none]

y

return location for the Y coordinate of device , or NULL.

[out][allow-none]

mask

return location for the modifier mask, or NULL.

[out][allow-none]

gdk_surface_set_icon_name ()

void
gdk_surface_set_icon_name (GdkSurface *surface,
                           const gchar *name);

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

After calling this with a non-NULL name , calls to gdk_surface_set_title() will not update the icon title.

Using NULL for name unsets the icon title; further calls to gdk_surface_set_title() will again update the icon title as well.

Note that some platforms don't support surface icons.

Parameters

surface

a toplevel GdkSurface

 

name

name of surface while iconified (minimized).

[allow-none]

gdk_surface_set_transient_for ()

void
gdk_surface_set_transient_for (GdkSurface *surface,
                               GdkSurface *parent);

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

See gtk_window_set_transient_for() if you’re using GtkWindow or GtkDialog.

Parameters

surface

a toplevel GdkSurface

 

parent

another toplevel GdkSurface

 

gdk_surface_set_startup_id ()

void
gdk_surface_set_startup_id (GdkSurface *surface,
                            const gchar *startup_id);

When using GTK, typically you should use gtk_window_set_startup_id() instead of this low-level function.

Parameters

surface

a toplevel GdkSurface

 

startup_id

a string with startup-notification identifier

 

gdk_surface_set_decorations ()

void
gdk_surface_set_decorations (GdkSurface *surface,
                             GdkWMDecoration decorations);

“Decorations” are the features the window manager adds to a toplevel GdkSurface. This function sets the traditional Motif window manager hints that tell the window manager which decorations you would like your surface to have. Usually you should use gtk_window_set_decorated() on a GtkWindow instead of using the GDK function directly.

The decorations argument is the logical OR of the fields in the GdkWMDecoration 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.

Parameters

surface

a toplevel GdkSurface

 

decorations

decoration hint mask

 

gdk_surface_get_decorations ()

gboolean
gdk_surface_get_decorations (GdkSurface *surface,
                             GdkWMDecoration *decorations);

Returns the decorations set on the GdkSurface with gdk_surface_set_decorations().

Parameters

surface

The toplevel GdkSurface to get the decorations from

 

decorations

The surface decorations will be written here.

[out]

Returns

TRUE if the surface has decorations set, FALSE otherwise.


gdk_surface_set_functions ()

void
gdk_surface_set_functions (GdkSurface *surface,
                           GdkWMFunction 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 GdkWMFunction 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.

Parameters

surface

a toplevel GdkSurface

 

functions

bitmask of operations to allow on surface

 

gdk_surface_get_support_multidevice ()

gboolean
gdk_surface_get_support_multidevice (GdkSurface *surface);

Returns TRUE if the surface is aware of the existence of multiple devices.

Parameters

surface

a GdkSurface.

 

Returns

TRUE if the surface handles multidevice features.


gdk_surface_set_support_multidevice ()

void
gdk_surface_set_support_multidevice (GdkSurface *surface,
                                     gboolean support_multidevice);

This function will enable multidevice features in surface .

Multidevice aware surfaces will need to handle properly multiple, per device enter/leave events, device grabs and grab ownerships.

Parameters

surface

a GdkSurface.

 

support_multidevice

TRUE to enable multidevice support in surface .

 

gdk_surface_get_device_cursor ()

GdkCursor *
gdk_surface_get_device_cursor (GdkSurface *surface,
                               GdkDevice *device);

Retrieves a GdkCursor pointer for the device currently set on the specified GdkSurface, or NULL. If the return value is NULL then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface.

Parameters

surface

a GdkSurface.

 

device

a master, pointer GdkDevice.

 

Returns

a GdkCursor, or NULL. The returned object is owned by the GdkSurface and should not be unreferenced directly. Use gdk_surface_set_cursor() to unset the cursor of the surface.

[nullable][transfer none]


gdk_surface_set_device_cursor ()

void
gdk_surface_set_device_cursor (GdkSurface *surface,
                               GdkDevice *device,
                               GdkCursor *cursor);

Sets a specific GdkCursor for a given device when it gets inside surface . Use gdk_cursor_new_fromm_name() or gdk_cursor_new_from_texture() to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR. Passing NULL for the cursor argument to gdk_surface_set_cursor() means that surface will use the cursor of its parent surface. Most surfaces should use this default.

Parameters

surface

a GdkSurface

 

device

a master, pointer GdkDevice

 

cursor

a GdkCursor

 

Property Details

The “autohide” property

  “autohide”                 gboolean

Whether to dismiss the surface on outside clicks.

Owner: GdkSurface

Flags: Read / Write / Construct Only

Default value: FALSE


The “cursor” property

  “cursor”                   GdkCursor *

The mouse pointer for a GdkSurface. See gdk_surface_set_cursor() and gdk_surface_get_cursor() for details.

Owner: GdkSurface

Flags: Read / Write


The “display” property

  “display”                  GdkDisplay *

The GdkDisplay connection of the surface. See gdk_surface_get_display() for details.

Owner: GdkSurface

Flags: Read / Write / Construct Only


The “frame-clock” property

  “frame-clock”              GdkFrameClock *

Frame Clock.

Owner: GdkSurface

Flags: Read / Write / Construct Only


The “mapped” property

  “mapped”                   gboolean

Mapped.

Owner: GdkSurface

Flags: Read

Default value: FALSE


The “parent” property

  “parent”                   GdkSurface *

Parent surface.

Owner: GdkSurface

Flags: Read / Write / Construct Only


The “state” property

  “state”                    GdkSurfaceState

State.

Owner: GdkSurface

Flags: Read

Default value: GDK_SURFACE_STATE_WITHDRAWN


The “surface-type” property

  “surface-type”             GdkSurfaceType

Surface type.

Owner: GdkSurface

Flags: Read / Write / Construct Only

Default value: GDK_SURFACE_TOPLEVEL

Signal Details

The “event” signal

gboolean
user_function (GdkSurface *surface,
               GdkEvent   *event,
               gpointer    user_data)

Emitted when GDK receives an input event for surface .

Parameters

surface

the GdkSurface

 

event

an input event

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to indicate that the event has been handled

Flags: Run Last


The “moved-to-rect” signal

void
user_function (GdkSurface *surface,
               gpointer    flipped_rect,
               gpointer    final_rect,
               gboolean    flipped_x,
               gboolean    flipped_y,
               gpointer    user_data)

Emitted when the position of surface is finalized after being moved to a destination rectangle.

surface might be flipped over the destination rectangle in order to keep it on-screen, in which case flipped_x and flipped_y will be set to TRUE accordingly.

flipped_rect is the ideal position of surface after any possible flipping, but before any possible sliding. final_rect is flipped_rect , but possibly translated in the case that flipping is still ineffective in keeping surface on-screen.

Parameters

surface

the GdkSurface that moved

 

flipped_rect

the position of surface after any possible flipping or NULL if the backend can't obtain it.

[nullable]

final_rect

the final position of surface or NULL if the backend can't obtain it.

[nullable]

flipped_x

TRUE if the anchors were flipped horizontally

 

flipped_y

TRUE if the anchors were flipped vertically

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Stability Level: Private


The “render” signal

gboolean
user_function (GdkSurface  *surface,
               CairoRegion *region,
               gpointer     user_data)

Emitted when part of the surface needs to be redrawn.

Parameters

surface

the GdkSurface

 

region

the region that needs to be redrawn

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE to indicate that the signal has been handled

Flags: Run Last


The “size-changed” signal

void
user_function (GdkSurface *surface,
               gint        width,
               gint        height,
               gpointer    user_data)

Emitted when the size of surface is changed.

Parameters

surface

the GdkSurface

 

width

the new width

 

height

the new height

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First