FitImage

Example

Imperative Python StylesDeclarative Python Styles

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBoxLayout:
        radius: "36dp"
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint: .4, .8
        md_bg_color: self.theme_cls.onSurfaceVariantColor

        FitImage:
            source: "image.png"
            size_hint_y: .35
            pos_hint: {"top": 1}
            radius: "36dp", "36dp", 0, 0
'''


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)


Example().run()

API - kivymd.uix.fitimage.fitimage

class kivymd.uix.fitimage.fitimage.FitImage(*args, **kwargs)

Fit image class.

For more information, see in the DeclarativeBehavior and StencilBehavior and MaterialShape and AsyncImage and classes documentation.

fit_mode

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.

fit_mode is a OptionProperty and defaults to ‘cover’.

shape

The Material shape style applied to the image clipping mask.

Added in version 2.0.1.

Available shape options are: ‘circle’, ‘square’, ‘slanted’, ‘arch’, ‘semiCircle’, ‘oval’, ‘pill’, ‘triangle’, ‘arrow’, ‘fan’, ‘diamond’, ‘clamShell’, ‘pentagon’, ‘gem’, ‘sunny’, ‘verySunny’, ‘cookie4Sided’, ‘cookie6Sided’, ‘cookie7Sided’, ‘cookie9Sided’, ‘cookie12Sided’, ‘clover4Leaf’, ‘clover8Leaf’, ‘burst’, ‘softBurst’, ‘boom’, ‘softBoom’, ‘flower’, ‘puffy’, ‘puffyDiamond’, ‘ghostish’, ‘pixelCircle’, ‘pixelTriangle’, ‘bun’, ‘heart’.

If set to None, the image will be rendered as a standard rectangle.

shape is an OptionProperty and defaults to None.

Imperative Python StylesDeclarative Python Styles

from kivy.lang import Builder
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.fitimage import FitImage
from kivymd.uix.label import MDLabel

KV = '''
MDScreen:
    md_bg_color: app.theme_cls.surfaceColor

    MDScrollView:

        MDGridLayout:
            id: shape_grid
            cols: 6
            adaptive_height: True
            padding: dp(16)
            spacing: dp(16)
'''


class ExampleApp(MDApp):
    SHAPES = [
        "circle",
        "square",
        "slanted",
        "arch",
        "semiCircle",
        "oval",
        "pill",
        "triangle",
        "arrow",
        "fan",
        "diamond",
        "clamShell",
        "pentagon",
        "gem",
        "sunny",
        "verySunny",
        "cookie4Sided",
        "cookie6Sided",
        "cookie7Sided",
        "cookie9Sided",
        "cookie12Sided",
        "clover4Leaf",
        "clover8Leaf",
        "burst",
        "softBurst",
        "boom",
        "softBoom",
        "flower",
        "puffy",
        "puffyDiamond",
        "ghostish",
        "pixelCircle",
        "pixelTriangle",
        "bun",
        "heart",
    ]
    IMAGE_PATH = "bg.jpg"

    def build(self):
        return Builder.load_string(KV)

    def on_start(self):
        grid = self.root.ids.shape_grid

        for shape_name in self.SHAPES:
            item_box = MDBoxLayout(
                orientation="vertical",
                adaptive_height=True,
                spacing=dp(8),
            )

            shape_widget = FitImage(
                size_hint=(None, None),
                size=(dp(90), dp(90)),
                pos_hint={"center_x": 0.5},
                shape=shape_name,
                source=self.IMAGE_PATH,
            )

            label = MDLabel(
                text=shape_name,
                halign="center",
                adaptive_height=True,
                font_style="Label",
                role="medium",
            )

            item_box.add_widget(shape_widget)
            item_box.add_widget(label)
            grid.add_widget(item_box)


if __name__ == "__main__":
    ExampleApp().run()

on_source(instance, value)

Fired when the source value changes.

update_texture(*args)

Updates the widget texture.

If a custom Material shape is set, delegates texture generation to materialshapes.kivy_widget.MaterialShape.update_texture(). This builds a Cairo surface based on the target shape dimensions, applies the image pattern (or fill color), and renders the resulting vector mask directly to the Kivy texture.

If shape is None, execution falls back to standard GPU texture rendering via AsyncImage.