class Gdk::Surface

Overview

A Gdk::Surface 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 Gdk::Toplevel or Gdk::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.

Defined in:

lib/gi-crystal/src/auto/gdk-4.0/surface.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class GObject::Object

==(other : self) ==, bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void) | Nil data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, hash(hasher) hash, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void) | Nil qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void) | Nil) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void) | Nil steal_data, steal_qdata(quark : UInt32) : Pointer(Void) | Nil steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new
new
, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

cast?(obj : GObject::Object) : self | Nil cast?, compat_control(what : UInt64, data : Pointer(Void) | Nil) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Constructor Detail

def self.new #

Initialize a new Surface.


[View source]
def self.new(*, cursor : Gdk::Cursor | Nil = nil, display : Gdk::Display | Nil = nil, frame_clock : Gdk::FrameClock | Nil = nil, height : Int32 | Nil = nil, mapped : Bool | Nil = nil, scale_factor : Int32 | Nil = nil, width : Int32 | Nil = nil) #

[View source]
def self.new_popup(parent : Gdk::Surface, autohide : Bool) : self #

Create a new popup surface.

The surface will be attached to parent and can be positioned relative to it using Gdk::Popup#present.


[View source]
def self.new_toplevel(display : Gdk::Display) : self #

Creates a new toplevel surface.


[View source]

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


[View source]

Instance Method Detail

def ==(other : self) #
Description copied from class Reference

Returns true if this reference is the same as other. Invokes same?.


def beep : Nil #

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 Gdk::Display#beep.


[View source]
def create_cairo_context : Gdk::CairoContext #

Creates a new Gdk::CairoContext for rendering on surface.


[View source]
def create_gl_context : Gdk::GLContext #

Creates a new Gdk::GLContext for the Gdk::Surface.

The context is disconnected from any particular surface or surface. If the creation of the Gdk::GLContext failed, error will be set. Before using the returned Gdk::GLContext, you will need to call Gdk::GLContext#make_current or Gdk::GLContext#realize.


[View source]
def create_similar_surface(content : Cairo::Content, width : Int32, height : Int32) : Cairo::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.


[View source]
def create_vulkan_context : Gdk::VulkanContext #

Creates a new Gdk::VulkanContext for rendering on surface.

If the creation of the Gdk::VulkanContext failed, error will be set.


[View source]
def cursor : Gdk::Cursor | Nil #

Retrieves a Gdk::Cursor pointer for the cursor currently set on the Gdk::Surface.

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

Use Gdk::Surface#cursor= to unset the cursor of the surface.


[View source]
def cursor=(cursor : Gdk::Cursor | Nil) : Nil #

Sets the default mouse pointer for a Gdk::Surface.

Passing nil 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 Gdk::Cursor#new_from_name or Gdk::Cursor#new_from_texture to create the cursor. To make the cursor invisible, use %GDK_BLANK_CURSOR.


[View source]
def destroy : Nil #

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.


[View source]
def device_cursor(device : Gdk::Device) : Gdk::Cursor | Nil #

Retrieves a Gdk::Cursor pointer for the device currently set on the specified Gdk::Surface.

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

Use Gdk::Surface#cursor= to unset the cursor of the surface.


[View source]
def device_position(device : Gdk::Device) : Bool #

Obtains the current device position and modifier state.

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


[View source]
def display : Gdk::Display #

Gets the Gdk::Display associated with a Gdk::Surface.


[View source]
def display=(value : Gdk::Display | Nil) : Gdk::Display | Nil #

[View source]
def enter_monitor_signal #

[View source]
def event_signal #

[View source]
def frame_clock : Gdk::FrameClock #

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.


[View source]
def frame_clock=(value : Gdk::FrameClock | Nil) : Gdk::FrameClock | Nil #

[View source]
def hash(hasher) #
Description copied from class Reference

See Object#hash(hasher)


def height : Int32 #

Returns the height of the given surface.

Surface size is reported in ”application pixels”, not ”device pixels” (see Gdk::Surface#scale_factor).


[View source]
def hide : Nil #

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.


[View source]
def input_region=(region : Cairo::Region) : Nil #

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 Gdk::Display#supports_input_shapes to find out if a particular backend supports input regions.


[View source]
def is_destroyed : Bool #

Check to see if a surface is destroyed.


[View source]
def layout_signal #

[View source]
def leave_monitor_signal #

[View source]
def mapped : Bool #

Checks whether the surface has been mapped.

A surface is mapped with Gdk::Toplevel#present or Gdk::Popup#present.


[View source]
def mapped? : Bool #

[View source]
def opaque_region=(region : Cairo::Region | Nil) : Nil #

Marks a region of the Gdk::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 Gtk::Widget#css_changed handler.


[View source]
def queue_render : Nil #

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

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


[View source]
def render_signal #

[View source]
def request_layout : Nil #

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

See Gdk::FrameClock#request_phase.


[View source]
def scale_factor : Int32 #

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.


[View source]
def set_device_cursor(device : Gdk::Device, cursor : Gdk::Cursor) : Nil #

Sets a specific Gdk::Cursor for a given device when it gets inside surface.

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

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.


[View source]
def translate_coordinates(to : Gdk::Surface, x : Float64, y : Float64) : Bool #

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


[View source]
def width : Int32 #

Returns the width of the given surface.

Surface size is reported in ”application pixels”, not ”device pixels” (see Gdk::Surface#scale_factor).


[View source]