ae.kivy_auto_width

automatic width mix-in classes for kivy widgets

this ae portion is providing classes to mix them into any kivy widget having a texture property (like e.g. Label or Button), to automatically size and resize widgets and/or to display a long text as scrolling ticker within a tall widget.

automatic font size iteration with animation

mix-in the AutoFontSizeBehavior into any kivy widget with a texture property, to automatically grow or shrink the font size to fully fill the width/height of the widget with the size of their texture.

for more details see in the documentation of the AutoFontSizeBehavior class.

automatic container width with opening animation

the mix-in-class ContainerChildrenAutoWidthBehavior determines the optimal width of a container widget, so that the text of any children widget is fully visible/displayed.

the optimal container width is determined by increasing width of the container in iterations, which are implemented through a kivy Animation. as soon as the texts of all children are fully displayed (or the maximum width is reached), the animation stops.

for more details see in the documentation of the ContainerChildrenAutoWidthBehavior class.

automatic ticker animation

mix-in the SimpleAutoTickerBehavior class to automatically slide the texture of a widget if it is too big to be completely/fully displayed, like in a news-ping-pong-ticker.

for more details check the documentation of the SimpleAutoTickerBehavior class.

Classes

AutoFontSizeBehavior(**kwargs)	mix-in to interpolate the optimal font size so that the texture is filling the full width of the widget.
ContainerChildrenAutoWidthBehavior()	detect minimum width for the complete display of the textures of all children at opening with animation.
SimpleAutoTickerBehavior(**kwargs)	mix-in class to slide texture in a ping-pong-like-ticker animation, if too long to be displayed completely.

class AutoFontSizeBehavior(**kwargs)

Bases: object

mix-in to interpolate the optimal font size so that the texture is filling the full width of the widget.

the desired spacing (left plus right) between the texture border and the widget borders can be set via the auto_font_text_spacing property. additional horizontal padding can be added via the padding[0] value of the mixing-in widget.

to disable the animation, set the length of the auto_font_anim_duration to zero or very short value.

the minimum and maximum of the texture font size can be restricted by setting the attributes auto_font_min_size and auto_font_max_size.

bind: Callable

font_size: float

texture_size: tuple

texture_update: Callable

width: float

height: float

auto_font_anim_duration: float

duration in seconds of the font size grow/shrink animation.

auto_font_anim_duration is a NumericProperty and defaults to 0.9 seconds.

auto_font_text_spacing: float

horizontal padding in pixels between widget and texture width; including the additional horizontal padding[0].

auto_font_text_spacing is a NumericProperty and defaults to 18sp.

_font_size_anim: Animation | None = None

_font_anim_mode: int = 0

_last_font_size: float = 0.0

__init__(**kwargs)

auto_font_max_size: float

maximum font size.

auto_font_max_size is a NumericProperty and defaults to min(MAX_FONT_SIZE, max_font_size).

auto_font_min_size: float

minimum font size.

auto_font_min_size is a NumericProperty and defaults to max(MIN_FONT_SIZE, min_font_size).

_font_size_adjustable()

check if font size needs/has to be adjustable.

_start_font_anim(*_args)

delayed anim check

_stop_font_anim()

_font_size_progress(_anim, _self, _progress)

animation on_progress event handler.

class ContainerChildrenAutoWidthBehavior

Bases: object

detect minimum width for the complete display of the textures of all children at opening with animation.

this mix-in class can be added to any type of container or layout widget to provide a consistent API with open() and close() methods, a on_complete_opened() event and a container attribute.

Note

a container attribute will be automatically created for container classes without it.

the animation starts when the open() method gets called. this call will be forwarded via super() to the container if it has an open method.

at animation start, the width of this container will be set to the value of the auto_width_start attribute. then the container width increases via the running animation until, either:

• the container width is greater than the value of the auto_width_minimum attribute, and the textures of all children are fully visible or

• the container width reaches the app window width minus the window padding specified in the auto_width_window_padding attribute.

the window width gets bound to the container width to ensure proper displaying if the window width changes.

Events:

on_complete_opened:

fired when the container width animation is finished or stopped because all children are fully visible.

children: list[Widget]

list of children widgets of this widget (if it is a BoxLayout).

container: Widget

widget to add the dynamic children to (provided by the widget to be mixed into)

dismiss: Callable

optional method provided by the widget to be mixed into

dispatch: Callable

event dispatch method, provided by the widget to be mixed into

opacity: float

opacity of the widget to be mixed into

parent: Widget

parent of this widget/container.

width: float

width of the widget to be mixed into (mostly a parent of self.container)

auto_width_anim_duration: float

duration in seconds of the auto-width-animation.

auto_width_anim_duration is a NumericProperty and defaults to 0.9 seconds.

auto_width_window_padding: float

horizontal padding in pixels between the window and the container.

auto_width_window_padding is a NumericProperty and defaults to 96sp.

auto_width_minimum: float

minimum container width in pixels (before the width animation will be stopped).

auto_width_minimum is a NumericProperty and defaults to 369sp.

auto_width_child_padding: float

horizontal padding in pixels between child widget and child texture.

auto_width_child_padding is a NumericProperty and defaults to 87sp.

auto_width_start: float

container width in pixels at the start of the width animation.

auto_width_start is a NumericProperty and defaults to 3sp.

_width_anim: Animation = None

_complete_width: float = 0.0

__events__ = ('on_complete_opened',)

close(*_args, **_kwargs)

close/dismiss container/layout (ae.gui popup handling compatibility for all GUI frameworks).

Parameters:

• _args – unused argument (to have compatible signature for DropDown/Popup/ModalView widgets).

• _kwargs – unused argument (to have compatible signature for DropDown/Popup/ModalView widgets).

on_complete_opened()

dispatch event default handler, called on opening when the final width got determined.

open(*_args, **kwargs)

open container, optionally starting auto-width-animation.

Parameters:

• _args – unused argument (to have compatible signature for Popup/ModalView and DropDown widgets passing the parent widget).

• kwargs –

  optional extra arguments:

  • ’animation’: False will disable the width and open()-animations (default=True).

reset_width_detection()

call to reset the last detected minimum container width (e.g., if the children text got changed).

_detect_complete_width()

check clients’ textures until the widest child texture got detected.

Return type:

float

Returns:

0.0 until complete width got detected, then the last detected minimum container width.

_on_complete_opened(*_args)

open animation completion callback/event.

_on_win_width(*_args)

Window.width event handler.

_open_width_progress(_anim, _self, _progress)

animation on_progress event handler.

_win_width_bind()

bind Window width property to container width.

class SimpleAutoTickerBehavior(**kwargs)

Bases: object

mix-in class to slide texture in a ping-pong-like-ticker animation, if too long to be displayed completely.

if the text or size of the widget where this class gets mixed in changes, then this instance is first determining the number of characters that can be displayed completely in this widget. this is done with a kivy animation. the duration of this animation can be set via the property auto_ticker_length_anim_duration.

to adjust the padding space between the widget border and their texture width, the property auto_ticker_text_spacing can be set accordingly.

after determining the maximum number of characters that can be displayed and storing this value into the private attribute _ticker_text_length a second animation - the offset animation - gets started to slide/scroll the text. the speed of the offset animation can be set via the property auto_ticker_offset_anim_speed.

Note

while the ticker animations are running, the text property of the widget is only containing the visible part of the full initial text string. use the private attribute _ori_text to determine the full-text string.

bind: Callable

get_root_window: Callable

halign: str

text: str

texture_size: tuple

texture_update: Callable

unbind: Callable

width: float

auto_ticker_length_anim_duration: float

duration in seconds of the iteration animation to determine the maximum text length.

auto_ticker_length_anim_duration is a NumericProperty and defaults to 0.9 seconds.

_min_text_len: int = 15

minimal length of shortened text

auto_ticker_minimum_text_length: int

minimum shortening text length in characters.

auto_ticker_minimum_text_length is a NumericProperty and defaults to 15 chars.

auto_ticker_offset_anim_speed: float

speed of the ticker text offset animation in characters per second.

auto_ticker_offset_anim_speed is a NumericProperty and defaults to 9.6 chars/s.

auto_ticker_text_spacing: float

horizontal padding between widget and texture width in pixels.

auto_ticker_text_spacing is a NumericProperty and defaults to 18sp.

_bound_properties: dict[str, Callable]

properties of the mixing in widget to bind

_length_anim: Animation | None = None

shorten length animation

_offset_anim: Animation | None = None

ticker text offset animation

_ori_text: str = ''

original/full text string

_ticker_text_offset: int = 0

current animated offset in the ticker text

_ticker_text_length: int = 15

number of characters that are completely visible in the widget

_ticker_text_updating: bool = False

flag to block restart of ticker on internal update of text property

__init__(**kwargs)

_bind_properties()

_start_length_anim(*_args)

_start_offset_anim(offset_on_complete=0)

_stop_length_anim(reset=True)

_stop_offset_anim(reset=True)

_text_changed(*_args)

called on change of the label text.

_ticker_length_progress(_anim, _self, progress)

_ticker_max_offset()

Return type:

int

_ticker_offset_progress(_anim, _self, progress)

_ticker_text_update(text)

_unbind_properties()