Top | ![]() |
![]() |
![]() |
![]() |
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 |
gboolean | event | Run Last |
void | moved-to-rect | Run First |
gboolean | render | Run Last |
void | size-changed | Run First |
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 |
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.
GdkSurface * gdk_surface_new_toplevel (GdkDisplay *display
,int width
,int height
);
Creates a new toplevel surface.
[constructor]
GdkSurface * gdk_surface_new_temp (GdkDisplay *display
,const GdkRectangle *position
);
Creates a new temporary surface. The surface will bypass surface management.
[constructor]
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]
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.
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.
GdkSurfaceType
gdk_surface_get_surface_type (GdkSurface *surface
);
Gets the type of the surface. See GdkSurfaceType.
GdkDisplay *
gdk_surface_get_display (GdkSurface *surface
);
Gets the GdkDisplay associated with a GdkSurface.
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.
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).
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()
.
gboolean
gdk_surface_is_destroyed (GdkSurface *surface
);
Check to see if a surface is destroyed..
gboolean
gdk_surface_is_visible (GdkSurface *surface
);
Checks whether the surface has been mapped (with gdk_surface_show()
or
gdk_surface_show_unraised()
).
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.)
GdkSurfaceState
gdk_surface_get_state (GdkSurface *surface
);
Gets the bitwise OR of the currently active surface state flags, from the GdkSurfaceState enumeration.
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.
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.
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.
void
gdk_surface_unstick (GdkSurface *surface
);
Reverse operation for gdk_surface_stick()
; see gdk_surface_stick()
,
and gtk_window_unstick()
.
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.
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.
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.
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.
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.
GdkFullscreenMode
gdk_surface_get_fullscreen_mode (GdkSurface *surface
);
Obtains the GdkFullscreenMode of the surface
.
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.
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.
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.
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.
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.
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.
surface |
the GdkSurface to move |
|
rect |
the destination GdkRectangle to align |
[not nullable] |
rect_anchor |
the point on |
|
surface_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 |
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.
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()
.)
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.
surface |
||
sibling |
a GdkSurface that is a sibling of |
[allow-none] |
above |
a boolean |
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.
void
gdk_surface_register_dnd (GdkSurface *surface
);
Registers a surface as a potential drop destination.
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.
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 |
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,”
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 |
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.
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 |
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).
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 |
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.
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).
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()
.
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.
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.
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()
.
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.
GdkCairoContext *
gdk_surface_create_cairo_context (GdkSurface *surface
);
Creates a new GdkCairoContext for rendering on surface
.
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.
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.
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.
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.
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.
surface |
a toplevel GdkSurface |
|
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.
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.
surface |
a toplevel GdkSurface |
|
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.
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.
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
.
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.
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.
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]
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.
surface |
a toplevel GdkSurface |
|
geometry |
geometry hints |
|
geom_mask |
bitmask indicating fields of |
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.
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.
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.
surface |
The GdkSurface toplevel surface to set the icon of. |
|
surfaces |
A list of image surfaces, of different sizes. |
[transfer none][element-type GdkTexture] |
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()
gboolean
gdk_surface_get_modal_hint (GdkSurface *surface
);
Determines whether or not the window manager is hinted that surface
has modal behaviour.
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.
GdkSurfaceTypeHint
gdk_surface_get_type_hint (GdkSurface *surface
);
This function returns the type hint set for a surface.
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.
void gdk_surface_get_position (GdkSurface *surface
,gint *x
,gint *y
);
Obtains the position of the surface relative to its parent.
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
.
surface |
a GdkSurface. |
|
device |
pointer GdkDevice to query to. |
|
x |
return location for the X coordinate of |
[out][allow-none] |
y |
return location for the Y coordinate of |
[out][allow-none] |
mask |
return location for the modifier mask, or |
[out][allow-none] |
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.
surface |
a toplevel GdkSurface |
|
name |
name of surface while iconified (minimized). |
[allow-none] |
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.
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.
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.
gboolean gdk_surface_get_decorations (GdkSurface *surface
,GdkWMDecoration *decorations
);
Returns the decorations set on the GdkSurface with
gdk_surface_set_decorations()
.
surface |
The toplevel GdkSurface to get the decorations from |
|
decorations |
The surface decorations will be written here. |
[out] |
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.
gboolean
gdk_surface_get_support_multidevice (GdkSurface *surface
);
Returns TRUE
if the surface is aware of the existence of multiple
devices.
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.
surface |
a GdkSurface. |
|
support_multidevice |
|
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.
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]
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.
“autohide”
property “autohide” gboolean
Whether to dismiss the surface on outside clicks.
Owner: GdkSurface
Flags: Read / Write / Construct Only
Default value: FALSE
“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
“display”
property“display” GdkDisplay *
The GdkDisplay connection of the surface. See gdk_surface_get_display()
for details.
Owner: GdkSurface
Flags: Read / Write / Construct Only
“frame-clock”
property“frame-clock” GdkFrameClock *
Frame Clock.
Owner: GdkSurface
Flags: Read / Write / Construct Only
“parent”
property“parent” GdkSurface *
Parent surface.
Owner: GdkSurface
Flags: Read / Write / Construct Only
“state”
property “state” GdkSurfaceState
State.
Owner: GdkSurface
Flags: Read
Default value: GDK_SURFACE_STATE_WITHDRAWN
“event”
signalgboolean user_function (GdkSurface *surface, GdkEvent *event, gpointer user_data)
Emitted when GDK receives an input event for surface
.
surface |
the GdkSurface |
|
event |
an input event |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“moved-to-rect”
signalvoid 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.
surface |
the GdkSurface that moved |
|
flipped_rect |
the position of |
[nullable] |
final_rect |
the final position of |
[nullable] |
flipped_x |
|
|
flipped_y |
|
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
Stability Level: Private
“render”
signalgboolean user_function (GdkSurface *surface, CairoRegion *region, gpointer user_data)
Emitted when part of the surface needs to be redrawn.
surface |
the GdkSurface |
|
region |
the region that needs to be redrawn |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“size-changed”
signalvoid user_function (GdkSurface *surface, gint width, gint height, gpointer user_data)
Emitted when the size of surface
is changed.
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