Skip to content

Layer Behaviors

morphui.uix.behaviors.layer

BaseLayerBehavior(**kwargs)

Bases: MorphStateBehavior, MorphAppReferenceBehavior

Base class for layer behaviors providing core geometric functionality.

This class provides common geometric calculations and mesh generation for all layer behaviors without any automatic binding setup. Each layer behavior subclass is responsible for setting up its own property bindings and event handlers.

Provides: - Radius and corner calculations - Contour generation for rounded rectangles - Mesh generation for filled shapes - Parameter calculation helpers

radius = VariableListProperty([0], length=4) class-attribute instance-attribute

Canvas radius for each corner.

The order of the corners is: top-left, top-right, bottom-right, bottom-left.

:attr:radius is a :class:~kivy.properties.VariableListProperty and defaults to [0, 0, 0, 0].

clamped_radius = AliasProperty(lambda self: self._clamp_radius(), bind=['size', 'radius'], cache=True) class-attribute instance-attribute

Get the clamped radius values (read-only).

This property returns the radius values adjusted to ensure that they do not exceed the widget's dimensions. It is automatically updated when the widget's size or radius changes. This property is applied internally when rendering rounded rectangles to ensure correct display.

:attr:clamped_radius is a :class:~kivy.properties.AliasProperty

rounded_rectangle_params = AliasProperty(lambda self: [*(get_effective_pos(self)), self.width, self.height, *(self.clamped_radius)], bind=['size', 'pos', 'clamped_radius'], cache=True) class-attribute instance-attribute

Get the parameters for creating a rounded rectangle (read-only).

The parameters are returned as a list suitable for use in :class:~kivy.graphics.instructions.SmoothLine instruction. If the widget is a RelativeLayout, the position is set to (0, 0) to ensure correct rendering within the layout's coordinate system.

RETURNS DESCRIPTION
list of float

List containing [x, y, width, height, *radius] for the rounded rectangle.

contour = AliasProperty(lambda self: self._generate_contour(), bind=['size', 'pos', 'clamped_radius'], cache=True) class-attribute instance-attribute

Get the contour points for the rounded rectangle (read-only).

This property returns a flat list of x, y coordinates representing the contour of the rounded rectangle. It is automatically updated when the widget's size, position, or clamped radius changes.

:attr:contour is a :class:~kivy.properties.AliasProperty

mesh = AliasProperty(lambda self: self._generate_mesh(), bind=['contour'], cache=True) class-attribute instance-attribute

Get the mesh vertices and indices for the rounded rectangle (read-only).

This property returns a tuple containing the vertices and indices needed to render the rounded rectangle as a filled shape. It is automatically updated when the contour changes.

:attr:mesh is a :class:~kivy.properties.AliasProperty

MorphHighlightLayerBehavior(**kwargs)

Bases: EventDispatcher

A behavior class that provides highlight styling capabilities.

This behavior adds highlight color properties to widgets. It automatically manages the canvas graphics instructions to render a highlight effect based on the widget's state.

highlight = BooleanProperty(False) class-attribute instance-attribute

Whether to show the highlight effect.

This property controls whether the highlight effect is rendered on the widget. When True, the highlight color is applied.

:attr:highlight is a :class:~kivy.properties.BooleanProperty and defaults to False.

normal_highlight_color = ColorProperty([0, 0, 0, 0]) class-attribute instance-attribute

Current highlight color of the widget.

This property reflects the active highlight color, which may change based on interaction states.

:attr:highlight_color is a :class:~kivy.properties.ColorProperty and defaults to [0, 0, 0, 0] (fully transparent).

highlight_opacity = BoundedNumericProperty(None, min=0, max=1, errorvalue=0.08, allownone=True) class-attribute instance-attribute

Opacity of the highlight color.

This property controls the transparency level of the highlight color, ranging from 0 (fully transparent) to 1 (fully opaque). If set to None, the :attr:highlight_color alpha value is used as is.

:attr:highlight_opacity is a :class:~kivy.properties.BoundedNumericProperty and defaults to None.

refresh_highlight(*args)

Refresh the highlight color.

This method is useful when external changes affect the highlight color and a manual refresh is needed.

on_highlight_updated(*args)

Event dispatched when the highlight is updated.

This event can be used to perform additional actions whenever the highlight effect is refreshed.

MorphSurfaceLayerBehavior(**kwargs)

Bases: BaseLayerBehavior

A behavior class that provides surface and border styling capabilities. Also known as the "surface" layer".

This behavior adds surface color, border color, border width, and corner radius properties to widgets. It automatically manages the canvas graphics instructions to render a rounded rectangle surface with optional border.

Initialize the surface behavior with canvas graphics instructions.

PARAMETER DESCRIPTION
**kwargs

Additional keyword arguments passed to the parent class.

DEFAULT: {}

normal_surface_color = ColorProperty([0, 0, 0, 0]) class-attribute instance-attribute

Surface color of the widget when it is in its normal state.

The color should be provided as a list of RGBA values between 0 and 1. Example: [1, 0, 0, 1] for solid red.

:attr:normal_surface_color is a :class:~kivy.properties.ColorProperty and defaults to [0, 0, 0, 0] (fully transparent).

disabled_surface_color = ColorProperty([0, 0, 0, 0]) class-attribute instance-attribute

Surface color when the widget is disabled.

This color is applied when the widget is in a disabled state. It should be a fully transparent color if you are using state layer. Otherwise, it can be set to any RGBA color.

:attr:disabled_surface_color is a :class:~kivy.properties.ColorProperty and defaults to [0, 0, 0, 0] (fully transparent).

error_surface_color = ColorProperty(None) class-attribute instance-attribute

Surface color when the widget is in an error state.

This color is applied when the widget is in an error state.

:attr:error_surface_color is a :class:~kivy.properties.ColorProperty and defaults to None.

focus_surface_color = ColorProperty(None) class-attribute instance-attribute

Surface color when the widget is focused.

:attr:focus_surface_color is a :class:~kivy.properties.ColorProperty and defaults to None.

active_surface_color = ColorProperty(None) class-attribute instance-attribute

Surface color when the widget is active.

:attr:active_surface_color is a :class:~kivy.properties.ColorProperty and defaults to None.

surface_color = AliasProperty(_get_surface_color, _set_surface_color, bind=['normal_surface_color', 'disabled_surface_color', 'error_surface_color', 'focus_surface_color', 'active_surface_color', 'current_surface_state']) class-attribute instance-attribute

Get the current surface color based on the current state or trigger updates.

This property automatically resolves the appropriate surface color based on the widget's current state (normal, disabled, error, focus, active). Setting this property updates the surface color accordingly. Passing different values will have no effect since it is always synced to the widget's state. However, it can be useful to trigger updates.

:attr:surface_color is a :class:~kivy.properties.AliasProperty and defaults to the resolved surface color based on the current state.

normal_border_color = ColorProperty([0, 0, 0, 0]) class-attribute instance-attribute

Border color of the widget when in the normal state.

The color should be provided as a list of RGBA values between 0 and 1. Example: [0, 1, 0, 1] for solid green.

:attr:normal_border_color is a :class:~kivy.properties.ColorProperty and defaults to [0, 0, 0, 0] (fully transparent).

disabled_border_color = ColorProperty(None) class-attribute instance-attribute

Border color when the widget is disabled.

This color is applied when the widget is in a disabled state.

:attr:disabled_border_color is a :class:~kivy.properties.ColorProperty and defaults to None.

error_border_color = ColorProperty(None) class-attribute instance-attribute

Border color when the widget is in an error state.

:attr:error_border_color is a :class:~kivy.properties.ColorProperty and defaults to None.

focus_border_color = ColorProperty(None) class-attribute instance-attribute

Border color when the widget is focused.

:attr:focus_border_color is a :class:~kivy.properties.ColorProperty and defaults to None.

active_border_color = ColorProperty(None) class-attribute instance-attribute

Border color when the widget is active.

:attr:active_border_color is a :class:~kivy.properties.ColorProperty and defaults to None.

border_color = AliasProperty(_get_border_color, _set_border_color, bind=['normal_border_color', 'disabled_border_color', 'error_border_color', 'focus_border_color', 'active_border_color', 'current_surface_state']) class-attribute instance-attribute

Get the current border color based on the current state or trigger updates.

This property automatically resolves the appropriate border color based on the widget's current state (normal, disabled, error, focus, active). Setting this property updates the border color accordingly. Passing different values will have no effect since it is always synced to the widget's state. However, it can be useful to trigger updates.

:attr:border_color is a :class:~kivy.properties.AliasProperty and defaults to the resolved border color based on the current state.

border_width = BoundedNumericProperty(dp(0.5), min=0.01, errorvalue=1) class-attribute instance-attribute

Width of the border.

The width is specified in pixels.

:attr:border_width is a :class:~kivy.properties.BoundedNumericProperty and defaults to 0.5 (0.5 pixels wide).

border_open_x = NumericProperty(None, allownone=True) class-attribute instance-attribute

X position of the open section of the border.

This property allows you to create an open border effect by specifying the X position in pixels for the open section.

:attr:border_open_x is a :class:~kivy.properties.NumericProperty and defaults to None.

border_open_length = BoundedNumericProperty(0, min=0, errorvalue=0) class-attribute instance-attribute

Length of the open section of the border at the top edge.

This property allows you to create an open border effect by specifying a length in pixels for the open section. A value of 0 means a closed border.

:attr:border_open_length is a :class:~kivy.properties.BoundedNumericProperty and defaults to 0.

border_bottom_line_only = BooleanProperty(False) class-attribute instance-attribute

Whether to show only a bottom line instead of the full border.

When True, only the bottom edge of the widget is drawn as a line. When False, the full border outline is drawn as usual.

:attr:border_bottom_line_only is a :class:~kivy.properties.BooleanProperty and defaults to False.

border_path = AliasProperty(lambda self: self._generate_border_path(), cache=True, bind=['contour', 'border_bottom_line_only', 'border_open_x', 'border_open_length', 'border_closed']) class-attribute instance-attribute

Get the border path points (read-only).

This property returns a flat list of x, y coordinates representing the border path of the rounded rectangle. It is automatically updated when any relevant property changes.

:attr:border_path is a :class:~kivy.properties.AliasProperty

border_closed = AliasProperty(lambda self: not self.border_bottom_line_only and self.border_open_length < dp(1), bind=['border_bottom_line_only', 'border_open_length']) class-attribute instance-attribute

Whether the border is closed (read-only).

This property returns True if the border is closed (i.e., border_open_length is 0), and False otherwise. When border_bottom_line_only is True, this always returns False since a single line would be drawn twice.

refresh_surface()

Reapply the current surface and border colors based on the widget's state.

This method is useful when the theme changes or when the widget's state properties are modified externally. It ensures that the surface and border colors reflect the current state and theme.

on_surface_updated(*args)

Event dispatched when the surface is updated.

This can be overridden by subclasses to perform additional actions when the surface changes.

MorphInteractionLayerBehavior(**kwargs)

Bases: BaseLayerBehavior

A behavior class that provides state layer capabilities.

This behavior adds a state layer on top of widgets, allowing them to display an overlay color based on their state (e.g., pressed, focus, hovered). It automatically manages the canvas graphics instructions to render the state layer.

Examples:

from morphui.app import MorphApp
from morphui.uix.label import MorphLabel
from morphui.uix.behaviors import MorphHoverBehavior
from morphui.uix.behaviors import MorphInteractionLayerBehavior

class TestWidget(MorphHoverBehavior, MorphInteractionLayerBehavior, MorphLabel):
    pass

class MyApp(MorphApp):
    def build(self) -> TestWidget:
        return TestWidget()
MyApp().run()
Notes
  • The interaction layer color is determined by the current theme (light or dark) to ensure visibility against the surface.
  • The opacity of the state layer can be customized for different states (hovered, pressed, focus).
  • This behavior assumes that the widget using it has hovered, pressed, and focus properties. If these properties are not present, the corresponding state layers will not be applied.
  • The state layer is implemented as a semi-transparent rectangle that covers the entire widget area.
  • Ensure this behavior is added after any surface behaviors to ensure the state layer appears above the surface.

hovered_state_opacity = NumericProperty(0.08) class-attribute instance-attribute

Opacity of the state layer when the widget is hovered.

The opacity is specified as a float between 0 and 1. A value of 0 means no state layer, while a value of 1 means a fully opaque state.

:attr:hovered_state_opacity is a :class:~kivy.properties.NumericProperty and defaults to 0.08.

pressed_state_opacity = NumericProperty(0.16) class-attribute instance-attribute

Opacity of the state layer when the widget is pressed.

The opacity is specified as a float between 0 and 1. A value of 0 means no state layer, while a value of 1 means a fully opaque state.

:attr:pressed_state_opacity is a :class:~kivy.properties.NumericProperty and defaults to 0.12.

focus_state_opacity = NumericProperty(0.05) class-attribute instance-attribute

Opacity of the state layer when the widget is focus.

The opacity is specified as a float between 0 and 1. A value of 0 means no state layer, while a value of 1 means a fully opaque state.

:attr:focus_state_opacity is a :class:~kivy.properties.NumericProperty and defaults to 0.05.

disabled_state_opacity = NumericProperty(0.0) class-attribute instance-attribute

Opacity of the state layer when the widget is disabled.

The opacity is specified as a float between 0 and 1. A value of 0 means no state layer, while a value of 1 means a fully opaque state.

:attr:disabled_state_opacity is a :class:~kivy.properties.NumericProperty and defaults to 0.0.

interaction_enabled = BooleanProperty(True) class-attribute instance-attribute

Whether to enable the interaction layer (state-layer) to be displayed.

:attr:interaction_enabled is a :class:~kivy.properties.BooleanProperty and defaults to True.

interaction_gray_value = BoundedNumericProperty(None, min=0, max=1, allownone=True) class-attribute instance-attribute

Base color value for the interaction layer.

This value determines the base grayscale color used for the interaction layer. When set to None (default), the color is automatically determined based on the theme: white (1.0) for dark theme and black (0.0) for light theme to ensure visibility against the surface. When set to a specific value (0-1), that value is used regardless of theme. The opacity of the layer is determined by the specific state (hovered, pressed, focus, etc.).

:attr:interaction_gray_value is a :class:~kivy.properties.BoundedNumericProperty and defaults to None (theme-based automatic selection).

interaction_expansion = VariableListProperty([dp(0)], length=4) class-attribute instance-attribute

Expansion values for the interaction layer.

When positive, these values make the interaction layer bigger than the widget size. The values represent expansion in pixels for each edge in the order: left, bottom, right, top.

:attr:interaction_expansion is a :class:~kivy.properties.VariableListProperty and defaults to [0, 0, 0, 0].

interaction_pos = AliasProperty(_get_interaction_pos, _set_interaction_pos, bind=['pos', 'interaction_expansion'], cache=True) class-attribute instance-attribute

Get the current position of the interaction layer or trigger updates.

The (x, y) position of the interaction layer is calculated by accounting for any expansion. Setting this property updates the position of the interaction layer accordingly. Passing different values will have no effect since it is always synced to the widget's position and expansion. However, it can be useful to trigger updates.

:attr:interaction_pos is a :class:~kivy.properties.AliasProperty and is bound to the pos and interaction_expansion properties.

interaction_size = AliasProperty(_get_interaction_size, _set_interaction_size, bind=['size', 'interaction_expansion'], cache=True) class-attribute instance-attribute

Get the current size of the interaction layer or trigger updates.

The (width, height) size of the interaction layer is calculated by accounting for any expansion. Setting this property updates the size of the interaction layer accordingly. Passing different values will have no effect since it is always synced to the widget's size and expansion. However, it can be useful to trigger updates.

:attr:interaction_size is a :class:~kivy.properties.AliasProperty and is bound to the size and interaction_expansion properties.

interaction_radius = AliasProperty(_get_interaction_radius, _set_interaction_radius, bind=['radius'], cache=True) class-attribute instance-attribute

Get the current radius of the interaction layer or trigger updates.

The radius values of the interaction layer are the same as the widget's clamped radius. Setting this property updates the radius of the interaction layer accordingly. Passing different values will have no effect since it is always synced to the widget's clamped radius. However, it can be useful to trigger updates.

:attr:interaction_radius is a :class:~kivy.properties.AliasProperty and is bound to the radius property.

interaction_color = AliasProperty(_get_interaction_color, _set_interaction_color, bind=['current_interaction_state', 'hovered_state_opacity', 'pressed_state_opacity', 'focus_state_opacity', 'disabled_state_opacity', 'interaction_gray_value', 'interaction_enabled']) class-attribute instance-attribute

Get the interaction layer color or trigger updates.

The interaction layer color is determined by the current theme (light or dark) and the specific state opacity. Setting this property updates the interaction layer color accordingly.

:attr:interaction_color is a :class:~kivy.properties.AliasProperty.

collide_point(x, y)

Check if a point collides with the interaction layer.

This method overrides the default collide_point to account for any expansion of the interaction layer.

PARAMETER DESCRIPTION
x

The x coordinate of the point to check.

TYPE: float

y

The y coordinate of the point to check.

TYPE: float

RETURNS DESCRIPTION
bool

True if the point collides with the interaction layer, False otherwise.

apply_interaction(state)

Apply the interaction layer color for the specified state.

This method sets the interaction layer color based on the widget's current theme (light or dark) and the state's configured opacity. It is called when a state becomes active to visually indicate that state.

PARAMETER DESCRIPTION
state 
'disabled', 'pressed', 'focus', 'hovered', 'active']

The interactive state that is being applied. This should be one of the states defined in :attr:supported_states.

TYPE: Literal[

Examples:

Apply a hover state layer with 8% opacity:

self.apply_interaction('hovered', 0.08)
Notes
  • This method assumes that the widget using this behavior has properties corresponding to the states defined in :attr:supported_states.
  • The method does not check if other states are active; it is assumed that precedence logic is handled elsewhere.
RAISES DESCRIPTION
AssertionError

If the specified state is not in :attr:available_states.

refresh_interaction()

Reapply the current state layer based on the widget's state.

This method is useful when the theme changes or when the widget's state properties are modified externally. It ensures that the state layer reflects the current state and theme.

on_interaction_updated(*args)

Event dispatched when the state layer is updated.

This can be overridden by subclasses to perform additional actions when the state layer changes.

MorphContentLayerBehavior(**kwargs)

Bases: BaseLayerBehavior

A behavior class that provides content layer capabilities.

This behavior adds content color properties to widgets, allowing them to style their content (e.g., text, icons) based on different states. It automatically manages the content color based on the widget's state (e.g., disabled).

Notes

The kivy Label widget uses the generic color property for text rendering. This can lead to ambiguity in theme configurations where the intention is to specify a content color. The content_color property provides a clear, dedicated binding target for content colors in theme configurations. The label widget does also support a outline_color and disabled_outline_color property, which can be used for text outlines/shadows, but this is less commonly used.

normal_content_color = ColorProperty(None) class-attribute instance-attribute

Explicit content color property for theme binding disambiguation.

This property provides a clear, dedicated binding target for content colors in theme configurations. Since Kivy uses the generic 'color' property for text rendering, this explicit content_color property allows theme bindings to unambiguously specify content color intentions in :attr:theme_color_bindings.

:attr:normal_content_color is a :class:~kivy.properties.ColorProperty and defaults to None.

disabled_content_color = AliasProperty(_get_disabled_content_color, _set_disabled_content_color, bind=('_disabled_content_color',)) class-attribute instance-attribute

Content color to use when the widget is disabled.

This property allows you to specify a different content color for the widget when it is in the disabled state. If not set, the default content color will be used.

:attr:disabled_content_color is a :class:~kivy.properties.ColorProperty and defaults to None.

error_content_color = ColorProperty(None) class-attribute instance-attribute

Content color to use when the widget is in an error state.

This property allows you to specify a different content color for the widget when it is in an error state. If not set, the default content color will be used.

:attr:error_content_color is a :class:~kivy.properties.ColorProperty and defaults to None.

focus_content_color = ColorProperty(None) class-attribute instance-attribute

Content color to use when the widget is focused.

This property allows you to specify a different content color for the widget when it is in the focused state. If not set, the default content color will be used.

:attr:focus_content_color is a :class:~kivy.properties.ColorProperty and defaults to None.

hovered_content_color = ColorProperty(None) class-attribute instance-attribute

Content color to use when the widget is hovered.

This property allows you to specify a different content color for the widget when it is in the hovered state. If not set, the default content color will be used.

:attr:hovered_content_color is a :class:~kivy.properties.ColorProperty and defaults to None.

active_content_color = ColorProperty(None) class-attribute instance-attribute

Content color to use when the widget is active.

This property allows you to specify a different content color for the widget when it is in the active state. If not set, the default content color will be used.

:attr:active_content_color is a :class:~kivy.properties.ColorProperty and defaults to None.

content_color = AliasProperty(_get_content_color, _set_content_color, bind=['normal_content_color', 'disabled_content_color', 'error_content_color', 'focus_content_color', 'hovered_content_color', 'active_content_color', 'current_content_state']) class-attribute instance-attribute

Get the current content color based on the current state or trigger updates.

This property automatically resolves the appropriate content color based on the widget's current state (normal, disabled, error, focus, hovered, active). Setting this property updates the content color accordingly. Passing different values will have no effect since it is always synced to the widget's state. However, it can be useful to trigger updates.

:attr:content_color is a :class:~kivy.properties.AliasProperty and defaults to the resolved content color based on the current state.

apply_content(color)

Apply the specified content color to the widget.

This method sets the widget's content color, which is typically used for text or icon colors. It can be called to update the content color based on theme changes or other conditions.

PARAMETER DESCRIPTION
color

The RGBA color to apply to the content, with values between 0 and 1. Example: [1, 0, 0, 1] for solid red.

TYPE: list of float

refresh_content()

Reapply the current content color based on the widget's state.

This method is useful when the theme changes or when the widget's state properties are modified externally. It ensures that the content color reflects the current state and theme.

on_content_updated(*args)

Event dispatched when the content layer is updated.

This can be overridden by subclasses to perform additional actions when the content layer changes.

MorphOverlayLayerBehavior(**kwargs)

Bases: BaseLayerBehavior

A behavior class that provides an overlay layer capability.

This behavior adds an overlay color on top of widgets, allowing them to display a semi-transparent overlay. It automatically manages the canvas graphics instructions to render the overlay.

Examples:

from morphui.app import MorphApp
from morphui.uix.label import MorphLabel
from morphui.uix.behaviors import MorphOverlayLayerBehavior

class TestWidget(MorphOverlayLayerBehavior, MorphLabel):
    pass

class MyApp(MorphApp):
    def build(self) -> TestWidget:
        return TestWidget()
MyApp().run()
Notes
  • The overlay color can be customized to achieve different visual effects.
  • The overlay is implemented as a semi-transparent rectangle that covers the entire widget area.
  • Ensure this behavior is added after any surface behaviors to ensure the overlay appears above the surface.

normal_overlay_color = ColorProperty([0, 0, 0, 0]) class-attribute instance-attribute

Color of the overlay.

The color should be provided as a list of RGBA values between 0 and 1. Example: [0, 0, 0, 0.1] for a semi-transparent black overlay.

:attr:normal_overlay_color is a :class:~kivy.properties.ColorProperty and defaults to [0, 0, 0, 0].

disabled_overlay_color = ColorProperty(None) class-attribute instance-attribute

Color of the overlay when the widget is disabled.

This color is applied when the widget is in a disabled state.

:attr:disabled_overlay_color is a :class:~kivy.properties.ColorProperty and defaults to None.

resizing_overlay_color = ColorProperty(None) class-attribute instance-attribute

Color of the overlay during resizing.

The color should be provided as a list of RGBA values between 0 and 1. Example: [0, 0, 0, 0.1] for a semi-transparent black overlay.

:attr:resizing_overlay_color is a :class:~kivy.properties.ColorProperty and defaults to None.

overlay_color = AliasProperty(_get_overlay_color, _set_overlay_color, bind=['normal_overlay_color', 'disabled_overlay_color', 'resizing_overlay_color', 'current_overlay_state']) class-attribute instance-attribute

Get the overlay color or trigger updates.

The overlay color is determined by the current overlay state. Passing different values will have no effect since it is always synced to the widget's state. However, it can be useful to trigger updates.

:attr:overlay_color is a :class:~kivy.properties.AliasProperty.

normal_overlay_edge_color = ColorProperty([0, 0, 0, 0]) class-attribute instance-attribute

Edge color of the overlay.

The edge color should be provided as a list of RGBA values between 0 and 1. Example: [0, 0, 0, 0.1] for a semi-transparent black edge. The edges can be used to show a resize border when hovering.

:attr:normal_overlay_edge_color is a :class:~kivy.properties.ColorProperty and defaults to [0, 0, 0, 0].

disabled_overlay_edge_color = ColorProperty(None) class-attribute instance-attribute

Edge color of the overlay when the widget is disabled.

This color is applied when the widget is in a disabled state.

:attr:disabled_overlay_edge_color is a :class:~kivy.properties.ColorProperty and defaults to None.

resizing_overlay_edge_color = ColorProperty(None) class-attribute instance-attribute

Edge color of the overlay during resizing.

The edge color should be provided as a list of RGBA values between 0 and 1. Example: [0, 0, 0, 0.1] for a semi-transparent black edge. The edges can be used to show a resize border when hovering.

:attr:resizing_overlay_edge_color is a :class:~kivy.properties.ColorProperty and defaults to None.

active_overlay_edge_color = ColorProperty(None) class-attribute instance-attribute

Edge color of the overlay when the widget is active.

This color is applied when the widget is in an active state.

:attr:active_overlay_edge_color is a :class:~kivy.properties.ColorProperty and defaults to None.

overlay_edge_color = AliasProperty(_get_overlay_edge_color, _set_overlay_edge_color, bind=['normal_overlay_edge_color', 'disabled_overlay_edge_color', 'resizing_overlay_edge_color', 'current_overlay_state', 'visible_edges']) class-attribute instance-attribute

Get the overlay edge color or trigger updates.

The overlay edge color is determined by the current overlay state. Passing different values will have no effect since it is always synced to the widget's state. However, it can be useful to trigger updates.

:attr:overlay_edge_color is a :class:~kivy.properties.AliasProperty.

overlay_edge_width = NumericProperty(dp(1)) class-attribute instance-attribute

Width of the overlay edge.

This width is applied when the widget is in a normal state.

:attr:overlay_edge_width is a :class:~kivy.properties.NumericProperty and defaults to 1.

resizing_overlay_edge_width = NumericProperty(dp(3)) class-attribute instance-attribute

Width of the overlay edge during resizing.

This width is applied when the widget is in a resizing state.

:attr:resizing_overlay_edge_width is a :class:~kivy.properties.NumericProperty and defaults to 3.

overlay_edge_inside = BooleanProperty(True) class-attribute instance-attribute

Whether the overlay edges are drawn inside the widget bounds.

If True, the edges are drawn inside the widget bounds. If False, the edges are drawn centered on the widget bounds.

:attr:overlay_edges_inside is a :class:~kivy.properties.BooleanProperty and defaults to True.

visible_edges = ListProperty([]) class-attribute instance-attribute

List of edges to show for the overlay.

The edges can be 'top', 'right', 'bottom', 'left'. If empty, no edges are shown. Example: ['top', 'bottom'] to show only the top and bottom edges.

:attr:visible_edges is a :class:~kivy.properties.ListProperty and defaults to an empty list.

overlay_layer_pos = AliasProperty(_get_overlay_layer_pos, _set_overlay_layer_pos, bind=['pos'], cache=True) class-attribute instance-attribute

Get or set the position of the overlay layer or trigger update.

The (x, y) position of the overlay layer. Passing different values will have no effect since it is always synced to the widget's position. However, it can be useful to trigger updates.

:attr:overlay_layer_pos is a :class:~kivy.properties.AliasProperty and is bound to the pos property.

overlay_layer_size = AliasProperty(_get_overlay_layer_size, _set_overlay_layer_size, bind=['size'], cache=True) class-attribute instance-attribute

Get the size of the overlay layer.

The (width, height) size of the overlay layer.

:attr:overlay_layer_size is a :class:~kivy.properties.AliasProperty and is bound to the size property.

overlay_layer_radius = AliasProperty(_get_overlay_layer_radius, _set_overlay_layer_radius, bind=['radius'], cache=True) class-attribute instance-attribute

Get the radius of the overlay layer.

The radius values of the overlay layer are the same as the widget's clamped radius.

:attr:overlay_layer_radius is a :class:~kivy.properties.AliasProperty and is bound to the radius property.

overlay_edges_params = AliasProperty(_get_overlay_edges_params, _set_overlay_edges_params, bind=['pos', 'size', 'overlay_edge_width', 'resizing_overlay_edge_width', 'overlay_edge_inside'], cache=True) class-attribute instance-attribute

Get the parameters for creating overlay edge lines.

The parameters are returned as a dictionary with edge names as keys and coordinate lists as values.

:attr:overlay_edges_params is a :class:~kivy.properties.AliasProperty.

get_resolved_edge_width(edge)

Get the overlay edge width based on the current state.

PARAMETER DESCRIPTION
edge

The name of the edge for which to get the width. If None, the default overlay edge width is returned.

TYPE: str | None

RETURNS DESCRIPTION
float

The width of the overlay edge. If the current overlay state is 'resizing', the resizing_overlay_edge_width is returned; otherwise, the standard overlay_edge_width is returned.

apply_overlay(color)

Apply the specified overlay color to the widget.

This method sets the widget's overlay color, which is typically used for visual effects. It can be called to update the overlay color based on theme changes or other conditions.

PARAMETER DESCRIPTION
color

The RGBA color to apply to the overlay, with values between 0 and 1. Example: [1, 0, 0, 0.5] for semi-transparent red.

TYPE: list of float

refresh_overlay()

Reapply the current overlay colors and properties.

This method is useful when the theme changes or when the widget's properties are modified externally. It ensures that the overlay colors and properties reflect the current state and theme.

on_overlay_updated(*args)

Event dispatched when the overlay is updated.

This can be overridden by subclasses to perform additional actions when the overlay changes.

MorphInteractiveLayerBehavior(**kwargs)

Bases: MorphInteractionLayerBehavior, MorphSurfaceLayerBehavior

Convenience mixin combining surface and interaction layers.

This behavior combines surface styling with interaction state management, making it ideal for interactive widgets like buttons, cards, and other clickable elements that need both visual styling and hover/press feedback.

Provides: - Surface color, border, and radius styling - Interaction state layers (hover, press, focus) - Automatic theme-aware state colors

Examples:

from morphui.uix.behaviors import MorphInteractiveLayerBehavior
from morphui.uix.behaviors import MorphHoverBehavior
from kivy.uix.label import Label

class InteractiveCard(
    MorphHoverBehavior,
    MorphInteractiveLayerBehavior, 
    Label
):
    pass
Notes
  • Ensure hover/press behaviors are included for full functionality
  • The interaction layer automatically appears above the surface
  • State colors adapt to the current theme (light/dark)

MorphTextLayerBehavior(**kwargs)

Bases: MorphContentLayerBehavior, MorphSurfaceLayerBehavior

Convenience mixin combining surface and content layers.

This behavior combines surface styling with content color management, making it ideal for text-based widgets like labels, buttons with text, and other widgets that need both background styling and text color theming.

Provides: - Surface color, border, and radius styling
- Content/text color management - Disabled state color handling - Theme-aware color bindings

Examples:

from morphui.uix.behaviors import MorphTextLayerBehavior
from kivy.uix.label import Label

class ThemedLabel(MorphTextLayerBehavior, Label):
    pass
Notes
  • Content colors automatically adapt to theme changes
  • Disabled state colors are handled automatically
  • Works with any widget that has a 'color' property

MorphCompleteLayerBehavior(**kwargs)

Bases: MorphOverlayLayerBehavior, MorphContentLayerBehavior, MorphInteractionLayerBehavior, MorphSurfaceLayerBehavior

Convenience mixin providing all layer behaviors.

This behavior combines all available layer behaviors, providing complete styling and interaction capabilities. It's ideal for complex interactive widgets that need full theming support.

Provides: - Surface color, border, and radius styling - Interaction state layers (hover, press, focus) - Content/text color management
- Overlay layer capability - Complete theme integration - Disabled state handling

Layer Stack (bottom to top): 1. Surface Layer - Background, borders 2. Interaction Layer - State feedback
3. Content Layer - Text/icon colors 4. Overlay Layer - Top-level overlays

Examples:

from morphui.uix.behaviors import MorphCompleteLayerBehavior
from morphui.uix.behaviors import MorphHoverBehavior
from kivy.uix.button import Button

class FullFeaturedButton(
    MorphHoverBehavior,
    MorphCompleteLayerBehavior,
    Button
):
    pass
Notes
  • This is equivalent to using MorphWidget as a base
  • Include appropriate interaction behaviors for full functionality
  • All layers are properly stacked and themed
  • Consider using more specific mixins if not all layers are needed