Composition Behaviors

morphui.uix.behaviors.composition

Widget composition behaviors for MorphUI.

This module provides behaviors for managing child widget delegation, allowing parent widgets to expose and control properties of their child widgets through aliased properties.

MorphLeadingWidgetBehavior(**kwargs)

Bases: EventDispatcher

Behavior for managing a leading icon widget.

This behavior provides properties and methods for delegating icon management to a child leading_widget. It handles both simple icon changes and stateful icons (normal/active) for toggle-able widgets.

The behavior creates aliased properties that automatically sync with the child widget's properties, providing a clean API for parent widgets.

ATTRIBUTE	DESCRIPTION
leading_widget	The child widget displaying the leading icon TYPE: MorphLeadingIconLabel
leading_icon	Alias to the child's icon property TYPE: str
normal_leading_icon	Alias to the child's normal_icon property TYPE: str
active_leading_icon	Alias to the child's active_icon property TYPE: str

leading_icon = AliasProperty(_get_leading_icon, _set_leading_icon, bind=['leading_widget', '_leading_icon']) class-attribute instance-attribute

The name of the leading icon displayed to the left.

This property gets/sets the icon property of the leading_widget. If the leading_widget supports scale animations, the icon change will be animated smoothly.

:attr:leading_icon is a :class:~kivy.properties.AliasProperty and is bound to changes in the leading_widget.

shows_leading_icon = AliasProperty(lambda self: _is_widget_visible(self.leading_widget), bind=['leading_widget', '_leading_icon']) class-attribute instance-attribute

Whether the leading icon is currently visible.

This property returns True if the leading_widget is not None, has a parent (is in the widget tree), and is not explicitly set to be hidden. It is a read-only property that provides a convenient way to check the visibility of the leading icon.

:attr:shows_leading_icon is a :class:~kivy.properties.AliasProperty that is bound to changes in the leading_widget and its icon.

normal_leading_icon = StringProperty('') class-attribute instance-attribute

The icon name in normal state of the leading icon displayed to the left.

This property is used for toggle-able widgets to specify the icon when the widget is in its normal state. It sets the normal_icon property of the leading_widget.

:attr:normal_leading_icon is a :class:~kivy.properties.StringProperty and defaults to an empty string.

disabled_leading_icon = StringProperty(None, allownone=True) class-attribute instance-attribute

The icon name in disabled state of the leading icon displayed to the left.

This property is used for toggle-able widgets to specify the icon when the widget is in its disabled state. It sets the disabled_icon property of the leading_widget.

:attr:disabled_leading_icon is a :class:~kivy.properties.StringProperty and defaults to None.

focus_leading_icon = StringProperty(None, allownone=True) class-attribute instance-attribute

The icon name in focus state of the leading icon displayed to the left.

This property is used for toggle-able widgets to specify the icon when the widget is in its focus state. It sets the focus_icon property of the leading_widget.

:attr:focus_leading_icon is a :class:~kivy.properties.StringProperty and defaults to None.

active_leading_icon = StringProperty('') class-attribute instance-attribute

The icon name in active state of the leading icon displayed to the left.

This property is used for toggle-able widgets to specify the icon when the widget is in its active state. It sets the active_icon property of the leading_widget.

:attr:active_leading_icon is a :class:~kivy.properties.StringProperty and defaults to an empty string.

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

Whether scale animations are enabled for the leading widget.

If True, changes to the leading icon will be animated with a scale effect. If False, icon changes will happen instantly without animation.

:attr:leading_scale_enabled is a :class:~kivy.properties.BooleanProperty that controls whether scale animations are enabled for the leading icon.

leading_widget = ObjectProperty(None) class-attribute instance-attribute

The leading icon widget displayed to the left.

:attr:leading_widget is by default an instance of :class:~morphui.uix.label.MorphLeadingIconLabel.

refresh_leading_widget()

Refresh the leading widget to reflect current properties.

This method updates the leading_widget to ensure it reflects the current state of the parent widget, including icon names and any other relevant properties.

MorphLabelWidgetBehavior(**kwargs)

Bases: EventDispatcher

Behavior for managing a text label widget.

This behavior provides properties and methods for delegating text content management to a child label_widget. It creates an aliased property that automatically syncs with the child widget's text property.

ATTRIBUTE	DESCRIPTION
label_widget	The child widget displaying the text label TYPE: MorphTextLabel
label_text	Alias to the child's text property TYPE: str

label_text = AliasProperty(_get_label_text, _set_label_text, bind=['label_widget', '_label_text']) class-attribute instance-attribute

The text displayed in the center.

This property gets/sets the text property of the label_widget.

:attr:label_text is a :class:~kivy.properties.AliasProperty and is bound to changes in the label_widget.

label_widget = ObjectProperty(None) class-attribute instance-attribute

The text label widget displayed in the center.

:attr:label_widget is by default an instance of :class:~morphui.uix.label.MorphTextLabel.

shows_label = AliasProperty(lambda self: _is_widget_visible(self.label_widget), bind=['label_widget', '_label_text']) class-attribute instance-attribute

Whether the label is currently visible.

This property returns True if the label_widget is not None, has a parent (is in the widget tree), and has text content. It is a read-only property that provides a convenient way to check the visibility of the label.

:attr:shows_label is a :class:~kivy.properties.AliasProperty that is bound to changes in the label_widget and its text.

refresh_label_widget()

Refresh the label widget to reflect current properties.

This method updates the label_widget to ensure it reflects the current state of the parent widget, including text content and any other relevant properties.

MorphTripleLabelBehavior(**kwargs)

Bases: EventDispatcher

Behavior for managing three text label widgets.

This behavior provides properties and methods for delegating text content management to three child label widgets: heading_widget, supporting_widget, and tertiary_widget. It creates aliased properties that automatically sync with the child widgets' text properties.

heading_text = AliasProperty(_get_heading_text, _set_heading_text, bind=['heading_widget', '_heading_text']) class-attribute instance-attribute

The heading text displayed at the top.

This property gets/sets the text property of the heading_widget.

:attr:heading_text is a :class:~kivy.properties.AliasProperty and is bound to changes in the heading_widget.

heading_widget = ObjectProperty(None) class-attribute instance-attribute

The heading label widget displayed at the top.

This widget is typically used above the main label to provide a headline text.

:attr:heading_widget is by default an instance of :class:~morphui.uix.label.MorphTextLabel.

supporting_text = AliasProperty(_get_supporting_text, _set_supporting_text, bind=['supporting_widget', '_supporting_text']) class-attribute instance-attribute

The supporting text displayed in the center.

This property gets/sets the text property of the supporting_widget.

:attr:supporting_text is a :class:~kivy.properties.AliasProperty and is bound to changes in the supporting_widget.

supporting_widget = ObjectProperty(None) class-attribute instance-attribute

The body label widget displayed in the center.

This widget is typically used below the main label to provide supporting text.

:attr:supporting_widget is by default an instance of :class:~morphui.uix.label.MorphTextLabel.

tertiary_text = AliasProperty(_get_tertiary_text, _set_tertiary_text, bind=['tertiary_widget', '_tertiary_text']) class-attribute instance-attribute

The tertiary text displayed at the bottom.

This property gets/sets the text property of the tertiary_widget.

:attr:tertiary_text is a :class:~kivy.properties.AliasProperty and is bound to changes in the tertiary_widget.

tertiary_widget = ObjectProperty(None) class-attribute instance-attribute

The tertiary label widget displayed at the bottom.

This widget is typically used below the supporting label to provide additional tertiary text.

:attr:tertiary_widget is by default an instance of :class:~morphui.uix.label.MorphTextLabel.

shows_heading = AliasProperty(lambda self: _is_widget_visible(self.heading_widget), bind=['heading_widget', '_heading_text']) class-attribute instance-attribute

Whether the heading label is currently visible.

This property returns True if the heading_widget is not None, has a parent (is in the widget tree), and has text content. It is a read-only property that provides a convenient way to check the visibility of the heading label.

:attr:shows_heading is a :class:~kivy.properties.AliasProperty that is bound to changes in the heading_widget and its text.

shows_supporting = AliasProperty(lambda self: _is_widget_visible(self.supporting_widget), bind=['supporting_widget', '_supporting_text']) class-attribute instance-attribute

Whether the supporting label is currently visible.

This property returns True if the supporting_widget is not None, has a parent (is in the widget tree), and has text content. It is a read-only property that provides a convenient way to check the visibility of the supporting label.

:attr:shows_supporting is a :class:~kivy.properties.AliasProperty that is bound to changes in the supporting_widget and its text.

shows_tertiary = AliasProperty(lambda self: _is_widget_visible(self.tertiary_widget), bind=['tertiary_widget', '_tertiary_text']) class-attribute instance-attribute

Whether the tertiary label is currently visible.

This property returns True if the tertiary_widget is not None, has a parent (is in the widget tree), and has text content. It is a read-only property that provides a convenient way to check the visibility of the tertiary label.

:attr:shows_tertiary is a :class:~kivy.properties.AliasProperty that is bound to changes in the tertiary_widget and its text.

refresh_triple_labels()

Refresh all three label widgets to reflect current properties.

This method updates the heading_widget, supporting_widget, and tertiary_widget to ensure they reflect the current state of the parent widget, including text content and any other relevant properties.

MorphTrailingWidgetBehavior(**kwargs)

Bases: EventDispatcher

Behavior for managing a trailing icon widget.

This behavior provides properties and methods for delegating icon management to a child trailing_widget. It handles both simple icon changes and stateful icons (normal/active) for toggle-able widgets.

The behavior creates aliased properties that automatically sync with the child widget's properties, providing a clean API for parent widgets.

ATTRIBUTE	DESCRIPTION
trailing_widget	The child widget displaying the trailing icon TYPE: MorphTrailingIconLabel
trailing_icon	Alias to the child's icon property TYPE: str
normal_trailing_icon	Alias to the child's normal_icon property TYPE: str
active_trailing_icon	Alias to the child's active_icon property TYPE: str

trailing_icon = AliasProperty(_get_trailing_icon, _set_trailing_icon, bind=['trailing_widget', '_trailing_icon']) class-attribute instance-attribute

The name of the trailing icon displayed to the right.

This property gets/sets the icon property of the trailing_widget. If the trailing_widget supports scale animations, the icon change will be animated smoothly.

:attr:trailing_icon is a :class:~kivy.properties.AliasProperty and is bound to changes in the trailing_widget.

normal_trailing_icon = StringProperty('') class-attribute instance-attribute

The icon name in normal state of the trailing icon displayed to the right.

This property is used for toggle-able widgets to specify the icon when the widget is in its normal state. It sets the normal_icon property of the trailing_widget.

:attr:normal_trailing_icon is a :class:~kivy.properties.StringProperty and defaults to an empty string.

disabled_trailing_icon = StringProperty(None, allownone=True) class-attribute instance-attribute

The icon name in disabled state of the trailing icon displayed to the right.

This property is used for toggle-able widgets to specify the icon when the widget is in its disabled state. It sets the disabled_icon property of the trailing_widget.

:attr:disabled_trailing_icon is a :class:~kivy.properties.StringProperty and defaults to None.

focus_trailing_icon = StringProperty(None, allownone=True) class-attribute instance-attribute

The icon name in focus state of the trailing icon displayed to the right.

This property is used for toggle-able widgets to specify the icon when the widget is in its focus state. It sets the focus_icon property of the trailing_widget.

:attr:focus_trailing_icon is a :class:~kivy.properties.StringProperty and defaults to None.

active_trailing_icon = StringProperty(None, allownone=True) class-attribute instance-attribute

The icon name in active state of the trailing icon displayed to the right.

This property is used for toggle-able widgets to specify the icon when the widget is in its active state. It sets the active_icon property of the trailing_widget.

:attr:active_trailing_icon is a :class:~kivy.properties.StringProperty and defaults to None.

shows_trailing_icon = AliasProperty(lambda self: _is_widget_visible(self.trailing_widget), bind=['trailing_widget', '_trailing_icon']) class-attribute instance-attribute

Whether the trailing icon is currently visible.

This property returns True if the trailing_widget is not None, has a parent (is in the widget tree), and is not explicitly set to be hidden. It is a read-only property that provides a convenient way to check the visibility of the trailing icon.

:attr:shows_trailing_icon is a :class:~kivy.properties.AliasProperty that is bound to changes in the trailing_widget and its icon.

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

Whether scale animations are enabled for the trailing widget.

If True, changes to the trailing icon will be animated with a scale effect. If False, icon changes will happen instantly without animation.

:attr:trailing_scale_enabled is a :class:~kivy.properties.BooleanProperty that controls whether scale animations are enabled for the trailing icon.

trailing_widget = ObjectProperty(None) class-attribute instance-attribute

The trailing icon widget displayed to the right.

:attr:trailing_widget is by default an instance of :class:~morphui.uix.label.MorphTrailingIconLabel.

refresh_trailing_widget()

Refresh the trailing widget to reflect current properties.

This method updates the trailing_widget to ensure it reflects the current state of the parent widget, including icon names and any other relevant properties.