Elevation#

#

See also

Elevation is the relative distance between two surfaces along the z-axis.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/elevation-previous.png

To create an elevation effect, use the CommonElevationBehavior class. For example, let’s create a button with a rectangular elevation effect:

from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import (
    RectangularRippleBehavior,
    BackgroundColorBehavior,
    CommonElevationBehavior,
)

KV = '''
<ElevationWidget>
    size_hint: None, None
    size: "250dp", "50dp"


MDScreen:

    # With elevation effect
    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 4
        shadow_offset: 0, -6
        shadow_softness: 4

    # Without elevation effect
    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .4}
'''


class ElevationWidget(
    RectangularRippleBehavior,
    CommonElevationBehavior,
    ButtonBehavior,
    BackgroundColorBehavior,
):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.md_bg_color = "red"


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


Example().run()

from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import (
    RectangularRippleBehavior,
    BackgroundColorBehavior,
    CommonElevationBehavior,
)
from kivymd.uix.screen import MDScreen


class ElevationWidget(
    RectangularRippleBehavior,
    CommonElevationBehavior,
    ButtonBehavior,
    BackgroundColorBehavior,
):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.md_bg_color = "red"
        self.size_hint = (None, None)
        self.size = ("250dp", "50dp")


class Example(MDApp):
    def build(self):
        return (
            MDScreen(
                ElevationWidget(
                    pos_hint={"center_x": .5, "center_y": .6},
                    elevation=4,
                    shadow_softness=4,
                    shadow_offset=(0, -6),
                ),
                ElevationWidget(
                    pos_hint={"center_x": .5, "center_y": .4},
                ),
            )
        )


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-elevation-effect.png

Warning

If before the KivyMD 1.1.0 library version you used the elevation property with an average value of 12 for the shadow, then starting with the KivyMD 1.1.0 library version, the average value of the elevation property will be somewhere 4.

Similarly, create a circular button:

from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import CircularRippleBehavior, CommonElevationBehavior
from kivymd.uix.floatlayout import MDFloatLayout

KV = '''
<CircularElevationButton>
    size_hint: None, None
    size: "100dp", "100dp"
    radius: self.size[0] / 2
    shadow_radius: self.radius[0]
    md_bg_color: "red"

    MDIcon:
        icon: "hand-heart"
        halign: "center"
        valign: "center"
        pos_hint: {"center_x": .5, "center_y": .5}
        size: root.size
        pos: root.pos
        font_size: root.size[0] * .6
        theme_text_color: "Custom"
        text_color: "white"


MDScreen:

    CircularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 4
        shadow_softness: 4
'''


class CircularElevationButton(
    CommonElevationBehavior,
    CircularRippleBehavior,
    ButtonBehavior,
    MDFloatLayout,
):
    pass


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


Example().run()

from kivy.metrics import dp
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import CircularRippleBehavior, CommonElevationBehavior
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.label import MDIcon
from kivymd.uix.screen import MDScreen


class CircularElevationButton(
    CommonElevationBehavior,
    CircularRippleBehavior,
    ButtonBehavior,
    MDFloatLayout,
):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.size_hint = (None, None)
        self.size = (dp(100), dp(100))
        self.radius = dp(100) / 2
        self.shadow_radius = dp(100) / 2
        self.md_bg_color = "red"
        self.add_widget(
            MDIcon(
                icon="hand-heart",
                halign="center",
                valign="center",
                pos_hint={"center_x": .5, "center_y": .5},
                size=self.size,
                theme_text_color="Custom",
                text_color="white",
                font_size=self.size[0] * 0.6,
            )
        )


class Example(MDApp):
    def build(self):
        return (
            MDScreen(
                CircularElevationButton(
                    pos_hint={"center_x": .5, "center_y": .5},
                    elevation=4,
                    shadow_softness=4,
                )
            )
        )


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/circular-elevation-effect.png

Animating the elevation#

from kivy.animation import Animation
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior

from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior, RectangularRippleBehavior
from kivymd.uix.widget import MDWidget

KV = '''
MDScreen:

    ElevatedWidget:
        pos_hint: {'center_x': .5, 'center_y': .5}
        size_hint: None, None
        size: 100, 100
        md_bg_color: 0, 0, 1, 1
        elevation: 2
        radius: dp(18)
'''


class ElevatedWidget(
    CommonElevationBehavior,
    RectangularRippleBehavior,
    ButtonBehavior,
    MDWidget,
):
    _elev = 0  # previous elevation value

    def on_press(self, *args):
        if not self._elev:
            self._elev = self.elevation
        Animation(elevation=self.elevation + 2, d=0.4).start(self)

    def on_release(self, *args):
        Animation.cancel_all(self, "elevation")
        Animation(elevation=self._elev, d=0.1).start(self)


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


Example().run()

from kivy.animation import Animation
from kivy.uix.behaviors import ButtonBehavior
from kivy.metrics import dp

from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior, RectangularRippleBehavior
from kivymd.uix.screen import MDScreen
from kivymd.uix.widget import MDWidget


class ElevatedWidget(
    CommonElevationBehavior,
    RectangularRippleBehavior,
    ButtonBehavior,
    MDWidget,
):
    _elev = 0  # previous elevation value

    def on_press(self, *args):
        if not self._elev:
            self._elev = self.elevation
        Animation(elevation=self.elevation + 2, d=0.4).start(self)

    def on_release(self, *args):
        Animation.cancel_all(self, "elevation")
        Animation(elevation=self._elev, d=0.1).start(self)


class Example(MDApp):
    def build(self):
        return (
            MDScreen(
                ElevatedWidget(
                    pos_hint={'center_x': .5, 'center_y': .5},
                    size_hint=(None, None),
                    size=(100, 100),
                    md_bg_color="blue",
                    elevation=2,
                    radius=dp(18),
                )
            )
        )


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-elevation-animation-effect.gif

API - `kivymd.uix.behaviors.elevation`#

class kivymd.uix.behaviors.elevation.CommonElevationBehavior(**kwargs)#

Common base class for rectangular and circular elevation behavior.

For more information, see in the Widget class documentation.

elevation_level#

Elevation level (values from 0 to 5)

Added in version 1.2.0.

elevation_level is an BoundedNumericProperty and defaults to 0.

elevation_levels#

Elevation is measured as the distance between components along the z-axis in density-independent pixels (dps).

Added in version 1.2.0.

elevation_levels is an DictProperty and defaults to {0: dp(0), 1: dp(8), 2: dp(23), 3: dp(16), 4: dp(20), 5: dp(24)}.

elevation#

Elevation of the widget.

elevation is an BoundedNumericProperty and defaults to 0.

shadow_radius#

Radius of the corners of the shadow.

Added in version 1.1.0.

You don’t have to use this parameter. The radius of the elevation effect is calculated automatically one way or another based on the radius of the parent widget, for example:

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDCard:
        radius: dp(12), dp(46), dp(12), dp(46)
        size_hint: .5, .3
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 2
        shadow_softness: 4
        shadow_offset: (2, -2)
'''


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


Test().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-radius.png

shadow_radius is an VariableListProperty and defaults to [0, 0, 0, 0].

shadow_softness#

Softness of the shadow.

Added in version 1.1.0.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import BackgroundColorBehavior, CommonElevationBehavior

KV = '''
<ElevationWidget>
    size_hint: None, None
    size: "250dp", "50dp"


MDScreen:

    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 6
        shadow_softness: 6

    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .4}
        elevation: 6
        shadow_softness: 12
'''


class ElevationWidget(CommonElevationBehavior, BackgroundColorBehavior):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.md_bg_color = "blue"


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


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-softness.png

shadow_softness is an NumericProperty and defaults to 0.0.

shadow_offset#

Offset of the shadow.

Added in version 1.1.0.

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.behaviors import BackgroundColorBehavior, CommonElevationBehavior

KV = '''
<ElevationWidget>
    size_hint: None, None
    size: "100dp", "100dp"


MDScreen:

    ElevationWidget:
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 6
        shadow_radius: dp(6)
        shadow_softness: 12
        shadow_offset: -12, -12
'''


class ElevationWidget(CommonElevationBehavior, BackgroundColorBehavior):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.md_bg_color = "blue"


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


Example().run()

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-1.png

ElevationWidget:
    shadow_offset: 12, -12

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-2.png

ElevationWidget:
    shadow_offset: 12, 12

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-3.png

ElevationWidget:
    shadow_offset: -12, 12

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-4.png

shadow_offset is an ListProperty and defaults to (0, 0).

shadow_color#

Offset of the shadow.

Added in version 1.1.0.

ElevationWidget:
    shadow_color: 0, 0, 1, .8

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-color.png

shadow_color is an ColorProperty and defaults to [0, 0, 0, 0.6].

scale_value_x#

X-axis value.

Added in version 1.2.0.

scale_value_x is an NumericProperty and defaults to 1.

scale_value_y#

Y-axis value.

Added in version 1.2.0.

scale_value_y is an NumericProperty and defaults to 1.

scale_value_z#

Z-axis value.

Added in version 1.2.0.

scale_value_z is an NumericProperty and defaults to 1.

scale_value_center#

Origin of the scale.

Added in version 1.2.0.

The format of the origin can be either (x, y) or (x, y, z).

scale_value_center is an NumericProperty and defaults to [].

rotate_value_angle#

Property for getting/setting the angle of the rotation.

Added in version 1.2.0.

rotate_value_angle is an NumericProperty and defaults to 0.

rotate_value_axis#

Property for getting/setting the axis of the rotation.

Added in version 1.2.0.

rotate_value_axis is an ListProperty and defaults to (0, 0, 1).

Elevation

Contents

Elevation#

#

Animating the elevation#

API - kivymd.uix.behaviors.elevation#

API - `kivymd.uix.behaviors.elevation`#