Package org.gnome.gdk

Class Surface

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gdk.Surface

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

DragSurface.DragSurface$Impl, Popup.Popup$Impl, Surface.Surface$Impl, Toplevel.Toplevel$Impl

@Generated("io.github.jwharm.JavaGI")
public abstract class Surface
extends GObject

Represents a rectangular region on the screen.

It’s a low-level object, used to implement high-level objects such as GtkWindow.

The surfaces you see in practice are either Toplevel or Popup, and those interfaces provide much of the required API to interact with these surfaces. Other, more specialized surface types exist, but you will rarely interact with them directly.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Surface.Builder<B extends Surface.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	Surface.EnterMonitorCallback	Functional interface declaration of the EnterMonitorCallback callback.
static interface	Surface.EventCallback	Functional interface declaration of the EventCallback callback.
static interface	Surface.LayoutCallback	Functional interface declaration of the LayoutCallback callback.
static interface	Surface.LeaveMonitorCallback	Functional interface declaration of the LeaveMonitorCallback callback.
static interface	Surface.RenderCallback	Functional interface declaration of the RenderCallback callback.
static class	Surface.Surface$Impl	The Surface$Impl type represents a native instance of the abstract Surface class.
static class	Surface.SurfaceClass

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
Surface()	Creates a new Surface.
Surface(MemorySegment address)	Create a Surface proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected Surface	asParent()	Returns this instance as if it were its parent type.
void	beep()	Emits a short beep associated to surface.
CairoContext	createCairoContext()	Deprecated. Drawing content with Cairo should be done via Cairo rendernodes, not by using the Cairo renderer.
GLContext	createGlContext()	Creates a new GdkGLContext for the GdkSurface.
org.freedesktop.cairo.Surface	createSimilarSurface(org.freedesktop.cairo.Content content, int width, int height)	Deprecated. Create a suitable cairo image surface yourself
VulkanContext	createVulkanContext()	Deprecated. GTK does not expose any Vulkan internals.
void	destroy()	Destroys the window system resources associated with this Surface and decrements surface's reference count.
void	emitEnterMonitor(@Nullable Monitor monitor)	Emits the "enter-monitor" signal.
boolean	emitEvent(Event event)	Emits the "event" signal.
void	emitLayout(int width, int height)	Emits the "layout" signal.
void	emitLeaveMonitor(@Nullable Monitor monitor)	Emits the "leave-monitor" signal.
boolean	emitRender(@Nullable org.freedesktop.cairo.Region region)	Emits the "render" signal.
@Nullable Cursor	getCursor()	Retrieves a GdkCursor pointer for the cursor currently set on the GdkSurface.
@Nullable Cursor	getDeviceCursor(Device device)	Retrieves a GdkCursor pointer for the device currently set on the specified GdkSurface.
boolean	getDevicePosition(Device device, @Nullable Out<Double> x, @Nullable Out<Double> y, @Nullable Out<Set<ModifierType>> mask)	Obtains the current device position and modifier state.
Display	getDisplay()	Gets the GdkDisplay associated with a GdkSurface.
FrameClock	getFrameClock()	Gets the frame clock for the surface.
int	getHeight()	Returns the height of the given surface.
boolean	getMapped()	Checks whether the surface has been mapped.
double	getScale()	Returns the internal scale that maps from surface coordinates to the actual device pixels.
int	getScaleFactor()	Returns the internal scale factor that maps from surface coordinates to the actual device pixels.
static @Nullable Type	getType()	Get the GType of the Surface class
int	getWidth()	Returns the width of the given surface.
void	hide()	Hide the surface.
boolean	isDestroyed()	Check to see if a surface is destroyed.
SignalConnection<Surface.EnterMonitorCallback>	onEnterMonitor(Surface.EnterMonitorCallback handler)	Emitted when surface starts being present on the monitor.
SignalConnection<Surface.EventCallback>	onEvent(Surface.EventCallback handler)	Emitted when GDK receives an input event for surface.
SignalConnection<Surface.LayoutCallback>	onLayout(Surface.LayoutCallback handler)	Emitted when the size of surface is changed, or when relayout should be performed.
SignalConnection<Surface.LeaveMonitorCallback>	onLeaveMonitor(Surface.LeaveMonitorCallback handler)	Emitted when surface stops being present on the monitor.
SignalConnection<Surface.RenderCallback>	onRender(Surface.RenderCallback handler)	Emitted when part of the surface needs to be redrawn.
static Surface	popup(Surface parent, boolean autohide)	Create a new popup surface.
void	queueRender()	Forces a Gdk.Surface::render signal emission for this Surface to be scheduled.
void	requestLayout()	Request a layout phase from the surface's frame clock.
void	setCursor(@Nullable Cursor cursor)	Sets the default mouse pointer for a GdkSurface.
void	setDeviceCursor(Device device, Cursor cursor)	Sets a specific GdkCursor for a given device when it gets inside surface.
void	setInputRegion(@Nullable org.freedesktop.cairo.Region region)	Apply the region to the surface for the purpose of event handling.
void	setOpaqueRegion(@Nullable org.freedesktop.cairo.Region region)	Deprecated. GDK can figure out the opaque parts of a window itself by inspecting the contents that are drawn.
static Surface	toplevel(Display display)	Creates a new toplevel surface.
boolean	translateCoordinates(Surface to, Out<Double> x, Out<Double> y)	Translates coordinates between two surfaces.

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, builder, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getMemoryLayout, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Surface

public Surface(MemorySegment address)

Create a Surface proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Surface

public Surface()

Creates a new Surface.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Surface class

Returns:

the GType

asParent

protected Surface asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GObject

popup

public static Surface popup(Surface parent,
 boolean autohide)

Create a new popup surface.

The surface will be attached to parent and can be positioned relative to it using Popup.present(int, int, org.gnome.gdk.PopupLayout).

Parameters:

parent - the parent surface to attach the surface to

autohide - whether to hide the surface on outside clicks

Returns:

a new GdkSurface

toplevel

public static Surface toplevel(Display display)

Creates a new toplevel surface.

Parameters:

display - the display to create the surface on

Returns:

the new GdkSurface

beep

public void beep()

Emits a short beep associated to surface.

If the display of this Surface does not support per-surface beeps, emits a short beep on the display just as Display.beep().

createCairoContext

@Deprecated
public CairoContext createCairoContext()

Deprecated.

Drawing content with Cairo should be done via Cairo rendernodes, not by using the Cairo renderer.

Creates a new GdkCairoContext for rendering on surface.

Returns:

the newly created GdkCairoContext

createGlContext

public GLContext createGlContext()
                          throws GErrorException

Creates a new GdkGLContext for 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 GLContext.makeCurrent() or GLContext.realize().

Returns:

the newly created GdkGLContext

Throws:

GErrorException - see GError

createSimilarSurface

@Deprecated
public org.freedesktop.cairo.Surface createSimilarSurface(org.freedesktop.cairo.Content content,
 int width,
 int height)

Deprecated.

Create a suitable cairo image surface yourself

Create a new Cairo surface that is as compatible as possible with the given surface.

For example the new surface will have the same fallback resolution and font options as surface. Generally, the new surface will also use the same backend as surface, unless that is not possible for some reason. The type of the returned surface may be examined with cairo_surface_get_type().

Initially the surface contents are all 0 (transparent if contents have transparency, black otherwise.)

This function always returns a valid pointer, but it will return a pointer to a “nil” surface if other is already in an error state or any other error occurs.

Parameters:

content - the content for the new surface

width - width of the new surface

height - height of the new surface

Returns:

a pointer to the newly allocated surface. The caller owns the surface and should call cairo_surface_destroy() when done with it.

createVulkanContext

@Deprecated
public VulkanContext createVulkanContext()
                                  throws GErrorException

Deprecated.

GTK does not expose any Vulkan internals. This function is a leftover that was accidentally exposed.

Sets an error and returns null.

Returns:

null

Throws:

GErrorException - see GError

destroy

public void destroy()

Destroys the window system resources associated with this Surface and decrements surface's reference count.

The window system resources for all children of this 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.

getCursor

public @Nullable Cursor getCursor()

Retrieves a GdkCursor pointer for the cursor currently set on the GdkSurface.

If the return value is null then there is no custom cursor set on the surface, and it is using the cursor for its parent surface.

Use setCursor(org.gnome.gdk.Cursor) to unset the cursor of the surface.

Returns:

a GdkCursor

getDeviceCursor

public @Nullable Cursor getDeviceCursor(Device device)

Retrieves a GdkCursor pointer for the device currently set on the specified GdkSurface.

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.

Use setCursor(org.gnome.gdk.Cursor) to unset the cursor of the surface.

Parameters:

device - a pointer GdkDevice

Returns:

a GdkCursor

getDevicePosition

public boolean getDevicePosition(Device device,
 @Nullable Out<Double> x,
 @Nullable Out<Double> y,
 @Nullable Out<Set<ModifierType>> mask)

Obtains the current device position and modifier state.

The position is given in coordinates relative to the upper left corner of surface.

Parameters:

device - pointer GdkDevice to query to

x - return location for the X coordinate of device

y - return location for the Y coordinate of device

mask - return location for the modifier mask

Returns:

true if the device is over the surface

getDisplay

public Display getDisplay()

Gets the GdkDisplay associated with a GdkSurface.

Returns:

the GdkDisplay associated with this Surface

getFrameClock

public FrameClock getFrameClock()

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.

Returns:

the frame clock

getHeight

public int getHeight()

Returns the height of the given surface.

Surface size is reported in ”application pixels”, not ”device pixels” (see getScaleFactor()).

Returns:

The height of this Surface

getMapped

public boolean getMapped()

Checks whether the surface has been mapped.

A surface is mapped with Toplevel.present(org.gnome.gdk.ToplevelLayout) or Popup.present(int, int, org.gnome.gdk.PopupLayout).

Returns:

true if the surface is mapped

getScale

public double getScale()

Returns the internal scale that maps from surface coordinates to the actual device pixels.

When the scale is bigger than 1, the windowing system prefers to get buffers with a resolution that is bigger than the surface size (e.g. to show the surface on a high-resolution display, or in a magnifier).

Compare with getScaleFactor(), which returns the next larger integer.

The scale may change during the lifetime of the surface.

Returns:

the scale

Since:

4.12

getScaleFactor

public int getScaleFactor()

Returns the internal scale factor that maps from surface coordinates 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 factor may change during the lifetime of the surface.

Returns:

the scale factor

getWidth

public int getWidth()

Returns the width of the given surface.

Surface size is reported in ”application pixels”, not ”device pixels” (see getScaleFactor()).

Returns:

The width of this Surface

hide

public void hide()

Hide the 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().

isDestroyed

public boolean isDestroyed()

Check to see if a surface is destroyed.

Returns:

true if the surface is destroyed

queueRender

public void queueRender()

Forces a Gdk.Surface::render signal emission for this Surface to be scheduled.

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

requestLayout

public void requestLayout()

Request a layout phase from the surface's frame clock.

See FrameClock.requestPhase(java.util.Set<org.gnome.gdk.FrameClockPhase>).

setCursor

public void setCursor(@Nullable Cursor cursor)

Sets the default mouse pointer for a GdkSurface.

Passing null for the cursor argument means that this Surface will use the cursor of its parent surface. Most surfaces should use this default. Note that cursor must be for the same display as surface.

Use Cursor.fromName(java.lang.String, org.gnome.gdk.Cursor) or Cursor.fromTexture(org.gnome.gdk.Texture, int, int, org.gnome.gdk.Cursor) to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR.

Parameters:

cursor - a GdkCursor

setDeviceCursor

public void setDeviceCursor(Device device,
 Cursor cursor)

Sets a specific GdkCursor for a given device when it gets inside surface.

Passing null for the cursor argument means that this Surface will use the cursor of its parent surface. Most surfaces should use this default.

Use Cursor.fromName(java.lang.String, org.gnome.gdk.Cursor) or Cursor.fromTexture(org.gnome.gdk.Texture, int, int, org.gnome.gdk.Cursor) to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR.

Parameters:

device - a pointer GdkDevice

cursor - a GdkCursor

setInputRegion

public void setInputRegion(@Nullable org.freedesktop.cairo.Region region)

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 region 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 region controls where the surface is “clickable”.

Use Display.supportsInputShapes() to find out if a particular backend supports input regions.

Parameters:

region - region of surface to be reactive, or null to make the entire surface reactive

setOpaqueRegion

@Deprecated
public void setOpaqueRegion(@Nullable org.freedesktop.cairo.Region region)

Deprecated.

GDK can figure out the opaque parts of a window itself by inspecting the contents that are drawn.

Marks a region of the GdkSurface as opaque.

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 this 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 GtkWidgetClass.css_changed handler.

Parameters:

region - a region, or null to make the entire surface opaque

translateCoordinates

public boolean translateCoordinates(Surface to,
 Out<Double> x,
 Out<Double> y)

Translates coordinates between two surfaces.

Note that this only works if to and this Surface are popups or transient-for to the same toplevel (directly or indirectly).

Parameters:

to - the target surface

x - coordinates to translate

y - coordinates to translate

Returns:

true if the coordinates were successfully translated

onEnterMonitor

public SignalConnection<Surface.EnterMonitorCallback> onEnterMonitor(Surface.EnterMonitorCallback handler)

Emitted when surface starts being present on the monitor.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Surface.EnterMonitorCallback.run(org.gnome.gdk.Monitor)

emitEnterMonitor

public void emitEnterMonitor(@Nullable Monitor monitor)

Emits the "enter-monitor" signal. See onEnterMonitor(org.gnome.gdk.Surface.EnterMonitorCallback).

onEvent

public SignalConnection<Surface.EventCallback> onEvent(Surface.EventCallback handler)

Emitted when GDK receives an input event for surface.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Surface.EventCallback.run(org.gnome.gdk.Event)

emitEvent

public boolean emitEvent(Event event)

Emits the "event" signal. See onEvent(org.gnome.gdk.Surface.EventCallback).

onLayout

public SignalConnection<Surface.LayoutCallback> onLayout(Surface.LayoutCallback handler)

Emitted when the size of surface is changed, or when relayout should be performed.

Surface size is reported in ”application pixels”, not ”device pixels” (see gdk_surface_get_scale_factor()).

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Surface.LayoutCallback.run(int, int)

emitLayout

public void emitLayout(int width,
 int height)

Emits the "layout" signal. See onLayout(org.gnome.gdk.Surface.LayoutCallback).

onLeaveMonitor

public SignalConnection<Surface.LeaveMonitorCallback> onLeaveMonitor(Surface.LeaveMonitorCallback handler)

Emitted when surface stops being present on the monitor.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Surface.LeaveMonitorCallback.run(org.gnome.gdk.Monitor)

emitLeaveMonitor

public void emitLeaveMonitor(@Nullable Monitor monitor)

Emits the "leave-monitor" signal. See onLeaveMonitor(org.gnome.gdk.Surface.LeaveMonitorCallback).

onRender

public SignalConnection<Surface.RenderCallback> onRender(Surface.RenderCallback handler)

Emitted when part of the surface needs to be redrawn.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Surface.RenderCallback.run(org.freedesktop.cairo.Region)

emitRender

public boolean emitRender(@Nullable org.freedesktop.cairo.Region region)

Emits the "render" signal. See onRender(org.gnome.gdk.Surface.RenderCallback).