==========
Background
==========

.. py:class:: Background


   .. py:method:: id
      :property:

      The id of the background.

      :type: str, read-only

   .. py:method:: name
      :property:

      The name of the background.

      :type: str
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: group
      :property:

      The group of the background.

      :type: BackgroundGroup
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: gradient
      :property:

      Whether the gradient is enabled.

      :type: bool
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: gradient_start
      :property:

      The start color of the gradient.

      :type: ColorRgb
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: gradient_end
      :property:

      The end color of the gradient.

      :type: ColorRgb
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: gradient_orientation
      :property:

      The orientation of the gradient in degrees (0 for vertical gradient).

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: map
      :property:

      The map of the background or :py:obj:`None` if there is no map assigned.

      :type: Texture or None
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: map_enabled
      :property:

      Whether the map is enabled.

      :type: bool
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: preserve_aspect
      :property:

      Whether the map aspect ratio is kept.

      :type: bool
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: map_offset_u
      :property:

      The texture offset in U direction, in meters.

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: map_offset_v
      :property:

      The texture offset in V direction, in meters.

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: map_scale_u
      :property:

      The texture scaling in U direction.

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set a negative scale.

   .. py:method:: map_scale_v
      :property:

      The texture scaling in V direction.

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.
      :raises ValueError: If trying to set a negative scale.

   .. py:method:: map_rotation
      :property:

      The texture rotation, in degrees.

      :type: float
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.


   .. py:method:: duplicate()

      Duplicate this background.


      :returns: The duplicated background.
      :rtype: Background

      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: remove(force = False)

      Delete this background

      .. note::
         By default, only not used background can be deleted (:py:obj:`InUseError` is raised otherwise), use ``force`` to force deletion of used backgrounds.

      :param force: Force the deletion of the background even if it is in use.
      :type force: bool


      :raises InUseError: If ``force`` is :py:obj:`False` and the background is used.
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.