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 = '''
<RectangularElevationButton>
    size_hint: None, None
    size: "250dp", "50dp"


MDScreen:

    # With elevation effect
    RectangularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .6}
        elevation: 4.5
        shadow_offset: 0, 6

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


class RectangularElevationButton(
    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
'''


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: 4
        radius: 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.

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: 12, 46, 12, 46
        size_hint: .5, .3
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 4
        shadow_softness: 8
        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

Note

However, if you want to use this parameter, remember that the angle values for the radius of the Kivy widgets and the radius for the shader are different.

shadow_radius = ['top-right', 'bot-right', 'top-left', 'bot-left']
kivy_radius = ['top-left', 'top-right', 'bottom-right', 'bottom-left']

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 = '''
<RectangularElevationButton>
    size_hint: None, None
    size: "250dp", "50dp"


MDScreen:

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

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


class RectangularElevationButton(CommonElevationBehavior, BackgroundColorBehavior):
    md_bg_color = [0, 0, 1, 1]


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

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 = '''
<RectangularElevationButton>
    size_hint: None, None
    size: "100dp", "100dp"


MDScreen:

    RectangularElevationButton:
        pos_hint: {"center_x": .5, "center_y": .5}
        elevation: 6
        shadow_radius: 18
        shadow_softness: 24
        shadow_offset: 12, 12
'''


class RectangularElevationButton(CommonElevationBehavior, BackgroundColorBehavior):
    md_bg_color = [0, 0, 1, 1]


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
RectangularElevationButton:
    shadow_offset: -12, 12
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-2.png
RectangularElevationButton:
    shadow_offset: -12, -12
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-offset-3.png
RectangularElevationButton:
    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, 2).

shadow_color#

Offset of the shadow.

New in version 1.1.0.

RectangularElevationButton:
    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.4, 0.4, 0.4, 0.8].

window_pos#
after_init(self, *args)#
check_for_relative_behavior(self, *args)#

Checks if the widget has relative properties and if necessary binds Window.on_draw and screen events to fix behavior

apply_correction(self, *args)#
reset_correction(self, *args)#
get_shader_string(self)#
set_shader_string(self, *args)#
update_resolution(self)#
on_shadow_color(self, instance, value)#
on_shadow_radius(self, instance, value)#
on_shadow_softness(self, instance, value)#
on_elevation(self, instance, value)#
on_shadow_offset(self, instance, value)#
update_window_position(self, *args)#

This function is used only when the widget has relative position properties.

on_pos(self, *args)#
on_size(self, *args)#
on_opacity(self, instance, value: int | float)#

Adjusts the transparency of the shadow according to the transparency of the widget.

on_radius(self, instance, value)#
on_disabled(self, instance, value)#
hide_elevation(self, hide: bool)#
class kivymd.uix.behaviors.elevation.RectangularElevationBehavior(**kwargs)#

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.

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

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.

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

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.

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

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.

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

Deprecated since version 1.1.0.

Use CommonElevationBehavior class instead.