wayland Module
**************


WlBuffer
========

class pywayland.protocol.wayland.WlBuffer

   Content for a "WlSurface"

   A buffer provides the content for a "WlSurface". Buffers are
   created through factory interfaces such as "WlShm",
   wp_linux_buffer_params (from the linux-dmabuf protocol extension)
   or similar. It has a width and a height and can be attached to a
   "WlSurface", but the mechanism by which a client provides and
   updates the contents is defined by the buffer factory interface.

   Color channels are assumed to be electrical rather than optical (in
   other words, encoded with a transfer function) unless otherwise
   specified. If the buffer uses a format that has an alpha channel,
   the alpha channel is assumed to be premultiplied into the
   electrical color channel values (after transfer function encoding)
   unless otherwise specified.

   Note, because "WlBuffer" objects are created from multiple
   independent factory interfaces, the "WlBuffer" interface is frozen
   at version 1.

   destroy() -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Destroy a buffer

      Destroy a buffer. If and how you need to release the backing
      storage is defined by the buffer factory interface.

      For possible side-effects to a surface, see
      "WlSurface.attach()".

   release() -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Compositor releases buffer

      Sent when this "WlBuffer" is no longer used by the compositor.
      The client is now free to reuse or destroy this buffer and its
      backing storage.

      If a client receives a release event before the frame callback
      requested in the same "WlSurface.commit()" that attaches this
      "WlBuffer" to a surface, then the client is immediately free to
      reuse the buffer and its backing storage, and does not need a
      second buffer for the next surface content update. Typically
      this is possible, when the compositor maintains a copy of the
      "WlSurface" contents, e.g. as a GL texture. This is an important
      optimization for GL(ES) compositors with "WlShm" clients.


WlCallback
==========

class pywayland.protocol.wayland.WlCallback

   Callback object

   Clients can handle the 'done' event to get notified when the
   related request is done.

   Note, because "WlCallback" objects are created from multiple
   independent factory interfaces, the "WlCallback" interface is
   frozen at version 1.

   done(callback_data: 'int') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Done event

      Notify the client when the related request is done.

      Parameters:
         **callback_data** (*ArgumentType.Uint*) -- request-specific
         data for the callback


WlCompositor
============

class pywayland.protocol.wayland.WlCompositor

   The compositor singleton

   A compositor.  This object is a singleton global.  The compositor
   is in charge of combining the contents of multiple surfaces into
   one displayable output.

   create_surface() -> 'Proxy[WlSurface]'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Create new surface

      Ask the compositor to create a new surface.

      Returns:
         "WlSurface" -- the new surface

   create_region() -> 'Proxy[WlRegion]'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Create new region

      Ask the compositor to create a new region.

      Returns:
         "WlRegion" -- the new region


WlDataDevice
============

class pywayland.protocol.wayland.WlDataDevice

   Data transfer device

   There is one "WlDataDevice" per seat which can be obtained from the
   global "WlDataDeviceManager" singleton.

   A "WlDataDevice" provides access to inter-client data transfer
   mechanisms such as copy-and-paste and drag-and-drop.

   start_drag(source: 'WlDataSource | None', origin: 'WlSurface', icon: 'WlSurface | None', serial: 'int') -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Start drag-and-drop operation

      This request asks the compositor to start a drag-and-drop
      operation on behalf of the client.

      The source argument is the data source that provides the data
      for the eventual data transfer. If source is NULL, enter, leave
      and motion events are sent only to the client that initiated the
      drag and the client is expected to handle the data passing
      internally. If source is destroyed, the drag-and-drop session
      will be cancelled.

      The origin surface is the surface where the drag originates and
      the client must have an active implicit grab that matches the
      serial.

      The icon surface is an optional (can be NULL) surface that
      provides an icon to be moved around with the cursor.  Initially,
      the top-left corner of the icon surface is placed at the cursor
      hotspot, but subsequent "WlSurface.offset()" requests can move
      the relative position. Attach requests must be confirmed with
      "WlSurface.commit()" as usual. The icon surface is given the
      role of a drag-and-drop icon. If the icon surface already has
      another role, it raises a protocol error.

      The input region is ignored for wl_surfaces with the role of a
      drag- and-drop icon.

      The given source may not be used in any further set_selection or
      start_drag requests. Attempting to reuse a previously-used
      source may send a used_source error.

      Parameters:
         * **source** ("WlDataSource" or *None*) -- data source for
           the eventual transfer

         * **origin** ("WlSurface") -- surface where the drag
           originates

         * **icon** ("WlSurface" or *None*) -- drag-and-drop icon
           surface

         * **serial** (*ArgumentType.Uint*) -- serial number of the
           implicit grab on the origin

   set_selection(source: 'WlDataSource | None', serial: 'int') -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Copy data to the selection

      This request asks the compositor to set the selection to the
      data from the source on behalf of the client.

      To unset the selection, set the source to NULL.

      The given source may not be used in any further set_selection or
      start_drag requests. Attempting to reuse a previously-used
      source may send a used_source error.

      Parameters:
         * **source** ("WlDataSource" or *None*) -- data source for
           the selection

         * **serial** (*ArgumentType.Uint*) -- serial number of the
           event that triggered this request

   release() -> 'None'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Destroy data device

      This request destroys the data device.

   data_offer(id: 'WlDataOffer') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Introduce a new "WlDataOffer"

      The data_offer event introduces a new "WlDataOffer" object,
      which will subsequently be used in either the data_device.enter
      event (for drag- and-drop) or the data_device.selection event
      (for selections). Immediately following the
      data_device.data_offer event, the new data_offer object will
      send out data_offer.offer events to describe the mime types it
      offers.

      Parameters:
         **id** ("WlDataOffer") -- the new data_offer object

   enter(serial: 'int', surface: 'WlSurface', x: 'float', y: 'float', id: 'WlDataOffer | None') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Initiate drag-and-drop session

      This event is sent when an active drag-and-drop pointer enters a
      surface owned by the client.  The position of the pointer at
      enter time is provided by the x and y arguments, in surface-
      local coordinates.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           enter event

         * **surface** ("WlSurface") -- client surface entered

         * **x** (*ArgumentType.Fixed*) -- surface-local x coordinate

         * **y** (*ArgumentType.Fixed*) -- surface-local y coordinate

         * **id** ("WlDataOffer" or *None*) -- source data_offer
           object

   leave() -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      End drag-and-drop session

      This event is sent when the drag-and-drop pointer leaves the
      surface and the session ends.  The client must destroy the
      "WlDataOffer" introduced at enter time at this point.

   motion(time: 'int', x: 'float', y: 'float') -> 'None'

      -[ Event -- opcode 3 (attached to "Proxy" instance) ]-

      Drag-and-drop session motion

      This event is sent when the drag-and-drop pointer moves within
      the currently focused surface. The new position of the pointer
      is provided by the x and y arguments, in surface-local
      coordinates.

      Parameters:
         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **x** (*ArgumentType.Fixed*) -- surface-local x coordinate

         * **y** (*ArgumentType.Fixed*) -- surface-local y coordinate

   drop() -> 'None'

      -[ Event -- opcode 4 (attached to "Proxy" instance) ]-

      End drag-and-drop session successfully

      The event is sent when a drag-and-drop operation is ended
      because the implicit grab is removed.

      The drag-and-drop destination is expected to honor the last
      action received through "WlDataOffer.action()", if the resulting
      action is "copy" or "move", the destination can still perform
      "WlDataOffer.receive()" requests, and is expected to end all
      transfers with a "WlDataOffer.finish()" request.

      If the resulting action is "ask", the action will not be
      considered final. The drag-and-drop destination is expected to
      perform one last "WlDataOffer.set_actions()" request, or
      "WlDataOffer.destroy()" in order to cancel the operation.

   selection(id: 'WlDataOffer | None') -> 'None'

      -[ Event -- opcode 5 (attached to "Proxy" instance) ]-

      Advertise new selection

      The selection event is sent out to notify the client of a new
      "WlDataOffer" for the selection for this device.  The
      data_device.data_offer and the data_offer.offer events are sent
      out immediately before this event to introduce the data offer
      object.  The selection event is sent to a client immediately
      before receiving keyboard focus and when a new selection is set
      while the client has keyboard focus.  The data_offer is valid
      until a new data_offer or NULL is received or until the client
      loses keyboard focus.  Switching surface with keyboard focus
      within the same client doesn't mean a new selection will be
      sent.  The client must destroy the previous selection
      data_offer, if any, upon receiving this event.

      Parameters:
         **id** ("WlDataOffer" or *None*) -- selection data_offer
         object


WlDataDeviceManager
===================

class pywayland.protocol.wayland.WlDataDeviceManager

   Data transfer interface

   The "WlDataDeviceManager" is a singleton global object that
   provides access to inter-client data transfer mechanisms such as
   copy-and-paste and drag-and-drop.  These mechanisms are tied to a
   "WlSeat" and this interface lets a client get a "WlDataDevice"
   corresponding to a "WlSeat".

   Depending on the version bound, the objects created from the bound
   "WlDataDeviceManager" object will have different requirements for
   functioning properly. See "WlDataSource.set_actions()",
   "WlDataOffer.accept()" and "WlDataOffer.finish()" for details.

   create_data_source() -> 'Proxy[WlDataSource]'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Create a new data source

      Create a new data source.

      Returns:
         "WlDataSource" -- data source to create

   get_data_device(seat: 'WlSeat') -> 'Proxy[WlDataDevice]'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Create a new data device

      Create a new data device for a given seat.

      Parameters:
         **seat** ("WlSeat") -- seat associated with the data device

      Returns:
         "WlDataDevice" -- data device to create


WlDataOffer
===========

class pywayland.protocol.wayland.WlDataOffer

   Offer to transfer data

   A "WlDataOffer" represents a piece of data offered for transfer by
   another client (the source client).  It is used by the copy-and-
   paste and drag-and-drop mechanisms.  The offer describes the
   different mime types that the data can be converted to and provides
   the mechanism for transferring the data directly from the source
   client.

   accept(serial: 'int', mime_type: 'str | None') -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Accept one of the offered mime types

      Indicate that the client can accept the given mime type, or NULL
      for not accepted.

      For objects of version 2 or older, this request is used by the
      client to give feedback whether the client can receive the given
      mime type, or NULL if none is accepted; the feedback does not
      determine whether the drag-and-drop operation succeeds or not.

      For objects of version 3 or newer, this request determines the
      final result of the drag-and-drop operation. If the end result
      is that no mime types were accepted, the drag-and-drop operation
      will be cancelled and the corresponding drag source will receive
      "WlDataSource.cancelled()". Clients may still use this event in
      conjunction with "WlDataSource.action()" for feedback.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           accept request

         * **mime_type** (*ArgumentType.String* or *None*) -- mime
           type accepted by the client

   receive(mime_type: 'str', fd: 'int') -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Request that the data is transferred

      To transfer the offered data, the client issues this request and
      indicates the mime type it wants to receive.  The transfer
      happens through the passed file descriptor (typically created
      with the pipe system call).  The source client writes the data
      in the mime type representation requested and then closes the
      file descriptor.

      The receiving client reads from the read end of the pipe until
      EOF and then closes its end, at which point the transfer is
      complete.

      This request may happen multiple times for different mime types,
      both before and after "WlDataDevice.drop()". Drag-and-drop
      destination clients may preemptively fetch data or examine it
      more closely to determine acceptance.

      Parameters:
         * **mime_type** (*ArgumentType.String*) -- mime type desired
           by receiver

         * **fd** (*ArgumentType.FileDescriptor*) -- file descriptor
           for data transfer

   destroy() -> 'None'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Destroy data offer

      Destroy the data offer.

   finish() -> 'None'

      -[ Request -- opcode 3 (attached to "Resource" instance) ]-

      The offer will no longer be used

      Notifies the compositor that the drag destination successfully
      finished the drag-and-drop operation.

      Upon receiving this request, the compositor will emit
      "WlDataSource.dnd_finished()" on the drag source client.

      It is a client error to perform other requests than
      "WlDataOffer.destroy()" after this one. It is also an error to
      perform this request after a NULL mime type has been set in
      "WlDataOffer.accept()" or no action was received through
      "WlDataOffer.action()".

      If "WlDataOffer.finish()" request is received for a non drag and
      drop operation, the invalid_finish protocol error is raised.

   set_actions(dnd_actions: 'int', preferred_action: 'int') -> 'None'

      -[ Request -- opcode 4 (attached to "Resource" instance) ]-

      Set the available/preferred drag-and-drop actions

      Sets the actions that the destination side client supports for
      this operation. This request may trigger the emission of
      "WlDataSource.action()" and "WlDataOffer.action()" events if the
      compositor needs to change the selected action.

      This request can be called multiple times throughout the drag-
      and-drop operation, typically in response to
      "WlDataDevice.enter()" or "WlDataDevice.motion()" events.

      This request determines the final result of the drag-and-drop
      operation. If the end result is that no action is accepted, the
      drag source will receive "WlDataSource.cancelled()".

      The dnd_actions argument must contain only values expressed in
      the "WlDataDeviceManager.dnd_actions()" enum, and the
      preferred_action argument must only contain one of those values
      set, otherwise it will result in a protocol error.

      While managing an "ask" action, the destination drag-and-drop
      client may perform further "WlDataOffer.receive()" requests, and
      is expected to perform one last "WlDataOffer.set_actions()"
      request with a preferred action other than "ask" (and optionally
      "WlDataOffer.accept()") before requesting
      "WlDataOffer.finish()", in order to convey the action selected
      by the user. If the preferred action is not in the
      "WlDataOffer.source_actions()" mask, an error will be raised.

      If the "ask" action is dismissed (e.g. user cancellation), the
      client is expected to perform "WlDataOffer.destroy()" right
      away.

      This request can only be made on drag-and-drop offers, a
      protocol error will be raised otherwise.

      Parameters:
         * **dnd_actions** (*ArgumentType.Uint*) -- actions supported
           by the destination client

         * **preferred_action** (*ArgumentType.Uint*) -- action
           preferred by the destination client

   offer(mime_type: 'str') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Advertise offered mime type

      Sent immediately after creating the "WlDataOffer" object.  One
      event per offered mime type.

      Parameters:
         **mime_type** (*ArgumentType.String*) -- offered mime type

   source_actions(source_actions: 'int') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Notify the source-side available actions

      This event indicates the actions offered by the data source. It
      will be sent immediately after creating the "WlDataOffer"
      object, or anytime the source side changes its offered actions
      through "WlDataSource.set_actions()".

      Parameters:
         **source_actions** (*ArgumentType.Uint*) -- actions offered
         by the data source

   action(dnd_action: 'int') -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      Notify the selected action

      This event indicates the action selected by the compositor after
      matching the source/destination side actions. Only one action
      (or none) will be offered here.

      This event can be emitted multiple times during the drag-and-
      drop operation in response to destination side action changes
      through "WlDataOffer.set_actions()".

      This event will no longer be emitted after "WlDataDevice.drop()"
      happened on the drag- and-drop destination, the client must
      honor the last action received, or the last preferred one set
      through "WlDataOffer.set_actions()" when handling an "ask"
      action.

      Compositors may also change the selected action on the fly,
      mainly in response to keyboard modifier changes during the drag-
      and-drop operation.

      The most recent action received is always the valid one. Prior
      to receiving "WlDataDevice.drop()", the chosen action may change
      (e.g. due to keyboard modifiers being pressed). At the time of
      receiving "WlDataDevice.drop()" the drag-and-drop destination
      must honor the last action received.

      Action changes may still happen after "WlDataDevice.drop()",
      especially on "ask" actions, where the drag-and-drop destination
      may choose another action afterwards. Action changes happening
      at this stage are always the result of inter-client negotiation,
      the compositor shall no longer be able to induce a different
      action.

      Upon "ask" actions, it is expected that the drag-and-drop
      destination may potentially choose a different action and/or
      mime type, based on "WlDataOffer.source_actions()" and finally
      chosen by the user (e.g. popping up a menu with the available
      options). The final "WlDataOffer.set_actions()" and
      "WlDataOffer.accept()" requests must happen before the call to
      "WlDataOffer.finish()".

      Parameters:
         **dnd_action** (*ArgumentType.Uint*) -- action selected by
         the compositor


WlDataSource
============

class pywayland.protocol.wayland.WlDataSource

   Offer to transfer data

   The "WlDataSource" object is the source side of a "WlDataOffer". It
   is created by the source client in a data transfer and provides a
   way to describe the offered data and a way to respond to requests
   to transfer the data.

   offer(mime_type: 'str') -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Add an offered mime type

      This request adds a mime type to the set of mime types
      advertised to targets.  Can be called several times to offer
      multiple types.

      Parameters:
         **mime_type** (*ArgumentType.String*) -- mime type offered by
         the data source

   destroy() -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Destroy the data source

      Destroy the data source.

   set_actions(dnd_actions: 'int') -> 'None'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Set the available drag-and-drop actions

      Sets the actions that the source side client supports for this
      operation. This request may trigger "WlDataSource.action()" and
      "WlDataOffer.action()" events if the compositor needs to change
      the selected action.

      The dnd_actions argument must contain only values expressed in
      the "WlDataDeviceManager.dnd_actions()" enum, otherwise it will
      result in a protocol error.

      This request must be made once only, and can only be made on
      sources used in drag-and-drop, so it must be performed before
      "WlDataDevice.start_drag()". Attempting to use the source other
      than for drag-and-drop will raise a protocol error.

      Parameters:
         **dnd_actions** (*ArgumentType.Uint*) -- actions supported by
         the data source

   target(mime_type: 'str | None') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      A target accepts an offered mime type

      Sent when a target accepts pointer_focus or motion events.  If a
      target does not accept any of the offered types, type is NULL.

      Used for feedback during drag-and-drop.

      Parameters:
         **mime_type** (*ArgumentType.String* or *None*) -- mime type
         accepted by the target

   send(mime_type: 'str', fd: 'int') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Send the data

      Request for data from the client.  Send the data as the
      specified mime type over the passed file descriptor, then close
      it.

      Parameters:
         * **mime_type** (*ArgumentType.String*) -- mime type for the
           data

         * **fd** (*ArgumentType.FileDescriptor*) -- file descriptor
           for the data

   cancelled() -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      Selection was cancelled

      This data source is no longer valid. There are several reasons
      why this could happen:

      * The data source has been replaced by another data source.

      * The drag-and-drop operation was performed, but the drop
        destination did not accept any of the mime types offered
        through "WlDataSource.target()".

      * The drag-and-drop operation was performed, but the drop
        destination did not select any of the actions present in the
        mask offered through "WlDataSource.action()".

      * The drag-and-drop operation was performed but didn't happen
        over a surface.

      * The compositor cancelled the drag-and-drop operation (e.g.
        compositor dependent timeouts to avoid stale drag-and-drop
        transfers).

      The client should clean up and destroy this data source.

      For objects of version 2 or older, "WlDataSource.cancelled()"
      will only be emitted if the data source was replaced by another
      data source.

   dnd_drop_performed() -> 'None'

      -[ Event -- opcode 3 (attached to "Proxy" instance) ]-

      The drag-and-drop operation physically finished

      The user performed the drop action. This event does not indicate
      acceptance, "WlDataSource.cancelled()" may still be emitted
      afterwards if the drop destination does not accept any mime
      type.

      However, this event might however not be received if the
      compositor cancelled the drag-and-drop operation before this
      event could happen.

      Note that the data_source may still be used in the future and
      should not be destroyed here.

   dnd_finished() -> 'None'

      -[ Event -- opcode 4 (attached to "Proxy" instance) ]-

      The drag-and-drop operation concluded

      The drop destination finished interoperating with this data
      source, so the client is now free to destroy this data source
      and free all associated data.

      If the action used to perform the operation was "move", the
      source can now delete the transferred data.

   action(dnd_action: 'int') -> 'None'

      -[ Event -- opcode 5 (attached to "Proxy" instance) ]-

      Notify the selected action

      This event indicates the action selected by the compositor after
      matching the source/destination side actions. Only one action
      (or none) will be offered here.

      This event can be emitted multiple times during the drag-and-
      drop operation, mainly in response to destination side changes
      through "WlDataOffer.set_actions()", and as the data device
      enters/leaves surfaces.

      It is only possible to receive this event after
      "WlDataSource.dnd_drop_performed()" if the drag-and-drop
      operation ended in an "ask" action, in which case the final
      "WlDataSource.action()" event will happen immediately before
      "WlDataSource.dnd_finished()".

      Compositors may also change the selected action on the fly,
      mainly in response to keyboard modifier changes during the drag-
      and-drop operation.

      The most recent action received is always the valid one. The
      chosen action may change alongside negotiation (e.g. an "ask"
      action can turn into a "move" operation), so the effects of the
      final action must always be applied in
      "WlDataOffer.dnd_finished()".

      Clients can trigger cursor surface changes from this point, so
      they reflect the current action.

      Parameters:
         **dnd_action** (*ArgumentType.Uint*) -- action selected by
         the compositor


WlDisplay
=========

class pywayland.protocol.wayland.WlDisplay

   Core global object

   The core global object.  This is a special singleton object.  It is
   used for internal Wayland protocol features.

   sync() -> 'Proxy[WlCallback]'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Asynchronous roundtrip

      The sync request asks the server to emit the 'done' event on the
      returned "WlCallback" object.  Since requests are handled in-
      order and events are delivered in-order, this can be used as a
      barrier to ensure all previous requests and the resulting events
      have been handled.

      The object returned by this request will be destroyed by the
      compositor after the callback is fired and as such the client
      must not attempt to use it after that point.

      The callback_data passed in the callback is undefined and should
      be ignored.

      Returns:
         "WlCallback" -- callback object for the sync request

   get_registry() -> 'Proxy[WlRegistry]'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Get global registry object

      This request creates a registry object that allows the client to
      list and bind the global objects available from the compositor.

      It should be noted that the server side resources consumed in
      response to a get_registry request can only be released when the
      client disconnects, not when the client side proxy is destroyed.
      Therefore, clients should invoke get_registry as infrequently as
      possible to avoid wasting memory.

      Returns:
         "WlRegistry" -- global registry object

   error(object_id: 'Any', code: 'int', message: 'str') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Fatal error event

      The error event is sent out when a fatal (non-recoverable) error
      has occurred.  The object_id argument is the object where the
      error occurred, most often in response to a request to that
      object.  The code identifies the error and is defined by the
      object interface.  As such, each interface defines its own set
      of error codes.  The message is a brief description of the
      error, for (debugging) convenience.

      Parameters:
         * **object_id** (*ArgumentType.Object*) -- object where the
           error occurred

         * **code** (*ArgumentType.Uint*) -- error code

         * **message** (*ArgumentType.String*) -- error description

   delete_id(id: 'int') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Acknowledge object id deletion

      This event is used internally by the object ID management logic.
      When a client deletes an object that it had created, the server
      will send this event to acknowledge that it has seen the delete
      request. When the client receives this event, it will know that
      it can safely reuse the object ID.

      Parameters:
         **id** (*ArgumentType.Uint*) -- deleted object ID


WlKeyboard
==========

class pywayland.protocol.wayland.WlKeyboard

   Keyboard input device

   The "WlKeyboard" interface represents one or more keyboards
   associated with a seat.

   Each "WlKeyboard" has the following logical state:

   * an active surface (possibly null),

   * the keys currently logically down,

   * the active modifiers,

   * the active group.

   By default, the active surface is null, the keys currently
   logically down are empty, the active modifiers and the active group
   are 0.

   release() -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Release the keyboard object

   keymap(format: 'int', fd: 'int', size: 'int') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Keyboard mapping

      This event provides a file descriptor to the client which can be
      memory-mapped in read-only mode to provide a keyboard mapping
      description.

      From version 7 onwards, the fd must be mapped with MAP_PRIVATE
      by the recipient, as MAP_SHARED may fail.

      Parameters:
         * **format** (*ArgumentType.Uint*) -- keymap format

         * **fd** (*ArgumentType.FileDescriptor*) -- keymap file
           descriptor

         * **size** (*ArgumentType.Uint*) -- keymap size, in bytes

   enter(serial: 'int', surface: 'WlSurface', keys: 'list') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Enter event

      Notification that this seat's keyboard focus is on a certain
      surface.

      The compositor must send the "WlKeyboard.modifiers()" event
      after this event.

      In the "WlKeyboard" logical state, this event sets the active
      surface to the surface argument and the keys currently logically
      down to the keys in the keys argument. The compositor must not
      send this event if the "WlKeyboard" already had an active
      surface immediately before this event.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           enter event

         * **surface** ("WlSurface") -- surface gaining keyboard focus

         * **keys** (*ArgumentType.Array*) -- the keys currently
           logically down

   leave(serial: 'int', surface: 'WlSurface') -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      Leave event

      Notification that this seat's keyboard focus is no longer on a
      certain surface.

      The leave notification is sent before the enter notification for
      the new focus.

      In the "WlKeyboard" logical state, this event resets all values
      to their defaults. The compositor must not send this event if
      the active surface of the "WlKeyboard" was not equal to the
      surface argument immediately before this event.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           leave event

         * **surface** ("WlSurface") -- surface that lost keyboard
           focus

   key(serial: 'int', time: 'int', key: 'int', state: 'int') -> 'None'

      -[ Event -- opcode 3 (attached to "Proxy" instance) ]-

      Key event

      A key was pressed or released. The time argument is a timestamp
      with millisecond granularity, with an undefined base.

      The key is a platform-specific key code that can be interpreted
      by feeding it to the keyboard mapping (see the keymap event).

      If this event produces a change in modifiers, then the resulting
      "WlKeyboard.modifiers()" event must be sent after this event.

      In the "WlKeyboard" logical state, this event adds the key to
      the keys currently logically down (if the state argument is
      pressed) or removes the key from the keys currently logically
      down (if the state argument is released). The compositor must
      not send this event if the "WlKeyboard" did not have an active
      surface immediately before this event. The compositor must not
      send this event if state is pressed (resp. released) and the key
      was already logically down (resp. was not logically down)
      immediately before this event.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           key event

         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **key** (*ArgumentType.Uint*) -- key that produced the
           event

         * **state** (*ArgumentType.Uint*) -- physical state of the
           key

   modifiers(serial: 'int', mods_depressed: 'int', mods_latched: 'int', mods_locked: 'int', group: 'int') -> 'None'

      -[ Event -- opcode 4 (attached to "Proxy" instance) ]-

      Modifier and group state

      Notifies clients that the modifier and/or group state has
      changed, and it should update its local state.

      The compositor may send this event without a surface of the
      client having keyboard focus, for example to tie modifier
      information to pointer focus instead. If a modifier event with
      pressed modifiers is sent without a prior enter event, the
      client can assume the modifier state is valid until it receives
      the next "WlKeyboard.modifiers()" event. In order to reset the
      modifier state again, the compositor can send a
      "WlKeyboard.modifiers()" event with no pressed modifiers.

      In the "WlKeyboard" logical state, this event updates the
      modifiers and group.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           modifiers event

         * **mods_depressed** (*ArgumentType.Uint*) -- depressed
           modifiers

         * **mods_latched** (*ArgumentType.Uint*) -- latched modifiers

         * **mods_locked** (*ArgumentType.Uint*) -- locked modifiers

         * **group** (*ArgumentType.Uint*) -- keyboard layout

   repeat_info(rate: 'int', delay: 'int') -> 'None'

      -[ Event -- opcode 5 (attached to "Proxy" instance) ]-

      Repeat rate and delay

      Informs the client about the keyboard's repeat rate and delay.

      This event is sent as soon as the "WlKeyboard" object has been
      created, and is guaranteed to be received by the client before
      any key press event.

      Negative values for either rate or delay are illegal. A rate of
      zero will disable any repeating (regardless of the value of
      delay).

      This event can be sent later on as well with a new value if
      necessary, so clients should continue listening for the event
      past the creation of "WlKeyboard".

      Parameters:
         * **rate** (*ArgumentType.Int*) -- the rate of repeating keys
           in characters per second

         * **delay** (*ArgumentType.Int*) -- delay in milliseconds
           since key down until repeating starts


WlOutput
========

class pywayland.protocol.wayland.WlOutput

   Compositor output region

   An output describes part of the compositor geometry.  The
   compositor works in the 'compositor coordinate system' and an
   output corresponds to a rectangular area in that space that is
   actually visible.  This typically corresponds to a monitor that
   displays part of the compositor space.  This object is published as
   global during start up, or when a monitor is hotplugged.

   release() -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Release the output object

      Using this request a client can tell the server that it is not
      going to use the output object anymore.

   geometry(x: 'int', y: 'int', physical_width: 'int', physical_height: 'int', subpixel: 'int', make: 'str', model: 'str', transform: 'int') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Properties of the output

      The geometry event describes geometric properties of the output.
      The event is sent when binding to the output object and whenever
      any of the properties change.

      The physical size can be set to zero if it doesn't make sense
      for this output (e.g. for projectors or virtual outputs).

      The geometry event will be followed by a done event (starting
      from version 2).

      Clients should use "WlSurface.preferred_buffer_transform()"
      instead of the transform advertised by this event to find the
      preferred buffer transform to use for a surface.

      Note: "WlOutput" only advertises partial information about the
      output position and identification. Some compositors, for
      instance those not implementing a desktop-style output layout or
      those exposing virtual outputs, might fake this information.
      Instead of using x and y, clients should use
      xdg_output.logical_position. Instead of using make and model,
      clients should use name and description.

      Parameters:
         * **x** (*ArgumentType.Int*) -- x position within the global
           compositor space

         * **y** (*ArgumentType.Int*) -- y position within the global
           compositor space

         * **physical_width** (*ArgumentType.Int*) -- width in
           millimeters of the output

         * **physical_height** (*ArgumentType.Int*) -- height in
           millimeters of the output

         * **subpixel** (*ArgumentType.Int*) -- subpixel orientation
           of the output

         * **make** (*ArgumentType.String*) -- textual description of
           the manufacturer

         * **model** (*ArgumentType.String*) -- textual description of
           the model

         * **transform** (*ArgumentType.Int*) -- additional
           transformation applied to buffer contents during
           presentation

   mode(flags: 'int', width: 'int', height: 'int', refresh: 'int') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Advertise available modes for the output

      The mode event describes an available mode for the output.

      The event is sent when binding to the output object and there
      will always be one mode, the current mode.  The event is sent
      again if an output changes mode, for the mode that is now
      current.  In other words, the current mode is always the last
      mode that was received with the current flag set.

      Non-current modes are deprecated. A compositor can decide to
      only advertise the current mode and never send other modes.
      Clients should not rely on non-current modes.

      The size of a mode is given in physical hardware units of the
      output device. This is not necessarily the same as the output
      size in the global compositor space. For instance, the output
      may be scaled, as described in "WlOutput.scale()", or
      transformed, as described in "WlOutput.transform()". Clients
      willing to retrieve the output size in the global compositor
      space should use xdg_output.logical_size instead.

      The vertical refresh rate can be set to zero if it doesn't make
      sense for this output (e.g. for virtual outputs).

      The mode event will be followed by a done event (starting from
      version 2).

      Clients should not use the refresh rate to schedule frames.
      Instead, they should use the "WlSurface.frame()" event or the
      presentation-time protocol.

      Note: this information is not always meaningful for all outputs.
      Some compositors, such as those exposing virtual outputs, might
      fake the refresh rate or the size.

      Parameters:
         * **flags** (*ArgumentType.Uint*) -- bitfield of mode flags

         * **width** (*ArgumentType.Int*) -- width of the mode in
           hardware units

         * **height** (*ArgumentType.Int*) -- height of the mode in
           hardware units

         * **refresh** (*ArgumentType.Int*) -- vertical refresh rate
           in mHz

   done() -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      Sent all information about output

      This event is sent after all other properties have been sent
      after binding to the output object and after any other property
      changes done after that. This allows changes to the output
      properties to be seen as atomic, even if they happen via
      multiple events.

   scale(factor: 'int') -> 'None'

      -[ Event -- opcode 3 (attached to "Proxy" instance) ]-

      Output scaling properties

      This event contains scaling geometry information that is not in
      the geometry event. It may be sent after binding the output
      object or if the output scale changes later. The compositor will
      emit a non-zero, positive value for scale. If it is not sent,
      the client should assume a scale of 1.

      A scale larger than 1 means that the compositor will
      automatically scale surface buffers by this amount when
      rendering. This is used for very high resolution displays where
      applications rendering at the native resolution would be too
      small to be legible.

      Clients should use "WlSurface.preferred_buffer_scale()" instead
      of this event to find the preferred buffer scale to use for a
      surface.

      The scale event will be followed by a done event.

      Parameters:
         **factor** (*ArgumentType.Int*) -- scaling factor of output

   name(name: 'str') -> 'None'

      -[ Event -- opcode 4 (attached to "Proxy" instance) ]-

      Name of this output

      Many compositors will assign user-friendly names to their
      outputs, show them to the user, allow the user to refer to an
      output, etc. The client may wish to know this name as well to
      offer the user similar behaviors.

      The name is a UTF-8 string with no convention defined for its
      contents. Each name is unique among all "WlOutput" globals. The
      name is only guaranteed to be unique for the compositor
      instance.

      The same output name is used for all clients for a given
      "WlOutput" global. Thus, the name can be shared across processes
      to refer to a specific "WlOutput" global.

      The name is not guaranteed to be persistent across sessions,
      thus cannot be used to reliably identify an output in e.g.
      configuration files.

      Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc.
      However, do not assume that the name is a reflection of an
      underlying DRM connector, X11 connection, etc.

      The name event is sent after binding the output object. This
      event is only sent once per output object, and the name does not
      change over the lifetime of the "WlOutput" global.

      Compositors may re-use the same output name if the "WlOutput"
      global is destroyed and re-created later. Compositors should
      avoid re- using the same name if possible.

      The name event will be followed by a done event.

      Parameters:
         **name** (*ArgumentType.String*) -- output name

   description(description: 'str') -> 'None'

      -[ Event -- opcode 5 (attached to "Proxy" instance) ]-

      Human-readable description of this output

      Many compositors can produce human-readable descriptions of
      their outputs. The client may wish to know this description as
      well, e.g. for output selection purposes.

      The description is a UTF-8 string with no convention defined for
      its contents. The description is not guaranteed to be unique
      among all "WlOutput" globals. Examples might include 'Foocorp
      11" Display' or 'Virtual X11 output via :1'.

      The description event is sent after binding the output object
      and whenever the description changes. The description is
      optional, and may not be sent at all.

      The description event will be followed by a done event.

      Parameters:
         **description** (*ArgumentType.String*) -- output description


WlPointer
=========

class pywayland.protocol.wayland.WlPointer

   Pointer input device

   The "WlPointer" interface represents one or more input devices,
   such as mice, which control the pointer location and pointer_focus
   of a seat.

   The "WlPointer" interface generates motion, enter and leave events
   for the surfaces that the pointer is located over, and button and
   axis events for button presses, button releases and scrolling.

   set_cursor(serial: 'int', surface: 'WlSurface | None', hotspot_x: 'int', hotspot_y: 'int') -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Set the pointer surface

      Set the pointer surface, i.e., the surface that contains the
      pointer image (cursor). This request gives the surface the role
      of a cursor. If the surface already has another role, it raises
      a protocol error.

      The cursor actually changes only if the pointer focus for this
      device is one of the requesting client's surfaces or the surface
      parameter is the current pointer surface. If there was a
      previous surface set with this request it is replaced. If
      surface is NULL, the pointer image is hidden.

      The parameters hotspot_x and hotspot_y define the position of
      the pointer surface relative to the pointer location. Its top-
      left corner is always at (x, y) - (hotspot_x, hotspot_y), where
      (x, y) are the coordinates of the pointer location, in surface-
      local coordinates.

      On "WlSurface.offset()" requests to the pointer surface,
      hotspot_x and hotspot_y are decremented by the x and y
      parameters passed to the request. The offset must be applied by
      "WlSurface.commit()" as usual.

      The hotspot can also be updated by passing the currently set
      pointer surface to this request with new values for hotspot_x
      and hotspot_y.

      The input region is ignored for wl_surfaces with the role of a
      cursor. When the use as a cursor ends, the "WlSurface" is
      unmapped.

      The serial parameter must match the latest "WlPointer.enter()"
      serial number sent to the client. Otherwise the request will be
      ignored.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           enter event

         * **surface** ("WlSurface" or *None*) -- pointer surface

         * **hotspot_x** (*ArgumentType.Int*) -- surface-local x
           coordinate

         * **hotspot_y** (*ArgumentType.Int*) -- surface-local y
           coordinate

   release() -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Release the pointer object

      Using this request a client can tell the server that it is not
      going to use the pointer object anymore.

      This request destroys the pointer proxy object, so clients must
      not call wl_pointer_destroy() after using this request.

   enter(serial: 'int', surface: 'WlSurface', surface_x: 'float', surface_y: 'float') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Enter event

      Notification that this seat's pointer is focused on a certain
      surface.

      When a seat's focus enters a surface, the pointer image is
      undefined and a client should respond to this event by setting
      an appropriate pointer image with the set_cursor request.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           enter event

         * **surface** ("WlSurface") -- surface entered by the pointer

         * **surface_x** (*ArgumentType.Fixed*) -- surface-local x
           coordinate

         * **surface_y** (*ArgumentType.Fixed*) -- surface-local y
           coordinate

   leave(serial: 'int', surface: 'WlSurface') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Leave event

      Notification that this seat's pointer is no longer focused on a
      certain surface.

      The leave notification is sent before the enter notification for
      the new focus.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           leave event

         * **surface** ("WlSurface") -- surface left by the pointer

   motion(time: 'int', surface_x: 'float', surface_y: 'float') -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      Pointer motion event

      Notification of pointer location change. The arguments surface_x
      and surface_y are the location relative to the focused surface.

      Parameters:
         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **surface_x** (*ArgumentType.Fixed*) -- surface-local x
           coordinate

         * **surface_y** (*ArgumentType.Fixed*) -- surface-local y
           coordinate

   button(serial: 'int', time: 'int', button: 'int', state: 'int') -> 'None'

      -[ Event -- opcode 3 (attached to "Proxy" instance) ]-

      Pointer button event

      Mouse button click and release notifications.

      The location of the click is given by the last motion or enter
      event. The time argument is a timestamp with millisecond
      granularity, with an undefined base.

      The button is a button code as defined in the Linux kernel's
      linux/input-event-codes.h header file, e.g. BTN_LEFT.

      Any 16-bit button code value is reserved for future additions to
      the kernel's event code list. All other button codes above
      0xFFFF are currently undefined but may be used in future
      versions of this protocol.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           button event

         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **button** (*ArgumentType.Uint*) -- button that produced
           the event

         * **state** (*ArgumentType.Uint*) -- physical state of the
           button

   axis(time: 'int', axis: 'int', value: 'float') -> 'None'

      -[ Event -- opcode 4 (attached to "Proxy" instance) ]-

      Axis event

      Scroll and other axis notifications.

      For scroll events (vertical and horizontal scroll axes), the
      value parameter is the length of a vector along the specified
      axis in a coordinate space identical to those of motion events,
      representing a relative movement along the specified axis.

      For devices that support movements non-parallel to axes multiple
      axis events will be emitted.

      When applicable, for example for touch pads, the server can
      choose to emit scroll events where the motion vector is
      equivalent to a motion event vector.

      When applicable, a client can transform its content relative to
      the scroll distance.

      Parameters:
         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **axis** (*ArgumentType.Uint*) -- axis type

         * **value** (*ArgumentType.Fixed*) -- length of vector in
           surface-local coordinate space

   frame() -> 'None'

      -[ Event -- opcode 5 (attached to "Proxy" instance) ]-

      End of a pointer event sequence

      Indicates the end of a set of events that logically belong
      together. A client is expected to accumulate the data in all
      events within the frame before proceeding.

      All "WlPointer" events before a "WlPointer.frame()" event belong
      logically together. For example, in a diagonal scroll motion the
      compositor will send an optional "WlPointer.axis_source()"
      event, two "WlPointer.axis()" events (horizontal and vertical)
      and finally a "WlPointer.frame()" event. The client may use this
      information to calculate a diagonal vector for scrolling.

      When multiple "WlPointer.axis()" events occur within the same
      frame, the motion vector is the combined motion of all events.
      When a "WlPointer.axis()" and a "WlPointer.axis_stop()" event
      occur within the same frame, this indicates that axis movement
      in one axis has stopped but continues in the other axis. When
      multiple "WlPointer.axis_stop()" events occur within the same
      frame, this indicates that these axes stopped in the same
      instance.

      A "WlPointer.frame()" event is sent for every logical event
      group, even if the group only contains a single "WlPointer"
      event. Specifically, a client may get a sequence: motion, frame,
      button, frame, axis, frame, axis_stop, frame.

      The "WlPointer.enter()" and "WlPointer.leave()" events are
      logical events generated by the compositor and not the hardware.
      These events are also grouped by a "WlPointer.frame()". When a
      pointer moves from one surface to another, a compositor should
      group the "WlPointer.leave()" event within the same
      "WlPointer.frame()". However, a client must not rely on
      "WlPointer.leave()" and "WlPointer.enter()" being in the same
      "WlPointer.frame()". Compositor-specific policies may require
      the "WlPointer.leave()" and "WlPointer.enter()" event being
      split across multiple "WlPointer.frame()" groups.

   axis_source(axis_source: 'int') -> 'None'

      -[ Event -- opcode 6 (attached to "Proxy" instance) ]-

      Axis source event

      Source information for scroll and other axes.

      This event does not occur on its own. It is sent before a
      "WlPointer.frame()" event and carries the source information for
      all events within that frame.

      The source specifies how this event was generated. If the source
      is "WlPointer.axis_source()".finger, a "WlPointer.axis_stop()"
      event will be sent when the user lifts the finger off the
      device.

      If the source is "WlPointer.axis_source()".wheel,
      "WlPointer.axis_source()".wheel_tilt or
      "WlPointer.axis_source()".continuous, a "WlPointer.axis_stop()"
      event may or may not be sent. Whether a compositor sends an
      axis_stop event for these sources is hardware- specific and
      implementation-dependent; clients must not rely on receiving an
      axis_stop event for these scroll sources and should treat scroll
      sequences from these scroll sources as unterminated by default.

      This event is optional. If the source is unknown for a
      particular axis event sequence, no event is sent. Only one
      "WlPointer.axis_source()" event is permitted per frame.

      The order of "WlPointer.axis_discrete()" and
      "WlPointer.axis_source()" is not guaranteed.

      Parameters:
         **axis_source** (*ArgumentType.Uint*) -- source of the axis
         event

   axis_stop(time: 'int', axis: 'int') -> 'None'

      -[ Event -- opcode 7 (attached to "Proxy" instance) ]-

      Axis stop event

      Stop notification for scroll and other axes.

      For some "WlPointer.axis_source()" types, a
      "WlPointer.axis_stop()" event is sent to notify a client that
      the axis sequence has terminated. This enables the client to
      implement kinetic scrolling. See the "WlPointer.axis_source()"
      documentation for information on when this event may be
      generated.

      Any "WlPointer.axis()" events with the same axis_source after
      this event should be considered as the start of a new axis
      motion.

      The timestamp is to be interpreted identical to the timestamp in
      the "WlPointer.axis()" event. The timestamp value may be the
      same as a preceding "WlPointer.axis()" event.

      Parameters:
         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **axis** (*ArgumentType.Uint*) -- the axis stopped with
           this event

   axis_discrete(axis: 'int', discrete: 'int') -> 'None'

      -[ Event -- opcode 8 (attached to "Proxy" instance) ]-

      Axis click event

      Discrete step information for scroll and other axes.

      This event carries the axis value of the "WlPointer.axis()"
      event in discrete steps (e.g. mouse wheel clicks).

      This event is deprecated with "WlPointer" version 8 - this event
      is not sent to clients supporting version 8 or later.

      This event does not occur on its own, it is coupled with a
      "WlPointer.axis()" event that represents this axis value on a
      continuous scale. The protocol guarantees that each
      axis_discrete event is always followed by exactly one axis event
      with the same axis number within the same "WlPointer.frame()".
      Note that the protocol allows for other events to occur between
      the axis_discrete and its coupled axis event, including other
      axis_discrete or axis events. A "WlPointer.frame()" must not
      contain more than one axis_discrete event per axis type.

      This event is optional; continuous scrolling devices like two-
      finger scrolling on touchpads do not have discrete steps and do
      not generate this event.

      The discrete value carries the directional information. e.g. a
      value of -2 is two steps towards the negative direction of this
      axis.

      The axis number is identical to the axis number in the
      associated axis event.

      The order of "WlPointer.axis_discrete()" and
      "WlPointer.axis_source()" is not guaranteed.

      Parameters:
         * **axis** (*ArgumentType.Uint*) -- axis type

         * **discrete** (*ArgumentType.Int*) -- number of steps

   axis_value120(axis: 'int', value120: 'int') -> 'None'

      -[ Event -- opcode 9 (attached to "Proxy" instance) ]-

      Axis high-resolution scroll event

      Discrete high-resolution scroll information.

      This event carries high-resolution wheel scroll information,
      with each multiple of 120 representing one logical scroll step
      (a wheel detent). For example, an axis_value120 of 30 is one
      quarter of a logical scroll step in the positive direction, a
      value120 of -240 are two logical scroll steps in the negative
      direction within the same hardware event. Clients that rely on
      discrete scrolling should accumulate the value120 to multiples
      of 120 before processing the event.

      The value120 must not be zero.

      This event replaces the "WlPointer.axis_discrete()" event in
      clients supporting "WlPointer" version 8 or later.

      Where a "WlPointer.axis_source()" event occurs in the same
      "WlPointer.frame()", the axis source applies to this event.

      The order of "WlPointer".axis_value120 and
      "WlPointer.axis_source()" is not guaranteed.

      Parameters:
         * **axis** (*ArgumentType.Uint*) -- axis type

         * **value120** (*ArgumentType.Int*) -- scroll distance as
           fraction of 120

   axis_relative_direction(axis: 'int', direction: 'int') -> 'None'

      -[ Event -- opcode 10 (attached to "Proxy" instance) ]-

      Axis relative physical direction event

      Relative directional information of the entity causing the axis
      motion.

      For a "WlPointer.axis()" event, the
      "WlPointer.axis_relative_direction()" event specifies the
      movement direction of the entity causing the "WlPointer.axis()"
      event. For example: - if a user's fingers on a touchpad move
      down and this   causes a "WlPointer.axis()" vertical_scroll down
      event, the physical   direction is 'identical' - if a user's
      fingers on a touchpad move down and this causes a
      "WlPointer.axis()" vertical_scroll up scroll up event ('natural
      scrolling'), the physical direction is 'inverted'.

      A client may use this information to adjust scroll motion of
      components. Specifically, enabling natural scrolling causes the
      content to change direction compared to traditional scrolling.
      Some widgets like volume control sliders should usually match
      the physical direction regardless of whether natural scrolling
      is active. This event enables clients to match the scroll
      direction of a widget to the physical direction.

      This event does not occur on its own, it is coupled with a
      "WlPointer.axis()" event that represents this axis value. The
      protocol guarantees that each axis_relative_direction event is
      always followed by exactly one axis event with the same axis
      number within the same "WlPointer.frame()". Note that the
      protocol allows for other events to occur between the
      axis_relative_direction and its coupled axis event.

      The axis number is identical to the axis number in the
      associated axis event.

      The order of "WlPointer.axis_relative_direction()",
      "WlPointer.axis_discrete()" and "WlPointer.axis_source()" is not
      guaranteed.

      Parameters:
         * **axis** (*ArgumentType.Uint*) -- axis type

         * **direction** (*ArgumentType.Uint*) -- physical direction
           relative to axis motion


WlRegion
========

class pywayland.protocol.wayland.WlRegion

   Region interface

   A region object describes an area.

   Region objects are used to describe the opaque and input regions of
   a surface.

   destroy() -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Destroy region

      Destroy the region.  This will invalidate the object ID.

   add(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Add rectangle to region

      Add the specified rectangle to the region.

      Parameters:
         * **x** (*ArgumentType.Int*) -- region-local x coordinate

         * **y** (*ArgumentType.Int*) -- region-local y coordinate

         * **width** (*ArgumentType.Int*) -- rectangle width

         * **height** (*ArgumentType.Int*) -- rectangle height

   subtract(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Subtract rectangle from region

      Subtract the specified rectangle from the region.

      Parameters:
         * **x** (*ArgumentType.Int*) -- region-local x coordinate

         * **y** (*ArgumentType.Int*) -- region-local y coordinate

         * **width** (*ArgumentType.Int*) -- rectangle width

         * **height** (*ArgumentType.Int*) -- rectangle height


WlRegistry
==========

class pywayland.protocol.wayland.WlRegistry

   Global registry object

   The singleton global registry object.  The server has a number of
   global objects that are available to all clients.  These objects
   typically represent an actual object in the server (for example, an
   input device) or they are singleton objects that provide extension
   functionality.

   When a client creates a registry object, the registry object will
   emit a global event for each global currently in the registry.
   Globals come and go as a result of device or monitor hotplugs,
   reconfiguration or other events, and the registry will send out
   global and global_remove events to keep the client up to date with
   the changes.  To mark the end of the initial burst of events, the
   client can use the "WlDisplay.sync()" request immediately after
   calling "WlDisplay.get_registry()".

   A client can bind to a global object by using the bind request.
   This creates a client-side handle that lets the object emit events
   to the client and lets the client invoke requests on the object.

   bind(name: 'int', interface: 'type[T]', version: 'int') -> 'Proxy[T]'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Bind an object to the display

      Binds a new, client-created object to the server using the
      specified name as the identifier.

      Parameters:
         * **name** (*ArgumentType.Uint*) -- unique numeric name of
           the object

         * **interface** (*string*) -- Interface name

         * **version** (*int*) -- Interface version

      Returns:
         "pywayland.client.proxy.Proxy" of specified Interface --
         bounded object

   global_(name: 'int', interface: 'str', version: 'int') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Announce global object

      Notify the client of global objects.

      The event notifies the client that a global object with the
      given name is now available, and it implements the given version
      of the given interface.

      Parameters:
         * **name** (*ArgumentType.Uint*) -- numeric name of the
           global object

         * **interface** (*ArgumentType.String*) -- interface
           implemented by the object

         * **version** (*ArgumentType.Uint*) -- interface version

   global_remove(name: 'int') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Announce removal of global object

      Notify the client of removed global objects.

      This event notifies the client that the global identified by
      name is no longer available.  If the client bound to the global
      using the bind request, the client should now destroy that
      object.

      The object remains valid and requests to the object will be
      ignored until the client destroys it, to avoid races between the
      global going away and a client sending a request to it.

      Parameters:
         **name** (*ArgumentType.Uint*) -- numeric name of the global
         object


WlSeat
======

class pywayland.protocol.wayland.WlSeat

   Group of input devices

   A seat is a group of keyboards, pointer and touch devices. This
   object is published as a global during start up, or when such a
   device is hot plugged.  A seat typically has a pointer and
   maintains a keyboard focus and a pointer focus.

   get_pointer() -> 'Proxy[WlPointer]'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Return pointer object

      The ID provided will be initialized to the "WlPointer" interface
      for this seat.

      This request only takes effect if the seat has the pointer
      capability, or has had the pointer capability in the past. It is
      a protocol violation to issue this request on a seat that has
      never had the pointer capability. The missing_capability error
      will be sent in this case.

      Returns:
         "WlPointer" -- seat pointer

   get_keyboard() -> 'Proxy[WlKeyboard]'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Return keyboard object

      The ID provided will be initialized to the "WlKeyboard"
      interface for this seat.

      This request only takes effect if the seat has the keyboard
      capability, or has had the keyboard capability in the past. It
      is a protocol violation to issue this request on a seat that has
      never had the keyboard capability. The missing_capability error
      will be sent in this case.

      Returns:
         "WlKeyboard" -- seat keyboard

   get_touch() -> 'Proxy[WlTouch]'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Return touch object

      The ID provided will be initialized to the "WlTouch" interface
      for this seat.

      This request only takes effect if the seat has the touch
      capability, or has had the touch capability in the past. It is a
      protocol violation to issue this request on a seat that has
      never had the touch capability. The missing_capability error
      will be sent in this case.

      Returns:
         "WlTouch" -- seat touch interface

   release() -> 'None'

      -[ Request -- opcode 3 (attached to "Resource" instance) ]-

      Release the seat object

      Using this request a client can tell the server that it is not
      going to use the seat object anymore.

   capabilities(capabilities: 'int') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Seat capabilities changed

      This is emitted whenever a seat gains or loses the pointer,
      keyboard or touch capabilities.  The argument is a capability
      enum containing the complete set of capabilities this seat has.

      When the pointer capability is added, a client may create a
      "WlPointer" object using the "WlSeat.get_pointer()" request.
      This object will receive pointer events until the capability is
      removed in the future.

      When the pointer capability is removed, a client should destroy
      the "WlPointer" objects associated with the seat where the
      capability was removed, using the "WlPointer.release()" request.
      No further pointer events will be received on these objects.

      In some compositors, if a seat regains the pointer capability
      and a client has a previously obtained "WlPointer" object of
      version 4 or less, that object may start sending pointer events
      again. This behavior is considered a misinterpretation of the
      intended behavior and must not be relied upon by the client.
      "WlPointer" objects of version 5 or later must not send events
      if created before the most recent event notifying the client of
      an added pointer capability.

      The above behavior also applies to "WlKeyboard" and "WlTouch"
      with the keyboard and touch capabilities, respectively.

      Parameters:
         **capabilities** (*ArgumentType.Uint*) -- capabilities of the
         seat

   name(name: 'str') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Unique identifier for this seat

      In a multi-seat configuration the seat name can be used by
      clients to help identify which physical devices the seat
      represents.

      The seat name is a UTF-8 string with no convention defined for
      its contents. Each name is unique among all "WlSeat" globals.
      The name is only guaranteed to be unique for the current
      compositor instance.

      The same seat names are used for all clients. Thus, the name can
      be shared across processes to refer to a specific "WlSeat"
      global.

      The name event is sent after binding to the seat global. This
      event is only sent once per seat object, and the name does not
      change over the lifetime of the "WlSeat" global.

      Compositors may re-use the same seat name if the "WlSeat" global
      is destroyed and re-created later.

      Parameters:
         **name** (*ArgumentType.String*) -- seat identifier


WlShell
=======

class pywayland.protocol.wayland.WlShell

   Create desktop-style surfaces

   This interface is implemented by servers that provide desktop-style
   user interfaces.

   It allows clients to associate a "WlShellSurface" with a basic
   surface.

   Note! This protocol is deprecated and not intended for production
   use. For desktop-style user interfaces, use xdg_shell. Compositors
   and clients should not implement this interface.

   get_shell_surface(surface: 'WlSurface') -> 'Proxy[WlShellSurface]'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Create a shell surface from a surface

      Create a shell surface for an existing surface. This gives the
      "WlSurface" the role of a shell surface. If the "WlSurface"
      already has another role, it raises a protocol error.

      Only one shell surface can be associated with a given surface.

      Parameters:
         **surface** ("WlSurface") -- surface to be given the shell
         surface role

      Returns:
         "WlShellSurface" -- shell surface to create


WlShellSurface
==============

class pywayland.protocol.wayland.WlShellSurface

   Desktop-style metadata interface

   An interface that may be implemented by a "WlSurface", for
   implementations that provide a desktop-style user interface.

   It provides requests to treat surfaces like toplevel, fullscreen or
   popup windows, move, resize or maximize them, associate metadata
   like title and class, etc.

   On the server side the object is automatically destroyed when the
   related "WlSurface" is destroyed. On the client side,
   wl_shell_surface_destroy() must be called before destroying the
   "WlSurface" object.

   pong(serial: 'int') -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Respond to a ping event

      A client must respond to a ping event with a pong request or the
      client may be deemed unresponsive.

      Parameters:
         **serial** (*ArgumentType.Uint*) -- serial number of the ping
         event

   move(seat: 'WlSeat', serial: 'int') -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Start an interactive move

      Start a pointer-driven move of the surface.

      This request must be used in response to a button press event.
      The server may ignore move requests depending on the state of
      the surface (e.g. fullscreen or maximized).

      Parameters:
         * **seat** ("WlSeat") -- seat whose pointer is used

         * **serial** (*ArgumentType.Uint*) -- serial number of the
           implicit grab on the pointer

   resize(seat: 'WlSeat', serial: 'int', edges: 'int') -> 'None'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Start an interactive resize

      Start a pointer-driven resizing of the surface.

      This request must be used in response to a button press event.
      The server may ignore resize requests depending on the state of
      the surface (e.g. fullscreen or maximized).

      Parameters:
         * **seat** ("WlSeat") -- seat whose pointer is used

         * **serial** (*ArgumentType.Uint*) -- serial number of the
           implicit grab on the pointer

         * **edges** (*ArgumentType.Uint*) -- which edge or corner is
           being dragged

   set_toplevel() -> 'None'

      -[ Request -- opcode 3 (attached to "Resource" instance) ]-

      Make the surface a toplevel surface

      Map the surface as a toplevel surface.

      A toplevel surface is not fullscreen, maximized or transient.

   set_transient(parent: 'WlSurface', x: 'int', y: 'int', flags: 'int') -> 'None'

      -[ Request -- opcode 4 (attached to "Resource" instance) ]-

      Make the surface a transient surface

      Map the surface relative to an existing surface.

      The x and y arguments specify the location of the upper left
      corner of the surface relative to the upper left corner of the
      parent surface, in surface-local coordinates.

      The flags argument controls details of the transient behaviour.

      Parameters:
         * **parent** ("WlSurface") -- parent surface

         * **x** (*ArgumentType.Int*) -- surface-local x coordinate

         * **y** (*ArgumentType.Int*) -- surface-local y coordinate

         * **flags** (*ArgumentType.Uint*) -- transient surface
           behavior

   set_fullscreen(method: 'int', framerate: 'int', output: 'WlOutput | None') -> 'None'

      -[ Request -- opcode 5 (attached to "Resource" instance) ]-

      Make the surface a fullscreen surface

      Map the surface as a fullscreen surface.

      If an output parameter is given then the surface will be made
      fullscreen on that output. If the client does not specify the
      output then the compositor will apply its policy - usually
      choosing the output on which the surface has the biggest surface
      area.

      The client may specify a method to resolve a size conflict
      between the output size and the surface size - this is provided
      through the method parameter.

      The framerate parameter is used only when the method is set to
      "driver", to indicate the preferred framerate. A value of 0
      indicates that the client does not care about framerate.  The
      framerate is specified in mHz, that is framerate of 60000 is
      60Hz.

      A method of "scale" or "driver" implies a scaling operation of
      the surface, either via a direct scaling operation or a change
      of the output mode. This will override any kind of output
      scaling, so that mapping a surface with a buffer size equal to
      the mode can fill the screen independent of buffer_scale.

      A method of "fill" means we don't scale up the buffer, however
      any output scale is applied. This means that you may run into an
      edge case where the application maps a buffer with the same size
      of the output mode but buffer_scale 1 (thus making a surface
      larger than the output). In this case it is allowed to downscale
      the results to fit the screen.

      The compositor must reply to this request with a configure event
      with the dimensions for the output on which the surface will be
      made fullscreen.

      Parameters:
         * **method** (*ArgumentType.Uint*) -- method for resolving
           size conflict

         * **framerate** (*ArgumentType.Uint*) -- framerate in mHz

         * **output** ("WlOutput" or *None*) -- output on which the
           surface is to be fullscreen

   set_popup(seat: 'WlSeat', serial: 'int', parent: 'WlSurface', x: 'int', y: 'int', flags: 'int') -> 'None'

      -[ Request -- opcode 6 (attached to "Resource" instance) ]-

      Make the surface a popup surface

      Map the surface as a popup.

      A popup surface is a transient surface with an added pointer
      grab.

      An existing implicit grab will be changed to owner-events mode,
      and the popup grab will continue after the implicit grab ends
      (i.e. releasing the mouse button does not cause the popup to be
      unmapped).

      The popup grab continues until the window is destroyed or a
      mouse button is pressed in any other client's window. A click in
      any of the client's surfaces is reported as normal, however,
      clicks in other clients' surfaces will be discarded and trigger
      the callback.

      The x and y arguments specify the location of the upper left
      corner of the surface relative to the upper left corner of the
      parent surface, in surface-local coordinates.

      Parameters:
         * **seat** ("WlSeat") -- seat whose pointer is used

         * **serial** (*ArgumentType.Uint*) -- serial number of the
           implicit grab on the pointer

         * **parent** ("WlSurface") -- parent surface

         * **x** (*ArgumentType.Int*) -- surface-local x coordinate

         * **y** (*ArgumentType.Int*) -- surface-local y coordinate

         * **flags** (*ArgumentType.Uint*) -- transient surface
           behavior

   set_maximized(output: 'WlOutput | None') -> 'None'

      -[ Request -- opcode 7 (attached to "Resource" instance) ]-

      Make the surface a maximized surface

      Map the surface as a maximized surface.

      If an output parameter is given then the surface will be
      maximized on that output. If the client does not specify the
      output then the compositor will apply its policy - usually
      choosing the output on which the surface has the biggest surface
      area.

      The compositor will reply with a configure event telling the
      expected new surface size. The operation is completed on the
      next buffer attach to this surface.

      A maximized surface typically fills the entire output it is
      bound to, except for desktop elements such as panels. This is
      the main difference between a maximized shell surface and a
      fullscreen shell surface.

      The details depend on the compositor implementation.

      Parameters:
         **output** ("WlOutput" or *None*) -- output on which the
         surface is to be maximized

   set_title(title: 'str') -> 'None'

      -[ Request -- opcode 8 (attached to "Resource" instance) ]-

      Set surface title

      Set a short title for the surface.

      This string may be used to identify the surface in a task bar,
      window list, or other user interface elements provided by the
      compositor.

      The string must be encoded in UTF-8.

      Parameters:
         **title** (*ArgumentType.String*) -- surface title

   set_class(class_: 'str') -> 'None'

      -[ Request -- opcode 9 (attached to "Resource" instance) ]-

      Set surface class

      Set a class for the surface.

      The surface class identifies the general class of applications
      to which the surface belongs. A common convention is to use the
      file name (or the full path if it is a non-standard location) of
      the application's .desktop file as the class.

      Parameters:
         **class** (*ArgumentType.String*) -- surface class

   ping(serial: 'int') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Ping client

      Ping a client to check if it is receiving events and sending
      requests. A client is expected to reply with a pong request.

      Parameters:
         **serial** (*ArgumentType.Uint*) -- serial number of the ping

   configure(edges: 'int', width: 'int', height: 'int') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Suggest resize

      The configure event asks the client to resize its surface.

      The size is a hint, in the sense that the client is free to
      ignore it if it doesn't resize, pick a smaller size (to satisfy
      aspect ratio or resize in steps of NxM pixels).

      The edges parameter provides a hint about how the surface was
      resized. The client may use this information to decide how to
      adjust its content to the new size (e.g. a scrolling area might
      adjust its content position to leave the viewable content
      unmoved).

      The client is free to dismiss all but the last configure event
      it received.

      The width and height arguments specify the size of the window in
      surface-local coordinates.

      Parameters:
         * **edges** (*ArgumentType.Uint*) -- how the surface was
           resized

         * **width** (*ArgumentType.Int*) -- new width of the surface

         * **height** (*ArgumentType.Int*) -- new height of the
           surface

   popup_done() -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      Popup interaction is done

      The popup_done event is sent out when a popup grab is broken,
      that is, when the user clicks a surface that doesn't belong to
      the client owning the popup surface.


WlShm
=====

class pywayland.protocol.wayland.WlShm

   Shared memory support

   A singleton global object that provides support for shared memory.

   Clients can create "WlShmPool" objects using the create_pool
   request.

   On binding the "WlShm" object one or more format events are emitted
   to inform clients about the valid pixel formats that can be used
   for buffers.

   create_pool(fd: 'int', size: 'int') -> 'Proxy[WlShmPool]'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Create a shm pool

      Create a new "WlShmPool" object.

      The pool can be used to create shared memory based buffer
      objects.  The server will mmap size bytes of the passed file
      descriptor, to use as backing memory for the pool.

      Parameters:
         * **fd** (*ArgumentType.FileDescriptor*) -- file descriptor
           for the pool

         * **size** (*ArgumentType.Int*) -- pool size, in bytes

      Returns:
         "WlShmPool" -- pool to create

   release() -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Release the shm object

      Using this request a client can tell the server that it is not
      going to use the shm object anymore.

      Objects created via this interface remain unaffected.

   format(format: 'int') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Pixel format description

      Informs the client about a valid pixel format that can be used
      for buffers. Known formats include argb8888 and xrgb8888.

      Parameters:
         **format** (*ArgumentType.Uint*) -- buffer pixel format


WlShmPool
=========

class pywayland.protocol.wayland.WlShmPool

   A shared memory pool

   The "WlShmPool" object encapsulates a piece of memory shared
   between the compositor and client.  Through the "WlShmPool" object,
   the client can allocate shared memory "WlBuffer" objects. All
   objects created through the same pool share the same underlying
   mapped memory. Reusing the mapped memory avoids the setup/teardown
   overhead and is useful when interactively resizing a surface or for
   many small buffers.

   create_buffer(offset: 'int', width: 'int', height: 'int', stride: 'int', format: 'int') -> 'Proxy[WlBuffer]'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Create a buffer from the pool

      Create a "WlBuffer" object from the pool.

      The buffer is created offset bytes into the pool and has width
      and height as specified.  The stride argument specifies the
      number of bytes from the beginning of one row to the beginning
      of the next.  The format is the pixel format of the buffer and
      must be one of those advertised through the "WlShm.format()"
      event.

      A buffer will keep a reference to the pool it was created from
      so it is valid to destroy the pool immediately after creating a
      buffer from it.

      Parameters:
         * **offset** (*ArgumentType.Int*) -- buffer byte offset
           within the pool

         * **width** (*ArgumentType.Int*) -- buffer width, in pixels

         * **height** (*ArgumentType.Int*) -- buffer height, in pixels

         * **stride** (*ArgumentType.Int*) -- number of bytes from the
           beginning of one row to the beginning of the next row

         * **format** (*ArgumentType.Uint*) -- buffer pixel format

      Returns:
         "WlBuffer" -- buffer to create

   destroy() -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Destroy the pool

      Destroy the shared memory pool.

      The mmapped memory will be released when all buffers that have
      been created from this pool are gone.

   resize(size: 'int') -> 'None'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Change the size of the pool mapping

      This request will cause the server to remap the backing memory
      for the pool from the file descriptor passed when the pool was
      created, but using the new size.  This request can only be used
      to make the pool bigger.

      This request only changes the amount of bytes that are mmapped
      by the server and does not touch the file corresponding to the
      file descriptor passed at creation time. It is the client's
      responsibility to ensure that the file is at least as big as the
      new pool size.

      Parameters:
         **size** (*ArgumentType.Int*) -- new size of the pool, in
         bytes


WlSubcompositor
===============

class pywayland.protocol.wayland.WlSubcompositor

   Sub-surface compositing

   The global interface exposing sub-surface compositing capabilities.
   A "WlSurface", that has sub-surfaces associated, is called the
   parent surface. Sub-surfaces can be arbitrarily nested and create a
   tree of sub-surfaces.

   The root surface in a tree of sub-surfaces is the main surface. The
   main surface cannot be a sub-surface, because sub-surfaces must
   always have a parent.

   A main surface with its sub-surfaces forms a (compound) window. For
   window management purposes, this set of "WlSurface" objects is to
   be considered as a single window, and it should also behave as
   such.

   The aim of sub-surfaces is to offload some of the compositing work
   within a window from clients to the compositor. A prime example is
   a video player with decorations and video in separate "WlSurface"
   objects. This should allow the compositor to pass YUV video buffer
   processing to dedicated overlay hardware when possible.

   destroy() -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Unbind from the subcompositor interface

      Informs the server that the client will not be using this
      protocol object anymore. This does not affect any other objects,
      "WlSubsurface" objects included.

   get_subsurface(surface: 'WlSurface', parent: 'WlSurface') -> 'Proxy[WlSubsurface]'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Give a surface the role sub-surface

      Create a sub-surface interface for the given surface, and
      associate it with the given parent surface. This turns a plain
      "WlSurface" into a sub-surface.

      The to-be sub-surface must not already have another role, and it
      must not have an existing "WlSubsurface" object. Otherwise the
      bad_surface protocol error is raised.

      Adding sub-surfaces to a parent is a double-buffered operation
      on the parent (see "WlSurface.commit()"). The effect of adding a
      sub-surface becomes visible on the next time the state of the
      parent surface is applied.

      The parent surface must not be one of the child surface's
      descendants, and the parent must be different from the child
      surface, otherwise the bad_parent protocol error is raised.

      This request modifies the behaviour of "WlSurface.commit()"
      request on the sub- surface, see the documentation on
      "WlSubsurface" interface.

      Parameters:
         * **surface** ("WlSurface") -- the surface to be turned into
           a sub-surface

         * **parent** ("WlSurface") -- the parent surface

      Returns:
         "WlSubsurface" -- the new sub- surface object ID


WlSubsurface
============

class pywayland.protocol.wayland.WlSubsurface

   Sub-surface interface to a "WlSurface"

   An additional interface to a "WlSurface" object, which has been
   made a sub-surface. A sub-surface has one parent surface. A sub-
   surface's size and position are not limited to that of the parent.
   Particularly, a sub-surface is not automatically clipped to its
   parent's area.

   A sub-surface becomes mapped, when a non-NULL "WlBuffer" is applied
   and the parent surface is mapped. The order of which one happens
   first is irrelevant. A sub-surface is hidden if the parent becomes
   hidden, or if a NULL "WlBuffer" is applied. These rules apply
   recursively through the tree of surfaces.

   The behaviour of a "WlSurface.commit()" request on a sub-surface
   depends on the sub-surface's mode. The possible modes are
   synchronized and desynchronized, see methods
   "WlSubsurface.set_sync()" and "WlSubsurface.set_desync()".
   Synchronized mode caches the "WlSurface" state to be applied when
   the parent's state gets applied, and desynchronized mode applies
   the pending "WlSurface" state directly. A sub- surface is initially
   in the synchronized mode.

   Sub-surfaces also have another kind of state, which is managed by
   "WlSubsurface" requests, as opposed to "WlSurface" requests. This
   state includes the sub-surface position relative to the parent
   surface ("WlSubsurface.set_position()"), and the stacking order of
   the parent and its sub-surfaces ("WlSubsurface.place_above()" and
   .place_below). This state is applied when the parent surface's
   "WlSurface" state is applied, regardless of the sub-surface's mode.
   As the exception, set_sync and set_desync are effective
   immediately.

   The main surface can be thought to be always in desynchronized
   mode, since it does not have a parent in the sub-surfaces sense.

   Even if a sub-surface is in desynchronized mode, it will behave as
   in synchronized mode, if its parent surface behaves as in
   synchronized mode. This rule is applied recursively throughout the
   tree of surfaces. This means, that one can set a sub-surface into
   synchronized mode, and then assume that all its child and grand-
   child sub-surfaces are synchronized, too, without explicitly
   setting them.

   Destroying a sub-surface takes effect immediately. If you need to
   synchronize the removal of a sub-surface to the parent surface
   update, unmap the sub-surface first by attaching a NULL "WlBuffer",
   update parent, and then destroy the sub-surface.

   If the parent "WlSurface" object is destroyed, the sub-surface is
   unmapped.

   A sub-surface never has the keyboard focus of any seat.

   The "WlSurface.offset()" request is ignored: clients must use
   set_position instead to move the sub-surface.

   destroy() -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Remove sub-surface interface

      The sub-surface interface is removed from the "WlSurface" object
      that was turned into a sub-surface with a
      "WlSubcompositor.get_subsurface()" request. The wl_surface's
      association to the parent is deleted. The "WlSurface" is
      unmapped immediately.

   set_position(x: 'int', y: 'int') -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Reposition the sub-surface

      This schedules a sub-surface position change. The sub-surface
      will be moved so that its origin (top left corner pixel) will be
      at the location x, y of the parent surface coordinate system.
      The coordinates are not restricted to the parent surface area.
      Negative values are allowed.

      The scheduled coordinates will take effect whenever the state of
      the parent surface is applied.

      If more than one set_position request is invoked by the client
      before the commit of the parent surface, the position of a new
      request always replaces the scheduled position from any previous
      request.

      The initial position is 0, 0.

      Parameters:
         * **x** (*ArgumentType.Int*) -- x coordinate in the parent
           surface

         * **y** (*ArgumentType.Int*) -- y coordinate in the parent
           surface

   place_above(sibling: 'WlSurface') -> 'None'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Restack the sub-surface

      This sub-surface is taken from the stack, and put back just
      above the reference surface, changing the z-order of the sub-
      surfaces. The reference surface must be one of the sibling
      surfaces, or the parent surface. Using any other surface,
      including this sub-surface, will cause a protocol error.

      The z-order is double-buffered. Requests are handled in order
      and applied immediately to a pending state. The final pending
      state is copied to the active state the next time the state of
      the parent surface is applied.

      A new sub-surface is initially added as the top-most in the
      stack of its siblings and parent.

      Parameters:
         **sibling** ("WlSurface") -- the reference surface

   place_below(sibling: 'WlSurface') -> 'None'

      -[ Request -- opcode 3 (attached to "Resource" instance) ]-

      Restack the sub-surface

      The sub-surface is placed just below the reference surface. See
      "WlSubsurface.place_above()".

      Parameters:
         **sibling** ("WlSurface") -- the reference surface

   set_sync() -> 'None'

      -[ Request -- opcode 4 (attached to "Resource" instance) ]-

      Set sub-surface to synchronized mode

      Change the commit behaviour of the sub-surface to synchronized
      mode, also described as the parent dependent mode.

      In synchronized mode, "WlSurface.commit()" on a sub-surface will
      accumulate the committed state in a cache, but the state will
      not be applied and hence will not change the compositor output.
      The cached state is applied to the sub-surface immediately after
      the parent surface's state is applied. This ensures atomic
      updates of the parent and all its synchronized sub-surfaces.
      Applying the cached state will invalidate the cache, so further
      parent surface commits do not (re-)apply old state.

      See "WlSubsurface" for the recursive effect of this mode.

   set_desync() -> 'None'

      -[ Request -- opcode 5 (attached to "Resource" instance) ]-

      Set sub-surface to desynchronized mode

      Change the commit behaviour of the sub-surface to desynchronized
      mode, also described as independent or freely running mode.

      In desynchronized mode, "WlSurface.commit()" on a sub-surface
      will apply the pending state directly, without caching, as
      happens normally with a "WlSurface". Calling
      "WlSurface.commit()" on the parent surface has no effect on the
      sub-surface's "WlSurface" state. This mode allows a sub-surface
      to be updated on its own.

      If cached state exists when "WlSurface.commit()" is called in
      desynchronized mode, the pending state is added to the cached
      state, and applied as a whole. This invalidates the cache.

      Note: even if a sub-surface is set to desynchronized, a parent
      sub- surface may override it to behave as synchronized. For
      details, see "WlSubsurface".

      If a surface's parent surface behaves as desynchronized, then
      the cached state is applied on set_desync.


WlSurface
=========

class pywayland.protocol.wayland.WlSurface

   An onscreen surface

   A surface is a rectangular area that may be displayed on zero or
   more outputs, and shown any number of times at the compositor's
   discretion. They can present wl_buffers, receive user input, and
   define a local coordinate system.

   The size of a surface (and relative positions on it) is described
   in surface-local coordinates, which may differ from the buffer
   coordinates of the pixel content, in case a buffer_transform or a
   buffer_scale is used.

   A surface without a "role" is fairly useless: a compositor does not
   know where, when or how to present it. The role is the purpose of a
   "WlSurface". Examples of roles are a cursor for a pointer (as set
   by "WlPointer.set_cursor()"), a drag icon
   ("WlDataDevice.start_drag()"), a sub-surface
   ("WlSubcompositor.get_subsurface()"), and a window as defined by a
   shell protocol (e.g. "WlShell.get_shell_surface()").

   A surface can have only one role at a time. Initially a "WlSurface"
   does not have a role. Once a "WlSurface" is given a role, it is set
   permanently for the whole lifetime of the "WlSurface" object.
   Giving the current role again is allowed, unless explicitly
   forbidden by the relevant interface specification.

   Surface roles are given by requests in other interfaces such as
   "WlPointer.set_cursor()". The request should explicitly mention
   that this request gives a role to a "WlSurface". Often, this
   request also creates a new protocol object that represents the role
   and adds additional functionality to "WlSurface". When a client
   wants to destroy a "WlSurface", they must destroy this role object
   before the "WlSurface", otherwise a defunct_role_object error is
   sent.

   Destroying the role object does not remove the role from the
   "WlSurface", but it may stop the "WlSurface" from "playing the
   role". For instance, if a "WlSubsurface" object is destroyed, the
   "WlSurface" it was created for will be unmapped and forget its
   position and z-order. It is allowed to create a "WlSubsurface" for
   the same "WlSurface" again, but it is not allowed to use the
   "WlSurface" as a cursor (cursor is a different role than sub-
   surface, and role switching is not allowed).

   destroy() -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Delete surface

      Deletes the surface and invalidates its object ID.

   attach(buffer: 'WlBuffer | None', x: 'int', y: 'int') -> 'None'

      -[ Request -- opcode 1 (attached to "Resource" instance) ]-

      Set the surface contents

      Set a buffer as the content of this surface.

      The new size of the surface is calculated based on the buffer
      size transformed by the inverse buffer_transform and the inverse
      buffer_scale. This means that at commit time the supplied buffer
      size must be an integer multiple of the buffer_scale. If that's
      not the case, an invalid_size error is sent.

      The x and y arguments specify the location of the new pending
      buffer's upper left corner, relative to the current buffer's
      upper left corner, in surface-local coordinates. In other words,
      the x and y, combined with the new surface size define in which
      directions the surface's size changes. Setting anything other
      than 0 as x and y arguments is discouraged, and should instead
      be replaced with using the separate "WlSurface.offset()"
      request.

      When the bound "WlSurface" version is 5 or higher, passing any
      non-zero x or y is a protocol violation, and will result in an
      'invalid_offset' error being raised. The x and y arguments are
      ignored and do not change the pending state. To achieve
      equivalent semantics, use "WlSurface.offset()".

      Surface contents are double-buffered state, see
      "WlSurface.commit()".

      The initial surface contents are void; there is no content.
      "WlSurface.attach()" assigns the given "WlBuffer" as the pending
      "WlBuffer". "WlSurface.commit()" makes the pending "WlBuffer"
      the new surface contents, and the size of the surface becomes
      the size calculated from the "WlBuffer", as described above.
      After commit, there is no pending buffer until the next attach.

      Committing a pending "WlBuffer" allows the compositor to read
      the pixels in the "WlBuffer". The compositor may access the
      pixels at any time after the "WlSurface.commit()" request. When
      the compositor will not access the pixels anymore, it will send
      the "WlBuffer.release()" event. Only after receiving
      "WlBuffer.release()", the client may reuse the "WlBuffer". A
      "WlBuffer" that has been attached and then replaced by another
      attach instead of committed will not receive a release event,
      and is not used by the compositor.

      If a pending "WlBuffer" has been committed to more than one
      "WlSurface", the delivery of "WlBuffer.release()" events becomes
      undefined. A well behaved client should not rely on
      "WlBuffer.release()" events in this case. Alternatively, a
      client could create multiple "WlBuffer" objects from the same
      backing storage or use wp_linux_buffer_release.

      Destroying the "WlBuffer" after "WlBuffer.release()" does not
      change the surface contents. Destroying the "WlBuffer" before
      "WlBuffer.release()" is allowed as long as the underlying buffer
      storage isn't re-used (this can happen e.g. on client process
      termination). However, if the client destroys the "WlBuffer"
      before receiving the "WlBuffer.release()" event and mutates the
      underlying buffer storage, the surface contents become undefined
      immediately.

      If "WlSurface.attach()" is sent with a NULL "WlBuffer", the
      following "WlSurface.commit()" will remove the surface content.

      If a pending "WlBuffer" has been destroyed, the result is not
      specified. Many compositors are known to remove the surface
      content on the following "WlSurface.commit()", but this
      behaviour is not universal. Clients seeking to maximise
      compatibility should not destroy pending buffers and should
      ensure that they explicitly remove content from surfaces, even
      after destroying buffers.

      Parameters:
         * **buffer** ("WlBuffer" or *None*) -- buffer of surface
           contents

         * **x** (*ArgumentType.Int*) -- surface-local x coordinate

         * **y** (*ArgumentType.Int*) -- surface-local y coordinate

   damage(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None'

      -[ Request -- opcode 2 (attached to "Resource" instance) ]-

      Mark part of the surface damaged

      This request is used to describe the regions where the pending
      buffer is different from the current surface contents, and where
      the surface therefore needs to be repainted. The compositor
      ignores the parts of the damage that fall outside of the
      surface.

      Damage is double-buffered state, see "WlSurface.commit()".

      The damage rectangle is specified in surface-local coordinates,
      where x and y specify the upper left corner of the damage
      rectangle.

      The initial value for pending damage is empty: no damage.
      "WlSurface.damage()" adds pending damage: the new pending damage
      is the union of old pending damage and the given rectangle.

      "WlSurface.commit()" assigns pending damage as the current
      damage, and clears pending damage. The server will clear the
      current damage as it repaints the surface.

      Note! New clients should not use this request. Instead damage
      can be posted with "WlSurface.damage_buffer()" which uses buffer
      coordinates instead of surface coordinates.

      Parameters:
         * **x** (*ArgumentType.Int*) -- surface-local x coordinate

         * **y** (*ArgumentType.Int*) -- surface-local y coordinate

         * **width** (*ArgumentType.Int*) -- width of damage rectangle

         * **height** (*ArgumentType.Int*) -- height of damage
           rectangle

   frame() -> 'Proxy[WlCallback]'

      -[ Request -- opcode 3 (attached to "Resource" instance) ]-

      Request a frame throttling hint

      Request a notification when it is a good time to start drawing a
      new frame, by creating a frame callback. This is useful for
      throttling redrawing operations, and driving animations.

      When a client is animating on a "WlSurface", it can use the
      'frame' request to get notified when it is a good time to draw
      and commit the next frame of animation. If the client commits an
      update earlier than that, it is likely that some updates will
      not make it to the display, and the client is wasting resources
      by drawing too often.

      The frame request will take effect on the next
      "WlSurface.commit()". The notification will only be posted for
      one frame unless requested again. For a "WlSurface", the
      notifications are posted in the order the frame requests were
      committed.

      The server must send the notifications so that a client will not
      send excessive updates, while still allowing the highest
      possible update rate for clients that wait for the reply before
      drawing again. The server should give some time for the client
      to draw and commit after sending the frame callback events to
      let it hit the next output refresh.

      A server should avoid signaling the frame callbacks if the
      surface is not visible in any way, e.g. the surface is off-
      screen, or completely obscured by other opaque surfaces.

      The object returned by this request will be destroyed by the
      compositor after the callback is fired and as such the client
      must not attempt to use it after that point.

      The callback_data passed in the callback is the current time, in
      milliseconds, with an undefined base.

      Returns:
         "WlCallback" -- callback object for the frame request

   set_opaque_region(region: 'WlRegion | None') -> 'None'

      -[ Request -- opcode 4 (attached to "Resource" instance) ]-

      Set opaque region

      This request sets the region of the surface that contains opaque
      content.

      The opaque region is an optimization hint for the compositor
      that lets it optimize the redrawing of content behind opaque
      regions.  Setting an opaque region is not required for correct
      behaviour, but marking transparent content as opaque will result
      in repaint artifacts.

      The opaque region is specified in surface-local coordinates.

      The compositor ignores the parts of the opaque region that fall
      outside of the surface.

      Opaque region is double-buffered state, see
      "WlSurface.commit()".

      "WlSurface.set_opaque_region()" changes the pending opaque
      region. "WlSurface.commit()" copies the pending region to the
      current region. Otherwise, the pending and current regions are
      never changed.

      The initial value for an opaque region is empty. Setting the
      pending opaque region has copy semantics, and the "WlRegion"
      object can be destroyed immediately. A NULL "WlRegion" causes
      the pending opaque region to be set to empty.

      Parameters:
         **region** ("WlRegion" or *None*) -- opaque region of the
         surface

   set_input_region(region: 'WlRegion | None') -> 'None'

      -[ Request -- opcode 5 (attached to "Resource" instance) ]-

      Set input region

      This request sets the region of the surface that can receive
      pointer and touch events.

      Input events happening outside of this region will try the next
      surface in the server surface stack. The compositor ignores the
      parts of the input region that fall outside of the surface.

      The input region is specified in surface-local coordinates.

      Input region is double-buffered state, see "WlSurface.commit()".

      "WlSurface.set_input_region()" changes the pending input region.
      "WlSurface.commit()" copies the pending region to the current
      region. Otherwise the pending and current regions are never
      changed, except cursor and icon surfaces are special cases, see
      "WlPointer.set_cursor()" and "WlDataDevice.start_drag()".

      The initial value for an input region is infinite. That means
      the whole surface will accept input. Setting the pending input
      region has copy semantics, and the "WlRegion" object can be
      destroyed immediately. A NULL "WlRegion" causes the input region
      to be set to infinite.

      Parameters:
         **region** ("WlRegion" or *None*) -- input region of the
         surface

   commit() -> 'None'

      -[ Request -- opcode 6 (attached to "Resource" instance) ]-

      Commit pending surface state

      Surface state (input, opaque, and damage regions, attached
      buffers, etc.) is double-buffered. Protocol requests modify the
      pending state, as opposed to the active state in use by the
      compositor.

      A commit request atomically creates a content update from the
      pending state, even if the pending state has not been touched.
      The content update is placed in a queue until it becomes active.
      After commit, the new pending state is as documented for each
      related request.

      When the content update is applied, the "WlBuffer" is applied
      before all other state. This means that all coordinates in
      double-buffered state are relative to the newly attached
      wl_buffers, except for "WlSurface.attach()" itself. If there is
      no newly attached "WlBuffer", the coordinates are relative to
      the previous content update.

      All requests that need a commit to become effective are
      documented to affect double-buffered state.

      Other interfaces may add further double-buffered surface state.

   set_buffer_transform(transform: 'int') -> 'None'

      -[ Request -- opcode 7 (attached to "Resource" instance) ]-

      Sets the buffer transformation

      This request sets the transformation that the client has already
      applied to the content of the buffer. The accepted values for
      the transform parameter are the values for
      "WlOutput.transform()".

      The compositor applies the inverse of this transformation
      whenever it uses the buffer contents.

      Buffer transform is double-buffered state, see
      "WlSurface.commit()".

      A newly created surface has its buffer transformation set to
      normal.

      "WlSurface.set_buffer_transform()" changes the pending buffer
      transformation. "WlSurface.commit()" copies the pending buffer
      transformation to the current one. Otherwise, the pending and
      current values are never changed.

      The purpose of this request is to allow clients to render
      content according to the output transform, thus permitting the
      compositor to use certain optimizations even if the display is
      rotated. Using hardware overlays and scanning out a client
      buffer for fullscreen surfaces are examples of such
      optimizations. Those optimizations are highly dependent on the
      compositor implementation, so the use of this request should be
      considered on a case-by-case basis.

      Note that if the transform value includes 90 or 270 degree
      rotation, the width of the buffer will become the surface height
      and the height of the buffer will become the surface width.

      If transform is not one of the values from the
      "WlOutput.transform()" enum the invalid_transform protocol error
      is raised.

      Parameters:
         **transform** (*ArgumentType.Int*) -- transform for
         interpreting buffer contents

   set_buffer_scale(scale: 'int') -> 'None'

      -[ Request -- opcode 8 (attached to "Resource" instance) ]-

      Sets the buffer scaling factor

      This request sets an optional scaling factor on how the
      compositor interprets the contents of the buffer attached to the
      window.

      Buffer scale is double-buffered state, see "WlSurface.commit()".

      A newly created surface has its buffer scale set to 1.

      "WlSurface.set_buffer_scale()" changes the pending buffer scale.
      "WlSurface.commit()" copies the pending buffer scale to the
      current one. Otherwise, the pending and current values are never
      changed.

      The purpose of this request is to allow clients to supply higher
      resolution buffer data for use on high resolution outputs. It is
      intended that you pick the same buffer scale as the scale of the
      output that the surface is displayed on. This means the
      compositor can avoid scaling when rendering the surface on that
      output.

      Note that if the scale is larger than 1, then you have to attach
      a buffer that is larger (by a factor of scale in each dimension)
      than the desired surface size.

      If scale is not greater than 0 the invalid_scale protocol error
      is raised.

      Parameters:
         **scale** (*ArgumentType.Int*) -- scale for interpreting
         buffer contents

   damage_buffer(x: 'int', y: 'int', width: 'int', height: 'int') -> 'None'

      -[ Request -- opcode 9 (attached to "Resource" instance) ]-

      Mark part of the surface damaged using buffer coordinates

      This request is used to describe the regions where the pending
      buffer is different from the current surface contents, and where
      the surface therefore needs to be repainted. The compositor
      ignores the parts of the damage that fall outside of the
      surface.

      Damage is double-buffered state, see "WlSurface.commit()".

      The damage rectangle is specified in buffer coordinates, where x
      and y specify the upper left corner of the damage rectangle.

      The initial value for pending damage is empty: no damage.
      "WlSurface.damage_buffer()" adds pending damage: the new pending
      damage is the union of old pending damage and the given
      rectangle.

      "WlSurface.commit()" assigns pending damage as the current
      damage, and clears pending damage. The server will clear the
      current damage as it repaints the surface.

      This request differs from "WlSurface.damage()" in only one way -
      it takes damage in buffer coordinates instead of surface-local
      coordinates. While this generally is more intuitive than surface
      coordinates, it is especially desirable when using wp_viewport
      or when a drawing library (like EGL) is unaware of buffer scale
      and buffer transform.

      Note: Because buffer transformation changes and damage requests
      may be interleaved in the protocol stream, it is impossible to
      determine the actual mapping between surface and buffer damage
      until "WlSurface.commit()" time. Therefore, compositors wishing
      to take both kinds of damage into account will have to
      accumulate damage from the two requests separately and only
      transform from one to the other after receiving the
      "WlSurface.commit()".

      Parameters:
         * **x** (*ArgumentType.Int*) -- buffer-local x coordinate

         * **y** (*ArgumentType.Int*) -- buffer-local y coordinate

         * **width** (*ArgumentType.Int*) -- width of damage rectangle

         * **height** (*ArgumentType.Int*) -- height of damage
           rectangle

   offset(x: 'int', y: 'int') -> 'None'

      -[ Request -- opcode 10 (attached to "Resource" instance) ]-

      Set the surface contents offset

      The x and y arguments specify the location of the new pending
      buffer's upper left corner, relative to the current buffer's
      upper left corner, in surface-local coordinates. In other words,
      the x and y, combined with the new surface size define in which
      directions the surface's size changes.

      Surface location offset is double-buffered state, see
      "WlSurface.commit()".

      This request is semantically equivalent to and the replaces the
      x and y arguments in the "WlSurface.attach()" request in
      "WlSurface" versions prior to 5. See "WlSurface.attach()" for
      details.

      Parameters:
         * **x** (*ArgumentType.Int*) -- surface-local x coordinate

         * **y** (*ArgumentType.Int*) -- surface-local y coordinate

   enter(output: 'WlOutput') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Surface enters an output

      This is emitted whenever a surface's creation, movement, or
      resizing results in some part of it being within the scanout
      region of an output.

      Note that a surface may be overlapping with zero or more
      outputs.

      Parameters:
         **output** ("WlOutput") -- output entered by the surface

   leave(output: 'WlOutput') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      Surface leaves an output

      This is emitted whenever a surface's creation, movement, or
      resizing results in it no longer having any part of it within
      the scanout region of an output.

      Clients should not use the number of outputs the surface is on
      for frame throttling purposes. The surface might be hidden even
      if no leave event has been sent, and the compositor might expect
      new surface content updates even if no enter event has been
      sent. The frame event should be used instead.

      Parameters:
         **output** ("WlOutput") -- output left by the surface

   preferred_buffer_scale(factor: 'int') -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      Preferred buffer scale for the surface

      This event indicates the preferred buffer scale for this
      surface. It is sent whenever the compositor's preference
      changes.

      Before receiving this event the preferred buffer scale for this
      surface is 1.

      It is intended that scaling aware clients use this event to
      scale their content and use "WlSurface.set_buffer_scale()" to
      indicate the scale they have rendered with. This allows clients
      to supply a higher detail buffer.

      The compositor shall emit a scale value greater than 0.

      Parameters:
         **factor** (*ArgumentType.Int*) -- preferred scaling factor

   preferred_buffer_transform(transform: 'int') -> 'None'

      -[ Event -- opcode 3 (attached to "Proxy" instance) ]-

      Preferred buffer transform for the surface

      This event indicates the preferred buffer transform for this
      surface. It is sent whenever the compositor's preference
      changes.

      Before receiving this event the preferred buffer transform for
      this surface is normal.

      Applying this transformation to the surface buffer contents and
      using "WlSurface.set_buffer_transform()" might allow the
      compositor to use the surface buffer more efficiently.

      Parameters:
         **transform** (*ArgumentType.Uint*) -- preferred transform


WlTouch
=======

class pywayland.protocol.wayland.WlTouch

   Touchscreen input device

   The "WlTouch" interface represents a touchscreen associated with a
   seat.

   Touch interactions can consist of one or more contacts. For each
   contact, a series of events is generated, starting with a down
   event, followed by zero or more motion events, and ending with an
   up event. Events relating to the same contact point can be
   identified by the ID of the sequence.

   release() -> 'None'

      -[ Request -- opcode 0 (attached to "Resource" instance) ]-

      Release the touch object

   down(serial: 'int', time: 'int', surface: 'WlSurface', id: 'int', x: 'float', y: 'float') -> 'None'

      -[ Event -- opcode 0 (attached to "Proxy" instance) ]-

      Touch down event and beginning of a touch sequence

      A new touch point has appeared on the surface. This touch point
      is assigned a unique ID. Future events from this touch point
      reference this ID. The ID ceases to be valid after a touch up
      event and may be reused in the future.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           touch down event

         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **surface** ("WlSurface") -- surface touched

         * **id** (*ArgumentType.Int*) -- the unique ID of this touch
           point

         * **x** (*ArgumentType.Fixed*) -- surface-local x coordinate

         * **y** (*ArgumentType.Fixed*) -- surface-local y coordinate

   up(serial: 'int', time: 'int', id: 'int') -> 'None'

      -[ Event -- opcode 1 (attached to "Proxy" instance) ]-

      End of a touch event sequence

      The touch point has disappeared. No further events will be sent
      for this touch point and the touch point's ID is released and
      may be reused in a future touch down event.

      Parameters:
         * **serial** (*ArgumentType.Uint*) -- serial number of the
           touch up event

         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **id** (*ArgumentType.Int*) -- the unique ID of this touch
           point

   motion(time: 'int', id: 'int', x: 'float', y: 'float') -> 'None'

      -[ Event -- opcode 2 (attached to "Proxy" instance) ]-

      Update of touch point coordinates

      A touch point has changed coordinates.

      Parameters:
         * **time** (*ArgumentType.Uint*) -- timestamp with
           millisecond granularity

         * **id** (*ArgumentType.Int*) -- the unique ID of this touch
           point

         * **x** (*ArgumentType.Fixed*) -- surface-local x coordinate

         * **y** (*ArgumentType.Fixed*) -- surface-local y coordinate

   frame() -> 'None'

      -[ Event -- opcode 3 (attached to "Proxy" instance) ]-

      End of touch frame event

      Indicates the end of a set of events that logically belong
      together. A client is expected to accumulate the data in all
      events within the frame before proceeding.

      A "WlTouch.frame()" terminates at least one event but otherwise
      no guarantee is provided about the set of events within a frame.
      A client must assume that any state not updated in a frame is
      unchanged from the previously known state.

   cancel() -> 'None'

      -[ Event -- opcode 4 (attached to "Proxy" instance) ]-

      Touch session cancelled

      Sent if the compositor decides the touch stream is a global
      gesture. No further events are sent to the clients from that
      particular gesture. Touch cancellation applies to all touch
      points currently active on this client's surface. The client is
      responsible for finalizing the touch points, future touch points
      on this surface may reuse the touch point ID.

      No frame event is required after the cancel event.

   shape(id: 'int', major: 'float', minor: 'float') -> 'None'

      -[ Event -- opcode 5 (attached to "Proxy" instance) ]-

      Update shape of touch point

      Sent when a touchpoint has changed its shape.

      This event does not occur on its own. It is sent before a
      "WlTouch.frame()" event and carries the new shape information
      for any previously reported, or new touch points of that frame.

      Other events describing the touch point such as
      "WlTouch.down()", "WlTouch.motion()" or "WlTouch.orientation()"
      may be sent within the same "WlTouch.frame()". A client should
      treat these events as a single logical touch point update. The
      order of "WlTouch.shape()", "WlTouch.orientation()" and
      "WlTouch.motion()" is not guaranteed. A "WlTouch.down()" event
      is guaranteed to occur before the first "WlTouch.shape()" event
      for this touch ID but both events may occur within the same
      "WlTouch.frame()".

      A touchpoint shape is approximated by an ellipse through the
      major and minor axis length. The major axis length describes the
      longer diameter of the ellipse, while the minor axis length
      describes the shorter diameter. Major and minor are orthogonal
      and both are specified in surface-local coordinates. The center
      of the ellipse is always at the touchpoint location as reported
      by "WlTouch.down()" or "WlTouch.move()".

      This event is only sent by the compositor if the touch device
      supports shape reports. The client has to make reasonable
      assumptions about the shape if it did not receive this event.

      Parameters:
         * **id** (*ArgumentType.Int*) -- the unique ID of this touch
           point

         * **major** (*ArgumentType.Fixed*) -- length of the major
           axis in surface-local coordinates

         * **minor** (*ArgumentType.Fixed*) -- length of the minor
           axis in surface-local coordinates

   orientation(id: 'int', orientation: 'float') -> 'None'

      -[ Event -- opcode 6 (attached to "Proxy" instance) ]-

      Update orientation of touch point

      Sent when a touchpoint has changed its orientation.

      This event does not occur on its own. It is sent before a
      "WlTouch.frame()" event and carries the new shape information
      for any previously reported, or new touch points of that frame.

      Other events describing the touch point such as
      "WlTouch.down()", "WlTouch.motion()" or "WlTouch.shape()" may be
      sent within the same "WlTouch.frame()". A client should treat
      these events as a single logical touch point update. The order
      of "WlTouch.shape()", "WlTouch.orientation()" and
      "WlTouch.motion()" is not guaranteed. A "WlTouch.down()" event
      is guaranteed to occur before the first "WlTouch.orientation()"
      event for this touch ID but both events may occur within the
      same "WlTouch.frame()".

      The orientation describes the clockwise angle of a touchpoint's
      major axis to the positive surface y-axis and is normalized to
      the -180 to +180 degree range. The granularity of orientation
      depends on the touch device, some devices only support binary
      rotation values between 0 and 90 degrees.

      This event is only sent by the compositor if the touch device
      supports orientation reports.

      Parameters:
         * **id** (*ArgumentType.Int*) -- the unique ID of this touch
           point

         * **orientation** (*ArgumentType.Fixed*) -- angle between
           major axis and positive surface y-axis in degrees
