Skip to content

Latest commit

 

History

History
243 lines (185 loc) · 7.76 KB

PROGRESS_BARS.md

File metadata and controls

243 lines (185 loc) · 7.76 KB

Progress Bars

par-term renders thin overlay progress bars at the top or bottom of the terminal window, driven by standard escape sequences from running processes.

Table of Contents

Overview

Progress bars provide visual feedback for long-running operations directly in the terminal window. They render as thin overlays that do not interfere with terminal content.

graph TD
    Shell[Shell/Application]
    OSC[OSC Escape Sequences]
    Core[Core Library Parser]
    Render[egui Progress Renderer]
    Shader[Shader Uniforms]

    Shell -->|OSC 9;4 / OSC 934| OSC
    OSC --> Core
    Core --> Render
    Core --> Shader

    Render --> Bar[Progress Bar Overlay]
    Shader --> Effects[Shader Effects]

    class Shell neutral
    class OSC data
    class Core primary
    class Render active
    class Shader external
    class Bar,Effects primary

    classDef primary fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    classDef active fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    classDef data fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    classDef external fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    classDef neutral fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
Loading

Protocols

OSC 9;4 (ConEmu/Windows Terminal)

The standard protocol for simple progress bars. Supported states:

State Code Description Visual
Hidden 0 Remove progress bar Bar disappears
Normal 1 Standard progress Blue bar
Error 2 Error occurred Red bar
Indeterminate 3 Unknown progress Gray bar with an animated scrolling brightness wave
Warning 4 Warning state Yellow bar

Sequence format:

ESC ] 9 ; 4 ; state ; percent ST

Examples:

# Show 50% progress
printf "\033]9;4;1;50\007"

# Show error state at 75%
printf "\033]9;4;2;75\007"

# Show indeterminate (animated)
printf "\033]9;4;3;0\007"

# Hide progress bar
printf "\033]9;4;0;0\007"

OSC 934 (Named Progress Bars)

Extended protocol for multiple concurrent named progress bars. Each bar is identified by a unique name and managed independently.

Sequence format:

ESC ] 934 ; action ; id [ ; key=value ... ] ST

Actions:

  • set — Create or update a named progress bar
  • remove — Remove a specific named bar
  • remove_all — Remove all named bars

Parameters (key=value):

  • state — Progress state: normal, error, indeterminate, warning, hidden
  • percent — Progress percentage (0-100)
  • label — Optional text label, drawn only in barwithtext style and only when progress_bar_height is at least 10 pixels

Examples:

# Start two concurrent progress bars with labels
printf "\033]934;set;download;percent=30;label=Downloading file.tar.gz\007"
printf "\033]934;set;compile;state=indeterminate;label=Compiling\007"

# Update one
printf "\033]934;set;download;percent=80;label=Downloading file.tar.gz\007"

# Mark compile as complete and hide
printf "\033]934;remove;compile\007"

# Remove all named bars
printf "\033]934;remove_all\007"

Multiple concurrent bars stack vertically at the configured position (top or bottom of the terminal window), below the tab bar at the top or above the status bar at the bottom. The OSC 9;4 bar is drawn first, followed by named bars sorted by ID.

Configuration

All progress bar settings are available in the Settings UI under Appearance > Progress Bar, which has a General section (enable, style, position, height, opacity) and a Colors section.

Setting Description Default
progress_bar_enabled Enable progress bar rendering true
progress_bar_style Display style: bar or barwithtext (lowercased, no underscore) bar
progress_bar_position Position: top or bottom top
progress_bar_height Bar height in pixels (text labels need 10.0 or more) 4.0
progress_bar_opacity Opacity (0.0-1.0) 0.8
progress_bar_normal_color Color for normal state (RGB) [80, 180, 255] (blue)
progress_bar_warning_color Color for warning state (RGB) [255, 200, 50] (yellow)
progress_bar_error_color Color for error state (RGB) [255, 80, 80] (red)
progress_bar_indeterminate_color Color for indeterminate state (RGB) [150, 150, 150] (gray)

Example configuration:

progress_bar_enabled: true
progress_bar_style: barwithtext
progress_bar_position: bottom
progress_bar_height: 4.0
progress_bar_opacity: 0.9
progress_bar_normal_color: [80, 180, 255]
progress_bar_warning_color: [255, 200, 50]
progress_bar_error_color: [255, 80, 80]
progress_bar_indeterminate_color: [150, 150, 150]

Shader Integration

The iProgress vec4 uniform exposes progress bar state to custom GLSL shaders, enabling shader effects that react to progress:

Component Description Range
iProgress.x State of the OSC 9;4 bar: 0=hidden, 1=normal, 2=error, 3=indeterminate, 4=warning 0.0-4.0
iProgress.y Progress percentage of the OSC 9;4 bar 0.0-1.0
iProgress.z Active flag (any bar visible) 0.0 or 1.0
iProgress.w Active bar count (OSC 9;4 plus named bars) 0.0+

Example shader usage:

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    vec2 uv = fragCoord / iResolution.xy;

    // Glow effect at screen edges during progress
    if (iProgress.z > 0.5) {
        float edge = smoothstep(0.0, 0.05, uv.x) * smoothstep(0.0, 0.05, 1.0 - uv.x);
        float glow = (1.0 - edge) * iProgress.y * 0.3;

        // Color based on state
        vec3 color = vec3(0.0, 1.0, 0.0); // normal = green
        if (iProgress.x > 1.5 && iProgress.x < 2.5) color = vec3(1.0, 0.0, 0.0); // error = red
        if (iProgress.x > 3.5) color = vec3(1.0, 0.8, 0.0); // warning = yellow

        fragColor += vec4(color * glow, glow);
    }
}

See Custom Shaders Guide for complete uniform documentation.

Shell Usage Examples

Bash Progress Wrapper

# Function to show progress for a loop
progress_loop() {
    local total=$1
    shift
    for i in $(seq 1 "$total"); do
        printf "\033]9;4;1;%d\007" $((i * 100 / total))
        "$@"
    done
    printf "\033]9;4;0;0\007"
}

# Usage: progress_loop 10 sleep 0.5

Download Progress

# Show progress during a download
printf "\033]9;4;3;0\007"  # Indeterminate while starting
curl -O https://example.com/file.tar.gz
if [ $? -eq 0 ]; then
    printf "\033]9;4;1;100\007"  # Complete
else
    printf "\033]9;4;2;0\007"    # Error
fi
sleep 1
printf "\033]9;4;0;0\007"  # Hide

Named Concurrent Tasks

# Run multiple tasks with individual progress bars
printf "\033]934;set;lint;percent=0;label=Linting\007"
printf "\033]934;set;test;percent=0;label=Testing\007"

# Update as tasks progress
printf "\033]934;set;lint;percent=50;label=Linting\007"
printf "\033]934;set;test;percent=25;label=Testing\007"

# Complete
printf "\033]934;remove;lint\007"
printf "\033]934;set;test;percent=100;label=Testing complete\007"
printf "\033]934;remove;test\007"

Related Documentation