Siticone Logo
Siticone UI
DOCS
v2025.12.15
Docs Menu Button

Siticone Menu Button

The SiticoneMenuButton is a sophisticated navigation control designed to transform between a "Hamburger Menu" and a "Close" (X) icon. It extends the standard button capabilities with physics-based animations, particle effects, and specialized state management for modern UI sidebars.

Behavior & State

Properties controlling how the button switches states and responds to user input.

Property Type Description & Usage Example
AllowDynamicSwitch bool btn.AllowDynamicSwitch = true; If true, the button automatically toggles between the Menu (lines) and Close (X) icons when clicked. Set to false if you want to control the state manually via code.
IsOpened bool if (btn.IsOpened) { /* Menu is open */ } Gets or sets the current visual state.
False: Displays Hamburger Menu lines.
True: Displays the 'X' Close icon.
IsReadOnly bool btn.IsReadOnly = true; If set to true, the button appears interactive but will not toggle its state when clicked. Instead, it can trigger Shake or Beep feedback (see Interaction properties).

Icon Appearance

Fine-tune the geometry and color of the menu lines and the close icon.

Property Type Description & Usage Example
MenuLineColor Color btn.MenuLineColor = Color.White;
MenuLineWidth float btn.MenuLineWidth = 20f; The horizontal length of the three menu lines.
MenuLineHeight float btn.MenuLineHeight = 2f; The thickness (height) of each individual menu line.
MenuLineSpacing float btn.MenuLineSpacing = 6f; The vertical distance between the menu lines.
XIconColor Color btn.XIconColor = Color.Red; The color of the icon when in the IsOpened (True) state.
XIconSize float btn.XIconSize = 20f; The overall size (width/height) of the 'X' icon.
XIconThickness float btn.XIconThickness = 2f;
IconStrokeWidth float btn.IconStrokeWidth = 2f;

Styling & Dimensions

General properties for the button container, borders, and shadows.

Property Type Description & Usage Example
BorderRadius int btn.BorderRadius = 8; The roundness of the button corners. Set to higher values for a pill or circular shape.
HoverColor Color btn.HoverColor = Color.FromArgb(240, 240, 240); Background color overlay applied when the mouse hovers over the control.
HoverOpacity byte btn.HoverOpacity = 150; The alpha transparency (0-255) of the hover color effect.
PressColor Color btn.PressColor = Color.LightGray;
EnableShadow bool btn.EnableShadow = true; Renders a drop shadow behind the control to create depth.
ShadowColor Color btn.ShadowColor = Color.Black;
ShadowDepth int btn.ShadowDepth = 3;

Animation & Physics

Advanced visual effects including particles, bouncing, and pulsing.

Property Type Description & Usage Example
InteractiveBounce bool btn.InteractiveBounce = true; Enables a physics-based spring animation. The button scales up and bounces when clicked/released.
BounceStrength float btn.BounceStrength = 0.3f; The amplitude of the bounce effect (Recommended range: 0.1 to 1.0).
BounceDuration int btn.BounceDuration = 500;
EnableParticles bool btn.EnableParticles = true; If true, clicking the button emits a burst of particles ("confetti"). Great for "Gamified" UIs.
ParticleColor Color btn.ParticleColor = Color.Gold;
ParticleCount int btn.ParticleCount = 20;
ParticleSpeed float btn.ParticleSpeed = 3f;
EnableRippleEffect bool btn.EnableRippleEffect = true; Standard Material Design expanding circle effect on click.
EnablePulseEffect bool btn.EnablePulseEffect = true; Causes the icon to gently pulse (scale in/out) continuously while hovered.

Feedback & Interaction

Properties designed to provide user feedback, especially useful for invalid or locked states.

Property Type Description & Usage Example
CanShake bool btn.CanShake = true; When enabled, the button shakes horizontally if clicked while in IsReadOnly mode. Useful for indicating a disabled or locked feature.
CanBeep bool btn.CanBeep = true; If true, plays a system exclamation sound if clicked while in IsReadOnly mode.

Events

Events tailored to the specific animations of the Menu Button.

Event Description
HoverAnimationCompleted Fires when the hover fade-in/fade-out transition completes.
ParticleAnimationCompleted Fires when the last particle of an explosion effect fades out.
Click Standard Click event. Fires whenever the button is clicked (unless ReadOnly).

Detailed Usage Examples

Example 1: Standard Sidebar Navigation

This example sets up a classic "Hamburger" button that controls a sidebar panel. It utilizes the AllowDynamicSwitch property to handle the icon transformation automatically.

C# - Sidebar Toggle
public void InitializeSidebarButton()
{
                SiticoneMenuButton menuBtn = new SiticoneMenuButton();
    menuBtn.Size = new Size(50, 50);
    menuBtn.Location = new Point(10, 10);

                // 1. Configure Aesthetics
    menuBtn.MenuLineColor = Color.DimGray;
    menuBtn.XIconColor = Color.Red;
    menuBtn.BorderRadius = 10;
    menuBtn.HoverColor = Color.AliceBlue;

                // 2. Behavior
                // Let the button handle its own icon switching (Hamburger <-> X)
    menuBtn.AllowDynamicSwitch = true; 

                // 3. Handle Logic
    menuBtn.Click += (sender, e) => 
    {
                // The button state flips automatically before this event fires
                if (menuBtn.IsOpened)
        {
                ExpandSidebarPanel();
        }
                else
        {
                CollapseSidebarPanel();
        }
    };

                this.Controls.Add(menuBtn);
}

Example 2: The "Gamified" Button

A high-energy configuration suitable for games or playful interfaces. This setup uses particles, bounces, and ripple effects to create a "juicy" interaction.

C# - Gamified Setup
private void SetupGameMenu()
{
                var btn = new SiticoneMenuButton();
    
                // 1. Enable Physics (Bounce)
    btn.InteractiveBounce = true;
    btn.BounceStrength = 0.6f;  // High elasticity
    btn.BounceDuration = 600;

                // 2. Enable Particles (Confetti)
    btn.EnableParticles = true;
    btn.ParticleColor = Color.Gold;
    btn.ParticleCount = 25;
    btn.ParticleSpeed = 4.5f;

                // 3. Styling
    btn.MenuLineColor = Color.White;
    btn.XIconColor = Color.Yellow;
    btn.HoverColor = Color.Purple;
    
                // 4. Pulse effect to draw attention to the button
    btn.EnablePulseEffect = true;

    btn.Click += (s, e) => SoundPlayer.Play("menu_open.wav");
}

Example 3: Conditional Locking (ReadOnly State)

Demonstrates how to lock the menu button (e.g., during a loading process). Instead of disabling the button completely (which looks unresponsive), we set IsReadOnly = true and enable CanShake to give the user feedback that the action is currently denied.

C# - Locked Interaction
public async void PerformHeavyTask()
{
                // 1. Lock the menu button
    menuButton.IsReadOnly = true;
    
                // 2. Configure "Access Denied" feedback
    menuButton.CanShake = true; // Shakes if clicked
    menuButton.CanBeep = true;  // Beeps if clicked
    
                // Optional: Visual cue (Grey out lines)
                Color originalColor = menuButton.MenuLineColor;
    menuButton.MenuLineColor = Color.Gray;

                try 
    {
                // Simulate work
                await Task.Delay(3000);
    }
                finally
    {
                // 3. Unlock button and restore visuals
        menuButton.IsReadOnly = false;
        menuButton.MenuLineColor = originalColor;
    }
}

Example 4: Custom Material Styling

Configures the button to look like a modern Material Design control with specific line thickness and shadow depth.

C# - Material Style
var materialBtn = new SiticoneMenuButton();

// Icon Dimensions
materialBtn.MenuLineWidth = 24f;
materialBtn.MenuLineHeight = 3f; // Thicker lines
materialBtn.MenuLineSpacing = 5f;

// Colors
materialBtn.MenuLineColor = Color.FromArgb(33, 33, 33);
materialBtn.HoverColor = Color.FromArgb(20, 0, 0, 0); // Subtle dark overlay
materialBtn.PressColor = Color.FromArgb(40, 0, 0, 0);

// Shadow Elevation
materialBtn.EnableShadow = true;
materialBtn.ShadowColor = Color.FromArgb(40, 0, 0, 0);
materialBtn.ShadowDepth = 2;
materialBtn.PressShadowColor = Color.FromArgb(60, 0, 0, 0);

// Animation settings
materialBtn.EnableRippleEffect = true;
materialBtn.HoverAnimationSpeed = 300; // Slow, smooth fade