Label

morphui.uix.label

Label widgets for MorphUI.

This module provides themed label variants built on Kivy's Label. All labels support auto-sizing, icon rendering via the Material icon font, and full theme integration.

Key classes include MorphLabel for general text, MorphIconLabel for icon glyphs, and a variety of specialized labels used internally by button, chip, text field, tooltip, and data view components.

BaseLabel(**kwargs)

Bases: Label

Base class for MorphUI labels with auto-sizing support.

This class extends the standard Kivy Label to include auto-sizing properties for minimum width and height based on the label's content. It serves as a foundation for more specialized label classes in MorphUI. The auto-sizing properties calculate the minimum size required to display the label's text content, taking into account padding and texture size.

Notes

• Inherits from Kivy's Label.
• Provides :attr:minimum_height and :attr:minimum_width properties for auto-sizing based on content.
• Designed to be extended by other MorphUI label classes.
• Does not include any theming or styling behaviors.

minimum_height = AliasProperty(lambda self: self.texture_size[1], bind=['texture_size']) class-attribute instance-attribute

The minimum height required to display the label's content.

This property calculates the minimum height based on the label's texture size and padding.

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

minimum_width = AliasProperty(lambda self: self.texture_size[0], bind=['texture_size']) class-attribute instance-attribute

The minimum width required to display the label's content.

This property calculates the minimum width based on the label's texture size and padding.

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

default_config = dict() class-attribute instance-attribute

Default configuration values for BaseLabel instances.

MorphSimpleLabel(**kwargs)

Bases: MorphIdentificationBehavior, MorphThemeBehavior, MorphContentLayerBehavior, MorphAutoSizingBehavior, BaseLabel

A simplified themed label widget with only content theming.

This class provides a lightweight label that only handles content color theming without background or border styling. It's ideal for simple text display where you only need theme-aware text colors.

Examples:

from morphui.app import MorphApp
from morphui.uix.label import MorphSimpleLabel
from morphui.uix.boxlayout import MorphBoxLayout

class MyApp(MorphApp):
    def build(self):
        return MorphBoxLayout(
            MorphSimpleLabel(text='Simple themed text'),
            orientation='vertical',
            padding=50,
            spacing=15,)
MyApp().run()

Notes

• Only provides content color theming (no surface/border styling)
• Inherits typography support if typography behavior is available
• Auto-sizing properties can be used for content-based sizing
• Lighter weight than MorphLabel for simple text display needs

default_config = dict(theme_color_bindings=(dict(normal_content_color='content_surface_color')), typography_role='Label', typography_size='medium', typography_weight='Regular', halign='left', valign='center', auto_size=True) class-attribute instance-attribute

Default configuration values for MorphSimpleLabel instances.

Provides minimal label appearance settings: - Left alignment for text readability - Middle vertical alignment for centered appearance - Content color binding for theme integration - Label typography role with medium sizing

These values can be overridden by subclasses or during instantiation.

MorphSimpleIconLabel(**kwargs)

Bases: MorphIconBehavior, MorphSimpleLabel

A simplified icon label with only content theming.

This class extends `MorphSimpleLabel` to display icons using icon
fonts while only providing content color theming. It's ideal for
simple icon display without background or border styling.

Examples

```python

from morphui.app import MorphApp from morphui.uix.label import MorphSimpleIconLabel from morphui.uix.boxlayout import MorphBoxLayout

class MyApp(MorphApp): def build(self): return MorphBoxLayout( MorphSimpleIconLabel( icon='home', typography_size='large',), MorphSimpleIconLabel( icon='user', typography_size='large',), orientation='vertical', padding=50, spacing=15,) MyApp().run() ```

Notes

- Only provides content color theming (no surface/border styling)
- Inherits typography support for icon font rendering
- Auto-sizing properties available for icon-based sizing
- Lighter weight than MorphIconLabel for simple icon display

default_config = dict(theme_color_bindings=(dict(normal_content_color='content_surface_color')), font_name='MaterialIcons', typography_role='Label', typography_size='large', halign='center', valign='center', auto_size=True, padding=(dp(4))) class-attribute instance-attribute

Default configuration values for MorphSimpleIconLabel instances.

Provides minimal icon-specific display settings: - MaterialIcons font for icon character rendering - Center alignment for optimal icon positioning - Primary color theme for icon prominence - Large size suitable for icon visibility - Auto-sizing to fit icon dimensions

These values can be overridden by subclasses or during instantiation.

MorphLabel(**kwargs)

Bases: MorphRoundSidesBehavior, MorphSimpleLabel, MorphSurfaceLayerBehavior

A themed label widget with automatic sizing and typography support.

This class extends the standard Kivy Label to integrate MorphUI's theming, text layering, and auto-sizing behaviors. It provides a flexible label component that adapts to the app's theme and typography settings.

Examples:

from morphui.app import MorphApp
from morphui.uix.label import MorphLabel
from morphui.uix.boxlayout import MorphBoxLayout

class MyApp(MorphApp):
    def build(self):
        return MorphBoxLayout(
            MorphLabel(text='Hello, World!'),
            orientation='vertical',
            padding=50,
            spacing=15,
            theme_style='surface',)
MyApp().run()

Notes

• The theme_color_bindings are automatically removed when theme_style is specified.
• Typography properties are applied if the typography behavior is included.
• Auto-sizing properties can be used to make the label adjust its size based on content.
• Passing font_size, line_height or other typography-related properties in kwargs will override the typography settings.

default_config = dict(theme_color_bindings=(dict(normal_content_color='content_surface_color', normal_surface_color='surface_color')), typography_role='Label', typography_size='medium', typography_weight='Regular', halign='left', valign='center', auto_size=True, padding=(dp(8))) class-attribute instance-attribute

Default configuration values for MorphLabel instances.

Provides standard label appearance and behavior settings: - Left alignment for text readability - Middle vertical alignment for centered appearance - Bounded colors for theme integration - Label typography role with medium sizing

These values can be overridden by subclasses or during instantiation.

MorphIconLabel(**kwargs)

Bases: MorphIconBehavior, MorphLabel

A label designed to display icons using icon fonts.

This class extends MorphLabel to facilitate the use of icon fonts, allowing for easy integration of icons into your UI. It inherits all properties and behaviors from MorphLabel, including theming and auto-sizing capabilities.

Examples:

from morphui.app import MorphApp
from morphui.uix.iconlabel import MorphIconLabel
from morphui.uix.boxlayout import MorphBoxLayout

class MyApp(MorphApp):
    def build(self):
        self.theme_manager.seed_color = 'Purple'
        return MorphBoxLayout(
            MorphIconLabel(
                icon='home',
                theme_style='primary',
                typography_size='huge',),
            MorphIconLabel(
                icon='user',
                theme_style='secondary',
                typography_size='huge',),
            orientation='vertical',
            padding=50,
            spacing=15,
            theme_style='surface',)
        )
MyApp().run()

Notes

• The theme_color_bindings are automatically removed when theme_style is specified.
• Typography properties are applied if the typography behavior is included.
• Auto-sizing properties can be used to make the label adjust its size based on content.
• Passing font_size, line_height or other typography-related properties in kwargs will override the typography settings.

default_config = dict(theme_color_bindings=(dict(normal_content_color='content_surface_variant_color', normal_surface_color='transparent_color')), font_name='MaterialIcons', typography_role='Label', typography_size='large', halign='center', valign='center', auto_size=True, padding=(dp(8))) class-attribute instance-attribute

Default configuration values for MorphIconLabel instances.

Provides icon-specific display and behavior settings: - MaterialIcons font for icon character rendering - Center alignment for optimal icon positioning - Primary color theme for icon prominence - Font size suitable for icon visibility - Auto-sizing to fit icon dimensions

These values can be overridden by subclasses or during instantiation.

MorphLeadingIconLabel(**kwargs)

Bases: MorphScaleBehavior, MorphSimpleIconLabel

Leading icon label for containers.

This widget displays an icon on the left side of a container, with support for scale animations.

MorphTextLabel(**kwargs)

Bases: MorphSimpleLabel

Text label for containers.

This widget displays text mostly used in between leading and trailing icons or other widgets.

MorphHeadingLabel(**kwargs)

Bases: MorphSimpleLabel

Heading label for containers.

This widget displays a heading text mostly used in between leading and trailing icons or other widgets.

MorphTertiaryLabel(**kwargs)

Bases: MorphSimpleLabel

Tertiary label for containers.

This widget displays a tertiary text mostly used in between leading and trailing icons or other widgets.

MorphTrailingIconLabel(**kwargs)

Bases: MorphScaleBehavior, MorphSimpleIconLabel

Trailing icon label for containers.

This widget displays an icon on the right side of a container, with support for scale animations.

MorphButtonLeadingIconLabel(**kwargs)

Bases: MorphLeadingIconLabel

Leading icon label for icon text buttons.

Inherits from :class:~morphui.uix.label.MorphLeadingIconLabel.

MorphButtonTrailingIconLabel(**kwargs)

Bases: MorphTrailingIconLabel

Trailing icon label for text icon buttons.

Inherits from :class:~morphui.uix.label.MorphTrailingIconLabel.

MorphButtonTextLabel(**kwargs)

Bases: MorphTextLabel

Text label for icon text buttons.

Inherits from :class:~morphui.uix.label.MorphTextLabel.

MorphChipLeadingIconLabel(**kwargs)

Bases: MorphLeadingIconLabel

Leading icon label for chips.

Inherits from :class:~morphui.uix.label.MorphLeadingIconLabel.

MorphChipTextLabel(**kwargs)

Bases: MorphTextLabel

Text label for chips.

Inherits from :class:~morphui.uix.label.MorphTextLabel.

MorphTextFieldHeadingLabel(**kwargs)

Bases: MorphSimpleLabel

Heading for text fields with state properties.

This label is specifically designed for use within text field components. It includes properties to indicate whether the label is disabled, focused, or in an error state, allowing for dynamic styling based on the text field's status.

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

Indicates whether the text field label is disabled.

When True, the label is rendered in a disabled state, typically with a different color or style to indicate it is not interactive.

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

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

Indicates whether the text field label is focused.

When True, the label is rendered in a focused state, typically with a different color or style to indicate it is active.

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

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

Indicates whether the text field label is in an error state.

When True, the label is rendered in an error state, typically with a different color or style to indicate a validation issue.

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

MorphTextFieldSupportingLabel(**kwargs)

Bases: MorphSimpleLabel

Supporting label for text fields with state properties.

This label is specifically designed for use within text field components. It includes properties to indicate whether the label is disabled, focused, or in an error state, allowing for dynamic styling based on the text field's status.

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

Indicates whether the supporting label is disabled.

When True, the label is rendered in a disabled state, typically with a different color or style to indicate it is not interactive.

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

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

Indicates whether the supporting label is focused.

When True, the label is rendered in a focused state,typically with a different color or style to indicate it is active.

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

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

Indicates whether the supporting label is in an error state.

When True, the label is rendered in an error state, typically with a different color or style to indicate a validation issue.

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

maximum_width = NumericProperty(dp(200)) class-attribute instance-attribute

The maximum width for the supporting label.

This property defines the maximum width that the supporting label can occupy. It helps in constraining the label's size within the text field layout.

:attr:maximum_width is a :class:~kivy.properties.NumericProperty and defaults to dp(200).

MorphTextFieldTertiaryLabel(**kwargs)

Bases: MorphSimpleLabel

Tertiary label for text fields with state properties.

This label is specifically designed for use within text field components to display the current text length. It includes properties to indicate whether the label is disabled or in an error state, allowing for dynamic styling based on the text field's status.

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

Indicates whether the text length label is disabled.

When True, the label is rendered in a disabled state, typically with a different color or style to indicate it is not interactive.

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

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

Indicates whether the text length label is in an error state.

When True, the label is rendered in an error state, typically with a different color or style to indicate a validation issue.

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

MorphTextFieldLeadingIconLabel(**kwargs)

Bases: MorphSimpleIconLabel

Leading icon label for text fields with state properties.

This label is specifically designed for use within text field components to display a leading icon. It includes properties to indicate whether the label is disabled, focused, or in an error state, allowing for dynamic styling based on the text field's status.

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

Indicates whether the leading icon label is disabled.

When True, the label is rendered in a disabled state, typically with a different color or style to indicate it is not interactive.

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

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

Indicates whether the leading icon label is focused.

When True, the label is rendered in a focused state,typically with a different color or style to indicate it is active.

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

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

Indicates whether the leading icon label is in an error state.

When True, the label is rendered in an error state, typically with a different color or style to indicate a validation issue.

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

MorphTooltipLabel(**kwargs)

Bases: MorphSimpleLabel

A label variant tailored for use inside tooltip widgets.

Subclass of :class:MorphSimpleLabel with tooltip-specific defaults. Override default_config in a further subclass to adapt the appearance without touching the generic label.

default_config = MorphSimpleLabel.default_config | dict(typography_role='Label', typography_size='small') class-attribute instance-attribute

Default configuration for MorphTooltipLabel.

MorphTooltipHeadingLabel(**kwargs)

Bases: MorphTooltipLabel

A bold, medium-sized label for the heading row of a rich tooltip.

default_config = MorphTooltipLabel.default_config | dict(typography_size='medium', bold=True) class-attribute instance-attribute

Default configuration for MorphTooltipHeadingLabel.