Siticone Logo
Siticone UI
DOCS
v2025.12.15
Docs Text Button Advanced

Siticone TextButton Advanced

The SiticoneTextButtonAdvanced is an advanced text-centric button control designed for modern UI applications. It extends standard button functionality with text gradient capabilities, dynamic underlines (solid, wavy, dashed), and extensive theming support. It is optimized for scenarios where text presentation and subtle animations take precedence over traditional solid-block button styles.

Text & Typography

Properties controlling the core text appearance, including state-based coloring and advanced gradient effects.

Property Type Description & Usage Example
Text string btn.Text = "Get Started"; The primary text content displayed on the button.
Font Font btn.Font = new Font("Segoe UI Semibold", 10.25F); The font used for the button text. Defaults to Segoe UI Semibold.
TextColor Color btn.TextColor = Color.DimGray; The primary color of the text in the normal state.
HoverTextColor Color btn.HoverTextColor = Color.DodgerBlue; The text color applied when the mouse hovers over the control.
PressedTextColor Color btn.PressedTextColor = Color.Navy; The text color applied when the button is actively pressed.
DisabledTextColor Color btn.DisabledTextColor = Color.Silver; The text color used when the control is disabled.
TextTransform ButtonTextTransform btn.TextTransform = ButtonTextTransform.Uppercase; Automatically transforms the text case (None, Uppercase, Lowercase, Capitalize).

Text Gradient

Advanced options to render the text with a linear gradient.

Property Type Description & Usage Example
EnableTextGradient bool btn.EnableTextGradient = true; Enables gradient rendering for the text. Overrides standard `TextColor`.
TextGradientColor1 Color btn.TextGradientColor1 = Color.Fuchsia;
TextGradientColor2 Color btn.TextGradientColor2 = Color.Aqua;
TextGradientAngle float btn.TextGradientAngle = 45f; The angle of the gradient fill.

Images & Icons

Configuration for displaying icons alongside text with state-specific image support.

Property Type Description & Usage Example
IdleImage Image btn.IdleImage = Properties.Resources.icon_gray; The image displayed in the button's normal state.
HoverImage Image btn.HoverImage = Properties.Resources.icon_color; The image displayed when the mouse hovers over the button.
PressImage Image btn.PressImage = Properties.Resources.icon_active; The image displayed when the button is pressed.
IconSize Size btn.IconSize = new Size(16, 16); The rendering size of the icon.
ImageLocation ButtonImageLocation btn.ImageLocation = ButtonImageLocation.Left; Positions the image relative to the text (Left or Right).
ImageTextGap int btn.ImageTextGap = 8; The pixel gap between the image and the text.

Underline Styling

The control features a robust underline system capable of rendering solid, dashed, dotted, or wavy lines, often used for hyperlinks or emphatic buttons.

Property Type Description & Usage Example
ShowUnderline bool btn.ShowUnderline = false; Determines if the underline is visible in the normal state.
HoverShowUnderline bool btn.HoverShowUnderline = true; If true, the underline fades in when the mouse hovers over the button.
UnderlineColor Color btn.UnderlineColor = Color.Blue;
UnderlineHeight int btn.UnderlineHeight = 2; The thickness of the underline in pixels.
UnderlineOffset int btn.UnderlineOffset = 2; The vertical distance between the text bottom and the underline.
UnderlineStyle UnderlineStyle btn.UnderlineStyle = AdvancedTextButtonUnderlineStyle.Wavy; Sets the style: Solid, Dashed, Dotted, or Wavy.
WavyUnderlineAmplitude float btn.WavyUnderlineAmplitude = 2f; The height of the waves when `UnderlineStyle` is Wavy.
WavyUnderlineWavelength float btn.WavyUnderlineWavelength = 10f; The width (frequency) of the waves.

Animation & Effects

Controls visual feedback loops such as ripples and press scaling to enhance interactivity.

Property Type Description & Usage Example
EnableRippleEffect bool btn.EnableRippleEffect = true; Toggles the expanding circle (Material Design ripple) animation on click.
RippleColor Color btn.RippleColor = Color.FromArgb(100, 0, 123, 255);
RippleAnimationDuration float btn.RippleAnimationDuration = 0.5f; Duration of the ripple effect in seconds.
EnablePressAnimation bool btn.EnablePressAnimation = true; If enabled, the button content scales down when pressed.
PressAnimationScale float btn.PressAnimationScale = 0.96f; The scale factor (e.g., 0.96 = 96%) the button shrinks to when held.
ScaleTextOnClick bool btn.ScaleTextOnClick = true; If true, the text and images scale during the press animation.
HoverAnimationSpeed float btn.HoverAnimationSpeed = 6f; Controls the speed of color transitions on hover. Higher is faster.
PressAnimationSpeed float btn.PressAnimationSpeed = 10f; Controls the speed of press/unpress animations. Higher is faster.

Layout & Padding

Controls for adjusting the internal spacing and layout of the button's content.

Property Type Description & Usage Example
Padding Padding btn.Padding = new Padding(12, 6, 12, 6); Specifies the padding within the button, affecting the position of the content relative to the button edges.
Size Size btn.Size = new Size(200, 45); The overall dimensions of the button control (inherited from Control). Default is 260x40.

Theming

The control includes a powerful `Theme` property that applies predefined color palettes and visual styles instantly.

Property Type Description & Usage Example
Theme ThemePreset btn.Theme = ThemePreset.Cyberpunk; Applies a preset theme. Doing so overwrites individual color properties like `TextColor`, `UnderlineColor`, and `RippleColor`.

Designer & Smart Tags

The `SiticoneTextButtonAdvanced` includes a custom designer (`SiticoneTextButtonAdvancedDesigner`) providing a rich Smart Tag experience in Visual Studio. The designer features include theme presets, copy/paste settings functionality, and quick access to common properties.

Feature Description
Theme Presets Access to all `ThemePreset` options directly from the action list (e.g., "Apply Cyberpunk Theme", "Apply Oceanic Theme").
Settings Clipboard Copy Settings: Copies all visual properties (Colors, Fonts, Animations) from the selected control to an in-memory clipboard.
Paste Settings: Applies the copied settings to another instance of the control.
Property Shortcuts Quick access to common properties like `Text`, `Font`, `ShowUnderline`, and `IconSize` without searching the Properties window.

Designer Code Example

C# - Using the Designer Features Programmatically
// Accessing the designer's clipboard functionality programmatically
private void CopyButtonSettings(SiticoneTextButtonAdvanced sourceButton)
{
                // The designer uses a static clipboard class internally
                var settings = new Dictionary<string, object>();
    
                // Copy all relevant properties
                foreach (PropertyDescriptor pd in TypeDescriptor.GetProperties(sourceButton))
    {
                if (!pd.IsReadOnly && pd.SerializationVisibility != DesignerSerializationVisibility.Hidden)
        {
                if (pd.Name != "Name" && pd.Name != "Location" && pd.Name != "Site")
            {
                if (pd.ShouldSerializeValue(sourceButton))
                {
                    settings[pd.Name] = pd.GetValue(sourceButton);
                }
            }
        }
    }
    
                // Store in the static clipboard (same as designer uses)
                SiticoneTextButtonAdvancedSettingsClipboard.Settings = settings;
    
                MessageBox.Show($"Copied {settings.Count} settings from '{sourceButton.Name}'");
}

Events

The control inherits all standard Windows Forms events from its base class and provides additional mouse interaction tracking through its state properties.

Event Description Usage Example
MouseEnter EventHandler btn.MouseEnter += (s, e) => { Console.WriteLine("Mouse entered"); }; Raised when the mouse enters the button's client area.
MouseLeave EventHandler btn.MouseLeave += (s, e) => { Console.WriteLine("Mouse left"); }; Raised when the mouse leaves the button's client area.
MouseDown MouseEventHandler btn.MouseDown += (s, e) => { if (e.Button == MouseButtons.Left) Console.WriteLine("Left button pressed"); }; Raised when a mouse button is pressed while over the button.
MouseUp MouseEventHandler btn.MouseUp += (s, e) => { Console.WriteLine("Mouse button released"); }; Raised when a mouse button is released while over the button.
Click EventHandler btn.Click += (s, e) => { MessageBox.Show("Button clicked!"); }; Raised when the button is clicked (mouse down then up).

Enumerations

Enumerations specific to the configuration of `SiticoneTextButtonAdvanced`.

ThemePreset Enum
// Available theme presets in the Theme property.
public enum ThemePreset
{
    Default,
    Cyberpunk,        // Neon cyan/magenta gradient with dashed underline
    NeonGlow,         // High contrast with glowing green underline
    Oceanic,          // Blue gradients with wavy underline
    Sunset,           // Warm red/orange gradient
    EnchantedForest,  // Green palette with dotted underline
    MinimalistDark,   // Clean white on dark
    MinimalistLight,  // Clean black on light
    LuxuryGold,       // Gold gradient
    VintagePaper,     // Brown/Sepia tones
    Holographic,      // Iridescent colors with wavy underline
    Industrial,       // Gray/Slate tones
    ArcticBlue,       // Icy blue gradient
    Galaxy,           // Space-themed purple/blue gradient
    Steampunk,        // Bronze/Brown with dashed underline
    RetroWave,        // Pink/Cyan synthwave style
    Jungle            // Vibrant green/yellow
}
AdvancedTextButtonUnderlineStyle Enum
// Specifies the drawing style of the text underline.
public enum AdvancedTextButtonUnderlineStyle
{
    Solid,
    Dashed,
    Dotted,
    Wavy    // Renders a sine wave (controlled by Amplitude and Wavelength)
}
ButtonTextTransform Enum
// Defines automatic text case transformations.
public enum ButtonTextTransform
{
    None,
    Uppercase,  // "hello world" -> "HELLO WORLD"
    Lowercase,  // "Hello World" -> "hello world"
    Capitalize  // "hello world" -> "Hello World"
}
ButtonImageLocation Enum
// Defines the position of the image relative to the text.
public enum ButtonImageLocation
{
    Left,   // Image appears to the left of the text
    Right   // Image appears to the right of the text
}

Detailed Usage Examples

Example 1: Gradient Text with Wavy Underline

Creates a stylized button often used for "Magic" or "Special" actions in a game or creative app.

C# - Stylized Button
private void SetupMagicButton()
{
                var btn = new SiticoneTextButtonAdvanced();
    btn.Text = "Cast Spell";
    btn.Font = new Font("Segoe UI", 12f, FontStyle.Bold);
    
                // Gradient Text
    btn.EnableTextGradient = true;
    btn.TextGradientColor1 = Color.MediumPurple;
    btn.TextGradientColor2 = Color.Cyan;
    btn.TextGradientAngle = 90f;

                // Wavy Underline on Hover
    btn.ShowUnderline = false;
    btn.HoverShowUnderline = true;
    btn.UnderlineStyle = AdvancedTextButtonUnderlineStyle.Wavy;
    btn.UnderlineColor = Color.Magenta;
    btn.WavyUnderlineAmplitude = 3f;
    btn.WavyUnderlineWavelength = 8f;

                // Animation Settings
    btn.HoverAnimationSpeed = 8f;
    btn.PressAnimationSpeed = 12f;
    btn.RippleAnimationDuration = 0.6f;

                this.Controls.Add(btn);
}

Example 2: Applying a Theme Preset

Demonstrates how to quickly apply a complex visual style using the `Theme` property.

C# - Theme Application
private void ApplyTheme()
{
                // Instantly applies the 'Cyberpunk' look:
                // - Cyan/Magenta gradient text
                // - Dashed underline
                // - Neon ripple effects
    advancedButton1.Theme = SiticoneTextButtonAdvanced.ThemePreset.Cyberpunk;
    
                // You can still override specific properties after setting a theme
    advancedButton1.TextTransform = ButtonTextTransform.Uppercase;
    advancedButton1.Padding = new Padding(16, 8, 16, 8);
}

Example 3: Complex Image Configuration

Shows how to configure state-based images with proper sizing and positioning.

C# - Image Configuration
private void SetupDownloadButton()
{
                var btn = new SiticoneTextButtonAdvanced();
    btn.Text = "Download";
    
                // Load images from resources
    btn.IdleImage = Properties.Resources.download_gray;
    btn.HoverImage = Properties.Resources.download_blue;
    btn.PressImage = Properties.Resources.download_white;
    
                // Image configuration
    btn.IconSize = new Size(20, 20);
    btn.ImageLocation = ButtonImageLocation.Left;
    btn.ImageTextGap = 10;
    
                // Layout adjustments
    btn.Size = new Size(180, 45);
    btn.Padding = new Padding(20, 10, 20, 10);
    
                // Animation effects
    btn.EnableRippleEffect = true;
    btn.RippleColor = Color.FromArgb(80, 0, 120, 215);
    btn.EnablePressAnimation = true;
    btn.PressAnimationScale = 0.95f;
    btn.ScaleTextOnClick = true;

    btn.Click += (sender, e) => 
    {
                MessageBox.Show("Download started!");
    };

                this.Controls.Add(btn);
}

Example 4: Complete Themed Navigation Button

Creates a fully-featured navigation button with all advanced properties configured.

C# - Complete Navigation Button
public SiticoneTextButtonAdvanced CreateNavigationButton(string text, Image icon, EventHandler clickHandler)
{
                var btn = new SiticoneTextButtonAdvanced
    {
                // Text Configuration
        Text = text,
        Font = new Font("Segoe UI Semibold", 11f),
        TextColor = Color.FromArgb(64, 64, 64),
        HoverTextColor = Color.FromArgb(0, 123, 255),
        PressedTextColor = Color.FromArgb(0, 86, 179),
        TextTransform = ButtonTextTransform.Capitalize,
        
                // Image Configuration
        IdleImage = icon,
        IconSize = new Size(18, 18),
        ImageLocation = ButtonImageLocation.Left,
        ImageTextGap = 12,
        
                // Underline Configuration
        ShowUnderline = false,
        HoverShowUnderline = true,
        UnderlineColor = Color.FromArgb(0, 123, 255),
        UnderlineHeight = 2,
        UnderlineStyle = AdvancedTextButtonUnderlineStyle.Solid,
        UnderlineOffset = 3,
        
                // Animation Configuration
        EnableRippleEffect = true,
        RippleColor = Color.FromArgb(60, 0, 123, 255),
        RippleAnimationDuration = 0.4f,
        EnablePressAnimation = true,
        PressAnimationScale = 0.97f,
        HoverAnimationSpeed = 8f,
        PressAnimationSpeed = 15f,
        ScaleTextOnClick = true,
        
                // Layout
        Size = new Size(220, 42),
        Padding = new Padding(16, 10, 16, 10),
        
                // Cursor
        Cursor = Cursors.Hand
    };
    
                // Event handling
    btn.Click += clickHandler;
    
                // Mouse events for custom interactions
    btn.MouseEnter += (s, e) => 
    {
        btn.BackColor = Color.FromArgb(240, 250, 255);
    };
    
    btn.MouseLeave += (s, e) => 
    {
        btn.BackColor = Color.Transparent;
    };
    
                return btn;
}

// Usage
private void InitializeNavigation()
{
                var homeBtn = CreateNavigationButton("Home", Properties.Resources.home_icon,
        (s, e) => { MessageBox.Show("Navigating to Home"); });
    
                var settingsBtn = CreateNavigationButton("Settings", Properties.Resources.settings_icon,
        (s, e) => { MessageBox.Show("Opening Settings"); });
    
    homeBtn.Location = new Point(20, 20);
    settingsBtn.Location = new Point(20, 70);
    
                this.Controls.Add(homeBtn);
                this.Controls.Add(settingsBtn);
}

Example 5: Dynamic Theme Switching

Demonstrates how to programmatically switch themes and handle theme changes.

C# - Dynamic Theme Management
// Dictionary mapping theme names to ThemePreset values
private readonly Dictionary<string, SiticoneTextButtonAdvanced.ThemePreset> _themes = new Dictionary<string, SiticoneTextButtonAdvanced.ThemePreset>
{
    { "Default", SiticoneTextButtonAdvanced.ThemePreset.Default },
    { "Cyberpunk", SiticoneTextButtonAdvanced.ThemePreset.Cyberpunk },
    { "Oceanic", SiticoneTextButtonAdvanced.ThemePreset.Oceanic },
    { "Minimalist Dark", SiticoneTextButtonAdvanced.ThemePreset.MinimalistDark },
    { "Luxury Gold", SiticoneTextButtonAdvanced.ThemePreset.LuxuryGold }
};

// Apply theme to multiple buttons
private void ApplyThemeToAllButtons(SiticoneTextButtonAdvanced.ThemePreset theme)
{
                foreach (Control control in this.Controls)
    {
                if (control is SiticoneTextButtonAdvanced button)
        {
                // Store original text for restoration
                string originalText = button.Text;
            
                // Apply theme
            button.Theme = theme;
            
                // Restore text (theme might have changed text properties)
            button.Text = originalText;
            
                // Force redraw
            button.Invalidate();
        }
    }
}

// Create theme selector buttons
private void CreateThemeSelector()
{
                int yPos = 20;
    
                foreach (var theme in _themes)
    {
                var themeButton = new SiticoneTextButtonAdvanced
        {
            Text = theme.Key,
            Size = new Size(150, 35),
            Location = new Point(20, yPos),
                // Apply the theme to the selector button itself
            Theme = theme.Value
        };
        
                // Capture the theme value for the click event
                var selectedTheme = theme.Value;
        themeButton.Click += (s, e) => 
        {
                ApplyThemeToAllButtons(selectedTheme);
                MessageBox.Show($"Applied {theme.Key} theme to all buttons");
        };
        
                this.Controls.Add(themeButton);
        yPos += 45;
    }
}