:github_url: https://github.com/kivymd/KivyMD/blob/master/kivymd/uix/exprogressindicator/exprogressindicator.py ExProgressIndicator =================== .. py:module:: kivymd.uix.exprogressindicator.exprogressindicator .. autoapi-nested-parse:: Components/ExProgressIndicator ============================== .. seealso:: `Material Design spec, Progress indicators `_ .. rubric:: Expressive progress indicators with wave-style animation. - Adds wave amplitude, speed, and wavelength controls. - Supports determinate and indeterminate modes. - Circular indeterminate mode features retreat and advance animation styles. - Linear indeterminate mode offers contiguous and discontinuous visual options. - Linear and circular variants. .. image:: https://github.com/user-attachments/assets/e58e0274-d8c4-42c2-aae8-211907f95788 :align: center :alt: Linear and circular expressive progress indicator variants. Terminologies ------------- .. image:: https://github.com/user-attachments/assets/181298fc-0751-4b42-9b59-7ed7150ff0a8 :align: center :alt: Linear and circular expressive progress indicator variants. :width: 400px - *Amplitude* measures from the center of the resting position to the center of the peak .. image:: https://github.com/user-attachments/assets/04519538-9e7f-4b11-a434-1eab03fad560 :align: center :alt: Linear and circular expressive progress indicator variants. :width: 400px - *Wavelength* measures the distance between two adjacent peaks Usage ----- Linear ~~~~~~~~ .. tabs:: .. tab:: Declarative Python style with KV .. code-block:: python 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() .. tab:: Declarative Python style .. code-block:: python 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() .. image:: https://github.com/user-attachments/assets/d433c88a-24ea-46ce-acd5-4dd2f901d578 :align: center :alt: Example of a linear expressive progress indicator in use. Circular ~~~~~~~~ .. tabs:: .. tab:: Declarative Python style with KV .. code-block:: python 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() .. tab:: Declarative Python style .. code-block:: python 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() .. image:: https://github.com/user-attachments/assets/8c8da3a6-cb70-422b-8be7-cfc29cb40034 :align: center :alt: Example of a circular expressive progress indicator in use. Determinate and indeterminate modes ----------------------------------- Both linear and circular indicators support determinate and indeterminate variants. Set :attr:`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 :class:`kivy.animation.Animation`. .. tabs:: .. tab:: Declarative Python style with KV .. code-block:: python 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() .. tab:: Declarative Python style .. code-block:: python 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() .. image:: https://github.com/user-attachments/assets/c0468075-0f63-43b4-9d78-6324de3dd643 :align: center :alt: Determinate expressive progress indicator animation. .. image:: https://github.com/user-attachments/assets/f68c5cdb-d691-4b6f-b17d-05a4b57724e0 :align: center :alt: 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 :attr:`MDExLinearProgressIndicator.indeterminate_animator`. .. code-block:: python MDExLinearProgressIndicator( indeterminate_animator="contiguous", ) .. image:: https://github.com/user-attachments/assets/5f4fbc91-8507-4098-a388-a85ba90afc30 :align: center :alt: Linear contiguous indeterminate animation. .. code-block:: python MDExLinearProgressIndicator( indeterminate_animator="discontinuous", ) .. image:: https://github.com/user-attachments/assets/c93a29c4-4ce9-4a18-9836-e40df8ae9554 :align: center :alt: 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 :attr:`MDExCircularProgressIndicator.indeterminate_animator`. .. code-block:: python MDExCircularProgressIndicator( indeterminate_animator="advanced", ) .. image:: https://github.com/user-attachments/assets/61be6cf2-d98e-46d5-aab9-c824a54e3d16 :align: center :alt: Circular advanced indeterminate animation with color transitions. .. code-block:: python MDExCircularProgressIndicator( indeterminate_animator="retreat", ) .. image:: https://github.com/user-attachments/assets/1ba0b5de-3824-4209-abe3-e3c5dfeef705 :align: center :alt: Circular retreat indeterminate animation with a single arc. .. note:: A comprehensive interactive demo is available in :file:`examples/exprogressindicator.py`. API - :mod:`kivymd.uix.exprogressindicator.exprogressindicator` --------------------------------------------------------------- .. py:class:: 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 :class:`~kivymd.uix.behaviors.declarative_behavior.DeclarativeBehavior` and :class:`~kivymd.theming.ThemableBehavior` and classes documentation. .. py:attribute:: value Current value used for the slider. :attr:`value` is an :class:`~kivy.properties.AliasProperty` that returns the value of the progress bar. If the value is < 0 or > :attr:`max`, it will be normalized to those boundaries. .. py:attribute:: value_normalized Normalized value inside the range 0-1:: >>> pb = ProgressBar(value=50, max=100) >>> pb.value 50 >>> pb.value_normalized 0.5 :attr:`value_normalized` is an :class:`~kivy.properties.AliasProperty`. .. py:attribute:: max Maximum value allowed for :attr:`value`. :attr:`max` is a :class:`~kivy.properties.NumericProperty` and defaults to 100. .. py:attribute:: active_track_color Color of active track :attr:`active_track_color` is a :class:`~kivy.properties.ColorProperty` and defaults to None. .. py:attribute:: inactive_track_color Color of inactive track :attr:`inactive_track_color` is a :class:`~kivy.properties.ColorProperty` and defaults to None. .. py:attribute:: thickness Thickness of tracks :attr:`thickness` is an :class:`~kivy.properties.NumericProperty` and defaults to `dp(4)`. .. py:attribute:: spacing Spacing between tracks/segments. :attr:`spacing` is an :class:`~kivy.properties.NumericProperty` and defaults to `dp(4)`. .. py:attribute:: amplitude Amplitude of the wave effect. :attr:`amplitude` is an :class:`~kivy.properties.NumericProperty` and defaults to `dp(3)`. .. py:attribute:: wave_speed Speed of the wave effect. :attr:`wave_speed` is an :class:`~kivy.properties.NumericProperty` and defaults to `-dp(40)` per second. .. py:attribute:: wave_length Wavelength of the wave effect. :attr:`wave_length` is an :class:`~kivy.properties.NumericProperty` and defaults to `dp(40)`. .. py:attribute:: determinate Switch between determinate and indeterminate modes. :attr:`determinate` is an :class:`~kivy.properties.BooleanProperty` and defaults to `False`. .. py:attribute:: color_array List of RGBA colors used by indeterminate animations. :attr:`color_array` is an :class:`~kivy.properties.ListProperty` and defaults to three RGBA colors. .. py:method:: get_norm_value() .. py:method:: set_norm_value(value) .. py:method:: on_kv_post(base_widget) .. py:method:: color_obj(line_name) Get color object from line. .. py:method:: reset_colors() .. py:method:: refresh_lines(line_list) Clears points and returns a reusable queue. .. py:method:: setup_lines(*args) init line objs .. py:method:: render_determinate_wave() .. py:method:: render_indeterminate_wave() .. py:method:: save_frame_context(*args) .. py:method:: on_determinate(instance, value) .. py:method:: get_amplitude(A, t) fade in/out for amplitude using quadratic easing. .. py:class:: MDExLinearProgressIndicator(**kwargs) Implementation of the linear progress indicator. For more information, see in the :class:`~kivymd.uix.exprogressindicator.MDExBaseProgressBar` and classes documentation. .. py:attribute:: orientation Orientation of progressbar. Available options are: `'horizontal '`, `'vertical'`. :attr:`orientation` is an :class:`~kivy.properties.OptionProperty` and defaults to `'horizontal'`. .. py:attribute:: indeterminate_animator Name of the indeterminate animator to use for linear mode. Available options are: `'contiguous'`, `'discontinuous'`. :attr:`indeterminate_animator` is a :class:`~kivy.properties.StringProperty` and defaults to `'discontinuous'`. .. py:method:: save_frame_context(*args) Pre-calculate geometry and spacing factors for the current frame. .. py:method:: on_color_array(instance, value) .. py:method:: on_indeterminate_animator(instance, value) .. py:method:: on_orientation(*args) .. py:method:: w_seg(start, end) -> list High-performance wave point generator. .. py:method:: cleanup_lines(line_groups) .. py:method:: compute_inactive_segments(active_bars) .. py:method:: render_determinate_wave() .. py:method:: get_segment_coords(s_f, e_f, do_fade=True) Calculates points ensuring consistent visual gaps. .. py:method:: render_discts_wave() .. py:method:: render_cont_wave() .. py:method:: render_indeterminate_wave() .. py:class:: MDExCircularProgressIndicator(**kwargs) Implementation of the circular progress indicator. For more information, see in the :class:`~kivymd.uix.exprogressindicator.MDExBaseProgressBar` and classes documentation. .. py:attribute:: indeterminate_animator Name of the indeterminate animator to use for circular mode. Available options are: `'advanced'`, `'retreat'`. :attr:`indeterminate_animator` is a :class:`~kivy.properties.StringProperty` and defaults to `'retreat'`. .. py:attribute:: use_color_array Whether to use :attr:`color_array` for circular active track colors. :attr:`use_color_array` is an :class:`~kivy.properties.BooleanProperty` and defaults to `True`. .. py:method:: on_color_array(instance, value) .. py:method:: save_frame_context(*args) .. py:method:: w_seg(start, end) -> list .. py:method:: get_arc_points(start_rad, end_rad) -> list .. py:method:: get_start_and_end(init_rad, s_f, e_f) .. py:method:: render_retreat_wave() .. py:method:: render_indeterminate_wave() .. py:method:: render_advanced_wave() .. py:method:: render_determinate_wave()