:right-sidebar: True

DataSourceRequest
===================================================================

.. currentmodule:: gi.repository.Shumate


.. versionadded:: 1.1




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


Superclasses: :class:`~gi.repository.GObject.Object`





Represents a request to a :obj:`~gi.repository.Shumate.DataSource` for a tile.

Data sources can return a tile multiple times. For example, a
:obj:`~gi.repository.Shumate.TileDownloader` may return cached data first, then later return data
from a network service when it arrives. This allows the map to be rendered
as quickly as possible without waiting for the network unnecessarily.

Conventional async/finish method pairs don't support multiple returns.
Instead, :obj:`~gi.repository.DataSource.start_request` is available, which returns a
:obj:`~gi.repository.Shumate.DataSourceRequest` whose properties, :obj:`~gi.repository.Shumate.DataSourceRequest.props.data`
and :obj:`~gi.repository.Shumate.DataSourceRequest.props.error`\, update as data becomes available.
The :obj:`~gi.repository.GObject.Object.signals.notify` signal can be used to watch for these
changes. When the request is done and no more data will be returned,
:obj:`~gi.repository.Shumate.DataSourceRequest.props.completed` is set to :const:`True`.

:obj:`~gi.repository.Shumate.DataSource` implementations can use a subclass of
:obj:`~gi.repository.Shumate.DataSourceRequest`\, but the base class should be sufficient in most
cases.


Constructors
------------

.. rst-class:: interim-class

.. class:: DataSourceRequest
   :no-index:


   .. classmethod:: new(x: int, y: int, zoom_level: int) -> ~gi.repository.Shumate.DataSourceRequest

      Creates a new :obj:`~gi.repository.Shumate.DataSourceRequest`\.

      Only implementations of :obj:`~gi.repository.DataSource.start_request` should need to
      construct a new request object.


      .. versionadded:: 1.1





      :param x: X coordinate of the requested tile

      :param y: Y coordinate of the requested tile

      :param zoom_level: Zoom level of the requested tile








Methods
-------

.. rst-class:: interim-class

.. class:: DataSourceRequest
   :no-index:


   .. method:: complete() -> None

      Marks the request as complete. No more data or errors may be emitted.

      This can only be called if data has been emitted. If there is no data,
      use :obj:`~gi.repository.DataSourceRequest.emit_error` instead, which will automatically
      complete the request.


      .. versionadded:: 1.1








   .. method:: emit_data(data: ~gi.repository.GLib.Bytes, complete: bool) -> None

      Emits tile data as a response to the request. This sets the
      :obj:`~gi.repository.Shumate.DataSourceRequest.props.data` property.

      If ``complete`` is :const:`True`, then :obj:`~gi.repository.Shumate.DataSourceRequest.props.completed` is set to
      :const:`True` as well.


      .. versionadded:: 1.1





      :param data: the data to emit

      :param complete: :const:`True` to also complete the request, :const:`False` otherwise




   .. method:: emit_error(error: ~gi.repository.GLib.GError) -> None

      Emits a fatal error in response to the request. This completes the request,
      so no more data or errors can be emitted after this. Non-fatal errors should
      not be reported.

      If :obj:`~gi.repository.Shumate.DataSourceRequest.props.data` was previously set, it will be cleared.


      .. versionadded:: 1.1





      :param error: an error




   .. method:: get_data() -> ~gi.repository.GLib.Bytes | None

      Gets the latest data from the request.


      .. versionadded:: 1.1








   .. method:: get_error() -> ~gi.repository.GLib.GError | None

      Gets the latest error from the request.


      .. versionadded:: 1.1








   .. method:: get_x() -> int

      Gets the X coordinate of the requested tile.


      .. versionadded:: 1.1








   .. method:: get_y() -> int

      Gets the Y coordinate of the requested tile.


      .. versionadded:: 1.1








   .. method:: get_zoom_level() -> int

      Gets the zoom level of the requested tile.


      .. versionadded:: 1.1








   .. method:: is_completed() -> bool

      Gets whether the request has been completed. Completed requests will not
      receive new data or errors.


      .. versionadded:: 1.1












Properties
----------

.. rst-class:: interim-class

.. class:: DataSourceRequest
   :no-index:
   

   .. attribute:: props.completed
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.1





   .. attribute:: props.data
      :type: ~gi.repository.GLib.Bytes

      The type of the None singleton.



      .. versionadded:: 1.1





   .. attribute:: props.error
      :type: ~gi.repository.GLib.GError

      The type of the None singleton.



      .. versionadded:: 1.1





   .. attribute:: props.x
      :type: int

      The type of the None singleton.



      .. versionadded:: 1.1





   .. attribute:: props.y
      :type: int

      The type of the None singleton.



      .. versionadded:: 1.1





   .. attribute:: props.zoom_level
      :type: int

      The type of the None singleton.



      .. versionadded:: 1.1













Fields
------

.. rst-class:: interim-class

.. class:: DataSourceRequest
   :no-index:
   

   .. attribute:: parent_instance