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
// Begins the loading animation.
// If RefreshDuration > 0, it stops automatically after that time.
refreshButton1.StartRefreshing();
// Immediately stops the animation and resets to the idle arrow state.
// Triggers the RefreshStateChanged event with RefreshState.Stopped.
refreshButton1.StopRefreshing();
// Simulates a click programmatically.
// Starts the ripple effect and triggers the RefreshClicked event.
refreshButton1.PerformClick();
// 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.
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.
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.
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!";
}
};
}