Declarative Behavior

morphui.uix.behaviors.declarative

MorphIdentificationBehavior

A behavior that provides identity-based widget identification.

This behavior allows widgets to have an identity attribute that can be used to identify and reference them within their parent widget. This is particularly useful in declarative UI definitions where you want to reference specific widgets by name.

When a widget with this behavior has an identity set, and is added to a parent widget that also uses :class:MorphDeclarativeBehavior, the widget becomes accessible via the parent's identities dictionary using dot notation.

This functionality is similar to how the ids attribute works in Kivy's kv language, but implemented directly in Python code.

Examples:

class MyWidget(MorphIdentificationBehavior, Widget):
    pass

widget = MyWidget()
widget.identity = 'submit_button'
# When added to a declarative parent:
# parent.identities.submit_button == widget

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

The identity of the widget, similar to the id in kv language.

This property allows widgets to be identified and referenced within their parent widget's :attr:identities dictionary. When a widget with an identity is added to a parent that uses :class:MorphDeclarativeBehavior, it can be accessed via parent.identities.widget_identity.

:attr:identity is a :class:~kivy.properties.StringProperty and defaults to ''.

Examples:

widget = SomeWidget()
widget.identity = 'my_button'
parent.add_widget(widget)
# Access via parent.identities.my_button

identities = AliasProperty(_get_identities, _set_identities, bind=['_identities']) class-attribute instance-attribute

A mapping of child widget identities to their widget instances.

This property provides access to child widgets by their identity strings. When a child widget with an identity is added to this widget, it becomes accessible via this mapping. This is similar to the ids attribute in Kivy's kv language. The mapping is a :class:DotDict, allowing access via dot notation.

:attr:identities is a :class:~kivy.properties.AliasProperty that returns a :class:DotDict mapping identity strings to widget instances.

Examples:

parent = SomeDeclarativeWidget()
child = SomeWidget(identity='my_child')
parent.add_widget(child)
# Access the child via its identity
my_child = parent.identities.my_child

MorphDeclarativeBehavior(*widgets, **kwargs)

Bases: MorphIdentificationBehavior

A mixin that enables declarative widget composition.

This behavior allows you to define and manage child widgets declaratively using the :attr:declarative_children list or by passing widgets as constructor arguments. Child widgets are automatically added to the widget tree, and those with identities become accessible via the :attr:identities mapping.

This provides a Python-based approach to widget composition that's similar to Kivy's kv language but more programmatic and flexible.

Requirements

This behavior requires that the target widget class has:

• :meth:add_widget and :meth:remove_widget methods
• A :attr:children attribute

Most Kivy widgets satisfy these requirements.

Key Features

• Declarative child widget definition
• Automatic widget tree management
• Identity-based widget access
• Constructor-based widget composition
• Nested declarative structures

Examples:

Basic declarative usage:

from kivy.uix.label import Label
from kivy.uix.button import Button
from kivy.uix.boxlayout import BoxLayout
from morphui.uix.behaviors import MorphDeclarativeBehavior

class MyLabel(MorphIdentificationBehavior, Label):
    pass

class MyButton(MorphIdentificationBehavior, Button):
    pass

class MyLayout(MorphDeclarativeBehavior, BoxLayout):
    pass

layout = MyLayout(
    MyLabel(text='Title', identity='title'),
    MyButton(text='OK', identity='ok_button'))

# Access children by identity
title = layout.identities.title
ok_button = layout.identities.ok_button

Initialize the declarative behavior.

This constructor allows widgets to be passed as positional arguments, which will be automatically added to :attr:declarative_children. This provides a convenient way to compose widgets at construction time.

PARAMETER	DESCRIPTION
*widgets	Child widgets to add to :attr:declarative_children. These will be automatically added to the widget tree. TYPE: Widget DEFAULT: ()
**kwargs	Additional keyword arguments passed to the parent constructor. TYPE: Any DEFAULT: {}

Examples:

# Pass children as constructor arguments
layout = MyDeclarativeWidget(
    Label(text='Child 1', identity='label1'),
    Button(text='Child 2', identity='button1')
)

declarative_children = list(widgets) class-attribute instance-attribute

List of child widgets managed declaratively by this widget.

This property contains the widgets that are added as children to this widget through declarative composition. When widgets are added to this list, they are automatically added to the widget tree. Widgets with identities become accessible via the :attr:identities mapping.

The list can be modified directly, and changes will automatically trigger the appropriate add/remove operations on the widget tree.

:attr:declarative_children is a :class:~kivy.properties.ListProperty and defaults to [].

Examples:

Adding children declaratively:

widget.declarative_children = [
    Label(text='First child', identity='label1'),
    Button(text='Second child', identity='btn1')
]

Adding children incrementally:

widget.declarative_children.append(
    Label(text='New child', identity='label2')
)

Removing children:

# Remove by reference
widget.declarative_children.remove(some_widget)

# Or replace the entire list
widget.declarative_children = [new_widget1, new_widget2]

add_widget(widget, *args, **kwargs)

Add a widget as a child and register it declaratively.

This method overrides the standard Kivy :meth:add_widget to integrate with the declarative behavior system. When a widget is added, it's automatically included in :attr:declarative_children and registered in the :attr:identities mapping if it has an identity.

The method prevents duplicate additions and ensures proper synchronization between the declarative children list and the actual widget tree.

PARAMETER	DESCRIPTION
widget	The widget to add as a child. TYPE: Widget
*args	Additional positional arguments passed to the parent's :meth:add_widget method. TYPE: Any DEFAULT: ()
**kwargs	Additional keyword arguments passed to the parent's :meth:add_widget method. TYPE: Any DEFAULT: {}

Notes

If the widget is not already in :attr:declarative_children, it will be added to the list, which will trigger another call to this method to actually add it to the widget tree.

remove_widget(widget, *args, **kwargs)

Remove a child widget and unregister it from declarative management.

This method overrides the standard Kivy :meth:remove_widget to integrate with the declarative behavior system. When a widget is removed, it's automatically removed from :attr:declarative_children and unregistered from the :attr:identities mapping.

The method ensures proper synchronization between the declarative children list and the actual widget tree.

PARAMETER	DESCRIPTION
widget	The widget to remove. TYPE: Widget
*args	Additional positional arguments passed to the parent's :meth:remove_widget method. TYPE: Any DEFAULT: ()
**kwargs	Additional keyword arguments passed to the parent's :meth:remove_widget method. TYPE: Any DEFAULT: {}

Notes

If the widget is in :attr:declarative_children, it will be removed from the list, which will trigger another call to this method to actually remove it from the widget tree.

add_widgets(*children)

Handle changes to the declarative children list.

This method is automatically called when :attr:declarative_children is modified. It ensures that the actual widget tree stays synchronized with the declarative children list by adding new widgets and removing widgets that are no longer in the list.

The synchronization process: 1. Remove widgets that are in the current children but not in the new list 2. Add widgets that are in the new list but not in the current children

This ensures that the widget tree always reflects the current state of :attr:declarative_children.

PARAMETER	DESCRIPTION
children	The new list of declarative children. TYPE: list[Widget] DEFAULT: ()

Notes

This method is called automatically by Kivy's property system when :attr:declarative_children changes. You typically don't need to call this method directly.