Siticone Button

// Simulates a button click programmatically.
// This triggers the Click event, plays standard animations (like Ripple),
// and executes any logic associated with the button's action.
// Useful for keyboard shortcuts or triggering the button from other UI elements.
public void TriggerAction()
{
    siticoneButton1.PerformClick();
}

// Manually triggers the horizontal shake animation.
// This is primarily used for visual feedback during form validation
// (e.g., when a user submits a form with missing required fields).
// Requires the 'CanShake' property to be set to true.
if (string.IsNullOrEmpty(username.Text))
{
                // Shake the button to indicate an error to the user
    loginButton.StartShaking();
}

// Immediately terminates any active shake animation and resets
// the button's visual transform to its original position (0,0).
// Use this if you need to interrupt the animation before it finishes naturally.
loginButton.StopShaking();

// 1. Standard Click Event
// Fires when the button is clicked by the mouse or triggered via keyboard (Space/Enter).
// This is the primary event for handling button logic.
btn.Click += (s, e) => 
{
                SaveData();
};

// 2. LongPressed Event
// Fires only after the user holds the left mouse button down for the duration
// specified in 'LongPressDurationMS'.
// Requires 'EnableLongPress = true'.
// Ideal for showing advanced options or context menus without cluttering the UI.
btn.LongPressed += (s, e) => 
{
                ShowContextMenu();
};

// 3. ToggleChanged Event
// Fires when the 'IsToggled' state changes.
// Requires 'IsToggleButton = true'.
// Use this to handle logic for on/off switches, like enabling a dark mode or muting audio.
btn.ToggleChanged += (s, e) => 
{
                if (btn.IsToggled) 
    {
                EnableFeature();
    }
                else 
    {
                DisableFeature();
    }
};

// 4. ReadOnlyInteraction Event
// Fires when a user attempts to click the button while 'IsReadOnly = true'.
// This event intercepts the standard click.
// It is useful for "Premium" or "Locked" features
// where you want to show the user why they cannot perform the action.
// Setting 'e.WasHandled = true' prevents the default shake/beep feedback.
btn.ReadOnlyInteraction += (s, e) => 
{
                if (e.Type == InteractionType.Click)
    {
                MessageBox.Show("This feature requires a Pro subscription.");
        e.WasHandled = true; // Suppress automatic shake/beep
    }
};
// 5. StateChanged Event
// Fires whenever the visual state of the button changes (e.g., from Normal to Hover, or Hover to Pressed).
// Provides access to 'OldState', 'NewState', and animation details.
// Useful for logging user behavior or debugging custom visual transitions.
btn.StateChanged += (s, e) => 
{
                Debug.WriteLine($"State changed from {e.OldState} to {e.NewState}");
                Debug.WriteLine($"Is animating: {e.IsAnimating}, Duration: {e.TransitionDuration}");
};

// 6. AnimationCompleted Event
// Fires when a specific animation (Ripple, Shake, Glow, etc.) finishes playing.
// Can be used to chain animations or trigger logic *after* a visual effect concludes.
btn.AnimationCompleted += (s, e) => 
{
                if (e.AnimationType == AnimationType.Shake) 
    {
                // Focus the input field after the error shake finishes
                FocusInput();
    }
};
// 7. AnimationEffectStarted Event
// Fires at the exact moment a visual effect (like a Ripple or Particle explosion) begins.
// Provides the location and expected duration of the effect.
btn.AnimationEffectStarted += (s, e) => 
{
                if (e.EffectType == AnimationType.Ripple)
    {
                Debug.WriteLine($"Ripple started at {e.Location}");
    }
};

// 8. ThemeChanged Event
// Fires when the 'CurrentSystemTheme' property is manually updated or changes programmatically.
// Use this to re-apply color palettes if you are handling custom theming logic.
btn.ThemeChanged += (s, e) => 
{
                Debug.WriteLine($"Theme changed from {e.OldTheme} to {e.NewTheme}");
                ApplyThemeColors(e.NewTheme);
};

// 9. SystemThemeChanged Event
// Fires automatically when the Windows Operating System theme changes (e.g., user switches Windows to Dark Mode).
// Requires 'IsSystemThemeMonitoringEnabled = true'.
// allows your app to adapt instantly to OS preferences.
btn.SystemThemeChanged += (s, e) => 
{
                Debug.WriteLine($"Windows System Theme is now: {e.SystemTheme}");
};

// Defines the possible theme modes for the button.
public enum ThemeMode
{
                // Indicates a light theme (typically bright backgrounds, dark text).
    Light,
    
                // Indicates a dark theme (dark backgrounds, light text).
    Dark,
    
                // Indicates that the theme is manually configured or does not match system presets.
    Custom
}

// Represents the various visual states of the button.
// This enum is passed in the StateChanged event to indicate transitions.
public enum ButtonState
{
                // The default state when the mouse is not interacting with the button.
    Normal,
    
                // The mouse pointer is over the button.
    Hover,
    
                // The left mouse button is held down over the control.
    Pressed,
    
                // The button is disabled (Enabled = false).
    Disabled,
    
                // The button is in ReadOnly mode (IsReadOnly = true).
    ReadOnly,
    
                // The button is in the "On" state (IsToggleButton = true).
    Toggled,
    
                // Transitional states indicating an ongoing animation.
    AnimatingToNormal,
    AnimatingToHover,
    AnimatingToPressed
}

// Identifies the specific type of animation being played.
// Used in AnimationCompleted and AnimationEffectStarted events.
public enum AnimationType
{
                // Color fade transition to Hover state.
    Hover,
    
                // Color fade transition to Pressed state.
    Press,
    
                // Color fade transition back to Normal state.
    Release,
    
                // The expanding circle effect (Material Design ripple).
    Ripple,
    
                // Horizontal vibration effect (often for errors).
    Shake,
    
                // Pulsating glow effect on hover.
    Glow,
    
                // Confetti-like particle explosion effect.
    Particle,
    
                // Generic state change transition.
    StateTransition
}

// Defines the specific mouse action that triggered a ReadOnlyInteraction event.
public enum InteractionType
{
                // A standard left-click.
    Click,
    
                // A double-click event.
    DoubleClick,
    
                // A right-click event (often used for context menus).
    RightClick,
    
                // A middle mouse button click.
    MiddleClick,
    
                // The mouse pointer entered the control.
    Hover,
    
                // The mouse pointer left the control.
    Leave
}

// Creates a toggle button for audio mute/unmute control.
// The button acts as a switch: "Mute" (Green) when off, "Unmute" (Red) when on.
private SiticoneButton CreateToggleButton()
{
                var button = new SiticoneButton
    {
        Text = "Mute",
        Size = new Size(120, 40),
        
                // Enable toggle behavior
        IsToggleButton = true,
        
                // Default Appearance (Normal/Off State)
        ButtonBackColor = Color.SeaGreen,
        TextColor = Color.White,
        HoverBackColor = Color.MediumSeaGreen,
        PressedBackColor = Color.ForestGreen,
        
                // Effects
        EnableRippleEffect = true,
        RippleColor = Color.White,
        
                // Styling
        CornerRadiusTopLeft = 8,
        CornerRadiusTopRight = 8,
        CornerRadiusBottomLeft = 8,
        CornerRadiusBottomRight = 8
    };

                // Handle the ToggleChanged event to update visuals and logic
    button.ToggleChanged += (sender, e) =>
    {
                var btn = (SiticoneButton)sender;
                if (btn.IsToggled)
        {
                // State: Toggled ON (Audio Muted)
                // Visuals change to Red to indicate "Muted" state
            btn.Text = "Unmute";
            btn.ButtonBackColor = Color.Crimson;
            btn.HoverBackColor = Color.LightCoral;
            btn.PressedBackColor = Color.Firebrick;
            btn.TooltipText = "Click to restore audio";

                // Execute Logic
                MuteAudio();
        }
                else
        {
                // State: Toggled OFF (Audio Active)
                // Visuals revert to Green
            btn.Text = "Mute";
            btn.ButtonBackColor = Color.SeaGreen;
            btn.HoverBackColor = Color.MediumSeaGreen;
            btn.PressedBackColor = Color.ForestGreen;
            btn.TooltipText = "Click to silence audio";

                // Execute Logic
                UnmuteAudio();
        }
    };

                return button;
}

// Example of using the shake animation to reject a login attempt.
private void BtnLogin_Click(object sender, EventArgs e)
{
                // 1. Validate the password input
                if (string.IsNullOrWhiteSpace(txtPassword.Text))
    {
                // 2. Configure shake properties for this specific feedback
        btnLogin.CanShake = true;
        btnLogin.ShakeDuration = 800;   // 800ms duration
        btnLogin.ShakeIntensity = 7;    // Moderate intensity (1-10)
        
                // 3. Trigger the shake animation manually
        btnLogin.StartShaking();

                // 4. Provide visual text feedback
        lblStatus.Text = "Password is required!";
        lblStatus.ForeColor = Color.Red;
        
                // 5. Provide auditory feedback (System Beep)
                if (btnLogin.CanBeep)
        {
                SystemSounds.Exclamation.Play();
        }
        
                // Stop execution here since validation failed
                return;
    }
    
                // 6. Proceed with login if validation passes
                PerformLogin(txtUsername.Text, txtPassword.Text);
}

// Tracks the number of unread messages
private int _notificationCount = 0;

// Method called when a new message arrives
private void ReceiveNewMessage()
{
    _notificationCount++;

                // 1. Update the numeric value on the badge
    btnInbox.BadgeValue = _notificationCount;

                // 2. Configure badge styling
    btnInbox.BadgeBackColor = Color.Red;
    btnInbox.BadgeValueForeColor = Color.White;
    btnInbox.BadgeFont = new Font("Segoe UI", 8f, FontStyle.Bold);

                // 3. Ensure the text ("Inbox") and Badge ("5") are centered together
    btnInbox.CenterTextAndBadgeTogether = true;
    btnInbox.TextBadgeSpacing = 8;

                // 4. Optional: Shake the button gently to grab attention
                if (_notificationCount == 1)
    {
        btnInbox.ShakeIntensity = 4;
        btnInbox.StartShaking();
    }
    
                // 5. Update tooltip for accessibility
    btnInbox.TooltipText = $"You have {_notificationCount} new message(s)";
}

// Method called when user opens the inbox
private void BtnInbox_Click(object sender, EventArgs e)
{
                // Reset count and clear badge
    _notificationCount = 0;
    btnInbox.BadgeValue = 0; // Setting to 0 hides the badge
    btnInbox.TooltipText = "Inbox";
    
                OpenInbox();
}

// Handles an async download task with visual state updates
private async void BtnDownload_Click(object sender, EventArgs e)
{
                var btn = (SiticoneButton)sender;

                // 1. Store original state to restore later
                string originalText = btn.Text;
                Color originalColor = btn.ButtonBackColor;
    
                try
    {
                // 2. Set "Loading" state
        btn.Enabled = false;
                // Prevent double-clicks
        btn.Text = "Downloading...";
        btn.CustomCursor = Cursors.WaitCursor;
        btn.ButtonBackColor = Color.Gray;   // Visual "Disabled" look
        
                // 3. Enable UltraFastPerformance to save resources during heavy work
        btn.UltraFastPerformance = true;

                // 4. Simulate the heavy task (3 seconds)
                await Task.Delay(3000);

                // 5. Show Success State
        btn.Text = "Done!";
        btn.ButtonBackColor = Color.Green;
                await Task.Delay(1000); 
    }
                catch (Exception ex)
    {
                // 6. Handle Errors
        btn.Text = "Failed";
        btn.ButtonBackColor = Color.Red;
                MessageBox.Show(ex.Message);
    }
                finally
    {
                // 7. Restore Original State
        btn.Enabled = true;
        btn.Text = originalText;
        btn.ButtonBackColor = originalColor;
        btn.CustomCursor = Cursors.Hand;

                // 8. Re-enable animations
        btn.UltraFastPerformance = false;
    }
}

// Creates a button that automatically adapts to system theme changes.
private SiticoneButton CreateThemeAwareButton()
{
                var button = new SiticoneButton
    {
        Text = "Theme Aware",
        Size = new Size(150, 40),
                // Critical: Enable monitoring of Windows Registry for theme changes
        IsSystemThemeMonitoringEnabled = true
    };

                // Subscribe to the SystemThemeChanged event
    button.SystemThemeChanged += (s, e) =>
    {
                var btn = (SiticoneButton)s;

                // Apply colors based on the new detected theme
                switch (e.SystemTheme)
        {
                case ThemeMode.Light:
                // Configure for Light Mode
                btn.ButtonBackColor = Color.White;
                btn.TextColor = Color.Black;
                btn.BorderColor = Color.LightGray;
                btn.HoverBackColor = Color.FromArgb(240, 240, 240);
                break;

                case ThemeMode.Dark:
                // Configure for Dark Mode
                btn.ButtonBackColor = Color.FromArgb(45, 45, 45);
                btn.TextColor = Color.White;
                btn.BorderColor = Color.FromArgb(80, 80, 80);
                btn.HoverBackColor = Color.FromArgb(60, 60, 60);
                break;
        }
    };

                // Trigger the logic once initially to set the startup color
                // based on the current system state.
    button.CurrentSystemTheme = button.CurrentSystemTheme;

                return button;
}

// Configures a button to act as a "Premium Feature" lock.
private void InitializeLockedButton()
{
                var btnLocked = new SiticoneButton
    {
        Text = "Export to PDF",
        
                // Set ReadOnly: Looks active but standard Click is blocked
        IsReadOnly = true,
        
                // Enable default feedback (Shake/Beep) for basic clicks
        CanShake = true,
        CanBeep = true,
        
                // Styling for ReadOnly state
        ButtonBackColor = Color.LightGray,
        ReadOnlyTextColor = Color.DimGray,
        TooltipText = "Premium feature locked"
    };

                // Handle the interaction manually
    btnLocked.ReadOnlyInteraction += (s, e) =>
    {
                // Check what kind of interaction occurred
                switch (e.Type)
        {
                case InteractionType.Click:
                // Explain WHY it's locked
                MessageBox.Show(
                "Exporting to PDF requires a Pro License.\nClick here to upgrade.",
                "Feature Locked",
                MessageBoxButtons.OK, 
                MessageBoxIcon.Information
                );
                // Important: Set WasHandled to true to stop the default 
                // shake/beep because we handled it with a MessageBox.
                e.WasHandled = true;
                break;
                
                case InteractionType.Hover:
                // Make it slightly darker on hover even though it's locked
                btnLocked.HoverBackColor = Color.Silver;
                break;
        }
    };
}

// Creates a circular Floating Action Button (FAB).
private SiticoneButton CreateFABButton()
{
                var fabButton = new SiticoneButton
    {
        Text = "",                  // No text for FAB
        Size = new Size(56, 56),    // Standard FAB size
        
                // IsRadial=true automatically makes it circular regardless of corner radius
        IsRadial = true, 
        
                // Colors (Material Blue)
        ButtonBackColor = Color.DodgerBlue,
        HoverBackColor = Color.FromArgb(30, 144, 255),
        PressedBackColor = Color.RoyalBlue,
        
                // Shadow for elevation
        EnableShadow = true,
        ShadowColor = Color.FromArgb(60, 0, 0, 0),
        ShadowOffset = new Point(0, 3),
        ShadowBlur = 8,
        
                // Visuals
        EnableRippleEffect = true,
        RippleColor = Color.White,
        CustomCursor = Cursors.Hand
    };

                // Load and set icon image
    fabButton.ButtonImage = Image.FromFile("add_icon.png");
    fabButton.ImageSize = new Size(24, 24);
    fabButton.ImageAlign = ContentAlignment.MiddleCenter;

                // Anchor to bottom-right of the form
    fabButton.Anchor = AnchorStyles.Bottom | AnchorStyles.Right;
    fabButton.Location = new Point(
        this.ClientSize.Width - fabButton.Width - 20,
        this.ClientSize.Height - fabButton.Height - 20
    );

                return fabButton;
}

// Creates a high-impact "Premium" button with multiple visual effects.
private SiticoneButton CreatePremiumButton()
{
                var premiumButton = new SiticoneButton
    {
        Text = "GET PREMIUM",
        Size = new Size(200, 55),
        Font = new Font("Segoe UI", 11f, FontStyle.Bold),
        
                // 1. Gradient Background (Pink to Violet)
        GradientBackground = true,
        ButtonBackColor = Color.FromArgb(255, 105, 180), // Start: Hot Pink
        GradientColor = Color.FromArgb(138, 43, 226),   // End: Blue Violet
        GradientMode = LinearGradientMode.ForwardDiagonal,
        
                // 2. Text Styling
        TextColor = Color.White,
        HoverFontStyle = FontStyle.Bold | FontStyle.Underline,
        
                // 3. Rounded Geometry
        CornerRadiusTopLeft = 25,
        CornerRadiusTopRight = 25,
        CornerRadiusBottomLeft = 25,
        CornerRadiusBottomRight = 25,
        
                // 4. Drop Shadow (Colored to match button)
        EnableShadow = true,
        ShadowColor = Color.FromArgb(100, 255, 20, 147),
        ShadowOffset = new Point(0, 5),
        ShadowBlur = 15,
       
                // 5. Glow Effect on Hover
        CanGlow = true,
        GlowColor = Color.FromArgb(80, 255, 255, 255),
        GlowRadius = 30f,
        
                // 6. Particle Explosion on Click
        UseParticles = true,
        ParticleColor = Color.Gold,
        ParticleCount = 30,
        
                // 7. Press Animation (Scale down)
        EnablePressAnimation = true,
        PressAnimationScale = 0.95f,
        
        CustomCursor = Cursors.Hand
    };

                return premiumButton;
}