Siticone Logo
Siticone UI
DOCS
v2025.12.15
Docs Horizontal Progress Bar

Siticone HProgressBar

The SiticoneHProgressBar is a robust, feature-rich progress indicator designed for versatility. Unlike standard progress bars, it offers state-aware coloring (automatically changing colors for Success, Warning, and Error states), interactive dragging, advanced gradients, and built-in text rendering.

Values & Range

Core properties for managing the data represented by the bar.

Property Type Description & Usage Example
Value int progressBar.Value = 75; The current progress position. Setting this triggers a smooth animation to the new value unless UltraFastMode is enabled.
Minimum int progressBar.Minimum = 0; The lower bound of the range (default 0).
Maximum int progressBar.Maximum = 100; The upper bound of the range (default 100).

Appearance & Styling

Customize the visual structure, gradients, and geometry of the control.

Property Type Description & Usage Example
EnableGradient bool progressBar.EnableGradient = true; If true, fills the bar with a gradient blending Start and End colors.
GradientStartColor Color progressBar.GradientStartColor = Color.Blue; Primary color for the gradient.
GradientEndColor Color progressBar.GradientEndColor = Color.Cyan; Secondary color for the gradient.
BackgroundBarColor Color progressBar.BackgroundBarColor = Color.WhiteSmoke; Color of the empty track behind the progress fill.
IndeterminateBarColor Color progressBar.IndeterminateBarColor = Color.Gray; Fills the bar when Indeterminate is true, or serves as a fallback solid color.
EnableShadow bool progressBar.EnableShadow = true; Adds a subtle drop shadow for depth.
CornerRadius... int progressBar.CornerRadiusTopLeft = 15; Individual radius control for all four corners (TopLeft, TopRight, BottomLeft, BottomRight).

States & Thresholds

The control can automatically change colors based on the current value, useful for health bars, battery indicators, or capacity monitors.

Property Type Description & Usage Example
SuccessThreshold int progressBar.SuccessThreshold = 100; Value at which the bar turns to SuccessColor.
WarningThreshold int progressBar.WarningThreshold = 70; Value at which the bar turns to WarningColor.
ErrorThreshold int progressBar.ErrorThreshold = 90; Value at which the bar turns to ErrorColor.
SuccessColor Color progressBar.SuccessColor = Color.Green;
WarningColor Color progressBar.WarningColor = Color.Orange;
ErrorColor Color progressBar.ErrorColor = Color.Red;

Interaction & Behavior

Settings that define how users interact with the control.

Property Type Description & Usage Example
EnableValueDragging bool progressBar.EnableValueDragging = true; Allows the user to click and drag on the bar to change the Value manually.
ValueOrientation Orientation progressBar.ValueOrientation = ProgressBarOrientation.Vertical; Switches the fill direction between Horizontal and Vertical.
IsReadonly bool progressBar.IsReadonly = true; Disables interaction and applies a distinct "locked" visual style.
Indeterminate bool progressBar.Indeterminate = true; Activates the "Marquee" mode, showing a moving block for unknown progress duration.

Text & Labels

Options for displaying overlay text on the bar.

Property Type Description & Usage Example
ShowPercentage bool progressBar.ShowPercentage = true; Displays the current percentage (e.g., "50%") centered on the bar.
CustomLabel string progressBar.CustomLabel = "Loading..."; Overrides the percentage text with a custom string.
AutoLabelColor bool progressBar.AutoLabelColor = true; Automatically toggles text color between Black/White for best contrast against the background.
ShowValueToolTip bool progressBar.ShowValueToolTip = true; Displays a tooltip with the current value when hovering.

Animation & Effects

Property Type Description & Usage Example
EnableClickRipple bool progressBar.EnableClickRipple = true; Shows a material-design ripple animation where the user clicks.
ProgressRipple bool progressBar.ProgressRipple = true; Triggers ripple effects automatically as progress passes milestones.
CanShake bool progressBar.CanShake = true; Shakes the control if a user clicks it while in ReadOnly mode.
AnimationDurationMs double progressBar.AnimationDurationMs = 500; Duration of the fill animation in milliseconds.
UltraFastMode bool progressBar.UltraFastMode = true; Disables heavy visuals (gradients, ripples) for maximum performance.

Designer & Smart Tags

The control is equipped with rich design-time features for rapid prototyping.

Feature Description
Theme Presets Quickly apply full color schemes:
  • Standard: Blue, Green, Red, Orange, Purple.
  • Specialty: Dark Mode, Oceanic Teal, Hot Pink, Charcoal Gray.
  • System: Matches the OS Light/Dark setting.
Visual Styles Square, Rounded, Circular (Pill), Gradient, or Solid styles.
Test Actions Simulate animations directly in the designer: Animate to 0%, 50%, 100%, Success, Warning, or Error thresholds.
Clipboard Copy/Paste UI Settings: Copy the entire visual configuration of one progress bar and apply it to another instantly.

Detailed Usage Examples

Example 1: Dynamic Health Bar

Uses the state thresholds to create a health bar that changes color from Green (Healthy) to Orange (Injured) to Red (Critical).

C# - Health Bar Logic
private void SetupHealthBar()
{
    hpBar.Maximum = 100;
    hpBar.Value = 100;
    
                // Define thresholds (Reverse logic for health: High is Good)
                // Since the control uses >= logic, we configure colors manually or use custom logic
                // Or use the built-in thresholds for a "Damage" bar instead
    
                // Let's use custom logic for a classic HP bar
    hpBar.EnableGradient = false;
    hpBar.ShowPercentage = true;
    hpBar.CustomLabel = "HP: 100%";
    
                UpdateHealthColor();
}

private void TakeDamage(int damage)
{
    hpBar.Value -= damage;
    hpBar.CustomLabel = $"HP: {hpBar.Value}%";
                UpdateHealthColor();
}

private void UpdateHealthColor()
{
                if (hpBar.Value > 70) 
        hpBar.IndeterminateBarColor = Color.LimeGreen;
                else if (hpBar.Value > 30) 
        hpBar.IndeterminateBarColor = Color.Orange;
                else 
        hpBar.IndeterminateBarColor = Color.Red;
}

Example 2: File Upload with States

Demonstrates a file upload process. It starts in Indeterminate mode (Connecting), then switches to progress, and finally shows Success/Error states.

C# - Upload Process
private async void StartUpload()
{
                // 1. Connecting State
    uploadBar.Indeterminate = true;
    uploadBar.CustomLabel = "Connecting...";
                await Task.Delay(1500);
    
                // 2. Uploading State
    uploadBar.Indeterminate = false;
    uploadBar.CustomLabel = ""; // Revert to percentage
    
                for (int i = 0; i <= 100; i += 10)
    {
        uploadBar.Value = i;
                await Task.Delay(200);
        
                // Simulate Error at 50%
                if (i == 50 && ShouldFail())
        {
            uploadBar.IndeterminateBarColor = uploadBar.ErrorColor;
            uploadBar.CustomLabel = "Upload Failed!";
                return;
        }
    }
    
                // 3. Success State
    uploadBar.IndeterminateBarColor = uploadBar.SuccessColor;
    uploadBar.CustomLabel = "Done!";
}

Example 3: Interactive Slider

Using EnableValueDragging to turn the progress bar into an input control (e.g., Volume Slider).

C# - Volume Slider
private void SetupVolumeControl()
{
    volumeBar.EnableValueDragging = true;
    volumeBar.EnableClickRipple = true;
    volumeBar.ShowPercentage = false;
    
                // Visuals
    volumeBar.GradientStartColor = Color.DeepSkyBlue;
    volumeBar.GradientEndColor = Color.Blue;
    volumeBar.BackgroundBarColor = Color.WhiteSmoke;
    
                // Hook into event to update UI in real-time
    volumeBar.ValueChanged += (s, e) => 
    {
        lblVolume.Text = $"Volume: {e.CurrentValue}%";
                SetSystemVolume(e.CurrentValue);
    };
}