Events and Public Methods

This feature provides a set of events for user interactions and window state changes along with public methods to programmatically control the form's behavior, such as toggling maximization, etc.

Overview

This section covers the events that notify subscribers when key actions occur (for example, when the window is maximized, help is requested, or the form is closing) and the public methods that enable programmatic control over these behaviors. Developers can subscribe to these events to execute custom logic and can invoke public methods to change the form state at runtime.

The primary events and methods include:

• Events:

  • MaximizeStateChanged: Raised when the form toggles between maximized and normal states.

  • HelpButtonClicked: Occurs when the help button is clicked.

  • FormClosing: Raised when the form is about to close; can be canceled.

  • PinToTopClicked: Occurs when the pin-to-top button is clicked.

  • SettingsClicked: Occurs when the settings button is clicked.

• Public Methods:

  • ToggleMaximizeState(): Programmatically toggles the form’s maximized state.

  • RefreshAppearance(): Forces a refresh/redraw of the form’s visual elements.

  • Close(): Initiates the form close sequence, incorporating fade-out and confirmation logic.

---

Key Points

Aspect	Details	Default Behavior/Value	Example Usage
MaximizeStateChanged	Fires an event when the form changes its maximized state.	Raised automatically on toggle	Subscribe to update UI when form is maximized.
HelpButtonClicked	Fires when the help button is clicked, allowing integration of custom help dialogs or actions.	Not subscribed by default	myForm.HelpButtonClicked += (s,e) => { … };
FormClosing	Fires just before the form closes; event handlers can cancel the closing if needed.	Raised before initiating close fade-out	Use to confirm with the user or save state.
PinToTopClicked	Raised when the pin-to-top button is clicked, allowing custom logic for always-on-top behavior.	Automatically toggles TopMost	Toggle additional logging or UI updates.
SettingsClicked	Raised when the settings button is clicked, enabling the display of a settings dialog or configuration panel.	Not subscribed by default	Launch settings form on click.
ToggleMaximizeState()	Allows the form’s maximized state to be toggled programmatically.	Switches between normal and maximized	myForm.ToggleMaximizeState();
RefreshAppearance()	Forces a complete redraw of the form and its child controls; useful after dynamic theme changes.	Invokes Invalidate(true) on the form	Call after a theme update.
Close()	Overrides the default close behavior to include fade-out transitions and optional confirmation/countdown features.	Initiates the fade-out sequence	myForm.Close();

---

Best Practices

Recommendation	Explanation	Example in Code
Subscribe to key events early	Attach event handlers during form initialization to capture all interactions from the start.	myForm.FormClosing += (s, e) => { /* cleanup logic */ };
Use ToggleMaximizeState() for state changes	Instead of manually adjusting form size, use the provided method to maintain consistent behavior and margins.	if (buttonClicked) { myForm.ToggleMaximizeState(); }
Refresh the UI after dynamic changes	After making dynamic appearance or theme changes, call RefreshAppearance() to ensure the UI reflects updates.	myForm.RefreshAppearance();
Leverage FormClosing for cleanup	Use the FormClosing event to safely handle resource cleanup or prompt the user before exiting.	Attach a handler to FormClosing that cancels closure if needed.

---

Common Pitfalls

Issue	Cause	Prevention/Remedy
Missing event subscriptions	Failing to subscribe to events can leave key actions unhandled.	Always attach event handlers during form initialization.
Overriding Close behavior incorrectly	Custom close logic might inadvertently bypass confirmation dialogs or fade effects.	Ensure that overrides of Close() invoke the built-in fade/confirmation logic.
Not refreshing the UI after state changes	Changes to theme or control properties may not be visible without an explicit UI refresh.	Call RefreshAppearance() after modifying visual properties.
Canceling FormClosing improperly	Improper handling of the FormClosing event can block form closure when not intended.	Use CancelEventArgs carefully and test the closure flow thoroughly.

---

Usage Scenarios

Scenario	How It Works	Sample Code
Custom Closure Handling	A developer can subscribe to FormClosing to show a confirmation dialog or perform cleanup before closing.	csharp\nmyForm.FormClosing += (sender, e) => {\n if (!ConfirmUserExit()) {\n e.Cancel = true;\n }\n};
Programmatic Maximization	The form’s maximized state can be toggled via a method call, for example in response to a custom button click.	csharp\n// On a button click event\nmyForm.ToggleMaximizeState();
Dynamic UI Refresh	After updating the theme or changing appearance settings at runtime, calling RefreshAppearance() updates the display.	csharp\n// After dynamic theme update\nmyForm.RefreshAppearance();
Handling Help Requests	The application displays a help dialog when the help button is clicked by subscribing to HelpButtonClicked.	csharp\nmyForm.HelpButtonClicked += (s, e) => {\n ShowHelpDialog();\n};

---

Real Life Usage Scenarios

Scenario	Explanation	How to Implement
Enterprise Software	In a large-scale application, you might need to confirm closure and log state changes.	Subscribe to FormClosing to prompt for confirmation and to log user actions before closure.
Multimedia or Dashboard Applications	Toggling between maximized and normal states enhances the user's focus on content or analytics.	Use ToggleMaximizeState() tied to a custom control to switch display modes.
Customizable User Interfaces	Applications that allow end users to modify UI behavior can use these events to store user preferences.	Save user choices on events such as PinToTopClicked or SettingsClicked, then apply them on startup.

---

Troubleshooting Tips

Problem	Potential Cause	Suggested Fix
Event handlers not firing	Event subscriptions may have been missed during initialization.	Ensure that all events (e.g., HelpButtonClicked, FormClosing) are subscribed before the form is shown.
Inconsistent state after toggling	Direct manipulation of the form’s bounds outside of ToggleMaximizeState can cause layout issues.	Use ToggleMaximizeState() exclusively to change the form state to ensure all related logic is executed.
UI not updating after a state change	Failing to refresh the appearance may result in outdated visuals after a dynamic change.	Call RefreshAppearance() immediately after any state change or visual update.

---

Review

Aspect	Notes
Event-Driven Design	The events provide a robust mechanism for integrating custom business logic and UI behavior.
Ease of Control	Public methods such as ToggleMaximizeState() simplify state changes and maintain consistency.
Integration Simplicity	Subscribing to events and invoking public methods is straightforward, making integration seamless.

---

Summary

Summary Point	Description
Event Accessibility	Key events provide hooks for developers to integrate custom logic for help, closing, and state changes.
Programmatic Control	Public methods like ToggleMaximizeState() and RefreshAppearance() enable dynamic control over the UI.
Enhanced User Interaction	Custom events and methods allow the application to respond to user actions in a controlled, predictable manner.

---

Additional Code Example

Below is a complete integration sample demonstrating how to initialize a SiticoneForm, subscribe to its events, and use its public methods:

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Adjust namespace as needed

public class MainForm
{
    public static bool ConfirmUserExit()
    {
        return MessageBox.Show("Are you sure you want to exit?", "Confirm Exit",
            MessageBoxButtons.YesNo, MessageBoxIcon.Question) == DialogResult.Yes;
    }

    public static void ShowHelpDialog()
    {
        MessageBox.Show("This is the help dialog. Provide your help content here.", "Help");
    }

    public static void Main()
    {
        var myForm = new SiticoneForm
        {
            FormTitle = "Event-Driven Application",
            ThemeVariant = FormThemeVariant.DarkDefault
        };

        // Subscribe to events
        myForm.MaximizeStateChanged += (sender, e) =>
        {
            Console.WriteLine("The form's maximized state has changed.");
        };

        myForm.HelpButtonClicked += (sender, e) =>
        {
            ShowHelpDialog();
        };

        myForm.FormClosing += (sender, e) =>
        {
            // Prompt for confirmation before closing
            if (!ConfirmUserExit())
            {
                e.Cancel = true;
            }
        };

        myForm.PinToTopClicked += (sender, e) =>
        {
            Console.WriteLine("Pin-to-top toggled.");
        };

        myForm.SettingsClicked += (sender, e) =>
        {
            MessageBox.Show("Settings button clicked. Open settings dialog.", "Settings");
        };

        // Example: Toggle maximized state on a timer or button click (here simulated by a simple timer)
        Timer toggleTimer = new Timer { Interval = 5000 };
        toggleTimer.Tick += (s, e) =>
        {
            myForm.ToggleMaximizeState();
            Console.WriteLine("Toggled maximized state.");
        };
        toggleTimer.Start();

        Application.Run(myForm);
    }
}

---

Additional Resources

Resource	Description	Link/Reference
Inline Code Comments	The provided code includes inline comments explaining the purpose of each event and method.	Refer to the original code snippet.
Official WinForms Documentation	Microsoft’s WinForms documentation covers event handling and form state management in detail.	https://docs.microsoft.com/dotnet/desktop/winforms/
Community Forums	Developer forums offer insights into best practices for event-driven programming in WinForms.	Check .NET or WinForms-specific communities.

---

This documentation should serve as a comprehensive guide for integrating and utilizing the events and public methods available on your SiticoneForm. Each section is designed to help developers understand the hooks available for custom logic, follow best practices, and troubleshoot common issues while implementing event-driven features in the form.