Loading

Loading indicators are used when retrieving data or performing slow computations and help notify users that a process is underway.

Overview

Example of the loading component in a UI

The loading component provides visual feedback indicating a process or action is in progress. It helps set users’ expectations during wait times by signaling that the system is working behind the scenes. Depending on the context, it can be used as a full-page overlay or placed within a specific section or UI element. Use a loading indicator if the expected wait time exceeds three seconds.

Live demo

Note

This live demo contains only a preview of functionality and styles available for this component. Actual widgets may not show the exact same behavior but similar to expected.

Large

CLoadingIndicator:
    role: "Large"

Small

CLoadingIndicator:
    role: "Small"

With overlay

CLoadingLayout:
    CLoadingIndicator:
        role: "Large"

Size

There are two available size tokens for a loading indicator:

• Large

• Small

Use the role property to define the token for the loding indicator size.

CLoadingIndicator:
    role: "small"

Example

from kivy.clock import Clock
from kivy.core.window import Window


def set_softinput(*args) -> None:
    Window.keyboard_anim_args = {"d": 0.2, "t": "in_out_expo"}
    Window.softinput_mode = "below_target"


Window.on_restore(Clock.schedule_once(set_softinput, 0.1))

appkv = """
CScreen:

    GridLayout:
        size_hint: 1, 1
        cols: 1
        padding: dp(16)

        AnchorLayout:

            CLoadingIndicator:
                role: "Large"

        AnchorLayout:

            CLoadingIndicator:
                role: "Small"

        CFloatLayout:
            size_hint_x: 1

            CLabel:
                text: "Overlay"
                halign: "center"
                pos_hint: {"center_y": 0.5, "center_x": 0.5}
                style: "heading_05"

            CLoadingLayout:
                pos_hint: {"center_y": 0.5, "center_x": 0.5}
                CLoadingIndicator:
                    role: "Large"
"""

from kivy.lang import Builder

from carbonkivy.app import CarbonApp
from carbonkivy.uix.screen import CScreen


class myapp(CarbonApp):
    def __init__(self, *args, **kwargs):
        super(myapp, self).__init__(*args, **kwargs)

    def build(self) -> CScreen:
        screen = Builder.load_string(appkv)
        return screen


if __name__ == "__main__":
    myapp().run()

API

class carbonkivy.uix.loading.loading.CLoadingIndicator(*args: Any, **kwargs: Any)

Bases: Widget, HierarchicalLayerBehavior, DeclarativeBehavior

active

BooleanProperty(defaultvalue=True, **kw) Property that represents only a boolean value.

Parameters:

defaultvalue: boolean

Specifies the default value of the property.

angle

NumericProperty(defaultvalue=0, **kw) Property that represents a numeric value.

It only accepts the int or float numeric data type or a string that can be converted to a number as shown below. For other numeric types use ObjectProperty or use errorhandler to convert it to an int/float.

It does not support numpy numbers so they must be manually converted to int/float. E.g. widget.num = np.arange(4)[0] will raise an exception. Numpy arrays are not supported at all, even by ObjectProperty because their comparison does not return a bool. But if you must use a Kivy property, use a ObjectProperty with comparator set to np.array_equal. E.g.:

>>> class A(EventDispatcher):
...     data = ObjectProperty(comparator=np.array_equal)
>>> a = A()
>>> a.bind(data=print)
>>> a.data = np.arange(2)
<__main__.A object at 0x000001C839B50208> [0 1]
>>> a.data = np.arange(3)
<__main__.A object at 0x000001C839B50208> [0 1 2]

Parameters:

defaultvalue: int or float, defaults to 0

Specifies the default value of the property.

>>> wid = Widget()
>>> wid.x = 42
>>> print(wid.x)
42
>>> wid.x = "plop"
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
   File "properties.pyx", line 93, in kivy.properties.Property.__set__
   File "properties.pyx", line 111, in kivy.properties.Property.set
   File "properties.pyx", line 159, in kivy.properties.NumericProperty.check
 ValueError: NumericProperty accept only int/float

Changed in version 1.4.1: NumericProperty can now accept custom text and tuple value to indicate a type, like “in”, “pt”, “px”, “cm”, “mm”, in the format: ‘10pt’ or (10, ‘pt’).

angular_velocity

BoundedNumericProperty(*largs, **kw) Property that represents a numeric value within a minimum bound and/or

maximum bound – within a numeric range.

Parameters:

default: numeric

Specifies the default value of the property.

**kwargs: a list of keyword arguments

If a min parameter is included, this specifies the minimum numeric value that will be accepted. If a max parameter is included, this specifies the maximum numeric value that will be accepted.

bg_color

ColorProperty(defaultvalue=0, **kw) Property that represents a color. The assignment can take either:

• a collection of 3 or 4 float values between 0-1 (kivy default)

• a string in the format #rrggbb or #rrggbbaa

• a string representing color name (eg. ‘red’, ‘yellow’, ‘green’)

Object colormap is used to retrieve color from color name and names definitions can be found at this link. Color can be assigned in different formats, but it will be returned as ObservableList of 4 float elements with values between 0-1.

Parameters:

defaultvalue: list or string, defaults to [1.0, 1.0, 1.0, 1.0]

Specifies the default value of the property.

Added in version 1.10.0.

Changed in version 2.0.0: Color value will be dispatched when set through indexing or slicing, but when setting with slice you must ensure that slice has 4 components with float values between 0-1. Assingning color name as value is now supported. Value None is allowed as default value for property.

on_active(*args) → None

role

OptionProperty(*largs, **kw) Property that represents a string from a predefined list of valid

options.

If the string set in the property is not in the list of valid options (passed at property creation time), a ValueError exception will be raised.

Parameters:

default: any valid type in the list of options

Specifies the default value of the property.

**kwargs: a list of keyword arguments

Should include an options parameter specifying a list (not tuple) of valid options.

For example:

class MyWidget(Widget):
    state = OptionProperty("None", options=["On", "Off", "None"])

rotate(*args) → None

rotation_interval

BoundedNumericProperty(*largs, **kw) Property that represents a numeric value within a minimum bound and/or

maximum bound – within a numeric range.

Parameters:

default: numeric

Specifies the default value of the property.

**kwargs: a list of keyword arguments

If a min parameter is included, this specifies the minimum numeric value that will be accepted. If a max parameter is included, this specifies the maximum numeric value that will be accepted.

stroke_color

ColorProperty(defaultvalue=0, **kw) Property that represents a color. The assignment can take either:

• a collection of 3 or 4 float values between 0-1 (kivy default)

• a string in the format #rrggbb or #rrggbbaa

• a string representing color name (eg. ‘red’, ‘yellow’, ‘green’)

Object colormap is used to retrieve color from color name and names definitions can be found at this link. Color can be assigned in different formats, but it will be returned as ObservableList of 4 float elements with values between 0-1.

Parameters:

defaultvalue: list or string, defaults to [1.0, 1.0, 1.0, 1.0]

Specifies the default value of the property.

Added in version 1.10.0.

Changed in version 2.0.0: Color value will be dispatched when set through indexing or slicing, but when setting with slice you must ensure that slice has 4 components with float values between 0-1. Assingning color name as value is now supported. Value None is allowed as default value for property.

stroke_width

NumericProperty(defaultvalue=0, **kw) Property that represents a numeric value.

It only accepts the int or float numeric data type or a string that can be converted to a number as shown below. For other numeric types use ObjectProperty or use errorhandler to convert it to an int/float.

It does not support numpy numbers so they must be manually converted to int/float. E.g. widget.num = np.arange(4)[0] will raise an exception. Numpy arrays are not supported at all, even by ObjectProperty because their comparison does not return a bool. But if you must use a Kivy property, use a ObjectProperty with comparator set to np.array_equal. E.g.:

>>> class A(EventDispatcher):
...     data = ObjectProperty(comparator=np.array_equal)
>>> a = A()
>>> a.bind(data=print)
>>> a.data = np.arange(2)
<__main__.A object at 0x000001C839B50208> [0 1]
>>> a.data = np.arange(3)
<__main__.A object at 0x000001C839B50208> [0 1 2]

Parameters:

defaultvalue: int or float, defaults to 0

Specifies the default value of the property.

>>> wid = Widget()
>>> wid.x = 42
>>> print(wid.x)
42
>>> wid.x = "plop"
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
   File "properties.pyx", line 93, in kivy.properties.Property.__set__
   File "properties.pyx", line 111, in kivy.properties.Property.set
   File "properties.pyx", line 159, in kivy.properties.NumericProperty.check
 ValueError: NumericProperty accept only int/float

Changed in version 1.4.1: NumericProperty can now accept custom text and tuple value to indicate a type, like “in”, “pt”, “px”, “cm”, “mm”, in the format: ‘10pt’ or (10, ‘pt’).

class carbonkivy.uix.loading.loading.CLoadingLayout(*args: Any, **kwargs: Any)

Bases: CAnchorLayout, HierarchicalLayerBehavior

on_touch_down(touch)

on_touch_move(touch)

on_touch_up(touch)