Client Modules
**************

The base set of objects used by Wayland clients.  Users should only be
directly creating "Display" and "EventQueue" objects.  The "Proxy"
objects to interfaces should be returned by making request calls.


Display
=======

class pywayland.client.Display(name_or_fd: int | str | None = None)

   Represents a connection to the compositor

   A "Display" object represents a client connection to a Wayland
   compositor.  The connection and the corresponding Wayland object
   are created with "Display.connect()".  The display must be
   connected before it can be used.  A connection is terminated using
   "Display.disconnect()".

   A "Display" is also used as the "Proxy" for the
   "pywayland.protocol.wayland.WlDisplay" protocol object on the
   compositor side.

   A "Display" object handles all the data sent from and to the
   compositor.  When a "Proxy" marshals a request, it will write its
   wire representation to the display's write buffer. The data is sent
   to the compositor when the client calls "flush()".

   Incoming data is handled in two steps: queueing and dispatching. In
   the queue step, the data coming from the display fd is interpreted
   and added to a queue. On the dispatch step, the handler for the
   incoming event set by the client on the corresponding "Proxy" is
   called.

   A "Display" has at least one event queue, called the *default
   queue*.  Clients can create additional event queues with
   "Display.create_queue()" and assign "Proxy"'s to it. Events
   occurring in a particular proxy are always queued in its assigned
   queue.  A client can ensure that a certain assumption, such as
   holding a lock or running from a given thread, is true when a proxy
   event handler is called by assigning that proxy to an event queue
   and making sure that this queue is only dispatched when the
   assumption holds.

   The default queue is dispatched by calling "Display.dispatch()".
   This will dispatch any events queued on the default queue and
   attempt to read from the display fd if it's empty. Events read are
   then queued on the appropriate queues according to the proxy
   assignment.

   A user created queue is dispatched with "Display.dispatch_queue()".
   This function behaves exactly the same as "Display.dispatch()" but
   it dispatches given queue instead of the default queue.

   A real world example of event queue usage is Mesa's implementation
   of glSwapBuffers() for the Wayland platform. This function might
   need to block until a frame callback is received, but dispatching
   the default queue could cause an event handler on the client to
   start drawing gain.  This problem is solved using another event
   queue, so that only the events handled by the EGL code are
   dispatched during the block.

   Parameters:
      **name_or_fd** ("int" or "str") -- Either the name of the
      display to create or the file descriptor to connect the display
      to.  If not specified, then use the default name, generally
      "wayland-0"

   connect() -> None

      Connect to a Wayland display

      Connect to the Wayland display by name of fd.  An *int*
      parameter opens the connection using the file descriptor.  The
      "Display" takes ownership of the fd and will close it when the
      display is destroyed. The fd will also be closed in case of
      failure.  A string will open the display of the given name.  If
      name is "None", its value will be replaced with the
      "WAYLAND_DISPLAY" environment variable if it is set, otherwise
      display ""wayland-0"" will be used.

   disconnect() -> None

      Close a connection to a Wayland display

      Close the connection to display and free all resources
      associated with it.

   dispatch(*, block: bool = False, queue: EventQueue | None = None) -> int

      Process incoming events

      If block is *False*, it does not attempt to read the display fd
      or event queue and simply returns zero if the queue is empty.

      If the given queue is empty and *block* is *True*, this function
      blocks until there are events to be read from the display fd.
      Events are read and queued on the appropriate event queues.
      Finally, events on the default event queue are dispatched.

      Note:

        It is not possible to check if there are events on the queue
        or not.

   flush() -> int

      Send all buffered requests on the display to the server

      Send all buffered data on the client side to the server. Clients
      should call this function before blocking. On success, the
      number of bytes sent to the server is returned. On failure, this
      function returns -1 and errno is set appropriately.

      "Display.flush()" never blocks.  It will write as much data as
      possible, but if all data could not be written, errno will be
      set to EAGAIN and -1 returned.  In that case, use poll on the
      display file descriptor to wait for it to become writable again.

   get_fd() -> int

      Get a display context's file descriptor

      Return the file descriptor associated with a display so it can
      be integrated into the client's main loop.

   read(*, queue: EventQueue | None = None) -> None

      Read events from display file descriptor

      Calling this function will result in data available on the
      display file descriptor being read and read events will be
      queued on their corresponding event queues.

      Parameters:
         **queue** -- If specified, queue the events onto the given
         event queue, otherwise the default display queue will be
         used.

   roundtrip(*, queue: EventQueue | None = None) -> int

      Block until all pending request are processed by the server

      This function blocks until the server has processed all
      currently issued requests by sending a request to the display
      server and waiting for a reply before returning.

      This function uses wl_display_dispatch_queue() internally. It is
      not allowed to call this function while the thread is being
      prepared for reading events, and doing so will cause a dead
      lock.

      Note:

        This function may dispatch other events being received on the
        default queue.

      Parameters:
         **queue** ("EventQueue") -- The queue on which to run the
         roundtrip, if not given, uses the default queue.

      Returns:
         The number of dispatched events on success or -1 on failure


EventQueue
==========

class pywayland.client.EventQueue(display: Display)

   A queue for wl_proxy object events.

   Event queues allows the events on a display to be handled in a
   thread-safe manner. See "Display" for details.

   Parameters:
      **display** ("Display") -- The display object that the event
      queue is connected to.

   destroy() -> None

      Destroy an event queue

      Destroy the given event queue. Any pending event on that queue
      is discarded.

      The wl_display object used to create the queue should not be
      destroyed until all event queues created with it are destroyed
      with this function.

   property destroyed: bool

      Determine the state of the event queue
