ExProgressIndicator

ExProgressIndicator#

#

Terminologies#

Linear and circular expressive progress indicator variants.

Amplitude measures from the center of the resting position to the center of the peak

Wavelength measures the distance between two adjacent peaks

Usage#

Linear#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDExLinearProgressIndicator:
        id: linear_indicator
        size_hint_x: .7
        pos_hint: {'center_x': .5, 'center_y': .5}
        amplitude: dp(3)
        wave_length: dp(40)
        wave_speed: dp(20)
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()

from kivymd.app import MDApp
from kivymd.uix.exprogressindicator import MDExLinearProgressIndicator
from kivymd.uix.screen import MDScreen


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return (
            MDScreen(
                MDExLinearProgressIndicator(
                    size_hint_x=.7,
                    amplitude="3dp",
                    wave_length="40dp",
                    wave_speed="20dp",
                    pos_hint={"center_x": .5, "center_y": .5},
                ),
                md_bg_color=self.theme_cls.backgroundColor,
            )
        )


Example().run()

Example of a linear expressive progress indicator in use.

Circular#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDExCircularProgressIndicator:
        size_hint: None, None
        size: "48dp", "48dp"
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()

from kivymd.app import MDApp
from kivymd.uix.exprogressindicator import MDExCircularProgressIndicator
from kivymd.uix.screen import MDScreen


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return (
            MDScreen(
                MDExCircularProgressIndicator(
                    size_hint=(None, None),
                    size=("48dp", "48dp"),
                    pos_hint={"center_x": .5, "center_y": .5},
                ),
                md_bg_color=self.theme_cls.backgroundColor,
            )
        )


Example().run()

Example of a circular expressive progress indicator in use.

Determinate and indeterminate modes#

Both linear and circular indicators support determinate and indeterminate variants. Set MDExBaseProgressBar.determinate to toggle modes.

Determinate with animated progress#

To improve the visual flow of your progress bars, favor the easing_emphasized transition over linear movement when using kivy.animation.Animation.

from kivy.animation import Animation
from kivy.clock import Clock
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDExLinearProgressIndicator:
        id: progress
        size_hint_x: .7
        determinate: True
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        root = Builder.load_string(KV)
        Clock.schedule_once(self.animate, 0)
        return root

    def animate(self, *_):
        anim = Animation(
            value=100,
            d=1.6,
            t="easing_emphasized",
        )
        anim.start(self.root.ids.progress)


Example().run()

from kivy.animation import Animation
from kivy.clock import Clock

from kivymd.app import MDApp
from kivymd.uix.exprogressindicator import MDExLinearProgressIndicator
from kivymd.uix.screen import MDScreen


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        self.progress = MDExLinearProgressIndicator(
            size_hint_x=.7,
            determinate=True,
            pos_hint={"center_x": .5, "center_y": .5},
        )
        root = MDScreen(
            self.progress,
            md_bg_color=self.theme_cls.backgroundColor,
        )
        Clock.schedule_once(self.animate, 0)
        return root

    def animate(self, *_):
        anim = Animation(
            value=100,
            d=1.6,
            t="easing_emphasized",
        )
        anim.start(self.progress)


Example().run()

Determinate expressive progress indicator animation.

Indeterminate expressive progress indicator animation.

Indeterminate animation modes#

Linear indeterminate modes#

contiguous: a single bar that flows continuously across the track.
discontinuous: two separate bars with gaps between them.

Set the mode with MDExLinearProgressIndicator.indeterminate_animator.

MDExLinearProgressIndicator(
    indeterminate_animator="contiguous",
)

Linear contiguous indeterminate animation.

MDExLinearProgressIndicator(
    indeterminate_animator="discontinuous",
)

Linear discontinuous indeterminate animation.

Circular indeterminate modes#

advanced: multi-phase expansion/collapse with smooth color transitions.
retreat: a single arc that grows and shrinks with rotating emphasis.

Set the mode with MDExCircularProgressIndicator.indeterminate_animator.

MDExCircularProgressIndicator(
    indeterminate_animator="advanced",
)

Circular advanced indeterminate animation with color transitions.

MDExCircularProgressIndicator(
    indeterminate_animator="retreat",
)

Circular retreat indeterminate animation with a single arc.

Note

A comprehensive interactive demo is available in examples/exprogressindicator.py.

API - `kivymd.uix.exprogressindicator.exprogressindicator`#

class kivymd.uix.exprogressindicator.exprogressindicator.MDExBaseProgressBar(**kwargs)#

Base class for extended progress indicators.

Handles shared properties, frame context caching, and wave rendering hooks used by both linear and circular indicators.

For more information, see in the DeclarativeBehavior and ThemableBehavior and classes documentation.

value#

Current value used for the slider.

value is an AliasProperty that returns the value of the progress bar. If the value is < 0 or > max, it will be normalized to those boundaries.

value_normalized#

Normalized value inside the range 0-1:

>>> pb = ProgressBar(value=50, max=100)
>>> pb.value
50
>>> pb.value_normalized
0.5

value_normalized is an AliasProperty.

max#

Maximum value allowed for value.

max is a NumericProperty and defaults to 100.

active_track_color#

Color of active track

active_track_color is a ColorProperty and defaults to None.

inactive_track_color#

Color of inactive track

inactive_track_color is a ColorProperty and defaults to None.

thickness#

Thickness of tracks

thickness is an NumericProperty and defaults to dp(4).

spacing#

Spacing between tracks/segments.

spacing is an NumericProperty and defaults to dp(4).

amplitude#

Amplitude of the wave effect.

amplitude is an NumericProperty and defaults to dp(3).

wave_speed#

Speed of the wave effect.

wave_speed is an NumericProperty and defaults to -dp(40) per second.

wave_length#

Wavelength of the wave effect.

wave_length is an NumericProperty and defaults to dp(40).

determinate#

Switch between determinate and indeterminate modes.

determinate is an BooleanProperty and defaults to False.

color_array#

List of RGBA colors used by indeterminate animations.

color_array is an ListProperty and defaults to three RGBA colors.

get_norm_value()#

set_norm_value(value)#

on_kv_post(base_widget)#

color_obj(line_name)#: Get color object from line.

reset_colors()#

refresh_lines(line_list)#: Clears points and returns a reusable queue.

setup_lines(*args)#: init line objs

render_determinate_wave()#

render_indeterminate_wave()#

save_frame_context(*args)#

on_determinate(instance, value)#

get_amplitude(A, t)#: fade in/out for amplitude using quadratic easing.

class kivymd.uix.exprogressindicator.exprogressindicator.MDExLinearProgressIndicator(**kwargs)#

Implementation of the linear progress indicator.

For more information, see in the MDExBaseProgressBar and classes documentation.

orientation#

Orientation of progressbar. Available options are: ‘horizontal ‘, ‘vertical’.

orientation is an OptionProperty and defaults to ‘horizontal’.

indeterminate_animator#

Name of the indeterminate animator to use for linear mode. Available options are: ‘contiguous’, ‘discontinuous’.

indeterminate_animator is a StringProperty and defaults to ‘discontinuous’.

save_frame_context(*args)#: Pre-calculate geometry and spacing factors for the current frame.

on_color_array(instance, value)#

on_indeterminate_animator(instance, value)#

on_orientation(*args)#

w_seg(start, end) → list#: High-performance wave point generator.

cleanup_lines(line_groups)#

compute_inactive_segments(active_bars)#

render_determinate_wave()#

get_segment_coords(s_f, e_f, do_fade=True)#: Calculates points ensuring consistent visual gaps.

render_discts_wave()#

render_cont_wave()#

render_indeterminate_wave()#

class kivymd.uix.exprogressindicator.exprogressindicator.MDExCircularProgressIndicator(**kwargs)#

Implementation of the circular progress indicator.

For more information, see in the MDExBaseProgressBar and classes documentation.

indeterminate_animator#

Name of the indeterminate animator to use for circular mode. Available options are: ‘advanced’, ‘retreat’.

indeterminate_animator is a StringProperty and defaults to ‘retreat’.

use_color_array#

Whether to use color_array for circular active track colors.

use_color_array is an BooleanProperty and defaults to True.

on_color_array(instance, value)#

save_frame_context(*args)#

w_seg(start, end) → list#

get_arc_points(start_rad, end_rad) → list#

get_start_and_end(init_rad, s_f, e_f)#

render_retreat_wave()#

render_indeterminate_wave()#

render_advanced_wave()#

render_determinate_wave()#

ExProgressIndicator

Contents

ExProgressIndicator#

#

Terminologies#

Usage#

Linear#

Circular#

Determinate and indeterminate modes#

Determinate with animated progress#

Indeterminate animation modes#

Linear indeterminate modes#

Circular indeterminate modes#

API - kivymd.uix.exprogressindicator.exprogressindicator#

API - `kivymd.uix.exprogressindicator.exprogressindicator`#