Siticone Logo
Siticone UI
DOCS
v2025.12.15
Docs Button Advanced

Siticone Button Advanced

The SiticoneButtonAdvanced control is a high-performance, feature-rich button designed for modern WinForms applications. It extends functionality with gradient support, complex shadow rendering, audio feedback, and a built-in Ultra Performance Mode for data-heavy scenarios like grids or lists.

Performance Mode

When dealing with hundreds of controls (e.g., inside a UserControl list or DataGridView), standard rendering can slow down the UI. The Ultra Performance Mode strips away complex GDI+ calculations to prioritize frame rate.

Property Type Description & Usage Example
UltraPerformanceMode bool btn.UltraPerformanceMode = true; When enabled, it disables animations (ripple, hover fade, press scale) and shadows. It forces HighSpeed compositing for maximum responsiveness.

Appearance & Gradients

Control the visual style including background gradients, borders, and disabled states.

Property Type Description & Usage Example
ButtonColorStart Color btn.ButtonColorStart = Color.FromArgb(94, 148, 255); The starting color of the background gradient.
ButtonColorEnd Color btn.ButtonColorEnd = Color.FromArgb(50, 80, 200); The ending color of the background gradient. Set equal to Start for solid color.
BorderColor Color btn.BorderColor = Color.White; The color of the button border.
BorderThickness int btn.BorderThickness = 2; Width of the border in pixels.
EnableBorderGradient bool btn.EnableBorderGradient = true; Enables a separate gradient for the border stroke.
BorderColorStart Color btn.BorderColorStart = Color.Gold;
BorderColorEnd Color btn.BorderColorEnd = Color.Red;
DisabledOverlayOpacity float btn.DisabledOverlayOpacity = 0.5f; Opacity (0.0 - 1.0) of the gray overlay drawn when Enabled is false.

Shape & Geometry

Customize the geometry of the button, from individual corners to perfect circles.

Property Type Description & Usage Example
MakeRadial bool btn.MakeRadial = true; If true, automatically calculates the maximum possible corner radius to create a pill or circle shape.
BorderRadiusTopLeft int btn.BorderRadiusTopLeft = 10;
BorderRadiusTopRight int btn.BorderRadiusTopRight = 10;
BorderRadiusBottomLeft int btn.BorderRadiusBottomLeft = 10;
BorderRadiusBottomRight int btn.BorderRadiusBottomRight = 10;

Animations & Effects

Control the visual feedback loops, including ripples, scaling, and hover transitions.

Property Type Description & Usage Example
HoverColor Color btn.HoverColor = Color.FromArgb(40, 255, 255, 255); The overlay color drawn on top of the button during hover.
HoverTransitionSpeed float btn.HoverTransitionSpeed = 0.08f; Speed factor for the hover fade-in animation (0.01 to 1.0).
RippleColor Color btn.RippleColor = Color.White; The color of the ripple wave animation when clicked.
RippleExpandSpeedFactor float btn.RippleExpandSpeedFactor = 0.05f; Speed factor for ripple expansion.
RippleFadeSpeedFactor float btn.RippleFadeSpeedFactor = 0.03f; Speed factor for ripple fading (Higher is faster).
EnablePressScale bool btn.EnablePressScale = true; If true, the button physically shrinks slightly when clicked.
PressDepth int btn.PressDepth = 2; The pixel distance the button visually recedes when pressed.
PressAnimationSpeed float btn.PressAnimationSpeed = 0.2f; Controls the speed of the press/release animation (0.01 - 1.0).

Shadow System

A comprehensive shadow engine allowing for both box shadows and text shadows.

Property Type Description & Usage Example
ShadowColor Color btn.ShadowColor = Color.Black;
ShadowBlurFactor float btn.ShadowBlurFactor = 0.85f; Controls the softness of the main drop shadow (0.0 - 1.0).
ShadowOffsetX int btn.ShadowOffsetX = 3;
ShadowOffsetY int btn.ShadowOffsetY = 3;
EnableTextShadow bool btn.EnableTextShadow = true;
TextShadowColor Color btn.TextShadowColor = Color.FromArgb(100, 0, 0, 0);
TextShadowOffsetX int btn.TextShadowOffsetX = 1;
TextShadowOffsetY int btn.TextShadowOffsetY = 1;

Audio & Interaction

Enhance user feedback with sound effects and specialized states like ReadOnly.

Property Type Description & Usage Example
IsReadOnly bool btn.IsReadOnly = true; Prevents standard click actions but keeps the button visually active. Useful for premium/locked features.
CanShake bool btn.CanShake = true; If true, the button shakes when clicked while in ReadOnly mode.
CanBeep bool btn.CanBeep = true; If true, emits a system beep when clicked while in ReadOnly mode.
EnableFocusBorder bool btn.EnableFocusBorder = true; Draws a distinct border when the control receives focus via Tab or click.
FocusBorderColor Color btn.FocusBorderColor = Color.Blue;
ClickSoundPath string btn.ClickSoundPath = "Sounds/click.wav"; File path to a .wav file played on click.
EnableClickSound bool btn.EnableClickSound = true;
HoverSoundPath string btn.HoverSoundPath = "Sounds/hover.wav";
EnableHoverSound bool btn.EnableHoverSound = true;

Badge System

A built-in system to display notifications or numeric counts directly on the button.

Property Type Description & Usage Example
BadgeValue int btn.BadgeValue = 5; The number displayed in the badge. Setting to 0 automatically hides the badge.
BadgeBackColor Color btn.BadgeBackColor = Color.Red;
BadgeForeColor Color btn.BadgeForeColor = Color.White;
BadgeRadius int btn.BadgeRadius = 8;
BadgeRightMargin int btn.BadgeRightMargin = 10;

Text & Image Layout

Property Type Description & Usage Example
ButtonImage Image btn.ButtonImage = Resources.Icon;
ImageAlign ContentAlignment btn.ImageAlign = ContentAlignment.MiddleLeft;
ImageSize int btn.ImageSize = 24; Sets width and height of the image (square).
ImageLeftMargin int btn.ImageLeftMargin = 5;
ImageRightMargin int btn.ImageRightMargin = 8;
TextAlign ContentAlignment btn.TextAlign = ContentAlignment.MiddleCenter;
TextPaddingLeft int btn.TextPaddingLeft = 10;
TextPaddingRight int btn.TextPaddingRight = 10;
TextPaddingTop int btn.TextPaddingTop = 0;
TextPaddingBottom int btn.TextPaddingBottom = 0;

Inherited & Standard Properties

As a descendant of Control, SiticoneButtonAdvanced supports all standard Windows Forms properties. Below are the most relevant ones used for layout and typography.

Property Type Description
Text string The text caption displayed on the button.
Font Font The font used for the text caption. Defaults to Segoe UI 9pt in constructor.
ForeColor Color The color of the text caption. Defaults to White.
BackColor Color Note: Defaults to Color.Transparent. The actual visible background is painted using ButtonColorStart/End.
Size Size The dimensions of the control. Default is 230x60.
DoubleBuffered bool Enabled by default in constructor to prevent flicker.

Events

The SiticoneButtonAdvanced uses custom event arguments to provide detailed information about interactions, such as precise mouse coordinates and state changes.

Events Implementation
// 1. ButtonClick Event (Replaces standard Click)
// Provides extended mouse data via SiticoneButtonAdvancedMouseEventArgs
advancedBtn.ButtonClick += (s, e) => 
{
                if (e.Button == MouseButtons.Right)
    {
                Console.WriteLine($"Right click detected at X:{e.X} Y:{e.Y}");
    }
};

// 2. ButtonHoverEnter / ButtonHoverLeave
// Triggered when the mouse crosses the control boundaries.
advancedBtn.ButtonHoverEnter += (s, e) => 
{
    statusLabel.Text = "Ready to execute...";
};

// 3. ButtonStateChanged
// Fired when Enabled or IsReadOnly properties change.
// Useful for updating UI logic based on button availability.
advancedBtn.ButtonStateChanged += (s, e) => 
{
                Debug.WriteLine($"State Updated - Enabled: {e.IsEnabled}, ReadOnly: {e.IsReadOnly}");
                if (e.IsReadOnly)
    {
        advancedBtn.Text = "LOCKED";
    }
};

Detailed Usage Examples

Example 1: High Performance Grid Button

Use this configuration when generating lists of buttons in a loop or hosting them in complex containers where rendering speed is critical.

C# - Performance Config
private SiticoneButtonAdvanced CreateListButton(string label)
{
                var btn = new SiticoneButtonAdvanced();
    btn.Text = label;
    btn.Size = new Size(100, 30);
                // Enable Ultra Performance Mode
                // Disables ripples, shadows, and gradients for max speed
    btn.UltraPerformanceMode = true;
                // Set a flat, solid color (Start == End)
    btn.ButtonColorStart = Color.SteelBlue;
    btn.ButtonColorEnd = Color.SteelBlue;
    btn.ForeColor = Color.White;
    
                return btn;
}

Example 2: Premium Gradient & Sound

A "Call to Action" button with gradients, sound effects, and a badge notification.

C# - Premium UX
var btn = new SiticoneButtonAdvanced();
btn.Size = new Size(200, 60);
btn.Text = "UNLOCK PRO";
// 1. Gradient Appearance
btn.ButtonColorStart = Color.FromArgb(255, 105, 180); // Hot Pink
btn.ButtonColorEnd = Color.FromArgb(138, 43, 226); // Violet
btn.MakeRadial = true; // Auto-calculate rounded corners (Pill shape)

// 2. Audio Feedback
btn.EnableHoverSound = true;
btn.HoverSoundPath = "Audio/hover_pop.wav";
btn.EnableClickSound = true;
btn.ClickSoundPath = "Audio/confirm_chime.wav";

// 3. Notification Badge
btn.BadgeValue = 1;
btn.BadgeBackColor = Color.Gold;
btn.BadgeForeColor = Color.Black;

// 4. Text Shadow for readability
btn.EnableTextShadow = true;
btn.TextShadowColor = Color.FromArgb(50, 0, 0, 0);

Example 3: Locked/ReadOnly Feature

Simulates a locked feature that shakes when clicked, indicating to the user that an action is required to unlock it.

C# - ReadOnly Interaction
var btnLocked = new SiticoneButtonAdvanced();
btnLocked.Text = "Export Data (Locked)";
btnLocked.ButtonColorStart = Color.Gray;
btnLocked.ButtonColorEnd = Color.DimGray;
btnLocked.ForeColor = Color.LightGray;
// Enable ReadOnly mode (Active but not clickable)
btnLocked.IsReadOnly = true;
// Enable Shake feedback on click attempts
btnLocked.CanShake = true;
// Optional: Add Beep sound
btnLocked.CanBeep = true;

Example 4: Dynamic Badge Counter

Updates the badge value dynamically based on application logic.

C# - Badge Logic
public void UpdateCartCount(int itemCount)
{
    cartButton.BadgeValue = itemCount;
                if (itemCount > 0)
    {
        cartButton.BadgeBackColor = Color.Red;
                // Animate the button to draw attention
        cartButton.EnablePressScale = true;
    }
                else
    {
                // 0 automatically hides the badge
        cartButton.BadgeValue = 0;
    }
}