?? BeepFormUIManager

?? Overview

BeepFormUIManager is a sophisticated form-level component that provides centralized UI management for Beep applications. It automatically coordinates theming across all Beep controls, manages form-level properties like logos and titles, and provides seamless integration with application structure components like side menus and app bars.

As a design-time component, BeepFormUIManager integrates directly with Visual Studio's designer, providing immediate feedback and automatic control discovery. It serves as the central hub for form-level UI coordination in professional Beep applications.

?? Key Features

?? Basic Usage

// 1. Drag BeepFormUIManager from toolbox to your form
// 2. It will appear in the component tray at the bottom of the designer
// 3. Set properties in the Properties window:

// In the designer, set these properties:
beepFormUIManager1.Theme = "MaterialDesignTheme";
beepFormUIManager1.Title = "My Application";
beepFormUIManager1.LogoImage = @"C:\MyApp\Assets\logo.svg";
beepFormUIManager1.ShowBorder = true;
beepFormUIManager1.ShowShadow = true;
beepFormUIManager1.IsRounded = true;

public partial class MainForm : BeepiForm
{
    private BeepFormUIManager uiManager;
    
    public MainForm()
    {
        InitializeComponent();
        
        // Create and configure UI manager
        uiManager = new BeepFormUIManager(this.components);
        
        // Configure basic properties
        uiManager.Theme = "DarkTheme";
        uiManager.Title = "Beep Application";
        uiManager.LogoImage = @"Assets\app-logo.svg";
        
        // Initialize for runtime
        uiManager.Initialize(this);
        
        // Subscribe to theme changes
        uiManager.OnThemeChanged += UiManager_OnThemeChanged;
    }
    
    private void UiManager_OnThemeChanged(string newTheme)
    {
        // Handle theme changes
      //  Console.WriteLine($"Theme changed to: {newTheme}");
        
        // Perform any custom theme-specific logic
        UpdateCustomControls(newTheme);
    }
}

public class StandardFormSetup
{
    public static void ConfigureStandardLayout(BeepiForm form)
    {
        // Create UI manager
        var uiManager = new BeepFormUIManager(form.components);
        
        // Standard configuration
        uiManager.Theme = BeepThemesManager.CurrentThemeName;
        uiManager.Title = Application.ProductName;
        uiManager.ShowBorder = true;
        uiManager.ShowShadow = true;
        uiManager.IsRounded = true;
        uiManager.ApplyThemeOnImage = true;
        
        // Initialize
        uiManager.Initialize(form);
        
        // Apply current theme
        uiManager.ApplyThemeToForm();
    }
}

??? Design-Time Integration

// These properties are available in the Visual Studio Properties window:

[Browsable(true)]
[Category("Appearance")]
[Description("Select the theme to apply to all Beep controls.")]
public string Theme { get; set; }

[Browsable(true)]
[Category("Appearance")]
[Description("Set the title of the form.")]
public string Title { get; set; }

[Browsable(true)]
[Category("Appearance")]
[Description("Set the logo image of the form.")]
[Editor(typeof(FileNameEditor), typeof(UITypeEditor))]
public string LogoImage { get; set; }

[Browsable(true)]
[Category("Appearance")]
[Description("Enable or disable border styling.")]
public bool ShowBorder { get; set; }

[Browsable(true)]
[Category("Appearance")]
[Description("Enable or disable shadow effects.")]
public bool ShowShadow { get; set; }

[Browsable(true)]
[Category("Appearance")]
[Description("Enable or disable rounded corners.")]
public bool IsRounded { get; set; }

// BeepFormUIManager automatically discovers and configures these controls:

private void OnControlAdded(object sender, ControlEventArgs e)
{
    // Automatically handles these control types:
    
    if (e.Control is BeepSideMenu beepSideMenu)
    {
        // Configure side menu
        beepSideMenu.BeepForm = BeepiForm;
        beepSideMenu.Title = Title;
        beepSideMenu.LogoImage = LogoImage;
        SetupSideMenuEvents(beepSideMenu);
    }
    
    if (e.Control is BeepAppBar beepAppBar)
    {
        // Configure app bar
        beepAppBar.Title = Title;
        beepAppBar.LogoImage = LogoImage;
    }
    
    if (e.Control is BeepFunctionsPanel functionsPanel)
    {
        // Configure functions panel
        BeepFunctionsPanel = functionsPanel;
    }
    
    // Apply theme to any Beep control
    ApplyThemeToControlAndChildren(e.Control);
    
    // Apply form-level styling
    if (e.Control is ContainerControl container)
    {
        ThemeFunctions.ApplyBorderToControl(container, ShowBorder);
        ThemeFunctions.ApplyShadowToControl(container, ShowShadow);
        ThemeFunctions.ApplyRoundedToControl(container, IsRounded);
    }
}

??? Component Coordination

// BeepFormUIManager automatically coordinates between components:

private void SetupSideMenuEvents()
{
    if (BeepSideMenu != null)
    {
        // Handle menu collapse/expand
        BeepSideMenu.StartOnMenuCollapseExpand += StartMenuAnimation;
        BeepSideMenu.EndMenuCollapseExpand += EndMenuAnimation;
    }
}

private void StartMenuAnimation(bool isCollapsing)
{
    // Suspend layout updates for smooth animation
    if (BeepAppBar != null)
    {
        BeepAppBar.SuspendFormLayout();
    }
    
    if (DisplayContainer != null)
    {
        DisplayContainer.SuspendFormLayout();
    }
}

private void EndMenuAnimation(bool isCollapsed)
{
    // Update app bar based on menu state
    if (BeepAppBar != null)
    {
        BeepAppBar.ShowTitle = isCollapsed;
        BeepAppBar.ShowLogo = !isCollapsed;
        BeepAppBar.Title = Title;
        
        // Resume layout updates
        BeepAppBar.ResumeFormLayout();
    }
    
    if (DisplayContainer != null)
    {
        DisplayContainer.ResumeFormLayout();
    }
}

// Properties are automatically synchronized across components:

public string Title
{
    get => _title;
    set
    {
        _title = value;
        
        // Update all components with the new title
        if (BeepiForm != null)
        {
            BeepiForm.Text = _title;
        }
        
        if (BeepAppBar != null)
        {
            BeepAppBar.Title = _title;
        }
        
        if (BeepSideMenu != null)
        {
            BeepSideMenu.Title = _title;
        }
    }
}

public string LogoImage
{
    get => _logoImage;
    set
    {
        _logoImage = value;
        
        // Update logo in all components
        if (BeepAppBar != null)
        {
            BeepAppBar.LogoImage = _logoImage;
        }
        
        if (BeepSideMenu != null)
        {
            BeepSideMenu.LogoImage = _logoImage;
        }
        
        // Convert SVG to icon for form
        if (BeepiForm != null && !string.IsNullOrEmpty(value))
        {
            var beepImage = new BeepImage { ImagePath = value };
            if (beepImage.svgDocument != null)
            {
                BeepiForm.Icon = ImageConverters.ConvertSvgToIcon(
                    beepImage.svgDocument, 64);
            }
        }
    }
}

public void FindBeepSideMenu()
{
    if (_form != null)
    {
        foreach (Control control in _form.Controls)
        {
            // Discover and configure BeepSideMenu
            if (control is BeepSideMenu sideMenu)
            {
                BeepSideMenu = sideMenu;
                sideMenu.Title = Title;
                sideMenu.BeepForm = BeepiForm;
                sideMenu.LogoImage = LogoImage;
                SetupSideMenuEvents();
            }
            
            // Discover and configure BeepFunctionsPanel
            if (control is BeepFunctionsPanel functionsPanel)
            {
                BeepFunctionsPanel = functionsPanel;
            }
            
            // Discover and configure BeepiForm
            if (control is BeepiForm beepiForm)
            {
                BeepiForm = beepiForm;
                beepiForm.Text = Title;
            }
        }
    }
}

?? Theme Management

private void ApplyThemeToAllBeepControls(Control container)
{
    if (container == null) return;
    
    // Get current theme
    IBeepTheme theme = BeepThemesManager.GetTheme(_theme);
    if (theme == null) return;
    
    // Apply background color
    container.BackColor = theme.BackgroundColor;
    
    // Apply theme to the container itself
    ApplyThemeToControl(container);
    
    // Check if control manages its own child theming
    if (HasApplyThemeToChildsProperty(container))
    {
        if (GetPropertyFromControl(container, "ApplyThemeToChilds"))
        {
            // Control manages its own children
            return;
        }
    }
    
    // Recursively apply to all child controls
    foreach (Control child in container.Controls)
    {
        ApplyThemeToAllBeepControls(child);
    }
}

public void ApplyThemeToControl(Control control, string themeName, bool applyToImage)
{
    // Apply theme property
    var themeProperty = TypeDescriptor.GetProperties(control)["Theme"];
    if (themeProperty != null && themeProperty.PropertyType == typeof(string))
    {
        themeProperty.SetValue(control, themeName);
    }
    
    // Update component references
    if (BeepiForm != null)
    {
        if (BeepAppBar != null)
        {
            BeepAppBar.LogoImage = LogoImage;
            BeepAppBar.Title = Title;
        }
        
        if (BeepSideMenu != null)
        {
            BeepSideMenu.LogoImage = LogoImage;
            BeepSideMenu.Title = Title;
        }
    }
    
    // Apply theme-aware properties
    ApplyThemeAwareProperties(control);
}

private void ApplyFormLevelStyles()
{
    if (_form == null) return;
    
    foreach (Control child in _form.Controls)
    {
        // Apply border styling
        if (ShowBorder)
        {
            ThemeFunctions.ApplyBorderToControl(child, ShowBorder);
        }
        
        // Apply shadow effects
        if (ShowShadow)
        {
            ThemeFunctions.ApplyShadowToControl(child, ShowShadow);
        }
        
        // Apply rounded corners
        if (IsRounded)
        {
            ThemeFunctions.ApplyRoundedToControl(child, IsRounded);
        }
        
        // Apply theme to images
        if (ApplyThemeOnImage)
        {
            ThemeFunctions.ApplyThemeOnImageControl(child, ApplyThemeOnImage);
        }
    }
}

private void ApplyThemeAwareProperties(Control control)
{
    // Check and apply border theming
    if (GetPropertyFromControl(control, "IsBorderAffectedByTheme"))
    {
        ThemeFunctions.ApplyBorderToControl(control, ShowBorder);
    }
    
    // Check and apply shadow theming
    if (GetPropertyFromControl(control, "IsShadowAffectedByTheme"))
    {
        ThemeFunctions.ApplyShadowToControl(control, ShowShadow);
    }
    
    // Check and apply rounded corner theming
    if (GetPropertyFromControl(control, "IsRoundedAffectedByTheme"))
    {
        ThemeFunctions.ApplyRoundedToControl(control, IsRounded);
    }
}

public BeepFormUIManager(IContainer container)
{
    container.Add(this);
    
    // Subscribe to global theme changes
    BeepThemesManager.ThemeChanged -= BeepThemesManager_ThemeChanged;
    BeepThemesManager.ThemeChanged += BeepThemesManager_ThemeChanged;
}

private void BeepThemesManager_ThemeChanged(object sender, ThemeChangeEventArgs e)
{
    // Update local theme
    Theme = e.NewThemeName;
    
    // Apply to entire form
    ApplyThemeToForm();
}

public void ApplyThemeToForm()
{
    if (_form != null)
    {
        // Update theme reference
        Theme = BeepThemesManager.CurrentThemeName;
        
        // Apply to BeepiForm
        if (BeepiForm != null)
        {
            BeepiForm.Theme = Theme;
            BeepiForm.ApplyTheme();
        }
        
        // Apply to all controls
        ApplyThemeToAllBeepControls(_form);
        
        // Trigger theme changed event
        OnThemeChanged?.Invoke(Theme);
    }
}

?? Advanced Features

// Integration with BeepFormGenerator for advanced form styling
bool ApplyBeepFormStyle
{
    get => _applyBeepFormStyle;
    set
    {
        _applyBeepFormStyle = value;
        if (_applyBeepFormStyle)
        {
            ApplyBeepFormTheme(); // Apply BeepForm styling
        }
        else
        {
            RevertToDefaultFormStyle(); // Revert to standard WinForms
        }
    }
}

private void ApplyBeepFormTheme()
{
    if (_form != null)
    {
        // Apply advanced form styling through BeepFormGenerator
        BeepFormGenerator.ApplyBeepForm(_form, BeepThemesManager.GetTheme(_theme));
    }
}

private void RevertToDefaultFormStyle()
{
    if (_form != null)
    {
        // Remove BeepForm styling and restore standard appearance
        BeepFormGenerator.RemoveBeepForm(_form);
    }
}

public void Initialize(Form runtimeForm)
{
    if (runtimeForm == null)
        throw new ArgumentNullException(nameof(runtimeForm));

    _runtimeForm = runtimeForm;
    _form = runtimeForm;
    BeepiForm = runtimeForm as BeepiForm;

    // Set up theme synchronization
    if (BeepiForm != null)
    {
        BeepiForm.Theme = BeepThemesManager.CurrentThemeName;
        BeepiForm.ApplyTheme();
    }
    
    // Apply current theme
    Theme = BeepThemesManager.CurrentThemeName;
    ApplyThemeToForm();
    
    // Subscribe to theme events
    BeepThemesManager.ThemeChanged -= BeepThemesManager_ThemeChanged;
    BeepThemesManager.ThemeChanged += BeepThemesManager_ThemeChanged;
}

public override ISite Site
{
    get => base.Site;
    set
    {
        base.Site = value;
        
        if (value?.DesignMode == true)
        {
            // Design-time logic
            IDesignerHost host = value.GetService(typeof(IDesignerHost)) as IDesignerHost;
            _form = host?.RootComponent as Form;
            AttachControlAddedEvent(_form);
        }
        else if (_runtimeForm != null)
        {
            // Runtime logic
            _form = _runtimeForm;
            AttachControlAddedEvent(_form);
        }
    }
}

public bool GetPropertyFromControl(Control control, string propertyName)
{
    var property = TypeDescriptor.GetProperties(control)[propertyName];
    if (property != null)
    {
        return (bool)property.GetValue(control);
    }
    return false;
}

private bool HasApplyThemeToChildsProperty(Control control)
{
    var themeProperty = TypeDescriptor.GetProperties(control)["ApplyThemeToChilds"];
    return themeProperty != null && themeProperty.PropertyType == typeof(bool);
}

// Dynamic property setting with error handling
private void SetControlProperty(Control control, string propertyName, object value)
{
    try
    {
        var property = TypeDescriptor.GetProperties(control)[propertyName];
        if (property != null && property.CanResetValue(control))
        {
            property.SetValue(control, value);
        }
    }
    catch (Exception ex)
    {
        // Log error but continue processing
      //  Console.WriteLine($"Failed to set {propertyName} on {control.Name}: {ex.Message}");
    }
}

?? Real-World Examples

public partial class MainApplicationForm : BeepiForm
{
    private BeepFormUIManager uiManager;
    private BeepSideMenu sideMenu;
    private BeepAppBar appBar;
    private BeepDisplayContainer displayContainer;
    
    public MainApplicationForm()
    {
        InitializeComponent();
        SetupUIManager();
        SetupApplicationLayout();
    }
    
    private void SetupUIManager()
    {
        // Create UI manager
        uiManager = new BeepFormUIManager(this.components);
        
        // Configure application branding
        uiManager.Title = "Enterprise Data Manager";
        uiManager.LogoImage = @"Assets\company-logo.svg";
        uiManager.Theme = "CorporateTheme";
        
        // Configure styling
        uiManager.ShowBorder = true;
        uiManager.ShowShadow = true;
        uiManager.IsRounded = true;
        uiManager.ApplyThemeOnImage = true;
        
        // Initialize
        uiManager.Initialize(this);
        
        // Handle theme changes
        uiManager.OnThemeChanged += OnApplicationThemeChanged;
    }
    
    private void SetupApplicationLayout()
    {
        // Create side menu
        sideMenu = new BeepSideMenu
        {
            Dock = DockStyle.Left,
            Width = 250
        };
        this.Controls.Add(sideMenu);
        
        // Create app bar
        appBar = new BeepAppBar
        {
            Dock = DockStyle.Top,
            Height = 60
        };
        this.Controls.Add(appBar);
        
        // Create display container
        displayContainer = new BeepDisplayContainer
        {
            Dock = DockStyle.Fill
        };
        this.Controls.Add(displayContainer);
        
        // Assign to UI manager (will auto-configure)
        uiManager.BeepSideMenu = sideMenu;
        uiManager.BeepAppBar = appBar;
        uiManager.DisplayContainer = displayContainer;
    }
    
    private void OnApplicationThemeChanged(string newTheme)
    {
        // Handle theme-specific customizations
        switch (newTheme)
        {
            case "DarkTheme":
                ConfigureDarkThemeSpecifics();
                break;
            case "LightTheme":
                ConfigureLightThemeSpecifics();
                break;
            case "CorporateTheme":
                ConfigureCorporateThemeSpecifics();
                break;
        }
        
        // Update any custom UI elements
        UpdateCustomElements();
        
        // Save user preference
        SaveThemePreference(newTheme);
    }
}

public class ApplicationUICoordinator
{
    private static readonly List _activeManagers 
        = new List();
    
    public static void RegisterUIManager(BeepFormUIManager manager)
    {
        _activeManagers.Add(manager);
        
        // Apply current global theme
        manager.Theme = GlobalSettings.CurrentTheme;
        
        // Synchronize common properties
        manager.LogoImage = GlobalSettings.ApplicationLogo;
        manager.Title = GlobalSettings.ApplicationTitle;
    }
    
    public static void UnregisterUIManager(BeepFormUIManager manager)
    {
        _activeManagers.Remove(manager);
    }
    
    public static void ChangeGlobalTheme(string themeName)
    {
        GlobalSettings.CurrentTheme = themeName;
        
        // Update all active forms
        foreach (var manager in _activeManagers)
        {
            manager.Theme = themeName;
        }
        
        // Persist setting
        Properties.Settings.Default.GlobalTheme = themeName;
        Properties.Settings.Default.Save();
    }
    
    public static void UpdateGlobalBranding(string title, string logoPath)
    {
        GlobalSettings.ApplicationTitle = title;
        GlobalSettings.ApplicationLogo = logoPath;
        
        // Update all active forms
        foreach (var manager in _activeManagers)
        {
            manager.Title = title;
            manager.LogoImage = logoPath;
        }
    }
}

// Usage in each form:
public partial class DataEntryForm : BeepiForm
{
    private BeepFormUIManager uiManager;
    
    public DataEntryForm()
    {
        InitializeComponent();
        
        uiManager = new BeepFormUIManager(this.components);
        uiManager.Initialize(this);
        
        // Register with global coordinator
        ApplicationUICoordinator.RegisterUIManager(uiManager);
    }
    
    protected override void OnFormClosed(FormClosedEventArgs e)
    {
        ApplicationUICoordinator.UnregisterUIManager(uiManager);
        base.OnFormClosed(e);
    }
}

public class PluginAwareUIManager : BeepFormUIManager
{
    private readonly Dictionary _themePlugins;
    
    public PluginAwareUIManager(IContainer container) : base(container)
    {
        _themePlugins = new Dictionary();
        LoadThemePlugins();
    }
    
    private void LoadThemePlugins()
    {
        // Load theme plugins from plugin directory
        var pluginPath = Path.Combine(Application.StartupPath, "Plugins", "Themes");
        if (!Directory.Exists(pluginPath)) return;
        
        var pluginFiles = Directory.GetFiles(pluginPath, "*.dll");
        
        foreach (var file in pluginFiles)
        {
            try
            {
                var assembly = Assembly.LoadFrom(file);
                var pluginTypes = assembly.GetTypes()
                    .Where(t => typeof(IThemePlugin).IsAssignableFrom(t) && !t.IsInterface);
                
                foreach (var type in pluginTypes)
                {
                    var plugin = (IThemePlugin)Activator.CreateInstance(type);
                    _themePlugins[plugin.ThemeName] = plugin;
                    
                    // Register plugin theme with BeepThemesManager
                    BeepThemesManager.AddTheme(plugin.GetTheme());
                }
            }
            catch (Exception ex)
            {
              //  Console.WriteLine($"Failed to load theme plugin {file}: {ex.Message}");
            }
        }
    }
    
    protected override void OnThemeChanged(string newTheme)
    {
        base.OnThemeChanged(newTheme);
        
        // Apply plugin-specific customizations
        if (_themePlugins.TryGetValue(newTheme, out var plugin))
        {
            plugin.ApplyCustomizations(this);
        }
    }
}

public interface IThemePlugin
{
    string ThemeName { get; }
    IBeepTheme GetTheme();
    void ApplyCustomizations(BeepFormUIManager uiManager);
}

? Best Practices

??? Architecture

• Single Manager Per Form: Use one BeepFormUIManager per form for optimal coordination
• Design-Time Integration: Add managers during design-time for best Visual Studio integration
• Early Initialization: Initialize managers early in form construction for consistent behavior
• Event Subscription: Subscribe to theme events for responsive UI updates

?? Theme Management

• Consistent Theming: Use the same theme approach across all forms in your application
• Theme Persistence: Save and restore user theme preferences
• Graceful Fallbacks: Handle missing or invalid themes gracefully
• Performance: Batch theme changes to minimize UI updates

? Performance

• Lazy Loading: Initialize components only when needed
• Event Management: Properly unsubscribe from events to prevent memory leaks
• Efficient Updates: Use SuspendLayout/ResumeLayout for bulk changes
• Resource Cleanup: Dispose of managers properly when forms close

?? Advanced Usage

• Component Discovery: Leverage automatic component discovery for dynamic UIs
• Property Synchronization: Use the manager's property synchronization for consistency
• Custom Integration: Extend the manager for application-specific needs
• Plugin Support: Design for extensibility with plugin architectures

public class ProductionUIManager : BeepFormUIManager
{
    private static readonly ILogger Logger = LogManager.GetLogger(typeof(ProductionUIManager));
    
    public ProductionUIManager(IContainer container) : base(container)
    {
        // Production-specific initialization
    }
    
    protected override void OnThemeChanged(string newTheme)
    {
        try
        {
            Logger.Info($"Changing theme to: {newTheme}");
            
            // Validate theme before applying
            if (!BeepThemesManager.ThemeExists(newTheme))
            {
                Logger.Warn($"Theme {newTheme} not found, using default");
                newTheme = "DefaultTheme";
            }
            
            base.OnThemeChanged(newTheme);
            
            // Log successful change
            Logger.Info($"Theme changed successfully to: {newTheme}");
        }
        catch (Exception ex)
        {
            Logger.Error(ex, $"Failed to change theme to {newTheme}");
            
            // Fallback to default theme
            try
            {
                base.OnThemeChanged("DefaultTheme");
            }
            catch (Exception fallbackEx)
            {
                Logger.Fatal(fallbackEx, "Failed to apply fallback theme");
            }
        }
    }
    
    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            Logger.Debug("Disposing ProductionUIManager");
            
            // Clean up any additional resources
            CleanupProductionResources();
        }
        
        base.Dispose(disposing);
    }
}