Siticone Logo
Siticone UI
DOCS
v2025.12.15
Docs Progress Gauge

Siticone Progress Gauge

The SiticoneProgressGauge is a highly customizable, linear progress tracking control suitable for dashboards, loading screens, and data visualization. It supports multiple visual styles (Neon, Glass, Flat), orientation switching, multi-colored zones, scale rulers, and smooth value transitions.

Values & Range

Properties controlling the core data values, limits, and precision of the gauge.

Property Type Description & Usage Example
CurrentProgress double gauge.CurrentProgress = 75.5; The current value of the gauge. Clamped automatically between MinimumLevel and MaximumLevel.
MinimumLevel double gauge.MinimumLevel = 0; The lower bound of the progress range.
MaximumLevel double gauge.MaximumLevel = 100; The upper bound of the progress range.
DecimalPrecision int gauge.DecimalPrecision = 1; Number of decimal places to display in the progress text (e.g., 1 displays "50.5").
UnitSuffix string gauge.UnitSuffix = "%"; String appended to the value display (e.g., "%", "GB", "°C").

Visual Appearance

Controls the foundational look of the gauge track, including themes, colors, and dimensions.

Property Type Description & Usage Example
AppearanceStyle ProgressAppearanceStyle gauge.AppearanceStyle = ProgressAppearanceStyle.Neon; Applies a preset visual theme. Options: Flat, Modern, Elegant, Minimal, Bold, Gradient, Neon, Glass, Professional, Retro.
Orientation ProgressOrientation gauge.Orientation = ProgressOrientation.Horizontal; Determines layout direction (Horizontal or Vertical).
TrackBaseColor Color gauge.TrackBaseColor = Color.WhiteSmoke; The background color of the unfilled portion of the track.
ProgressFillColor Color gauge.ProgressFillColor = Color.DodgerBlue; The primary color of the filled progress bar.
EnableGradientFill bool gauge.EnableGradientFill = true; If true, fills the progress bar using a gradient from ProgressFillColor to SecondaryFillColor.
TrackHeight float gauge.TrackHeight = 15; The thickness of the progress bar track in pixels.
TrackRadius float gauge.TrackRadius = 8; The rounding radius of the track corners.
ShowTrackGlow bool gauge.ShowTrackGlow = true; Draws a subtle accent glow around the track.
ShowTrackShadow bool gauge.ShowTrackShadow = true; Adds a shadow effect for depth.

Indicator & Animation

Settings for the current-value pointer (head) and motion effects.

Property Type Description & Usage Example
IndicatorType ProgressIndicatorType gauge.IndicatorType = ProgressIndicatorType.Circle; The shape drawn at the current value tip. Options: None, Arrow, Triangle, Diamond, Circle, Square, Line.
IndicatorColor Color gauge.IndicatorColor = Color.White; The fill color of the indicator shape.
IndicatorSize float gauge.IndicatorSize = 10; Size of the indicator shape in pixels.
EnableIndicatorPulse bool gauge.EnableIndicatorPulse = true; If true, the indicator animates with a "breathing" pulse effect.
EnableTransitions bool gauge.EnableTransitions = true; Enables smooth sliding animation when the CurrentProgress value changes.
TransitionSpeed int gauge.TransitionSpeed = 25; Controls the speed of value changes (1-100).

Scale & Rulers

Configuration for the measurement ruler marks and scale labels drawn alongside the track.

Property Type Description & Usage Example
ShowScaleMarks bool gauge.ShowScaleMarks = true; Toggles visibility of measurement tick marks.
MarkType ScaleMarkType gauge.MarkType = ScaleMarkType.Line; Shape of the tick marks. Options: Line, Rectangle, Circle, Diamond.
MajorMarkCount int gauge.MajorMarkCount = 10; Number of primary division marks on the scale.
MinorMarksPerMajor int gauge.MinorMarksPerMajor = 4; Number of smaller marks between each major mark.
ShowScaleLabels bool gauge.ShowScaleLabels = true; Displays numeric text (e.g., "0", "50", "100") at major mark positions.

Zones & Danger

Features for highlighting specific ranges, such as "Critical" or "Success" zones.

Property Type Description & Usage Example
ShowDangerZone bool gauge.ShowDangerZone = true; Automatically highlights the upper portion of the track as a critical area.
DangerLevel double gauge.DangerLevel = 90; Value at which the Danger Zone starts (e.g., 90 to Max).
DangerColor Color gauge.DangerColor = Color.Red; Color used for the Danger Zone highlight.
EnableZoneColoring bool gauge.EnableZoneColoring = true; Enables the rendering of custom color zones added via AddProgressZone().

Text & Fonts

Property Type Description & Usage Example
ShowProgressText bool gauge.ShowProgressText = true; Displays the current numeric value on the gauge.
ProgressCaption string gauge.ProgressCaption = "CPU Load"; Static label text displayed alongside the gauge.
LabelColor Color gauge.LabelColor = Color.Gray; Color for scale labels and text.
ValueFont Font gauge.ValueFont = new Font("Segoe UI", 12f, FontStyle.Bold); Font used for the dynamic progress value.

Public Methods

SetProgress(double, bool)
// Updates the gauge value with optional animation control.
public void UpdateDownload(double bytesReceived, double totalBytes)
{
                double percentage = (bytesReceived / totalBytes) * 100;
    
                // Update value with smooth animation (true)
    progressGauge1.SetProgress(percentage, true);
}
The primary method to update value. The second parameter determines if the transition is animated.
AddProgressZone(start, end, color, label)
// Defines custom colored regions on the track.
// Useful for temperature gauges or performance metrics.
private void SetupZones()
{
    progressGauge1.ClearProgressZones();
    
                // Safe Zone (Green)
    progressGauge1.AddProgressZone(0, 60, Color.LightGreen, "Safe");
    
                // Warning Zone (Orange)
    progressGauge1.AddProgressZone(60, 85, Color.Orange, "Warning");
    
                // Critical Zone (Red)
    progressGauge1.AddProgressZone(85, 100, Color.Red, "Critical");
    
    progressGauge1.EnableZoneColoring = true;
}

Events

Events Wiring
// 1. ProgressChanged Event
// Fires immediately when the value property is updated.
gauge.ProgressChanged += (s, e) => 
{
                Debug.WriteLine($"Value changed from {e.OldProgress} to {e.NewProgress}");
};

// 2. TransitionComplete Event
// Fires when the visual animation has finished sliding to the new value.
// Useful for triggering actions only after the UI has settled.
gauge.TransitionComplete += (s, e) => 
{
                if (gauge.CurrentProgress >= 100) 
    {
                MessageBox.Show("Task Completed!");
    }
};

Designer & Smart Tags

The SiticoneProgressGauge includes a rich Smart Tag menu in the Visual Studio designer for rapid configuration.

Feature Description
Style Presets Instantly apply themes via the smart tag menu:
  • Modern: Gradient blue, glow enabled.
  • Neon: High contrast black/cyan, pulse enabled.
  • Flat: Clean, no gradients or glows.
  • Retro: Vintage color palette with square indicators.
Quick Actions Test Danger Zone: Sets value to danger level to preview visuals.
Calibrate: Resets Min/Max range.
Set Orientation: Quickly swap between Horizontal and Vertical layouts.

Detailed Usage Examples

Example 1: CPU Usage Monitor (Neon Style)

Creates a high-visibility, vertical gauge with a pulsating indicator and neon styling.

C# - CPU Monitor
private void ConfigureCpuGauge()
{
    cpuGauge.AppearanceStyle = ProgressAppearanceStyle.Neon;
    cpuGauge.Orientation = ProgressOrientation.Vertical;
    
                // Colors
    cpuGauge.TrackBaseColor = Color.FromArgb(20, 20, 20);
    cpuGauge.ProgressFillColor = Color.Cyan;
    cpuGauge.SecondaryFillColor = Color.BlueViolet;
    cpuGauge.EnableGradientFill = true;
    
                // Indicator
    cpuGauge.IndicatorType = ProgressIndicatorType.Diamond;
    cpuGauge.EnableIndicatorPulse = true;
    
                // Labels
    cpuGauge.ProgressCaption = "CPU Load";
    cpuGauge.UnitSuffix = "%";
    cpuGauge.DecimalPrecision = 0;
    
                // Scale
    cpuGauge.ShowScaleMarks = true;
    cpuGauge.MajorMarkCount = 5; // 0, 20, 40, 60, 80, 100
}

Example 2: Temperature Sensor (Zones)

Uses the Zone system to visually represent temperature ranges (Cold, Optimal, Overheat).

C# - Temp Sensor
private void ConfigureTempGauge()
{
    tempGauge.MinimumLevel = -20;
    tempGauge.MaximumLevel = 120;
    tempGauge.UnitSuffix = "°C";
    
                // Clear defaults
    tempGauge.ClearProgressZones();
    
                // Define Zones
                // Freezing: -20 to 0 (Blue)
    tempGauge.AddProgressZone(-20, 0, Color.LightBlue, "Freezing");
    
                // Optimal: 0 to 80 (Green)
    tempGauge.AddProgressZone(0, 80, Color.LightGreen, "Normal");
    
                // Overheat: 80 to 120 (Red)
    tempGauge.AddProgressZone(80, 120, Color.OrangeRed, "Overheat");
    
    tempGauge.EnableZoneColoring = true;
    tempGauge.ShowDangerZone = false; // Using custom zones instead
    
                // Visuals
    tempGauge.AppearanceStyle = ProgressAppearanceStyle.Glass;
    tempGauge.IndicatorType = ProgressIndicatorType.Arrow;
}

Example 3: File Upload (Transition Event)

Simulates a file upload and triggers a message when the visual transition completes.

C# - Async Upload
public async void StartUpload()
{
    uploadGauge.CurrentProgress = 0;
    uploadGauge.ProgressCaption = "Uploading...";
    
                // Hook into completion event
    uploadGauge.TransitionComplete += UploadGauge_TransitionComplete;
    
                // Simulate progress updates
                for (int i = 0; i <= 100; i += 10)
    {
                await Task.Delay(200);
        uploadGauge.SetProgress(i, true);
    }
}

private void UploadGauge_TransitionComplete(object sender, EventArgs e)
{
                if (uploadGauge.CurrentProgress >= 100)
    {
        uploadGauge.ProgressCaption = "Upload Complete";
        uploadGauge.ProgressFillColor = Color.SeaGreen;
        uploadGauge.IndicatorColor = Color.SeaGreen;
    }
}