Gnome::Gdk4::Surface
#------------------------------------------------------------------------------- #--[Class Description]---------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
Description
A Gnome::Gdk4::Surface is a rectangular region on the screen.
It’s a low-level object, used to implement high-level objects such as Gnome::Gtk4::Window or Gnome::Gtk4::Dialog in GTK.
The surfaces you see in practice are either Gnome::Gdk4::R-Toplevel or Gnome::Gdk4::R-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.
=end rakudoc
#------------------------------------------------------------------------------- #--[Class Initialization]------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
Class initialization
new
:native-object
Create an object using a native object from an object of the same type found elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object() :$native-object! )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
new-popup
Create a new popup surface.
The surface will be attached to $parent and can be positioned
relative to it using .present() in class Gnome-Popup.
method new-popup ( N-Object() $parent, Bool() $autohide --> Gnome::Gdk4::Surface )
$parent; the parent surface to attach the surface to.
$autohide; whether to hide the surface on outside clicks.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
new-toplevel
Creates a new toplevel surface.
method new-toplevel ( N-Object() $display --> Gnome::Gdk4::Surface )
$display; the display to create the surface on.
=end rakudoc
#------------------------------------------------------------------------------- #--[Methods]-------------------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
Methods =end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
beep
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 .beep() in class Gnome.
method beep ( )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
create-cairo-context
Creates a new Gnome::Gdk4::CairoContext for rendering on $surface.
method create-cairo-context (--> N-Object )
Return value; the newly created Gnome::Gdk4::CairoContext.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
create-gl-context
Creates a new Gnome::Gdk4::GLContext for the Gnome::Gdk4::Surface.
The context is disconnected from any particular surface or surface.
If the creation of the Gnome::Gdk4::GLContext failed, $error will be set.
Before using the returned Gnome::Gdk4::GLContext, you will need to
call .make-current() in class Gnome or .realize() in class Gnome.
method create-gl-context ( CArray[N-Error] $err --> N-Object )
$err; Error object. When defined, an error can be returned when there is one. Use
Pointerwhen you want to ignore the error. .
Return value; the newly created Gnome::Gdk4::GLContext.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
create-similar-surface
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.
method create-similar-surface ( Content $content, Int() $width, Int() $height --> Cairo::cairo_surface_t )
$content; the content for the new surface.
$width; width of the new surface.
$height; height of the new surface.
Return value; a pointer to the newly allocated surface. The caller owns the surface and should call cairo_surface_destroy() when done with it..
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
create-vulkan-context
Creates a new Gnome::Gdk4::VulkanContext for rendering on $surface.
If the creation of the Gnome::Gdk4::VulkanContext failed, $error will be set.
method create-vulkan-context ( CArray[N-Error] $err --> N-Object )
$err; Error object. When defined, an error can be returned when there is one. Use
Pointerwhen you want to ignore the error. .
Return value; the newly created Gnome::Gdk4::VulkanContext, or undefined on error.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
destroy
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.
method destroy ( )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-cursor
Retrieves a Gnome::Gdk4::Cursor pointer for the cursor currently set on the Gnome::Gdk4::Surface.
If the return value is undefined then there is no custom cursor set on the surface, and it is using the cursor for its parent surface.
Use .set-cursor() to unset the cursor of the surface.
method get-cursor (--> N-Object )
Return value; a Gnome::Gdk4::Cursor.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-device-cursor
Retrieves a Gnome::Gdk4::Cursor pointer for the $device currently set on the
specified Gnome::Gdk4::Surface.
If the return value is undefined then there is no custom cursor set on the specified surface, and it is using the cursor for its parent surface.
Use .set-cursor() to unset the cursor of the surface.
method get-device-cursor ( N-Object() $device --> N-Object )
$device; a pointer Gnome::Gdk4::Device.
Return value; a Gnome::Gdk4::Cursor.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-device-position
Obtains the current device position and modifier state.
The position is given in coordinates relative to the upper
left corner of $surface.
method get-device-position ( N-Object() $device, Num() $x, Num() $y, UInt $mask --> Bool )
$device; pointer Gnome::Gdk4::Device to query to.
$x; (transfer ownership: full) return location for the X coordinate of
$device.$y; (transfer ownership: full) return location for the Y coordinate of
$device.$mask; (transfer ownership: full) return location for the modifier mask.
Return value; True if the device is over the surface.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-display
Gets the Gnome::Gdk4::Display associated with a Gnome::Gdk4::Surface.
method get-display (--> N-Object )
Return value; the Gnome::Gdk4::Display associated with $surface.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-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.
method get-frame-clock (--> N-Object )
Return value; the frame clock.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-height
Returns the height of the given $surface.
Surface size is reported in ”application pixels”, not ”device pixels” (see .get-scale-factor()).
method get-height (--> Int )
Return value; The height of $surface.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-mapped
Checks whether the surface has been mapped.
A surface is mapped with .present() in class Gnome-Toplevel or .present() in class Gnome-Popup.
method get-mapped (--> Bool )
Return value; True if the surface is mapped.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-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.
method get-scale-factor (--> Int )
Return value; the scale factor.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
get-width
Returns the width of the given $surface.
Surface size is reported in ”application pixels”, not ”device pixels” (see .get-scale-factor()).
method get-width (--> Int )
Return value; The width of $surface.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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 .hide() in class Gnome.
method hide ( )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
is-destroyed
Check to see if a surface is destroyed.
method is-destroyed (--> Bool )
Return value; True if the surface is destroyed.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
queue-render
Forces a render signal emission for $surface
to be scheduled.
This function is useful for implementations that track invalid regions on their own.
method queue-render ( )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
request-layout
Request a layout phase from the surface's frame clock.
See .request-phase() in class Gnome.
method request-layout ( )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
set-cursor
Sets the default mouse pointer for a Gnome::Gdk4::Surface.
Passing undefined 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 .new-from-name() in class Gnome or .new-from-texture() in class Gnome
to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR.
method set-cursor ( N-Object() $cursor )
$cursor; a Gnome::Gdk4::Cursor.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
set-device-cursor
Sets a specific Gnome::Gdk4::Cursor for a given device when it gets inside $surface.
Passing undefined for the $cursor argument means that $surface will use the
cursor of its parent surface. Most surfaces should use this default.
Use .new-from-name() in class Gnome or .new-from-texture() in class Gnome
to create the cursor. To make the cursor invisible, use GDK_BLANK_CURSOR.
method set-device-cursor ( N-Object() $device, N-Object() $cursor )
$device; a pointer Gnome::Gdk4::Device.
$cursor; a Gnome::Gdk4::Cursor.
=end rakudoc
#`{{ Cairo::cairo_region_t not supported/found in Timo's Cairo #------------------------------------------------------------------------------- =begin rakudoc
set-input-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 .supports-input-shapes() in class Gnome to find out if a particular backend supports input regions.
method set-input-region (airo::cairo_region_t )
$region; region of surface to be reactive.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
set-opaque-region
Marks a region of the Gnome::Gdk4::Surface 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
[vfunc $Gtk.Widget.css_changed] handler.
method set-opaque-region (airo::cairo_region_t )
$region; a region, or undefined to make the entire surface opaque.
=end rakudoc }}
#------------------------------------------------------------------------------- =begin rakudoc
translate-coordinates
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).
method translate-coordinates ( N-Object() $to, Num() $x, Num() $y --> Bool )
$to; the target surface.
$x; (transfer ownership: full) coordinates to translate.
$y; (transfer ownership: full) coordinates to translate.
Return value; True if the coordinates were successfully translated.
=end rakudoc
#------------------------------------------------------------------------------- #--[Signal Documentation]------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
Signals
enter-monitor
Emitted when $surface starts being present on the monitor.
method handler (
N-Object $monitor,
Int :$_handle_id,
N-Object :$_native-object,
*%user-options
)
$monitor; the monitor.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This is a native Gnome::Gdk4::Surface object.
%user-options; A list of named arguments provided by .register-signal() in class Gnome.
event
Emitted when GDK receives an input event for $surface.
method handler (
gpointer $event,
Int :$_handle_id,
N-Object :$_native-object,
*%user-options
--> gboolean
)
$event; an input event.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This is a native Gnome::Gdk4::Surface object.
%user-options; A list of named arguments provided by .register-signal() in class Gnome.
Return value; True to indicate that the event has been handled
layout
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 .get-scale-factor()).
method handler (
gint $width,
gint $height,
Int :$_handle_id,
N-Object :$_native-object,
*%user-options
)
$width; the current width.
$height; the current height.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This is a native Gnome::Gdk4::Surface object.
%user-options; A list of named arguments provided by .register-signal() in class Gnome.
leave-monitor
Emitted when $surface stops being present on the monitor.
method handler (
N-Object $monitor,
Int :$_handle_id,
N-Object :$_native-object,
*%user-options
)
$monitor; the monitor.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This is a native Gnome::Gdk4::Surface object.
%user-options; A list of named arguments provided by .register-signal() in class Gnome.
render
Emitted when part of the surface needs to be redrawn.
method handler (
$region,
Int :$_handle_id,
N-Object :$_native-object,
*%user-options
--> gboolean
)
$region; the region that needs to be redrawn.
$_handle_id; The registered event handler id.
$_native-object; The native object provided by the Raku object which registered this event. This is a native Gnome::Gdk4::Surface object.
%user-options; A list of named arguments provided by .register-signal() in class Gnome.
Return value; True to indicate that the signal has been handled
=end rakudoc