:right-sidebar: True

VectorSpriteSheet
===================================================================

.. currentmodule:: gi.repository.Shumate


.. versionadded:: 1.1




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


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





A collection of :obj:`~gi.repository.Shumate.VectorSprite`\s.

Sprites are used as icons in symbols or as the pattern for a fill layer.

Most MapLibre stylesheets provide their spritesheet as a PNG image and a JSON
description of the sprites. This spritesheet can be added using
:obj:`~gi.repository.VectorSpriteSheet.add_page`\. Sprites can also be added individually
using :obj:`~gi.repository.VectorSpriteSheet.add_sprite`\.

Some map styles rely on application code to provide some or all of their
sprites. This is supported using a fallback function, which can be set using
:obj:`~gi.repository.VectorSpriteSheet.set_fallback`\. This function can generate sprites
on demand. For example, it could load a symbolic icon from the :obj:`~gi.repository.Gtk.IconTheme`
or render a custom highway shield.

HiDPI support
--------------------------------------------------------------------------------

Map styles should provide a double resolution spritesheet for high DPI
displays. That spritesheet can be added as a separate page.
The :obj:`~gi.repository.Shumate.VectorSpriteSheet` will pick the best sprites for the display's
scale factor.

If a fallback function is set, it receives the requested scale factor
as an argument. It should use this to generate the sprite at the correct size.
For example, if the scale factor is 2, the image should be twice as large
(but the *sprite's* width and height should be the same).

Thread Safety
--------------------------------------------------------------------------------

:obj:`~gi.repository.Shumate.VectorSpriteSheet` is thread safe.


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

.. rst-class:: interim-class

.. class:: VectorSpriteSheet
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Shumate.VectorSpriteSheet

      Creates a new, empty :obj:`~gi.repository.Shumate.VectorSpriteSheet`\.


      .. versionadded:: 1.1












Methods
-------

.. rst-class:: interim-class

.. class:: VectorSpriteSheet
   :no-index:


   .. method:: add_page(texture: ~gi.repository.Gdk.Texture, json: str, default_scale: float) -> bool

      Adds a page to the spritesheet.

      See `https://maplibre.org/maplibre-gl-js-docs/style-spec/sprite/ <https://maplibre.org/maplibre-gl-js-docs/style-spec/sprite/>`__ for
      details about the spritesheet format. Most stylesheets provide these files
      along with the main style JSON.

      Map styles should provide a double resolution spritesheet for high DPI
      displays. That spritesheet should be added as its own page, with a
      ``default_scale`` of 2.


      .. versionadded:: 1.1





      :param texture: a :obj:`~gi.repository.Gdk.Texture`

      :param json: a JSON string

      :param default_scale: the default scale factor of the page




   .. method:: add_sprite(name: str, sprite: ~gi.repository.Shumate.VectorSprite) -> None

      Adds a sprite to the spritesheet.


      .. versionadded:: 1.1





      :param name: the name of the sprite

      :param sprite: a :obj:`~gi.repository.Shumate.VectorSprite`




   .. method:: get_sprite(name: str, scale: float) -> ~gi.repository.Shumate.VectorSprite | None

      Gets a sprite from the spritesheet.

      The returned sprite might not be at the requested scale factor if an exact
      match is not found.


      .. versionadded:: 1.1





      :param name: an icon name

      :param scale: the scale factor of the icon




   .. method:: set_fallback(fallback: ~typing.Callable[[~gi.repository.Shumate.VectorSpriteSheet, str, float, ~typing.Any], ~gi.repository.Shumate.VectorSprite | None] | None = None, user_data: ~typing.Any = None) -> None

      Sets a fallback function to generate sprites.

      The fallback function is called when a texture is not found in the sprite
      sheet. It receives the icon name and scale factor, and should return a
      :obj:`~gi.repository.Shumate.VectorSprite`\, or :const:`None` if the icon could not be generated.
      It may be called in a different thread, and it may be called multiple times
      for the same icon name.

      If a previous fallback function was set, it will be replaced and any sprites
      it generated will be cleared.

      ``fallback`` may be :const:`None` to clear the fallback function.


      .. versionadded:: 1.1





      :param fallback: a [callback``ShumateVectorSpriteFallbackFunc``\] or :const:`None`

      :param user_data: user data to pass to ``fallback``