ProgressView

Previous Next

ProgressView

ProgressView control

A view that shows the progress of an ongoing task. When value is None, an indeterminate spinner is displayed. When value is provided, a determinate progress bar shows the completion percentage as value / total.

Constructor

nib.ProgressView(
    value=None,
    total=1.0,
    label="",
    style=None,
    tint=None,
    **modifiers,
)

Parameters

Parameter Type Default Description
value float | None None Current progress value. When None, displays an indeterminate spinner. When set, shows a progress bar filled to value / total.
total float 1.0 Maximum value representing 100% completion. Set to 100 for percentage values or the actual total for counts.
label str "" Optional text label displayed alongside the progress indicator.
style ProgressStyle | str None Visual style. Options: ProgressStyle.automatic, ProgressStyle.linear (horizontal bar), ProgressStyle.circular (ring indicator).
tint Color | str None Tint color for the progress indicator fill. Accepts a Color enum, hex string, or RGB tuple.
**modifiers Common view modifiers: padding, background, opacity, width, height, etc.

Mutable Properties

Property Type Description
value float | None Get or set the progress value. Set to None for indeterminate mode. Triggers a UI update.
progress float | None Get or set the progress as a fraction (0.0 to 1.0). Internally converts using total.
total float Get or set the total value. Triggers a UI update.
label str Get or set the progress label. Triggers a UI update.

Examples

Indeterminate loading spinner

progressview_indeterminate_loading_spinner

import nib


def main(app: nib.App):
    app.title = "Sync"
    app.icon = nib.SFSymbol("arrow.triangle.2.circlepath")

    app.build(
        nib.HStack(
            controls=[
                nib.ProgressView(style=nib.ProgressStyle.CIRCULAR),
                nib.VStack(
                    controls=[
                        nib.Text("Syncing library", font=nib.Font.HEADLINE),
                        nib.Text(
                            "Checking 1,204 files", foreground_color=nib.Color.SECONDARY
                        ),
                    ],
                    spacing=2,
                    alignment=nib.Alignment.LEADING,
                ),
            ],
            spacing=14,
            padding=20,
        )
    )


nib.run(main)

Determinate download progress

progressview_determinate_download_progress

import threading
import time

import nib


def main(app: nib.App):
    app.title = "Downloads"
    app.icon = nib.SFSymbol("arrow.down.circle")
    app.width = 310

    progress = nib.ProgressView(
        value=0,
        total=100,
        label="nib-runtime.zip",
        style=nib.ProgressStyle.LINEAR,
        tint=nib.Color.BLUE,
        width=260,
    )
    detail = nib.Text(
        "Starting", font=nib.Font.CAPTION, foreground_color=nib.Color.SECONDARY
    )

    def download():
        for done in range(101):
            if not app.is_running:
                return
            progress.value = done
            detail.content = f"{done * 0.42:.1f} MB of 42 MB"
            time.sleep(0.05)
        detail.content = "Complete"

    # Start when the popover opens, so the bar is seen moving.
    app.on_appear = lambda: threading.Thread(target=download, daemon=True).start()

    app.build(
        nib.VStack(
            controls=[nib.Text("Downloads", font=nib.Font.HEADLINE), progress, detail],
            spacing=8,
            padding=20,
            alignment=nib.Alignment.LEADING,
        )
    )


nib.run(main)
Picker Gauge