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 with 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.

more details see in the documentation of the AutoFontSizeBehavior class.

automatic container width with opening animation

the class ContainerChildrenAutoWidthBehavior determines the optimal width of a container widget, so that the text of any its children widgets 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.

more details see in the documentation of the ContainerChildrenAutoWidthBehavior class.

automatic ticker animation

mix-in the SimpleAutoTickerBehavior class to automatic 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)[source]

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 padding can be added via the padding_x property 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_x).

auto_font_text_spacing is a NumericProperty and defaults to 18sp.

_font_size_anim: Optional[kivy.animation.Animation] = None
_font_anim_mode: int = 0
_last_font_size: float = 0.0
__init__(**kwargs)[source]
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()[source]

check if font size need/has to be adjustable.

_start_font_anim(*_args)[source]

delayed anim check

_stop_font_anim()[source]
_font_size_progress(_anim, _self, _progress)[source]

animation on_progress event handler.

class ContainerChildrenAutoWidthBehavior[source]

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 get 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 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.

container: kivy.uix.widget.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: kivy.uix.widget.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: kivy.animation.Animation = None
_complete_width: float = 0.0
__events__ = ('on_complete_opened',)
close(*_args, **_kwargs)[source]

close/dismiss container/layout (ae.gui_app 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()[source]

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

open(*_args, **kwargs)[source]

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

    extra arguments that are removed before to be passed to the inheriting open method:

    • ’open_width_animation’: False will disable the width animation (default=True).

reset_width_detection()[source]

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

_detect_complete_width()[source]

check clients textures until 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)[source]

open animation completion callback/event.

_on_win_width(*_args)[source]

Window.width event handler.

_open_width_progress(_anim, _self, _progress)[source]

animation on_progress event handler.

_win_width_bind()[source]

bind Window width property to container width.

class SimpleAutoTickerBehavior(**kwargs)[source]

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 get 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 an 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
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.

auto_ticker_offset_anim_speed: float

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

auto_ticker_length_anim_duration is a NumericProperty and defaults to 9.6.

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: Optional[kivy.animation.Animation] = None

shorten length animation

_min_text_len: int = 6

minimal length of shortened text

_offset_anim: Optional[kivy.animation.Animation] = 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 = 6

number of characters that are completely visible in widget

_ticker_text_updating: bool = False

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

__init__(**kwargs)[source]
_bind_properties()[source]
_start_length_anim(*_args)[source]
_start_offset_anim(offset_on_complete=0)[source]
_stop_length_anim(reset=True)[source]
_stop_offset_anim(reset=True)[source]
_text_changed(*_args)[source]

called on change of label text. assert _args[1] == self.text

_ticker_length_progress(_anim, _self, progress)[source]
_ticker_max_offset()[source]
Return type

int

_ticker_offset_progress(_anim, _self, progress)[source]
_ticker_text_update(text)[source]
_unbind_properties()[source]