Elevation#

#

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()
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()
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()
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)

New 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).

New 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.

New 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.

New 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.

New 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.

New 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.

New in version 1.2.0.

scale_value_x is an NumericProperty and defaults to 1.

scale_value_y#

Y-axis value.

New in version 1.2.0.

scale_value_y is an NumericProperty and defaults to 1.

scale_value_z#

Z-axis value.

New in version 1.2.0.

scale_value_z is an NumericProperty and defaults to 1.

scale_value_center#

Origin of the scale.

New 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.

New 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.

New in version 1.2.0.

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