Icon Customization

This feature allows developers to customize the appearance of both the menu and X icons, including their dimensions, colors, spacing, and line thickness.

Overview

The Icon Customization feature provides developers with fine-grained control over how icons are rendered on the SiticoneMenuButton. Whether displaying the classic menu lines or the alternate X icon, you can adjust sizes, colors, spacing, and thicknesses to ensure the icons integrate seamlessly with your application's design.

---

Feature Details

The following table summarizes the customizable properties for icons:

Property	Data Type	Default Value	Description
MenuLineWidth	float	20f	Defines the width of each menu line.
MenuLineHeight	float	2f	Specifies the thickness of each menu line.
MenuLineColor	Color	Color.FromArgb(64, 64, 64)	Sets the color of the menu lines.
MenuLineSpacing	float	6f	Determines the spacing between each menu line.
XIconSize	float	20f	Specifies the size of the X icon when the button is in the opened state.
XIconThickness	float	2f	Defines the line thickness for the X icon.
XIconColor	Color	Color.FromArgb(64, 64, 64)	Sets the color of the X icon.
IconSize	float	24f	Provides a base size for the icons; used to scale icons generally.

---

Code Examples and Samples

Below are some extensive code examples that illustrate how to customize the icons on the SiticoneMenuButton control.

Sample Code: Customizing the Menu Icon Appearance

This sample demonstrates how to adjust the menu icon properties for a more modern appearance.

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Ensure the correct namespace is referenced

namespace IconCustomizationDemo
{
    public class MainForm : Form
    {
        private SiticoneMenuButton menuButton;

        public MainForm()
        {
            InitializeComponents();
        }

        private void InitializeComponents()
        {
            // Create and configure the SiticoneMenuButton
            menuButton = new SiticoneMenuButton
            {
                Size = new Size(60, 60),
                Location = new Point(40, 40),
                MenuLineWidth = 25f,           // Wider menu lines for enhanced visibility
                MenuLineHeight = 3f,           // Increased thickness for a bolder look
                MenuLineSpacing = 8f,          // More spacing for a cleaner design
                MenuLineColor = Color.DarkSlateGray, // Custom color for menu lines
                IconSize = 26f               // Slightly larger base icon size
            };

            Controls.Add(menuButton);

            Text = "Menu Icon Customization";
            Size = new Size(300, 200);
            StartPosition = FormStartPosition.CenterScreen;
        }

        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new MainForm());
        }
    }
}

Sample Code: Customizing the X Icon Appearance

This sample shows how to customize the X icon properties for a distinct opened-state appearance.

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Ensure the correct namespace is referenced

namespace XIconCustomizationDemo
{
    public class MainForm : Form
    {
        private SiticoneMenuButton menuButton;
        private Button btnToggle;

        public MainForm()
        {
            InitializeComponents();
        }

        private void InitializeComponents()
        {
            // Configure the SiticoneMenuButton with custom X icon settings
            menuButton = new SiticoneMenuButton
            {
                Size = new Size(60, 60),
                Location = new Point(40, 40),
                XIconSize = 30f,               // Larger X icon for emphasis
                XIconThickness = 3f,           // Thicker X icon lines for better clarity
                XIconColor = Color.Crimson,    // Vibrant color for the X icon
                IconSize = 28f                 // Adjusted base icon size for consistency
            };

            // Toggle button to simulate state change between menu and X icon
            btnToggle = new Button
            {
                Text = "Toggle Icon",
                Location = new Point(40, 120),
                Size = new Size(100, 30)
            };
            btnToggle.Click += (s, e) =>
            {
                // Toggle between the menu and X icon by changing the IsOpened property
                menuButton.IsOpened = !menuButton.IsOpened;
                menuButton.Invalidate();  // Refresh the control to update icon rendering
            };

            Controls.Add(menuButton);
            Controls.Add(btnToggle);

            Text = "X Icon Customization";
            Size = new Size(300, 250);
            StartPosition = FormStartPosition.CenterScreen;
        }

        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new MainForm());
        }
    }
}

Sample Code: Dynamic Icon Customization Based on User Settings

This example shows how to allow users to change icon settings dynamically at runtime using checkboxes and numeric up-down controls.

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace DynamicIconCustomizationDemo
{
    public class MainForm : Form
    {
        private SiticoneMenuButton menuButton;
        private NumericUpDown numMenuLineWidth;
        private NumericUpDown numMenuLineHeight;
        private NumericUpDown numXIconSize;

        public MainForm()
        {
            InitializeComponents();
        }

        private void InitializeComponents()
        {
            menuButton = new SiticoneMenuButton
            {
                Size = new Size(60, 60),
                Location = new Point(20, 20),
                MenuLineWidth = 20f,
                MenuLineHeight = 2f,
                XIconSize = 20f,
                MenuLineColor = Color.Black,
                XIconColor = Color.Black,
                IsOpened = false
            };

            // NumericUpDown for MenuLineWidth
            numMenuLineWidth = new NumericUpDown
            {
                Minimum = 10,
                Maximum = 40,
                Value = 20,
                Location = new Point(100, 20)
            };
            numMenuLineWidth.ValueChanged += (s, e) =>
            {
                menuButton.MenuLineWidth = (float)numMenuLineWidth.Value;
                menuButton.Invalidate();
            };

            // NumericUpDown for MenuLineHeight
            numMenuLineHeight = new NumericUpDown
            {
                Minimum = 1,
                Maximum = 10,
                Value = 2,
                Location = new Point(100, 60)
            };
            numMenuLineHeight.ValueChanged += (s, e) =>
            {
                menuButton.MenuLineHeight = (float)numMenuLineHeight.Value;
                menuButton.Invalidate();
            };

            // NumericUpDown for XIconSize
            numXIconSize = new NumericUpDown
            {
                Minimum = 10,
                Maximum = 40,
                Value = 20,
                Location = new Point(100, 100)
            };
            numXIconSize.ValueChanged += (s, e) =>
            {
                menuButton.XIconSize = (float)numXIconSize.Value;
                menuButton.Invalidate();
            };

            Controls.Add(menuButton);
            Controls.Add(new Label { Text = "Menu Line Width:", Location = new Point(20, 20), AutoSize = true });
            Controls.Add(numMenuLineWidth);
            Controls.Add(new Label { Text = "Menu Line Height:", Location = new Point(20, 60), AutoSize = true });
            Controls.Add(numMenuLineHeight);
            Controls.Add(new Label { Text = "X Icon Size:", Location = new Point(20, 100), AutoSize = true });
            Controls.Add(numXIconSize);

            Text = "Dynamic Icon Customization";
            Size = new Size(300, 200);
            StartPosition = FormStartPosition.CenterScreen;
        }

        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new MainForm());
        }
    }
}

---

Key Points

Aspect	Details
Flexibility	Customize both menu and X icons independently for various states.
Fine-grained Control	Adjust sizes, colors, spacing, and thickness to match design specifications.
Dynamic Switching	Use the IsOpened property to toggle between the menu and X icons dynamically.

---

Best Practices

Practice	Explanation
Maintain Consistency	Ensure that icon dimensions and colors align with the overall application theme.
Use Dynamic Updates Responsibly	When changing icon properties at runtime, always call Invalidate() to refresh the control.
Test on Multiple Resolutions	Verify that icon customizations appear clear and consistent across different screen sizes and DPI settings.

---

Common Pitfalls

Pitfall	How to Avoid
Mismatched Icon Sizes	Ensure that the IconSize, MenuLineWidth, and XIconSize values are proportionate to the control size.
Overly Thick or Thin Lines	Adjust MenuLineHeight and XIconThickness carefully to prevent icons from appearing too bold or too faint.
Neglecting Refresh	Always call Invalidate() after updating icon properties to ensure changes are rendered immediately.

---

Usage Scenarios

Scenario	How Icon Customization Helps
Modern UI Designs	Customize menu and X icons with sleek, thin lines and subtle colors for a modern look.
Branding Consistency	Adapt icon colors and sizes to match corporate branding and visual guidelines.
User Preference Customization	Allow users to adjust icon sizes dynamically via application settings or themes.

---

Review

The Icon Customization feature offers extensive control over the visual aspects of the icons rendered on the SiticoneMenuButton control. By adjusting parameters such as MenuLineWidth, MenuLineHeight, MenuLineSpacing, MenuLineColor, XIconSize, XIconThickness, XIconColor, and IconSize, developers can ensure that the control's icons meet the design needs of a variety of applications.

---

Summary

Icon Customization in the SiticoneMenuButton control empowers developers to create a tailored user experience through detailed control over both menu and X icons. Whether by static configuration at design time or dynamic adjustments at runtime, this feature ensures that icons are rendered in a way that aligns with the overall application theme and user expectations.

---

Additional Sections

Troubleshooting

Issue	Resolution
Icons Not Updating	Ensure Invalidate() is called after modifying icon properties to refresh the control display.
Inconsistent Icon Rendering	Verify that the property values (e.g., IconSize, MenuLineWidth) are set proportionally relative to the control’s dimensions.

Future Enhancements

Enhancement	Description
Advanced Icon Animation	Introduce animated transitions between menu and X icons for a smoother visual experience.
Theme Binding for Icons	Allow binding icon properties to application-wide themes for dynamic visual consistency.

By following this documentation, developers can effectively customize the icons on the SiticoneMenuButton control to meet a wide range of design and functionality requirements in their .NET WinForms applications.