Kivy-examples 2.3.1.dev0__py3-none-any.whl

kivy/uix/image.py

@@ -0,0 +1,528 @@
+'''
+Image
+=====
+
+The :class:`Image` widget is used to display an image::
+
+Example in python::
+
+    wimg = Image(source='mylogo.png')
+
+Kv Example::
+
+    Image:
+        source: 'mylogo.png'
+        size: self.texture_size
+
+
+Asynchronous Loading
+--------------------
+
+To load an image asynchronously (for example from an external webserver), use
+the :class:`AsyncImage` subclass::
+
+    aimg = AsyncImage(source='http://mywebsite.com/logo.png')
+
+This can be useful as it prevents your application from waiting until the image
+is loaded. If you want to display large images or retrieve them from URL's,
+using :class:`AsyncImage` will allow these resources to be retrieved on a
+background thread without blocking your application.
+
+Alignment
+---------
+
+By default, the image is centered inside the widget bounding box.
+
+Adjustment
+----------
+
+To control how the image should be adjusted to fit inside the widget box, you
+should use the :attr:`~kivy.uix.image.Image.fit_mode` property. Available
+options include:
+
+- ``"scale-down"``: maintains aspect ratio without stretching.
+- ``"fill"``: stretches to fill widget, may cause distortion.
+- ``"contain"``: maintains aspect ratio and resizes to fit inside widget.
+- ``"cover"``: maintains aspect ratio and stretches to fill widget, may clip
+image.
+
+For more details, refer to the :attr:`~kivy.uix.image.Image.fit_mode`.
+
+
+You can also inherit from Image and create your own style. For example, if you
+want your image to be greater than the size of your widget, you could do::
+
+    class FullImage(Image):
+        pass
+
+And in your kivy language file::
+
+    <-FullImage>:
+        canvas:
+            Color:
+                rgb: (1, 1, 1)
+            Rectangle:
+                texture: self.texture
+                size: self.width + 20, self.height + 20
+                pos: self.x - 10, self.y - 10
+
+'''
+__all__ = ('Image', 'AsyncImage')
+
+from kivy.uix.widget import Widget
+from kivy.core.image import Image as CoreImage
+from kivy.resources import resource_find
+from kivy.properties import (
+    StringProperty,
+    ObjectProperty,
+    ListProperty,
+    AliasProperty,
+    BooleanProperty,
+    NumericProperty,
+    ColorProperty,
+    OptionProperty
+)
+from kivy.logger import Logger
+
+# delayed imports
+Loader = None
+
+
+class Image(Widget):
+    '''Image class, see module documentation for more information.'''
+
+    source = StringProperty(None)
+    '''Filename / source of your image.
+
+    :attr:`source` is a :class:`~kivy.properties.StringProperty` and
+    defaults to None.
+    '''
+
+    texture = ObjectProperty(None, allownone=True)
+    '''Texture object of the image. The texture represents the original, loaded
+    image texture. It is stretched and positioned during rendering according to
+    the :attr:`fit_mode` property.
+
+    Depending of the texture creation, the value will be a
+    :class:`~kivy.graphics.texture.Texture` or a
+    :class:`~kivy.graphics.texture.TextureRegion` object.
+
+    :attr:`texture` is an :class:`~kivy.properties.ObjectProperty` and defaults
+    to None.
+    '''
+
+    texture_size = ListProperty([0, 0])
+    '''Texture size of the image. This represents the original, loaded image
+    texture size.
+
+    .. warning::
+
+        The texture size is set after the texture property. So if you listen to
+        the change on :attr:`texture`, the property texture_size will not be
+        up-to-date. Use self.texture.size instead.
+    '''
+
+    def get_image_ratio(self):
+        if self.texture:
+            return self.texture.width / float(self.texture.height)
+        return 1.0
+
+    mipmap = BooleanProperty(False)
+    '''Indicate if you want OpenGL mipmapping to be applied to the texture.
+    Read :ref:`mipmap` for more information.
+
+    .. versionadded:: 1.0.7
+
+    :attr:`mipmap` is a :class:`~kivy.properties.BooleanProperty` and defaults
+    to False.
+    '''
+
+    image_ratio = AliasProperty(get_image_ratio, bind=('texture',), cache=True)
+    '''Ratio of the image (width / float(height).
+
+    :attr:`image_ratio` is an :class:`~kivy.properties.AliasProperty` and is
+    read-only.
+    '''
+
+    color = ColorProperty([1, 1, 1, 1])
+    '''Image color, in the format (r, g, b, a). This attribute can be used to
+    'tint' an image. Be careful: if the source image is not gray/white, the
+    color will not really work as expected.
+
+    .. versionadded:: 1.0.6
+
+    :attr:`color` is a :class:`~kivy.properties.ColorProperty` and defaults to
+    [1, 1, 1, 1].
+
+    .. versionchanged:: 2.0.0
+        Changed from :class:`~kivy.properties.ListProperty` to
+        :class:`~kivy.properties.ColorProperty`.
+    '''
+
+    allow_stretch = BooleanProperty(False, deprecated=True)
+    '''If True, the normalized image size will be maximized to fit in the image
+    box. Otherwise, if the box is too tall, the image will not be
+    stretched more than 1:1 pixels.
+
+    .. versionadded:: 1.0.7
+
+    .. deprecated:: 2.2.0
+        :attr:`allow_stretch` have been deprecated. Please use `fit_mode`
+        instead.
+
+    :attr:`allow_stretch` is a :class:`~kivy.properties.BooleanProperty` and
+    defaults to False.
+    '''
+
+    keep_ratio = BooleanProperty(True, deprecated=True)
+    '''If False along with allow_stretch being True, the normalized image
+    size will be maximized to fit in the image box and ignores the aspect
+    ratio of the image.
+    Otherwise, if the box is too tall, the image will not be stretched more
+    than 1:1 pixels.
+
+    .. versionadded:: 1.0.8
+
+    .. deprecated:: 2.2.0
+        :attr:`keep_ratio` have been deprecated. Please use `fit_mode`
+        instead.
+
+    :attr:`keep_ratio` is a :class:`~kivy.properties.BooleanProperty` and
+    defaults to True.
+    '''
+
+    fit_mode = OptionProperty(
+        "scale-down", options=["scale-down", "fill", "contain", "cover"]
+    )
+    '''If the size of the image is different than the size of the widget,
+    determine how the image should be resized to fit inside the widget box.
+
+    Available options:
+
+    - ``"scale-down"``: the image will be scaled down to fit inside the widget
+    box, **maintaining its aspect ratio and without stretching**. If the size
+    of the image is smaller than the widget, it will be displayed at its
+    original size. If the image has a different aspect ratio than the widget,
+    there will be blank areas on the widget box.
+
+    - ``"fill"``: the image is stretched to fill the widget, **regardless of
+    its aspect ratio or dimensions**. If the image has a different aspect ratio
+    than the widget, this option can lead to distortion of the image.
+
+    - ``"contain"``: the image is resized to fit inside the widget box,
+    **maintaining its aspect ratio**. If the image size is larger than the
+    widget size, the behavior will be similar to ``"scale-down"``. However, if
+    the size of the image is smaller than the widget size, unlike
+    ``"scale-down``, the image will be resized to fit inside the widget.
+    If the image has a different aspect ratio than the widget, there will be
+    blank areas on the widget box.
+
+    - ``"cover"``: the image will be stretched horizontally or vertically to
+    fill the widget box, **maintaining its aspect ratio**. If the image has a
+    different aspect ratio than the widget, then the image will be clipped to
+    fit.
+
+    :attr:`fit_mode` is a :class:`~kivy.properties.OptionProperty` and
+    defaults to ``"scale-down"``.
+    '''
+
+    keep_data = BooleanProperty(False)
+    '''If True, the underlying _coreimage will store the raw image data.
+    This is useful when performing pixel based collision detection.
+
+    .. versionadded:: 1.3.0
+
+    :attr:`keep_data` is a :class:`~kivy.properties.BooleanProperty` and
+    defaults to False.
+    '''
+
+    anim_delay = NumericProperty(0.25)
+    '''Delay the animation if the image is sequenced (like an animated gif).
+    If anim_delay is set to -1, the animation will be stopped.
+
+    .. versionadded:: 1.0.8
+
+    :attr:`anim_delay` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 0.25 (4 FPS).
+    '''
+
+    anim_loop = NumericProperty(0)
+    '''Number of loops to play then stop animating. 0 means keep animating.
+
+    .. versionadded:: 1.9.0
+
+    :attr:`anim_loop` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 0.
+    '''
+
+    nocache = BooleanProperty(False)
+    '''If this property is set True, the image will not be added to the
+    internal cache. The cache will simply ignore any calls trying to
+    append the core image.
+
+    .. versionadded:: 1.6.0
+
+    :attr:`nocache` is a :class:`~kivy.properties.BooleanProperty` and defaults
+    to False.
+    '''
+
+    def get_norm_image_size(self):
+        if not self.texture:
+            return list(self.size)
+
+        ratio = self.image_ratio
+        w, h = self.size
+        tw, th = self.texture.size
+
+        if self.fit_mode == "cover":
+            widget_ratio = w / max(1, h)
+            if widget_ratio > ratio:
+                return [w, (w * th) / tw]
+            else:
+                return [(h * tw) / th, h]
+        elif self.fit_mode == "fill":
+            return [w, h]
+        elif self.fit_mode == "contain":
+            iw = w
+        else:
+            iw = min(w, tw)
+
+        # calculate the appropriate height
+        ih = iw / ratio
+        # if the height is too higher, take the height of the container
+        # and calculate appropriate width. no need to test further. :)
+        if ih > h:
+            if self.fit_mode == "contain":
+                ih = h
+            else:
+                ih = min(h, th)
+            iw = ih * ratio
+        return [iw, ih]
+
+    norm_image_size = AliasProperty(
+        get_norm_image_size,
+        bind=(
+            'texture',
+            'size',
+            'image_ratio',
+            'fit_mode',
+        ),
+        cache=True,
+    )
+    '''Normalized image size within the widget box.
+
+    This size will always fit the widget size and will preserve the image
+    ratio.
+
+    :attr:`norm_image_size` is an :class:`~kivy.properties.AliasProperty` and
+    is read-only.
+    '''
+
+    def __init__(self, **kwargs):
+        self._coreimage = None
+        self._loops = 0
+        update = self.texture_update
+        fbind = self.fbind
+        fbind('source', update)
+        fbind('mipmap', update)
+
+        # NOTE: Compatibility code due to deprecated properties.
+        fbind('keep_ratio', self._update_fit_mode)
+        fbind('allow_stretch', self._update_fit_mode)
+        super().__init__(**kwargs)
+
+    def _update_fit_mode(self, *args):
+        keep_ratio = self.keep_ratio
+        allow_stretch = self.allow_stretch
+        if (
+            not keep_ratio and not allow_stretch
+            or keep_ratio and not allow_stretch
+        ):
+            self.fit_mode = "scale-down"
+        elif not keep_ratio and allow_stretch:
+            self.fit_mode = "fill"
+        elif keep_ratio and allow_stretch:
+            self.fit_mode = "contain"
+
+    def texture_update(self, *largs):
+        self.set_texture_from_resource(self.source)
+
+    def set_texture_from_resource(self, resource):
+        if not resource:
+            self._clear_core_image()
+            return
+        source = resource_find(resource)
+        if not source:
+            Logger.error('Image: Not found <%s>' % resource)
+            self._clear_core_image()
+            return
+        if self._coreimage:
+            self._coreimage.unbind(on_texture=self._on_tex_change)
+        try:
+            self._coreimage = image = CoreImage(
+                source,
+                mipmap=self.mipmap,
+                anim_delay=self.anim_delay,
+                keep_data=self.keep_data,
+                nocache=self.nocache
+            )
+        except Exception:
+            Logger.error('Image: Error loading <%s>' % resource)
+            self._clear_core_image()
+            image = self._coreimage
+        if image:
+            image.bind(on_texture=self._on_tex_change)
+            self.texture = image.texture
+
+    def on_anim_delay(self, instance, value):
+        if self._coreimage is None:
+            return
+        self._coreimage.anim_delay = value
+        if value < 0:
+            self._coreimage.anim_reset(False)
+
+    def on_texture(self, instance, value):
+        self.texture_size = value.size if value else [0, 0]
+
+    def _clear_core_image(self):
+        if self._coreimage:
+            self._coreimage.unbind(on_texture=self._on_tex_change)
+        self.texture = None
+        self._coreimage = None
+        self._loops = 0
+
+    def _on_tex_change(self, *largs):
+        # update texture from core image
+        self.texture = self._coreimage.texture
+        ci = self._coreimage
+        if self.anim_loop and ci._anim_index == len(ci._image.textures) - 1:
+            self._loops += 1
+            if self.anim_loop == self._loops:
+                ci.anim_reset(False)
+                self._loops = 0
+
+    def reload(self):
+        '''Reload image from disk. This facilitates re-loading of
+        images from disk in case the image content changes.
+
+        .. versionadded:: 1.3.0
+
+        Usage::
+
+            im = Image(source = '1.jpg')
+            # -- do something --
+            im.reload()
+            # image will be re-loaded from disk
+
+        '''
+        self.remove_from_cache()
+        old_source = self.source
+        self.source = ''
+        self.source = old_source
+
+    def remove_from_cache(self):
+        '''Remove image from cache.
+
+        .. versionadded:: 2.0.0
+        '''
+        if self._coreimage:
+            self._coreimage.remove_from_cache()
+
+    def on_nocache(self, *args):
+        if self.nocache:
+            self.remove_from_cache()
+            if self._coreimage:
+                self._coreimage._nocache = True
+
+
+class AsyncImage(Image):
+    '''Asynchronous Image class. See the module documentation for more
+    information.
+
+    .. note::
+
+        The AsyncImage is a specialized form of the Image class. You may
+        want to refer to the :mod:`~kivy.loader` documentation and in
+        particular, the :class:`~kivy.loader.ProxyImage` for more detail
+        on how to handle events around asynchronous image loading.
+
+    .. note::
+
+        AsyncImage currently does not support properties
+        :attr:`anim_loop` and :attr:`mipmap` and setting those properties will
+        have no effect.
+    '''
+
+    __events__ = ('on_error', 'on_load')
+
+    def __init__(self, **kwargs):
+        self._found_source = None
+        self._coreimage = None
+        global Loader
+        if not Loader:
+            from kivy.loader import Loader
+        self.fbind('source', self._load_source)
+        super().__init__(**kwargs)
+
+    def _load_source(self, *args):
+        source = self.source
+        if not source:
+            self._clear_core_image()
+            return
+        if not self.is_uri(source):
+            source = resource_find(source)
+            if not source:
+                Logger.error('AsyncImage: Not found <%s>' % self.source)
+                self._clear_core_image()
+                return
+        self._found_source = source
+        self._coreimage = image = Loader.image(
+            source,
+            nocache=self.nocache,
+            mipmap=self.mipmap,
+            anim_delay=self.anim_delay
+        )
+        image.bind(
+            on_load=self._on_source_load,
+            on_error=self._on_source_error,
+            on_texture=self._on_tex_change
+        )
+        self.texture = image.texture
+
+    def _on_source_load(self, value):
+        image = self._coreimage.image
+        if not image:
+            return
+        self.texture = image.texture
+        self.dispatch('on_load')
+
+    def _on_source_error(self, instance, error=None):
+        self.dispatch('on_error', error)
+
+    def on_error(self, error):
+        pass
+
+    def on_load(self, *args):
+        pass
+
+    def is_uri(self, filename):
+        proto = filename.split('://', 1)[0]
+        return proto in ('http', 'https', 'ftp', 'smb')
+
+    def _clear_core_image(self):
+        if self._coreimage:
+            self._coreimage.unbind(on_load=self._on_source_load)
+        super()._clear_core_image()
+        self._found_source = None
+
+    def _on_tex_change(self, *largs):
+        if self._coreimage:
+            self.texture = self._coreimage.texture
+
+    def texture_update(self, *largs):
+        pass
+
+    def remove_from_cache(self):
+        if self._found_source:
+            Loader.remove_from_cache(self._found_source)
+        super().remove_from_cache()