"""
Behaviors/Elevation
===================
.. seealso::
`Material Design spec, Elevation <https://material.io/design/environment/elevation.html>`_
.. rubric:: Elevation is the relative distance between two surfaces along the z-axis.
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/elevation-previous.png
:align: center
There are 5 classes in KivyMD that can simulate shadow:
#. :class:`~FakeRectangularElevationBehavior`
#. :class:`~FakeCircularElevationBehavior`
#. :class:`~RectangularElevationBehavior`
#. :class:`~CircularElevationBehavior`
#. :class:`~RoundedRectangularElevationBehavior`
By default, KivyMD widgets use the elevation behavior implemented in classes
:class:`~FakeRectangularElevationBehavior` and :class:`~FakeCircularElevationBehavior`
for cast shadows. These classes use the old method of rendering shadows and it
doesn't look very aesthetically pleasing. Shadows are harsh, no softness:
The :class:`~RectangularElevationBehavior`, :class:`~CircularElevationBehavior`,
:class:`~RoundedRectangularElevationBehavior` classes use the new shadow
rendering algorithm, based on textures creation using the `Pillow` library.
It looks very aesthetically pleasing and beautiful.
.. warning:: Remember that :class:`~RectangularElevationBehavior`,
:class:`~CircularElevationBehavior`, :class:`~RoundedRectangularElevationBehavior`
classes require a lot of resources from the device on which your application will run,
so you should not use these classes on mobile devices.
.. code-block:: python
from kivy.lang import Builder
from kivy.uix.widget import Widget
from kivymd.app import MDApp
from kivymd.uix.card import MDCard
from kivymd.uix.behaviors import RectangularElevationBehavior
from kivymd.uix.boxlayout import MDBoxLayout
KV = '''
<Box@MDBoxLayout>
adaptive_size: True
orientation: "vertical"
spacing: "36dp"
<BaseShadowWidget>
size_hint: None, None
size: 100, 100
md_bg_color: 0, 0, 1, 1
elevation: 36
pos_hint: {'center_x': .5}
MDFloatLayout:
MDBoxLayout:
adaptive_size: True
pos_hint: {'center_x': .5, 'center_y': .5}
spacing: "56dp"
Box:
MDLabel:
text: "Deprecated shadow rendering"
adaptive_size: True
DeprecatedShadowWidget:
MDLabel:
text: "Doesn't require a lot of resources"
adaptive_size: True
Box:
MDLabel:
text: "New shadow rendering"
adaptive_size: True
NewShadowWidget:
MDLabel:
text: "It takes a lot of resources"
adaptive_size: True
'''
class BaseShadowWidget(Widget):
pass
class DeprecatedShadowWidget(MDCard, BaseShadowWidget):
'''Deprecated shadow rendering. Doesn't require a lot of resources.'''
class NewShadowWidget(RectangularElevationBehavior, BaseShadowWidget, MDBoxLayout):
'''New shadow rendering. It takes a lot of resources.'''
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/elevation-differential.png
:align: center
For example, let's create an button with a rectangular elevation effect:
.. code-block:: python
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior
from kivymd.app import MDApp
from kivymd.uix.behaviors import (
RectangularRippleBehavior,
BackgroundColorBehavior,
FakeRectangularElevationBehavior,
)
KV = '''
<RectangularElevationButton>:
size_hint: None, None
size: "250dp", "50dp"
MDScreen:
# With elevation effect
RectangularElevationButton:
pos_hint: {"center_x": .5, "center_y": .6}
elevation: 18
# Without elevation effect
RectangularElevationButton:
pos_hint: {"center_x": .5, "center_y": .4}
'''
class RectangularElevationButton(
RectangularRippleBehavior,
FakeRectangularElevationBehavior,
ButtonBehavior,
BackgroundColorBehavior,
):
md_bg_color = [0, 0, 1, 1]
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-elevation-effect.gif
:align: center
Similarly, create a circular button:
.. code-block:: python
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.app import MDApp
from kivymd.uix.behaviors import (
CircularRippleBehavior,
FakeCircularElevationBehavior,
)
KV = '''
<CircularElevationButton>:
size_hint: None, None
size: "100dp", "100dp"
radius: self.size[0] / 2
md_bg_color: 0, 0, 1, 1
MDIcon:
icon: "hand-heart"
halign: "center"
valign: "center"
size: root.size
pos: root.pos
font_size: root.size[0] * .6
theme_text_color: "Custom"
text_color: [1] * 4
MDScreen:
CircularElevationButton:
pos_hint: {"center_x": .5, "center_y": .6}
elevation: 24
'''
class CircularElevationButton(
FakeCircularElevationBehavior,
CircularRippleBehavior,
ButtonBehavior,
MDBoxLayout,
):
pass
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/circular-fake-elevation.png
:align: center
Animating the elevation
-----------------------
.. code-block:: python
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.properties import ObjectProperty
from kivy.uix.behaviors import ButtonBehavior
from kivymd.app import MDApp
from kivymd.theming import ThemableBehavior
from kivymd.uix.behaviors import FakeRectangularElevationBehavior, RectangularRippleBehavior
from kivymd.uix.boxlayout import MDBoxLayout
KV = '''
MDFloatLayout:
ElevatedWidget:
pos_hint: {'center_x': .5, 'center_y': .5}
size_hint: None, None
size: 100, 100
md_bg_color: 0, 0, 1, 1
'''
class ElevatedWidget(
ThemableBehavior,
FakeRectangularElevationBehavior,
RectangularRippleBehavior,
ButtonBehavior,
MDBoxLayout,
):
shadow_animation = ObjectProperty()
def on_press(self, *args):
if self.shadow_animation:
Animation.cancel_all(self, "_elevation")
self.shadow_animation = Animation(_elevation=self.elevation + 10, d=0.4)
self.shadow_animation.start(self)
def on_release(self, *args):
if self.shadow_animation:
Animation.cancel_all(self, "_elevation")
self.shadow_animation = Animation(_elevation=self.elevation, d=0.1)
self.shadow_animation.start(self)
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/rectangular-elevation-animation-effect.gif
:align: center
Lighting position
-----------------
.. code-block:: python
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.card import MDCard
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.behaviors import RectangularElevationBehavior
KV = '''
MDScreen:
ShadowCard:
pos_hint: {'center_x': .5, 'center_y': .5}
size_hint: None, None
size: 100, 100
shadow_pos: -10 + slider.value, -10 + slider.value
elevation: 24
md_bg_color: 1, 1, 1, 1
MDSlider:
id: slider
max: 20
size_hint_x: .6
pos_hint: {'center_x': .5, 'center_y': .3}
'''
class ShadowCard(RectangularElevationBehavior, MDBoxLayout):
pass
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/shadow-pos.gif
:align: center
"""
__all__ = (
"CommonElevationBehavior",
"RectangularElevationBehavior",
"CircularElevationBehavior",
"RoundedRectangularElevationBehavior",
"ObservableShadow",
"FakeRectangularElevationBehavior",
"FakeCircularElevationBehavior",
)
from io import BytesIO
from weakref import WeakMethod, ref
from kivy import Logger
from kivy.clock import Clock
from kivy.core.image import Image as CoreImage
from kivy.lang import Builder
from kivy.metrics import dp
from kivy.properties import (
AliasProperty,
BooleanProperty,
BoundedNumericProperty,
ListProperty,
NumericProperty,
ObjectProperty,
ReferenceListProperty,
StringProperty,
VariableListProperty,
)
from kivy.uix.widget import Widget
from PIL import Image, ImageDraw, ImageFilter
from kivymd.app import MDApp
Builder.load_string(
"""
#:import InstructionGroup kivy.graphics.instructions.InstructionGroup
<CommonElevationBehavior>
canvas.before:
# SOFT SHADOW
PushMatrix
Rotate:
angle: self.angle
origin: self._shadow_origin
Color:
group: "soft_shadow"
rgba: root.soft_shadow_cl
Rectangle:
group: "soft_shadow"
texture: self._soft_shadow_texture
size: self.soft_shadow_size
pos: self.soft_shadow_pos
PopMatrix
# HARD SHADOW
PushMatrix
Rotate:
angle: self.angle
origin: self.center
Color:
group: "hard_shadow"
rgba: root.hard_shadow_cl
Rectangle:
group: "hard_shadow"
texture: self.hard_shadow_texture
size: self.hard_shadow_size
pos: self.hard_shadow_pos
PopMatrix
Color:
group: "shadow"
a: 1
""",
filename="CommonElevationBehavior.kv",
)
class CommonElevationBehavior(Widget):
"""Common base class for rectangular and circular elevation behavior."""
elevation = BoundedNumericProperty(0, min=0, errorvalue=0)
"""
Elevation of the widget.
.. note::
Although, this value does not represent the current elevation of the
widget. :attr:`~CommonElevationBehavior._elevation` can be used to
animate the current elevation and come back using the
:attr:`~CommonElevationBehavior.elevation` property directly.
For example:
.. code-block:: python
from kivy.lang import Builder
from kivy.uix.behaviors import ButtonBehavior
from kivymd.app import MDApp
from kivymd.uix.behaviors import CircularElevationBehavior, CircularRippleBehavior
from kivymd.uix.boxlayout import MDBoxLayout
KV = '''
#:import Animation kivy.animation.Animation
<WidgetWithShadow>
size_hint: [None, None]
elevation: 6
animation_: None
md_bg_color: [1] * 4
on_size:
self.radius = [self.height / 2] * 4
on_press:
if self.animation_: \
self.animation_.cancel(self); \
self.animation_ = Animation(_elevation=self.elevation + 6, d=0.08); \
self.animation_.start(self)
on_release:
if self.animation_: \
self.animation_.cancel(self); \
self.animation_ = Animation(_elevation = self.elevation, d=0.08); \
self.animation_.start(self)
MDFloatLayout:
WidgetWithShadow:
size: [root.size[1] / 2] * 2
pos_hint: {"center": [0.5, 0.5]}
'''
class WidgetWithShadow(
CircularElevationBehavior,
CircularRippleBehavior,
ButtonBehavior,
MDBoxLayout,
):
def __init__(self, **kwargs):
# always set the elevation before the super().__init__ call
# self.elevation = 6
super().__init__(**kwargs)
def on_size(self, *args):
self.radius = [self.size[0] / 2]
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
:attr:`elevation` is an :class:`~kivy.properties.BoundedNumericProperty`
and defaults to `0`.
"""
# Shadow rendering properties.
# Shadow rotation memory - SHARED ACROSS OTHER CLASSES.
angle = NumericProperty(0)
"""
Angle of rotation in degrees of the current shadow.
This value is shared across different widgets.
.. note::
This value will affect both, hard and soft shadows.
Each shadow has his own origin point that's computed every time the
elevation changes.
.. warning::
Do not add `PushMatrix` inside the canvas before and add `PopMatrix`
in the next layer, this will cause visual errors, because the stack
used will clip the push and pop matrix already inside the canvas.before
canvas layer.
Incorrect:
.. code-block:: kv
<TiltedWidget>
canvas.before:
PushMatrix
[...]
canvas:
PopMatrix
Correct:
.. code-block:: kv
<TiltedWidget>
canvas.before:
PushMatrix
[...]
PopMatrix
:attr:`angle` is an :class:`~kivy.properties.NumericProperty`
and defaults to `0`.
"""
radius = VariableListProperty([0])
"""
Radius of the corners of the shadow.
This values represents each corner of the shadow, starting from `top-left`
corner and going clockwise.
.. code-block:: python
radius = [
"top-left",
"top-right",
"bottom-right",
"bottom-left",
]
This value can be expanded thus allowing this settings to be valid:
.. code-block:: python
widget.radius=[0] # Translates to [0, 0, 0, 0]
widget.radius=[10, 3] # Translates to [10, 3, 10, 3]
widget.radius=[7.0, 8.7, 1.5, 3.0] # Translates to [7, 8, 1, 3]
.. note::
This value will affect both, hard and soft shadows.
This value only affects :class:`~RoundedRectangularElevationBehavior`
for now, but can be stored and used by custom shadow draw functions.
:attr:`radius` is an :class:`~kivy.properties.VariableListProperty`
and defaults to `[0, 0, 0, 0]`.
"""
# Position of the shadow.
_shadow_origin_x = NumericProperty(0)
"""
Shadow origin `x` position for the rotation origin.
Managed by `_shadow_origin`.
:attr:`_shadow_origin_x` is an :class:`~kivy.properties.NumericProperty`
and defaults to `0`.
.. note::
This property is automatically processed. by _shadow_origin.
"""
_shadow_origin_y = NumericProperty(0)
"""
Shadow origin y position for the rotation origin.
Managed by :attr:`_shadow_origin`.
:attr:`_shadow_origin_y` is an :class:`~kivy.properties.NumericProperty`
and defaults to `0`.
.. note::
This property is automatically processed.
"""
_shadow_origin = ReferenceListProperty(_shadow_origin_x, _shadow_origin_y)
"""
Soft shadow rotation origin point.
:attr:`_shadow_origin` is an :class:`~kivy.properties.ReferenceListProperty`
and defaults to `[0, 0]`.
.. note::
This property is automatically processed and relative to the canvas center.
"""
_shadow_pos = ListProperty([0, 0]) # custom offset
"""
Soft shadow origin point.
:attr:`_shadow_pos` is an :class:`~kivy.properties.ListProperty`
and defaults to `[0, 0]`.
.. note::
This property is automatically processed and relative to the widget's
canvas center.
"""
shadow_pos = ListProperty([0, 0]) # bottom left corner
"""
Custom shadow origin point. If this property is set, :attr:`_shadow_pos`
will be ommited.
This property allows users to fake light source.
:attr:`shadow_pos` is an :class:`~kivy.properties.ListProperty`
and defaults to `[0, 0]`.
.. note::
this value overwrite the :attr:`_shadow_pos` processing.
"""
# Shadow Group shared memory
__shadow_groups = {"global": []}
shadow_group = StringProperty("global")
"""
Widget's shadow group.
By default every widget with a shadow is saved inside the memory
:attr:`__shadow_groups` as a weakref. This means that you can have multiple
light sources, one for every shadow group.
To fake a light source use :attr:`force_shadow_pos`.
:attr:`shadow_group` is an :class:`~kivy.properties.StringProperty`
and defaults to `"global"`.
"""
_elevation = BoundedNumericProperty(0, min=0, errorvalue=0)
"""
Current elevation of the widget.
.. warning::
This property is the current elevation of the widget, do not
use this property directly, instead, use :class:`~CommonElevationBehavior`
elevation.
:attr:`_elevation` is an :class:`~kivy.properties.NumericProperty`
and defaults to `0`.
"""
# soft shadow
_soft_shadow_texture = ObjectProperty()
"""
Texture of the soft shadow texture for the canvas.
:attr:`_soft_shadow_texture` is an :class:`~kivy.core.image.Image`
and defaults to `None`.
.. note::
This property is automatically processed.
"""
soft_shadow_size = ListProperty([0, 0])
"""
Size of the soft shadow texture over the canvas.
:attr:`soft_shadow_size` is an :class:`~kivy.properties.ListProperty`
and defaults to `[0, 0]`.
.. note::
This property is automatically processed.
"""
soft_shadow_pos = ListProperty([0, 0])
"""
Position of the hard shadow texture over the canvas.
:attr:`soft_shadow_pos` is an :class:`~kivy.properties.ListProperty`
and defaults to `[0, 0]`.
.. note::
This property is automatically processed.
"""
soft_shadow_cl = ListProperty([0, 0, 0, 0.50])
"""
Color of the soft shadow.
:attr:`soft_shadow_cl` is an :class:`~kivy.properties.ListProperty`
and defaults to `[0, 0, 0, 0.15]`.
"""
# hard shadow
hard_shadow_texture = ObjectProperty()
"""
Texture of the hard shadow texture for the canvas.
:attr:`hard_shadow_texture` is an :class:`~kivy.core.image.Image`
and defaults to `None`.
.. note::
This property is automatically processed when elevation is changed.
"""
hard_shadow_size = ListProperty([0, 0])
"""
Size of the hard shadow texture over the canvas.
:attr:`hard_shadow_size` is an :class:`~kivy.properties.ListProperty`
and defaults to `[0, 0]`.
.. note::
This property is automatically processed when elevation is changed.
"""
hard_shadow_pos = ListProperty([0, 0])
"""
Position of the hard shadow texture over the canvas.
:attr:`hard_shadow_pos` is an :class:`~kivy.properties.ListProperty`
and defaults to `[0, 0]`.
.. note::
This property is automatically processed when elevation is changed.
"""
hard_shadow_cl = ListProperty([0, 0, 0, 0.15])
"""
Color of the hard shadow.
.. note::
:attr:`hard_shadow_cl` is an :class:`~kivy.properties.ListProperty`
and defaults to `[0, 0, 0, 0.15]`.
"""
# Shared property for some calculations.
# This values are used to improve the gaussain blur and avoid that
# the blur goes outside the texture.
hard_shadow_offset = BoundedNumericProperty(
2, min=0, errorhandler=lambda x: 0 if x < 0 else x
)
"""
This value sets a special offset to the shadow canvas, this offset allows a
correct draw of the canvas size. allowing the effect to correctly blur the
image in the given space.
:attr:`hard_shadow_offset` is an :class:`~kivy.properties.BoundedNumericProperty`
and defaults to `2`.
"""
soft_shadow_offset = BoundedNumericProperty(
4, min=0, errorhandler=lambda x: 0 if x < 0 else x
)
"""
This value sets a special offset to the shadow canvas, this offset allows a
correct draw of the canvas size. allowing the effect to correctly blur the
image in the given space.
:attr:`soft_shadow_offset` is an :class:`~kivy.properties.BoundedNumericProperty`
and defaults to `4`.
"""
draw_shadow = ObjectProperty(None)
"""
This property controls the draw call of the context.
This property is automatically set to :attr:`__draw_shadow__` inside the
`super().__init__ call.` unless the property is different of None.
To set a different drawing instruction function, set this property before the
`super(),__init__` call inside the `__init__` definition of the new class.
You can use the source for this classes as example of how to draw over
with the context:
Real time shadows:
#. :class:`~RectangularElevationBehavior`
#. :class:`~CircularElevationBehavior`
#. :class:`~RoundedRectangularElevationBehavior`
#. :class:`~ObservableShadow`
Fake shadows (d`ont use this property):
#. :class:`~FakeRectangularElevationBehavior`
#. :class:`~FakeCircularElevationBehavior`
:attr:`draw_shadow` is an :class:`~kivy.properties.ObjectProperty`
and defaults to `None`.
.. note:: If this property is left to `None` the
:class:`~CommonElevationBehavior` will set to a function that will
raise a `NotImplementedError` inside `super().__init__`.
Follow the next example to set a new draw instruction for the class
inside `__init__`:
.. code-block:: python
class RoundedRectangularElevationBehavior(CommonElevationBehavior):
'''
Shadow class for the RoundedRectangular shadow behavior.
Controls the size and position of the shadow.
'''
def __init__(self, **kwargs):
self._draw_shadow = WeakMethod(self.__draw_shadow__)
super().__init__(**kwargs)
def __draw_shadow__(self, origin, end, context=None):
context.draw(...)
Context is a `Pillow` `ImageDraw` class. For more information check the
[Pillow official documentation](https://github.com/python-pillow/Pillow/).
"""
# All classes that uses a fake shadow shall set this value as `True`
# for performance.
_fake_elevation = BooleanProperty(False)
def __init__(self, **kwargs):
if self.draw_shadow is None:
self.draw_shadow = WeakMethod(self.__draw_shadow__)
self.prev_shadow_group = None
im = BytesIO()
Image.new("RGBA", (4, 4), color=(0, 0, 0, 0)).save(im, format="png")
im.seek(0)
# Setting a empty image as texture, improves performance.
self._soft_shadow_texture = self.hard_shadow_texture = CoreImage(
im, ext="png"
).texture
Clock.schedule_once(self.shadow_preset, -1)
self.on_shadow_group(self, self.shadow_group)
self.bind(
pos=self._update_shadow,
size=self._update_shadow,
radius=self._update_shadow,
)
super().__init__(**kwargs)
def on_shadow_group(self, instance, value):
"""
This function controls the shadow group of the widget.
Do not use Directly to change the group. instead, use the shadow_group
:attr:`property`.
"""
groups = CommonElevationBehavior.__shadow_groups
if self.prev_shadow_group:
group = groups[self.prev_shadow_group]
for widget in group[:]:
if widget() is self:
group.remove(widget)
group = self.prev_shadow_group = self.shadow_group
if group not in groups:
groups[group] = []
r = ref(self, CommonElevationBehavior._clear_shadow_groups)
groups[group].append(r)
@staticmethod
def _clear_shadow_groups(wk):
# auto flush the element when the weak reference have been deleted
groups = CommonElevationBehavior.__shadow_groups
for group in list(groups.values()):
if not group:
break
if wk in group:
group.remove(wk)
break
def force_shadow_pos(self, shadow_pos):
"""
This property forces the shadow position in every widget inside the
widget. The argument :attr:`shadow_pos` is expected as a <class 'list'>
or <class 'tuple'>.
"""
if self.shadow_group is None:
return
group = CommonElevationBehavior.__shadow_groups[self.shadow_group]
for wk in group[:]:
widget = wk()
if widget is None:
group.remove(wk)
widget.shadow_pos = shadow_pos
del group
def update_group_property(self, property_name, value):
"""
This functions allows to change properties of every widget inside the
shadow group.
"""
if self.shadow_group is None:
return
group = CommonElevationBehavior.__shadow_groups[self.shadow_group]
for wk in group[:]:
widget = wk()
if widget is None:
group.remove(wk)
setattr(widget, property_name, value)
del group
def shadow_preset(self, *args):
"""
This function is meant to set the default configuration of the
elevation.
After a new instance is created, the elevation property will be launched
and thus this function will update the elevation if the KV lang have not
done it already.
Works similar to an `__after_init__` call inside a widget.
"""
from kivymd.uix.card import MDCard
if self.elevation is None and not issubclass(self.__class__, MDCard):
self.elevation = 10
if self._fake_elevation is False:
self._update_shadow(self, self.elevation)
self.bind(
pos=self._update_shadow,
size=self._update_shadow,
_elevation=self._update_shadow,
)
def on_elevation(self, instance, value):
"""
Elevation event that sets the current elevation value to `_elevation`.
"""
if value is not None:
self._elevation = value
def _set_soft_shadow_a(self, value):
value = 0 if value < 0 else (1 if value > 1 else value)
self.soft_shadow_cl[-1] = value
return True
def _set_hard_shadow_a(self, value):
value = 0 if value < 0 else (1 if value > 1 else value)
self.hard_shadow_cl[-1] = value
return True
def _get_soft_shadow_a(self):
return self.soft_shadow_cl[-1]
def _get_hard_shadow_a(self):
return self.hard_shadow_cl[-1]
_soft_shadow_a = AliasProperty(
_get_soft_shadow_a, _set_soft_shadow_a, bind=["soft_shadow_cl"]
)
_hard_shadow_a = AliasProperty(
_get_hard_shadow_a, _set_hard_shadow_a, bind=["hard_shadow_cl"]
)
def on_disabled(self, instance, value):
"""
This function hides the shadow when the widget is disabled.
It sets the shadow to `0`.
"""
if self.disabled is True:
self._elevation = 0
else:
self._elevation = 0 if self.elevation is None else self.elevation
self._update_shadow(self, self._elevation)
try:
super().on_disabled(instance, value)
except Exception:
pass
def _update_elevation(self, instance, value):
self._elevation = value
self._update_shadow(instance, value)
def _update_shadow_pos(self, instance, value):
if self._elevation > 0:
self.hard_shadow_pos = [
self.x - dp(self.hard_shadow_offset), # + self.shadow_pos[0],
self.y - dp(self.hard_shadow_offset), # + self.shadow_pos[1],
]
if self.shadow_pos == [0, 0]:
self.soft_shadow_pos = [
self.x
+ self._shadow_pos[0]
- self._elevation
- dp(self.soft_shadow_offset),
self.y
+ self._shadow_pos[1]
- self._elevation
- dp(self.soft_shadow_offset),
]
else:
self.soft_shadow_pos = [
self.x
+ self.shadow_pos[0]
- self._elevation
- dp(self.soft_shadow_offset),
self.y
+ self.shadow_pos[1]
- self._elevation
- dp(self.soft_shadow_offset),
]
self._shadow_origin = [
self.soft_shadow_pos[0] + self.soft_shadow_size[0] / 2,
self.soft_shadow_pos[1] + self.soft_shadow_size[1] / 2,
]
def on__shadow_pos(self, ins, val):
"""
Updates the shadow with the computed value.
Call this function every time you need to force a shadow update.
"""
self._update_shadow_pos(ins, val)
def on_shadow_pos(self, ins, val):
"""
Updates the shadow with the fixed value.
Call this function every time you need to force a shadow update.
"""
self._update_shadow_pos(ins, val)
def _update_shadow(self, instance, value):
self._update_shadow_pos(instance, value)
if self._elevation > 0 and self._fake_elevation is False:
# dynamic elevation position for the shadow
if self.shadow_pos == [0, 0]:
self._shadow_pos = [0, -self._elevation * 0.4]
# HARD Shadow
offset = int(dp(self.hard_shadow_offset))
size = [
int(self.size[0] + (offset * 2)),
int(self.size[1] + (offset * 2)),
]
im = BytesIO()
# context
img = Image.new("RGBA", tuple(size), color=(0, 0, 0, 0))
# draw context
shadow = ImageDraw.Draw(img)
self.draw_shadow()(
[offset, offset],
[
int(size[0] - 1 - offset),
int(size[1] - 1 - offset),
],
context=shadow
# context=ref(shadow)
)
img = img.filter(
ImageFilter.GaussianBlur(
radius=int(dp(1 + self.hard_shadow_offset / 3))
)
)
img.save(im, format="png")
im.seek(0)
self.hard_shadow_size = size
self.hard_shadow_texture = CoreImage(im, ext="png").texture
# soft shadow
if self.soft_shadow_cl[-1] > 0:
offset = dp(self.soft_shadow_offset)
size = [
int(self.size[0] + dp(self._elevation * 2) + (offset * 2)),
int(self.size[1] + dp(self._elevation * 2) + (offset * 2)),
# ((self._elevation)*2) + x + (offset*2)) for x in self.size
]
im = BytesIO()
img = Image.new("RGBA", tuple(size), color=((0,) * 4))
shadow = ImageDraw.Draw(img)
_offset = int(dp(self._elevation + offset))
self.draw_shadow()(
[
_offset,
_offset,
],
[int(size[0] - _offset - 1), int(size[1] - _offset - 1)],
context=shadow
# context=ref(shadow)
)
img = img.filter(
ImageFilter.GaussianBlur(radius=self._elevation // 2)
)
shadow = ImageDraw.Draw(img)
img.save(im, format="png")
im.seek(0)
self.soft_shadow_size = size
self._soft_shadow_texture = CoreImage(im, ext="png").texture
else:
im = BytesIO()
Image.new("RGBA", (4, 4), color=(0, 0, 0, 0)).save(im, format="png")
im.seek(0)
self._soft_shadow_texture = self.hard_shadow_texture = CoreImage(
im, ext="png"
).texture
return
def _get_center(self):
center = [self.pos[0] + self.width / 2, self.pos[1] + self.height / 2]
return center
def __draw_shadow__(self, origin, end, context=None):
Logger.warning(
f"KivyMD: "
f"If you see this error, this means that either youre using "
f"`CommonElevationBehavio`r directly or your 'shader' dont have a "
f"`_draw_shadow` instruction, remember to overwrite this function"
f"to draw over the image context. Тhe figure you would like. "
f"Or your class {self.__class__.__name__} is not inherited from "
f"any of the classes {__all__}"
)
class RectangularElevationBehavior(CommonElevationBehavior):
"""
Base class for a rectangular elevation behavior.
"""
def __init__(self, **kwargs):
self.draw_shadow = WeakMethod(self.__draw_shadow__)
super().__init__(**kwargs)
def __draw_shadow__(self, origin, end, context=None):
context.rectangle(origin + end, fill=tuple([255] * 4))
class CircularElevationBehavior(CommonElevationBehavior):
"""
Base class for a circular elevation behavior.
"""
def __init__(self, **kwargs):
self.draw_shadow = WeakMethod(self.__draw_shadow__)
super().__init__(**kwargs)
def __draw_shadow__(self, origin, end, context=None):
context.ellipse(origin + end, fill=tuple([255] * 4))
class RoundedRectangularElevationBehavior(CommonElevationBehavior):
"""
Base class for rounded rectangular elevation behavior.
"""
def __init__(self, **kwargs):
self.bind(
radius=self._update_shadow,
)
self.draw_shadow = WeakMethod(self.__draw_shadow__)
super().__init__(**kwargs)
def __draw_shadow__(self, origin, end, context=None):
if self.radius == [0, 0, 0, 0]:
context.rectangle(origin + end, fill=tuple([255] * 4))
else:
radius = [x * 2 for x in self.radius]
context.pieslice(
[
origin[0],
origin[1],
origin[0] + radius[0],
origin[1] + radius[0],
],
180,
270,
fill=(255, 255, 255, 255),
)
context.pieslice(
[
end[0] - radius[1],
origin[1],
end[0],
origin[1] + radius[1],
],
270,
360,
fill=(255, 255, 255, 255),
)
context.pieslice(
[
end[0] - radius[2],
end[1] - radius[2],
end[0],
end[1],
],
0,
90,
fill=(255, 255, 255, 255),
)
context.pieslice(
[
origin[0],
end[1] - radius[3],
origin[0] + radius[3],
end[1],
],
90,
180,
fill=(255, 255, 255, 255),
)
if all((x == self.radius[0] for x in self.radius)):
radius = int(self.radius[0])
context.rectangle(
[
origin[0] + radius,
origin[1],
end[0] - radius,
end[1],
],
fill=(255,) * 4,
)
context.rectangle(
[
origin[0],
origin[1] + radius,
end[0],
end[1] - radius,
],
fill=(255,) * 4,
)
else:
radius = [
max((self.radius[0], self.radius[1])),
max((self.radius[1], self.radius[2])),
max((self.radius[2], self.radius[3])),
max((self.radius[3], self.radius[0])),
]
context.rectangle(
[
origin[0] + self.radius[0],
origin[1],
end[0] - self.radius[1],
end[1] - radius[2],
],
fill=(255,) * 4,
)
context.rectangle(
[
origin[0] + radius[3],
origin[1] + self.radius[1],
end[0],
end[1] - self.radius[2],
],
fill=(255,) * 4,
)
context.rectangle(
[
origin[0] + self.radius[3],
origin[1] + radius[0],
end[0] - self.radius[2],
end[1],
],
fill=(255,) * 4,
)
context.rectangle(
[
origin[0],
origin[1] + self.radius[0],
end[0] - radius[2],
end[1] - self.radius[3],
],
fill=(255,) * 4,
)
class ObservableShadow(CommonElevationBehavior):
"""
ObservableShadow is real time shadow render that it's intended to only
render a partial shadow of widgets based upon on the window observable
area, this is meant to improve the performance of bigger widgets.
.. warning::
This is an empty class, the name has been reserved for future use.
if you include this clas in your object, you wil get a
`NotImplementedError`.
"""
def __init__(self, **kwargs):
# self._shadow = MDApp.get_running_app().theme_cls.round_shadow
# self._fake_elevation=True
raise NotImplementedError(
"ObservableShadow:\n\t" "This class is in current development"
)
super().__init__(**kwargs)
class FakeRectangularElevationBehavior(CommonElevationBehavior):
"""
`FakeRectangularElevationBehavio`r is a shadow mockup for widgets. Improves
performance using cached images inside `kivymd.images` dir
This class cast a fake Rectangular shadow behaind the widget.
You can either use this behavior to overwrite the elevation of a prefab
widget, or use it directly inside a new widget class definition.
Use this class as follows for new widgets:
.. code-block:: python
class NewWidget(
ThemableBehavior,
FakeCircularElevationBehavior,
SpecificBackgroundColorBehavior,
# here you add the other front end classes for the widget front_end,
):
[...]
With this method each class can draw it's content in the canvas in the
correct order, avoiding some visual errors.
`FakeCircularElevationBehavior` will load prefabricated textures to
optimize loading times.
.. note:: About rounded corners:
be careful, since this behavior is a mockup and will not draw any
rounded corners.
"""
def __init__(self, **kwargs):
# self._shadow = MDApp.get_running_app().theme_cls.round_shadow
self.draw_shadow = WeakMethod(self.__draw_shadow__)
self._fake_elevation = True
self._update_shadow(self, self.elevation)
super().__init__(**kwargs)
def _update_shadow(self, *args):
if self._elevation > 0:
# Set shadow size.
ratio = self.width / (self.height if self.height != 0 else 1)
if -2 < ratio < 2:
self._shadow = MDApp.get_running_app().theme_cls.quad_shadow
width = soft_width = self.width * 1.9
height = soft_height = self.height * 1.9
elif ratio <= -2:
self._shadow = MDApp.get_running_app().theme_cls.rec_st_shadow
ratio = abs(ratio)
if ratio > 5:
ratio = ratio * 22
else:
ratio = ratio * 11.5
width = soft_width = self.width * 1.9
height = self.height + dp(ratio)
soft_height = (
self.height + dp(ratio) + dp(self._elevation) * 0.5
)
else:
self._shadow = MDApp.get_running_app().theme_cls.quad_shadow
width = soft_width = self.width * 1.8
height = soft_height = self.height * 1.8
self.soft_shadow_size = (soft_width, soft_height)
self.hard_shadow_size = (width, height)
# Set ``soft_shadow`` parameters.
center_x, center_y = self._get_center()
self.hard_shadow_pos = self.soft_shadow_pos = (
center_x - soft_width / 2,
center_y - soft_height / 2 - dp(self._elevation * 0.5),
)
# Set transparency
self._soft_shadow_a = 0.1 * 1.05**self._elevation
self._hard_shadow_a = 0.4 * 0.8**self._elevation
t = int(round(self._elevation))
if 0 < t <= 23:
self._soft_shadow_texture = (
self._hard_shadow_texture
) = self._shadow.textures[str(t)]
else:
self._soft_shadow_texture = (
self._hard_shadow_texture
) = self._shadow.textures["23"]
else:
self._soft_shadow_a = 0
self._hard_shadow_a = 0
def __draw_shadow__(self, origin, end, context=None):
pass
class FakeCircularElevationBehavior(CommonElevationBehavior):
"""
`FakeCircularElevationBehavior` is a shadow mockup for widgets. Improves
performance using cached images inside `kivymd.images` dir
This class cast a fake elliptic shadow behaind the widget.
You can either use this behavior to overwrite the elevation of a prefab
widget, or use it directly inside a new widget class definition.
Use this class as follows for new widgets:
.. code-block:: python
class NewWidget(
ThemableBehavior,
FakeCircularElevationBehavior,
SpecificBackgroundColorBehavior,
# here you add the other front end classes for the widget front_end,
):
[...]
With this method each class can draw it's content in the canvas in the
correct order, avoiding some visual errors.
`FakeCircularElevationBehavior` will load prefabricated textures to optimize
loading times.
.. note:: About rounded corners:
be careful, since this behavior is a mockup and will not draw any rounded
corners. only perfect ellipses.
"""
def __init__(self, **kwargs):
self._shadow = MDApp.get_running_app().theme_cls.round_shadow
self.draw_shadow = WeakMethod(self.__draw_shadow__)
self._fake_elevation = True
self._update_shadow(self, self.elevation)
super().__init__(**kwargs)
def _update_shadow(self, *args):
if self._elevation > 0:
# set shadow size
width = self.width * 2
height = self.height * 2
center_x, center_y = self._get_center()
x = center_x - width / 2
self.soft_shadow_size = (width, height)
self.hard_shadow_size = (width, height)
# set ``soft_shadow`` parameters
y = center_y - height / 2 - dp(0.5 * self._elevation)
self.soft_shadow_pos = (x, y)
# set ``hard_shadow`` parameters
y = center_y - height / 2 - dp(0.5 * self._elevation)
self.hard_shadow_pos = (x, y)
# shadow transparency
self._soft_shadow_a = 0.1 * 1.05**self._elevation
self._hard_shadow_a = 0.4 * 0.8**self._elevation
t = int(round(self._elevation))
if 0 < t <= 23:
if hasattr(self, "_shadow"):
self._soft_shadow_texture = (
self._hard_shadow_texture
) = self._shadow.textures[str(t)]
else:
self._soft_shadow_texture = (
self._hard_shadow_texture
) = self._shadow.textures["23"]
else:
self._soft_shadow_a = 0
self._hard_shadow_a = 0
def __draw_shadow__(self, origin, end, context=None):
pass