Siticone Logo
Siticone UI
DOCS
v2025.12.15
Docs Refresh Button

Siticone Refresh Button

The SiticoneRefreshButton is a specialized, interactive control designed for data reload scenarios. It features a procedural, vector-drawn arrow icon that smoothly transitions into a spinning loading indicator. With built-in support for Color Cycling, Material Design ripples, and automatic Light/Dark mode switching, it provides a modern user experience for asynchronous operations.

Core Behavior

Properties that control the fundamental state and logic of the refresh operation.

Property Type Description & Usage Example
IsRefreshing bool btn.IsRefreshing = true; Gets or sets the refreshing state. When set to true, the button transforms from an arrow to a spinning loader.
AutoStartRefreshing bool btn.AutoStartRefreshing = true; If true, clicking the button automatically sets IsRefreshing = true and begins the animation.
RefreshDuration int btn.RefreshDuration = 3000; The time in milliseconds the animation plays before automatically stopping. Set to 0 for indefinite (manual stop required).

Theming & Colors

The control maintains two separate color palettes (Light and Dark). You can toggle between them using the DarkMode property.

Property Type Description & Usage Example
DarkMode bool btn.DarkMode = true; Switches the active palette between Light and Dark properties.
LightBackColor Color btn.LightBackColor = Color.White; The background fill color of the button in Light mode.
DarkBackColor Color btn.DarkBackColor = Color.FromArgb(30, 30, 30); The background fill color of the button in Dark mode.
LightIdleIconColor Color The color of the static arrow icon when not refreshing (Light mode).
LightActivityIconColor Color The base color of the spinning loading indicator (Light mode).
LightBorderColor Color The border stroke color (Light mode).

Icon Geometry

The icon is drawn procedurally, allowing full customization of the arrow's shape and arc without using image files.

Property Type Description & Usage Example
ArrowHeadSizeFactor float btn.ArrowHeadSizeFactor = 1.2f; Scales the size of the arrow tip (0.5 to 3.0).
ArrowHeadAngle float btn.ArrowHeadAngle = 0.8f; Controls the width of the arrow head (0.3 to 1.0). Smaller values = wider arrow.
ArrowHeadLengthFactor float btn.ArrowHeadLengthFactor = 1.0f; Adjusts the elongation of the arrow tip (0.5 to 2.0).
StartAngle float btn.StartAngle = 45f; The starting degree of the static arc (0-360).
SweepAngle float btn.SweepAngle = 270f; How many degrees the arc extends. 360 is a full circle.
IdleIconStrokeWidth int btn.IdleIconStrokeWidth = 3; Thickness of the arrow line in pixels.

Animation & Effects

Settings for the spinner, color cycling, ripples, and shadows.

Property Type Description & Usage Example
EnableColorCycling bool btn.EnableColorCycling = true; If true, the spinner cycles through the colors in Light/DarkActivityIconColors.
ColorTransitionSpeed float btn.ColorTransitionSpeed = 0.04f; Controls how fast colors blend into each other (0.001 - 0.1).
AnimationSpeed int btn.AnimationSpeed = 10; Global multiplier for the frame rate of all animations (1-30).
RotationSpeed int btn.RotationSpeed = 8; Specific speed of the spinner rotation (1-20).
EnableDropShadow bool btn.EnableDropShadow = true; Draws a soft shadow behind the control for depth.
DropShadowDepth int btn.DropShadowDepth = 4; The blur radius of the shadow in pixels.
EnableRippleEffect bool btn.EnableRippleEffect = true; Enables the Material Design expanding circle effect on click.
ScaleDownFactor float btn.ScaleDownFactor = 0.9f; Size multiplier (0.5-1.0) applied when the button is pressed.

Public Methods

StartRefreshing()
// Begins the loading animation.
// If RefreshDuration > 0, it stops automatically after that time.
refreshButton1.StartRefreshing();
StopRefreshing()
// Immediately stops the animation and resets to the idle arrow state.
// Triggers the RefreshStateChanged event with RefreshState.Stopped.
refreshButton1.StopRefreshing();
PerformClick()
// Simulates a click programmatically.
// Starts the ripple effect and triggers the RefreshClicked event.
refreshButton1.PerformClick();
StartRippleEffect()
// Triggers the ripple visual from a specific point relative to the control.
refreshButton1.StartRippleEffect(new Point(15, 15));

Events

The control offers both standard events and enhanced events with detailed arguments.

Event Description & Arguments
RefreshStateChanged Fires on state transitions (Started, Completed, Stopped).
Args: RefreshStateEventArgs (State, Duration, ElapsedTime).
AnimationProgressChanged Fires periodically during animation.
Args: AnimationProgressEventArgs (Progress 0-1, Rotation, ArcLength).
ThemeChanged Fires when DarkMode toggles.
Args: RefreshButtonThemeChangedEventArgs (IsDarkMode, Colors).
ColorCycleChanged Fires when the spinner switches color.
Args: ColorCycleEventArgs (CurrentColor, NextColor).

Designer Features

The control includes a comprehensive Smart Tag panel in Visual Studio.

  • Theme Presets: Quickly apply styling like "Material Design", "Floating Action Button", or "Minimalist".
  • Copy/Paste Settings: Easily replicate complex configurations between buttons on your form.

Usage Examples

Example 1: Async Data Loading

Using the button to trigger a background task and wait for completion.

C# - Async Pattern
private async void OnRefreshClicked(object sender, EventArgs e)
{
                // 1. Disable auto-stop so we can control it manually
    siticoneRefreshButton1.RefreshDuration = 0;
    
                // 2. Start animation (if not using AutoStartRefreshing)
    siticoneRefreshButton1.StartRefreshing();

                try
    {
                // 3. Simulate fetching data from API
                await Task.Delay(4000);
                RefreshDataGrid();
    }
                finally
    {
                // 4. Stop animation when task is done
        siticoneRefreshButton1.StopRefreshing();
    }
}

Example 2: Custom Geometry & Styling

Creating a bold, thick arrow style often seen in modern mobile UIs.

C# - Custom Styling
private void ApplyBoldStyle()
{
                var btn = siticoneRefreshButton1;

                // Thick strokes
    btn.IdleIconStrokeWidth = 4;
    btn.ActivityIconStrokeWidth = 5;
    
                // Wide, aggressive arrow head
    btn.ArrowHeadSizeFactor = 1.5f;
    btn.ArrowHeadAngle = 0.6f; // Lower value = wider angle
    
                // Open arc look
    btn.StartAngle = 0f;
    btn.SweepAngle = 300f; // Leave a 60 degree gap

                // Colors
    btn.LightIdleIconColor = Color.DimGray;
    btn.EnableColorCycling = false; // Single color spinner
    btn.LightActivityIconColor = Color.Crimson;
}

Example 3: Event-Driven Progress

Using the AnimationProgressChanged event to synchronize an external progress bar with the spinner.

C# - Events
private void InitializeEvents()
{
    siticoneRefreshButton1.RefreshDuration = 5000;
    
    siticoneRefreshButton1.AnimationProgressChanged += (s, e) => 
    {
                // e.Progress is a float from 0.0 to 1.0
        progressBar1.Value = (int)(e.Progress * 100);
        
                // Rotate a label based on spinner rotation
        lblStatus.Text = $"Loading... {(int)(e.Progress * 100)}%";
    };
    
    siticoneRefreshButton1.RefreshStateChanged += (s, e) =>
    {
                if (e.State == RefreshState.Completed)
        {
            lblStatus.Text = "Update Complete!";
        }
    };
}