GI.Gdk.Objects.Surface

A GdkSurface is a rectangular region on the screen.

It’s a low-level object, used to implement high-level objects such as Gtk.Window or Gtk.Dialog in GTK.

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.

Exported types

newtype Surface

Memory-managed wrapper type.

Constructors

Surface (ManagedPtr Surface)

Instances

Eq Surface

Defined in GI.Gdk.Objects.Surface

Methods

(==) :: Surface -> Surface -> Bool

(/=) :: Surface -> Surface -> Bool

GObject Surface

Defined in GI.Gdk.Objects.Surface

ManagedPtrNewtype Surface

Defined in GI.Gdk.Objects.Surface

Methods

toManagedPtr :: Surface -> ManagedPtr Surface

TypedObject Surface

Defined in GI.Gdk.Objects.Surface

Methods

glibType :: IO GType

HasParentTypes Surface

Defined in GI.Gdk.Objects.Surface

IsGValue (Maybe Surface)

Convert Surface to and from GValue. See toGValue and fromGValue.

Defined in GI.Gdk.Objects.Surface

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Surface -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Surface)

type ParentTypes Surface

Defined in GI.Gdk.Objects.Surface

type ParentTypes Surface = '[Object]

class (GObject o, IsDescendantOf Surface o) => IsSurface o

Type class for types which can be safely cast to Surface, for instance with toSurface.

Instances

(GObject o, IsDescendantOf Surface o) => IsSurface o

Defined in GI.Gdk.Objects.Surface

toSurface :: (MonadIO m, IsSurface o) => o -> m Surface

Cast to Surface, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

beep, bindProperty, bindPropertyFull, createCairoContext, createGlContext, createSimilarSurface, createVulkanContext, destroy, forceFloating, freezeNotify, getv, hide, isDestroyed, isFloating, notify, notifyByPspec, queueRender, ref, refSink, requestLayout, runDispose, stealData, stealQdata, thawNotify, translateCoordinates, unref, watchClosure.

Getters

getCursor, getData, getDeviceCursor, getDevicePosition, getDisplay, getFrameClock, getHeight, getMapped, getProperty, getQdata, getScaleFactor, getWidth.

Setters

setCursor, setData, setDataFull, setDeviceCursor, setInputRegion, setOpaqueRegion, setProperty.

beep

surfaceBeep

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a toplevel GdkSurface

-> m ()

Emits a short beep associated to surface.

If the display of surface does not support per-surface beeps, emits a short beep on the display just as displayBeep.

createCairoContext

surfaceCreateCairoContext

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m CairoContext

Returns: the newly created GdkCairoContext

Creates a new GdkCairoContext for rendering on surface.

createGlContext

surfaceCreateGlContext

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m (Maybe GLContext)

Returns: the newly created GdkGLContext (Can throw GError)

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 gLContextMakeCurrent or gLContextRealize.

createSimilarSurface

surfaceCreateSimilarSurface

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: surface to make new surface similar to

-> Content

content: the content for the new surface

-> Int32

width: width of the new surface

-> Int32

height: height of the new surface

-> m Surface

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

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.

createVulkanContext

surfaceCreateVulkanContext

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m VulkanContext

Returns: the newly created GdkVulkanContext, or Nothing on error (Can throw GError)

Creates a new GdkVulkanContext for rendering on surface.

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

destroy

surfaceDestroy

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m ()

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.

getCursor

surfaceGetCursor

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m (Maybe Cursor)

Returns: a GdkCursor

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

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

Use surfaceSetCursor to unset the cursor of the surface.

getDeviceCursor

surfaceGetDeviceCursor

Arguments

:: (HasCallStack, MonadIO m, IsSurface a, IsDevice b)

=> a

surface: a GdkSurface

-> b

device: a pointer GdkDevice

-> m (Maybe Cursor)

Returns: a GdkCursor

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

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

Use surfaceSetCursor to unset the cursor of the surface.

getDevicePosition

surfaceGetDevicePosition

Arguments

:: (HasCallStack, MonadIO m, IsSurface a, IsDevice b)

=> a

surface: a GdkSurface

-> b

device: pointer GdkDevice to query to

-> m (Bool, Double, Double, [ModifierType])

Returns: True if the device is over the surface

Obtains the current device position and modifier state.

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

getDisplay

surfaceGetDisplay

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m Display

Returns: the GdkDisplay associated with surface

Gets the GdkDisplay associated with a GdkSurface.

getFrameClock

surfaceGetFrameClock

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: surface to get frame clock for

-> m FrameClock

Returns: the frame clock

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.

getHeight

surfaceGetHeight

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m Int32

Returns: The height of surface

Returns the height of the given surface.

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

getMapped

surfaceGetMapped

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m Bool

Returns: True if the surface is mapped

Checks whether the surface has been mapped.

A surface is mapped with toplevelPresent or popupPresent.

getScaleFactor

surfaceGetScaleFactor

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: surface to get scale factor for

-> m Int32

Returns: the scale factor

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 of a surface may change during runtime.

getWidth

surfaceGetWidth

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m Int32

Returns: The width of surface

Returns the width of the given surface.

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

hide

surfaceHide

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m ()

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

surfaceIsDestroyed

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m Bool

Returns: True if the surface is destroyed

Check to see if a surface is destroyed.

newPopup

surfaceNewPopup

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

parent: the parent surface to attach the surface to

-> Bool

autohide: whether to hide the surface on outside clicks

-> m Surface

Returns: a new GdkSurface

Create a new popup surface.

The surface will be attached to parent and can be positioned relative to it using popupPresent.

newToplevel

surfaceNewToplevel

Arguments

:: (HasCallStack, MonadIO m, IsDisplay a)

=> a

display: the display to create the surface on

-> m Surface

Returns: the new GdkSurface

Creates a new toplevel surface.

queueRender

surfaceQueueRender

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m ()

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

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

requestLayout

surfaceRequestLayout

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> m ()

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

See frameClockRequestPhase.

setCursor

surfaceSetCursor

Arguments

:: (HasCallStack, MonadIO m, IsSurface a, IsCursor b)

=> a

surface: a GdkSurface

-> Maybe b

cursor: a GdkCursor

-> m ()

Sets the default mouse pointer for a GdkSurface.

Passing Nothing for the cursor argument means that 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 cursorNewFromName or cursorNewFromTexture to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR.

setDeviceCursor

surfaceSetDeviceCursor

Arguments

:: (HasCallStack, MonadIO m, IsSurface a, IsDevice b, IsCursor c)

=> a

surface: a GdkSurface

-> b

device: a pointer GdkDevice

-> c

cursor: a GdkCursor

-> m ()

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

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

Use cursorNewFromName or cursorNewFromTexture to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR.

setInputRegion

surfaceSetInputRegion

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a GdkSurface

-> Region

region: region of surface to be reactive

-> m ()

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 displaySupportsInputShapes to find out if a particular backend supports input regions.

setOpaqueRegion

surfaceSetOpaqueRegion

Arguments

:: (HasCallStack, MonadIO m, IsSurface a)

=> a

surface: a top-level GdkSurface

-> Maybe Region

region: a region, or Nothing to make the entire surface opaque

-> m ()

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 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 Gtk.Widget.css_changed() handler.

translateCoordinates

surfaceTranslateCoordinates

Arguments

:: (HasCallStack, MonadIO m, IsSurface a, IsSurface b)

=> a

from: the origin surface

-> b

to: the target surface

-> Double

x: coordinates to translate

-> Double

y: coordinates to translate

-> m (Bool, Double, Double)

Returns: True if the coordinates were successfully translated

Translates coordinates between two surfaces.

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

Properties

cursor

The mouse pointer for the GdkSurface.

clearSurfaceCursor :: (MonadIO m, IsSurface o) => o -> m ()

Set the value of the “cursor” property to Nothing. When overloading is enabled, this is equivalent to

clear #cursor

constructSurfaceCursor :: (IsSurface o, MonadIO m, IsCursor a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “cursor” property. This is rarely needed directly, but it is used by new.

getSurfaceCursor :: (MonadIO m, IsSurface o) => o -> m (Maybe Cursor)

Get the value of the “cursor” property. When overloading is enabled, this is equivalent to

get surface #cursor

setSurfaceCursor :: (MonadIO m, IsSurface o, IsCursor a) => o -> a -> m ()

Set the value of the “cursor” property. When overloading is enabled, this is equivalent to

set surface [ #cursor := value ]

display

The GdkDisplay connection of the surface.

constructSurfaceDisplay :: (IsSurface o, MonadIO m, IsDisplay a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “display” property. This is rarely needed directly, but it is used by new.

getSurfaceDisplay :: (MonadIO m, IsSurface o) => o -> m Display

Get the value of the “display” property. When overloading is enabled, this is equivalent to

get surface #display

frameClock

The GdkFrameClock of the surface.

constructSurfaceFrameClock :: (IsSurface o, MonadIO m, IsFrameClock a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “frame-clock” property. This is rarely needed directly, but it is used by new.

getSurfaceFrameClock :: (MonadIO m, IsSurface o) => o -> m FrameClock

Get the value of the “frame-clock” property. When overloading is enabled, this is equivalent to

get surface #frameClock

height

The height of the surface, in pixels.

getSurfaceHeight :: (MonadIO m, IsSurface o) => o -> m Int32

Get the value of the “height” property. When overloading is enabled, this is equivalent to

get surface #height

mapped

Whether the surface is mapped.

getSurfaceMapped :: (MonadIO m, IsSurface o) => o -> m Bool

Get the value of the “mapped” property. When overloading is enabled, this is equivalent to

get surface #mapped

scaleFactor

The scale factor of the surface.

getSurfaceScaleFactor :: (MonadIO m, IsSurface o) => o -> m Int32

Get the value of the “scale-factor” property. When overloading is enabled, this is equivalent to

get surface #scaleFactor

width

The width of the surface in pixels.

getSurfaceWidth :: (MonadIO m, IsSurface o) => o -> m Int32

Get the value of the “width” property. When overloading is enabled, this is equivalent to

get surface #width

Signals

enterMonitor

type SurfaceEnterMonitorCallback

Arguments

 = Monitor

monitor: the monitor

-> IO ()

Emitted when surface starts being present on the monitor.

afterSurfaceEnterMonitor :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceEnterMonitorCallback) -> m SignalHandlerId

Connect a signal handler for the enterMonitor signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after surface #enterMonitor callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSurfaceEnterMonitor :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceEnterMonitorCallback) -> m SignalHandlerId

Connect a signal handler for the enterMonitor signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on surface #enterMonitor callback

event

type SurfaceEventCallback

Arguments

 = Event

event: an input event

-> IO Bool

Returns: True to indicate that the event has been handled

Emitted when GDK receives an input event for surface.

afterSurfaceEvent :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceEventCallback) -> m SignalHandlerId

Connect a signal handler for the event signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after surface #event callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSurfaceEvent :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceEventCallback) -> m SignalHandlerId

Connect a signal handler for the event signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on surface #event callback

layout

type SurfaceLayoutCallback

Arguments

 = Int32

width: the current width

-> Int32

height: the current height

-> IO ()

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 surfaceGetScaleFactor).

afterSurfaceLayout :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceLayoutCallback) -> m SignalHandlerId

Connect a signal handler for the layout signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after surface #layout callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSurfaceLayout :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceLayoutCallback) -> m SignalHandlerId

Connect a signal handler for the layout signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on surface #layout callback

leaveMonitor

type SurfaceLeaveMonitorCallback

Arguments

 = Monitor

monitor: the monitor

-> IO ()

Emitted when surface stops being present on the monitor.

afterSurfaceLeaveMonitor :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceLeaveMonitorCallback) -> m SignalHandlerId

Connect a signal handler for the leaveMonitor signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after surface #leaveMonitor callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSurfaceLeaveMonitor :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceLeaveMonitorCallback) -> m SignalHandlerId

Connect a signal handler for the leaveMonitor signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on surface #leaveMonitor callback

render

type SurfaceRenderCallback

Arguments

 = Region

region: the region that needs to be redrawn

-> IO Bool

Returns: True to indicate that the signal has been handled

Emitted when part of the surface needs to be redrawn.

afterSurfaceRender :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceRenderCallback) -> m SignalHandlerId

Connect a signal handler for the render signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after surface #render callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSurfaceRender :: (IsSurface a, MonadIO m) => a -> ((?self :: a) => SurfaceRenderCallback) -> m SignalHandlerId

Connect a signal handler for the render signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on surface #render callback