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("org.javagi.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.

  • Constructor Details

    • Surface

      public Surface(MemorySegment address)
      Create a Surface instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Surface

      public Surface()
      Create a new Surface.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Surface class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Surface asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GObject
      Returns:
      the instance as if it were its parent type

    • 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, 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(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(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(ToplevelLayout) or Popup.present(int, int, 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(Set).

    • 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(String, Cursor) or Cursor.fromTexture(Texture, int, int, 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(String, Cursor) or Cursor.fromTexture(Texture, int, int, 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:

    • emitEnterMonitor

      public void emitEnterMonitor(@Nullable Monitor monitor)
      Emits the "enter-monitor" signal. See onEnterMonitor(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:

    • emitEvent

      public boolean emitEvent(Event event)
      Emits the "event" signal. See onEvent(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:

    • emitLayout

      public void emitLayout(int width, int height)
      Emits the "layout" signal. See onLayout(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:

    • emitLeaveMonitor

      public void emitLeaveMonitor(@Nullable Monitor monitor)
      Emits the "leave-monitor" signal. See onLeaveMonitor(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:

    • emitRender

      public boolean emitRender(@Nullable org.freedesktop.cairo.Region region)
      Emits the "render" signal. See onRender(Surface.RenderCallback).