Description

Gnome::Gdk4::Display objects are the GDK representation of a workstation.

Their purpose are two-fold:

• To manage and provide information about input devices (pointers, keyboards, etc)

• To manage and provide information about output devices (monitors, projectors, etc)

Most of the input device handling has been factored out into separate Gnome::Gdk4::Seat objects. Every display has a one or more seats, which can be accessed with .get-default-seat() and .list-seats().

Output devices are represented by Gnome::Gdk4::Monitor objects, which can be accessed with .get-monitor-at-surface() and similar APIs.

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

Methods

beep

Emits a short beep on $display

method beep ( )

close

Closes the connection to the windowing system for the given display.

This cleans up associated resources.

method close ( )

create-gl-context

Creates a new Gnome::Gdk4::GLContext for the Gnome::Gdk4::Display.

The context is disconnected from any particular surface or surface and cannot be used to draw to any surface. It can only be used to draw to non-surface framebuffers like textures.

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 Pointer when you want to ignore the error. .

Return value; the newly created Gnome::Gdk4::GLContext.

device-is-grabbed

Returns True if there is an ongoing grab on $device for $display.

method device-is-grabbed ( N-Object() $device --> Bool )

• $device; a Gnome::Gdk4::Device.

Return value; True if there is a grab in effect for $device..

flush

Flushes any requests queued for the windowing system.

This happens automatically when the main loop blocks waiting for new events, but if your application is drawing without returning control to the main loop, you may need to call this function explicitly. A common case where this function needs to be called is when an application is executing drawing commands from a thread other than the thread where the main loop is running.

This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing.

method flush ( )

get-app-launch-context

Returns a Gnome::Gdk4::AppLaunchContext suitable for launching applications on the given display.

method get-app-launch-context (--> N-Object )

Return value; a new Gnome::Gdk4::AppLaunchContext for $display.

get-clipboard

Gets the clipboard used for copy/paste operations.

method get-clipboard (--> N-Object )

Return value; the display's clipboard.

get-default-seat

Returns the default Gnome::Gdk4::Seat for this display.

Note that a display may not have a seat. In this case, this function will return undefined.

method get-default-seat (--> N-Object )

Return value; the default seat..

get-monitor-at-surface

Gets the monitor in which the largest area of $surface resides.

Returns a monitor close to $surface if it is outside of all monitors.

method get-monitor-at-surface ( N-Object() $surface --> N-Object )

• $surface; a Gnome::Gdk4::Surface.

Return value; the monitor with the largest overlap with $surface.

get-monitors

Gets the list of monitors associated with this display.

Subsequent calls to this function will always return the same list for the same display.

You can listen to the GListModel::items-changed signal on this list to monitor changes to the monitor of this display.

method get-monitors (--> N-List )

Return value; a Gnome::Gio::R-ListModel of Gnome::Gdk4::Monitor.

get-name

Gets the name of the display.

method get-name (--> Str )

Return value; a string representing the display name. This string is owned by GDK and should not be modified or freed..

get-primary-clipboard

Gets the clipboard used for the primary selection.

On backends where the primary clipboard is not supported natively, GDK emulates this clipboard locally.

method get-primary-clipboard (--> N-Object )

Return value; the primary clipboard.

get-setting

Retrieves a desktop-wide setting such as double-click time for the $display.

method get-setting ( Str $name, N-Object $value --> Bool )

• $name; the name of the setting.

• $value; location to store the value of the setting

Return value; True if the setting existed and a value was stored in $value, False otherwise.

get-startup-notification-id

Gets the startup notification ID for a Wayland display, or undefined if no ID has been defined.

method get-startup-notification-id (--> Str )

Return value; the startup notification ID for $display.

is-closed

Finds out if the display has been closed.

method is-closed (--> Bool )

Return value; True if the display is closed..

is-composited

Returns whether surfaces can reasonably be expected to have their alpha channel drawn correctly on the screen.

Check .is-rgba() for whether the display supports an alpha channel.

On X11 this function returns whether a compositing manager is compositing on $display.

On modern displays, this value is always True.

method is-composited (--> Bool )

Return value; Whether surfaces with RGBA visuals can reasonably be expected to have their alpha channels drawn correctly on the screen..

is-rgba

Returns whether surfaces on this $display are created with an alpha channel.

Even if a True is returned, it is possible that the surface’s alpha channel won’t be honored when displaying the surface on the screen: in particular, for X an appropriate windowing manager and compositing manager must be running to provide appropriate display. Use .is-composited() to check if that is the case.

On modern displays, this value is always True.

method is-rgba (--> Bool )

Return value; True if surfaces are created with an alpha channel or False if the display does not support this functionality..

list-seats

Returns the list of seats known to $display.

method list-seats (--> N-List )

Return value; the list of seats known to the Gnome::Gdk4::Display.

map-keycode

Returns the keyvals bound to $keycode.

The Nth Gnome::Gdk4::N-KeymapKey in $keys is bound to the Nth keyval in $keyvals.

When a keycode is pressed by the user, the keyval from this list of entries is selected by considering the effective keyboard group and level.

Free the returned arrays with g_free().

method map-keycode ( UInt() $keycode, N-Object $keys, Array[Int] $keyvals, Array[Int] $n-entries --> Bool )

• $keycode; a keycode.

• $keys; (transfer ownership: full) return location for array of Gnome::Gdk4::N-KeymapKey

• $keyvals; (transfer ownership: full) return location for array of keyvals.

• $n-entries; (transfer ownership: full) length of $keys and $keyvals.

Return value; True if there were any entries.

map-keyval

Obtains a list of keycode/group/level combinations that will generate $keyval.

Groups and levels are two kinds of keyboard mode; in general, the level determines whether the top or bottom symbol on a key is used, and the group determines whether the left or right symbol is used.

On US keyboards, the shift key changes the keyboard level, and there are no groups. A group switch key might convert a keyboard between Hebrew to English modes, for example.

GdkEventKey contains a %group field that indicates the active keyboard group. The level is computed from the modifier mask.

The returned array should be freed with g_free().

method map-keyval ( UInt() $keyval, N-Object $keys, Array[Int] $n-keys --> Bool )

• $keyval; a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc..

• $keys; (transfer ownership: full) return location for an array of Gnome::Gdk4::N-KeymapKey

• $n-keys; (transfer ownership: full) return location for number of elements in returned array.

Return value; True if keys were found and returned.

notify-startup-complete

Indicates to the GUI environment that the application has finished loading, using a given identifier.

GTK will call this function automatically for Gnome::Gtk4::Window with custom startup-notification identifier unless .set-auto-startup-notification() in class Gnome is called to disable that feature.

method notify-startup-complete ( Str $startup-id )

• $startup-id; a startup-notification identifier, for which notification process should be completed.

prepare-gl

Checks that OpenGL is available for $self and ensures that it is properly initialized. When this fails, an $error will be set describing the error and this function returns False.

Note that even if this function succeeds, creating a Gnome::Gdk4::GLContext may still fail.

This function is idempotent. Calling it multiple times will just return the same value or error.

You never need to call this function, GDK will call it automatically as needed. But you can use it as a check when setting up code that might make use of OpenGL.

method prepare-gl ( CArray[N-Error] $err --> Bool )

• $err; Error object. When defined, an error can be returned when there is one. Use Pointer when you want to ignore the error. .

Return value; True if the display supports OpenGL.

put-event

Appends the given event onto the front of the event queue for $display.

This function is only useful in very special situations and should not be used by applications.

method put-event ( N-Object() $event )

• $event; a Gnome::Gdk4::Event.

supports-input-shapes

Returns True if the display supports input shapes.

This means that .set-input-region() in class Gnome can be used to modify the input shape of surfaces on $display.

On modern displays, this value is always True.

method supports-input-shapes (--> Bool )

Return value; True if surfaces with modified input shape are supported.

sync

Flushes any requests queued for the windowing system and waits until all requests have been handled.

This is often used for making sure that the display is synchronized with the current state of the program. Calling .sync() before .error-trap-pop() in class Gnome makes sure that any errors generated from earlier requests are handled before the error trap is removed.

This is most useful for X11. On windowing systems where requests are handled synchronously, this function will do nothing.

method sync ( )

translate-key

Translates the contents of a GdkEventKey into a keyval, effective group, and level.

Modifiers that affected the translation and are thus unavailable for application use are returned in $consumed-modifiers.

The $effective-group is the group that was actually used for the translation; some keys such as Enter are not affected by the active keyboard group. The $level is derived from $state. $consumed-modifiers gives modifiers that should be masked out from $state when comparing this key press to a keyboard shortcut. For instance, on a US keyboard, the plus symbol is shifted, so when comparing a key press to a `<Control>plus` accelerator `<Shift>` should be masked out.

This function should rarely be needed, since GdkEventKey already contains the translated keyval. It is exported for the benefit of virtualized test environments.

method translate-key ( UInt() $keycode, UInt $state, Int() $group, Array[Int] $keyval, Array[Int] $effective-group, Array[Int] $level, UInt $consumed --> Bool )

• $keycode; a keycode.

• $state; a modifier state.

• $group; active keyboard group.

• $keyval; (transfer ownership: full) return location for keyval.

• $effective-group; (transfer ownership: full) return location for effective group.

• $level; (transfer ownership: full) return location for level.

• $consumed; (transfer ownership: full) return location for modifiers that were used to determine the group or level.

Return value; True if there was a keyval bound to keycode/state/group..

Functions

get-default

Gets the default Gnome::Gdk4::Display.

This is a convenience function for:

gdk_display_manager_get_default_display (gdk_display_manager_get ())

method get-default (--> N-Object )

Return value; a Gnome::Gdk4::Display, or undefined if there is no default display.

open

Opens a display.

If opening the display fails, undefined is returned.

method open ( Str $display-name --> N-Object )

• $display-name; the name of the display to open.

Return value; a Gnome::Gdk4::Display.

Signals

closed

Emitted when the connection to the windowing system for $display is closed.

method handler (
  gboolean $is-error,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gdk4::Display :$_widget,
  *%user-options
)

• $is-error; True if the display was closed due to an error.

• $_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::Display object.

• %user-options; A list of named arguments provided by .register-signal() in class Gnome.

opened

Emitted when the connection to the windowing system for $display is opened.

method handler (
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gdk4::Display :$_widget,
  *%user-options
)

• $_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::Display object.

• %user-options; A list of named arguments provided by .register-signal() in class Gnome.

seat-added

Emitted whenever a new seat is made known to the windowing system.

method handler (
  N-Object $seat,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gdk4::Display :$_widget,
  *%user-options
)

• $seat; the seat that was just added.

• $_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::Display object.

• %user-options; A list of named arguments provided by .register-signal() in class Gnome.

seat-removed

Emitted whenever a seat is removed by the windowing system.

method handler (
  N-Object $seat,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gdk4::Display :$_widget,
  *%user-options
)

• $seat; the seat that was just removed.

• $_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::Display object.

• %user-options; A list of named arguments provided by .register-signal() in class Gnome.

setting-changed

Emitted whenever a setting changes its value.

method handler (
  Str $setting,
  Int :$_handle_id,
  N-GObject :$_native-object,
  Gnome::Gdk4::Display :$_widget,
  *%user-options
)

• $setting; the name of the setting that changed.

• $_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::Display object.

• %user-options; A list of named arguments provided by .register-signal() in class Gnome.