Siticone Overlay

The SiticoneOverlay component provides a robust, semi-transparent "mask" to cover any target control or form. It is ideal for blocking user interaction during long-running tasks, displaying loading indicators, or focusing attention on specific UI elements. Unlike simple solutions, it handles window resizing, movement, and offers smooth fade-in/out animations.

Behavior & Target

Core properties that define where the overlay appears and how it behaves.

Property	Type	Description & Usage Example
`OverlayTarget`	Control	overlay.OverlayTarget = this.panelMain; The control (Form, Panel, GroupBox, etc.) that will be covered by the overlay. The overlay automatically tracks the size and position of this target.
`Show`	bool	overlay.Show = true; Toggles the visibility of the overlay. Setting this to `true` triggers the fade-in animation.
`Opacity`	float	overlay.Opacity = 0.7f; The transparency level of the overlay background (0.0 to 1.0). Does not affect the loading indicator or message text opacity.
`OverlayColor`	Color	overlay.OverlayColor = Color.Black; The background color of the mask. Typically Black or White.

Activity Indicator

A built-in circular loading spinner to indicate background activity.

Property	Type	Description & Usage Example
`ShowActivityIndicator`	bool	overlay.ShowActivityIndicator = true; Shows or hides the spinning loader animation.
`IndicatorColor`	Color	overlay.IndicatorColor = Color.DodgerBlue;
`IndicatorSize`	int	overlay.IndicatorSize = 40; Diameter of the spinner in pixels.
`IndicatorThickness`	int	overlay.IndicatorThickness = 4; Stroke width of the spinner arc.
`IndicatorSpeed`	float	overlay.IndicatorSpeed = 3.5f; Speed of rotation. Higher values are faster.

Content & Message

Display status messages or loading text on top of the overlay.

Property	Type	Description & Usage Example
`MessageText`	string	overlay.MessageText = "Processing Data..."; Text displayed below the activity indicator.
`MessageColor`	Color	overlay.MessageColor = Color.White;
`MessageFont`	Font	overlay.MessageFont = new Font("Segoe UI", 10f);

Animation Settings

Customize the entrance and exit transitions.

Property	Type	Description & Usage Example
`FadeInDuration`	int	overlay.FadeInDuration = 300; Time in milliseconds for the overlay to reach full opacity.
`FadeOutDuration`	int	overlay.FadeOutDuration = 200; Time in milliseconds for the overlay to disappear.

Public Methods

Programmatic control over the overlay visibility.

ShowOverlay()

// Displays the overlay on the target control with animation.
// Equivalent to setting Show = true.
overlay.ShowOverlay();

HideOverlay(bool force)

// Hides the overlay.
// force: false = animate fade out (default), true = close immediately.
overlay.HideOverlay(true);

Events

Event	Description
`OverlayTargetChanged`	Fired when the `OverlayTarget` property is updated.
`OverlayShowing`	Fired just before the overlay begins to appear. Includes `OverlayCancelEventArgs` to allow cancellation.
`OverlayShown`	Fired after the overlay has become visible (and animation started).
`OverlayHiding`	Fired just before the overlay begins to hide. Includes `OverlayCancelEventArgs` to allow cancellation.
`OverlayHidden`	Fired after the overlay has fully disappeared and closed.

Detailed Usage Examples

Example 1: Blocking UI During Async Task

Prevents user interaction with a specific panel while loading data.

C# - Async Loading

private async void btnLoadData_Click(object sender, EventArgs e)
{
                // Configure overlay
    loadingOverlay.OverlayTarget = pnlDataGrid;
    loadingOverlay.MessageText = "Fetching Records...";
    loadingOverlay.ShowActivityIndicator = true;
    
                // Show blocking mask
    loadingOverlay.ShowOverlay();
    
                try
    {
                // Simulate long running task
                await Task.Delay(3000);
                LoadGridData();
    }
                finally
    {
                // Hide mask
        loadingOverlay.HideOverlay();
    }
}

Example 2: Full Form Blur Effect

Simulates a modal dialog effect by dimming the entire main form.

C# - Modal Effect

private void ShowSettingsDialog()
{
                // Target the form itself
    modalOverlay.OverlayTarget = this;
    modalOverlay.Opacity = 0.8f;
    modalOverlay.OverlayColor = Color.FromArgb(20, 20, 20);
    modalOverlay.ShowActivityIndicator = false; // Just dimming, no spinner
    
    modalOverlay.Show = true;
    
                using (var settings = new SettingsForm())
    {
        settings.ShowDialog();
    }
    
    modalOverlay.Show = false;
}

Example 3: Customizing the Indicator

Styling the loader to match a specific brand identity.

C# - Custom Style

private void InitializeOverlay()
{
    customOverlay.OverlayTarget = pnlDashboard;
    
                // Brand Colors: Orange and Dark Grey
    customOverlay.OverlayColor = Color.FromArgb(30, 30, 35);
    customOverlay.IndicatorColor = Color.Orange;
    customOverlay.MessageColor = Color.Orange;
    
                // Adjust Spinner appearance
    customOverlay.IndicatorSize = 60;       // Large spinner
    customOverlay.IndicatorThickness = 6;   // Bold lines
    customOverlay.IndicatorSpeed = 4.0f;    // Fast rotation
    
    customOverlay.MessageFont = new Font("Segoe UI", 14, FontStyle.Bold);
}