:right-sidebar: True

WaylandToplevel
===================================================================

.. currentmodule:: gi.repository.GdkWayland





.. class:: WaylandToplevel(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GdkWayland.WaylandSurface`, :class:`~gi.repository.Gdk.Surface`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gdk.Toplevel`



The Wayland implementation of ``GdkToplevel``\.

Beyond the :obj:`~gi.repository.Gdk.Toplevel` API, the Wayland implementation
has API to set up cross-process parent-child relationships between
surfaces with :obj:`~gi.repository.GdkWayland.WaylandToplevel.export_handle` and
:obj:`~gi.repository.GdkWayland.WaylandToplevel.set_transient_for_exported`\.




Methods
-------

.. rst-class:: interim-class

.. class:: WaylandToplevel
   :no-index:


   .. method:: drop_exported_handle(handle: str) -> None

      Destroy a handle that was obtained with :func:`~gi.repository.GdkWayland.WaylandToplevel.export_handle`.

      Note that this API depends on an unstable Wayland protocol,
      and thus may require changes in the future.


      .. versionadded:: 4.12





      :param handle: the handle to drop




   .. method:: export_handle(callback: ~typing.Callable[[~gi.repository.GdkWayland.WaylandToplevel, str, ~typing.Any], None], user_data: ~typing.Any = None) -> bool

      Asynchronously obtains a handle for a surface that can be passed
      to other processes.

      When the handle has been obtained, ``callback`` will be called.

      It is an error to call this function on a surface that is already
      exported.

      When the handle is no longer needed, :obj:`~gi.repository.GdkWayland.WaylandToplevel.unexport_handle`
      should be called to clean up resources.

      The main purpose for obtaining a handle is to mark a surface
      from another surface as transient for this one, see
      :obj:`~gi.repository.GdkWayland.WaylandToplevel.set_transient_for_exported`\.

      Before 4.12, this API could not safely be used multiple times,
      since there was no reference counting for handles. Starting with
      4.12, every call to this function obtains a new handle, and every
      call to :obj:`~gi.repository.GdkWayland.WaylandToplevel.drop_exported_handle` drops
      just the handle that it is given.

      Note that this API depends on an unstable Wayland protocol,
      and thus may require changes in the future.






      :param callback: callback to call with the handle

      :param user_data: user data for ``callback``




   .. method:: set_application_id(application_id: str) -> None

      Sets the application id on a ``GdkToplevel``\.






      :param application_id: the application id for the ``toplevel``




   .. method:: set_transient_for_exported(parent_handle_str: str) -> bool

      Marks ``toplevel`` as transient for the surface to which the given
      ``parent_handle_str`` refers.

      Typically, the handle will originate from a
      :obj:`~gi.repository.GdkWayland.WaylandToplevel.export_handle` call in another process.

      Note that this API depends on an unstable Wayland protocol,
      and thus may require changes in the future.






      :param parent_handle_str: an exported handle for a surface




   .. method:: unexport_handle() -> None

      Destroys the handle that was obtained with
      :func:`~gi.repository.GdkWayland.WaylandToplevel.export_handle`.

      It is an error to call this function on a surface that
      does not have a handle.

      Since 4.12, this function does nothing. Use
      :obj:`~gi.repository.GdkWayland.WaylandToplevel.drop_exported_handle` instead to drop a
      handle that was obtained with :obj:`~gi.repository.GdkWayland.WaylandToplevel.export_handle`\.

      Note that this API depends on an unstable Wayland protocol,
      and thus may require changes in the future.





      .. deprecated:: 4.12

         Use :obj:`~gi.repository.GdkWayland.WaylandToplevel.drop_exported_handle`
           instead, this function does nothing