Events

A feature that notifies the host application of signature pad activities, allowing developers to respond in real time to user interactions.

Overview

The control exposes events such as ReplayStarted, ReplayCompleted, AnalyticsUpdated, StrokeStarted, StrokeCompleted, and SignatureCleared to allow integration of responsive behavior based on signature activity.

---

Detailed Documentation

Key Points

Aspect	Details
Replay Notifications	ReplayStarted and ReplayCompleted indicate when the signature replay animation begins and ends.
Analytics Feedback	AnalyticsUpdated provides computed metrics (e.g., total length, stroke count, average speed, pressure) after signature analysis.
Stroke Lifecycle	StrokeStarted and StrokeCompleted signal the beginning and completion of a stroke.
Signature Reset	SignatureCleared informs the application when the signature pad has been cleared.

Best Practices

Practice	Recommendation
Subscribe Early	Attach event handlers immediately after initializing the control to ensure all user interactions are captured.
Keep Handlers Lightweight	Avoid complex operations inside event handlers; offload heavy processing to background tasks if necessary.
Unsubscribe on Dispose	Remove event handlers when the control is no longer needed to prevent memory leaks.

Common Pitfalls

Pitfall	Mitigation
Missed Event Attachments	Ensure that all critical events (e.g., StrokeCompleted) are subscribed to immediately after the control is created.
Overloading UI in Handlers	Avoid performing intensive operations in event handlers to keep the UI responsive.
Memory Leaks	Unsubscribe from events when the control is disposed or no longer visible to prevent lingering references.

Usage Scenarios

Scenario	Description
Real-Time UI Feedback	Update UI elements (status labels, buttons) based on signature activity using stroke and replay events.
Logging and Auditing	Record signature activity and analytics data by handling events like AnalyticsUpdated for audit or verification purposes.
Coordinating Animations	Synchronize additional UI animations with the signature replay using ReplayStarted and ReplayCompleted events.

Real Life Usage Scenarios

Scenario	Description
Financial Applications	Use events to provide immediate feedback to users and log interactions in high-security signature capture workflows.
Legal Document Signing	Leverage stroke events to ensure each signature stroke is recorded accurately for later verification.
Educational Tools	Use event-driven feedback to guide users through proper signature formation, providing instant corrections and tips.

Code Examples

Example 1: Handling Stroke and Replay Events

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

public class EventsDemoForm : Form
{
    private SiticoneSignaturePad signaturePad;
    private Label statusLabel;

    public EventsDemoForm()
    {
        signaturePad = new SiticoneSignaturePad
        {
            Location = new Point(10, 10),
            Size = new Size(400, 200)
        };

        statusLabel = new Label
        {
            Location = new Point(10, 220),
            Size = new Size(400, 30),
            Text = "Waiting for input..."
        };

        // Subscribe to events
        signaturePad.StrokeStarted += (s, e) => statusLabel.Text = "Stroke started...";
        signaturePad.StrokeCompleted += (s, e) => statusLabel.Text = "Stroke completed.";
        signaturePad.SignatureCleared += (s, e) => statusLabel.Text = "Signature cleared.";
        signaturePad.ReplayStarted += (s, e) => statusLabel.Text = "Replay started.";
        signaturePad.ReplayCompleted += (s, e) => statusLabel.Text = "Replay completed.";
        signaturePad.AnalyticsUpdated += (s, analytics) =>
        {
            // Log analytics data
            Console.WriteLine($"Total Length: {analytics.TotalLength}, Stroke Count: {analytics.StrokeCount}");
        };

        Controls.Add(signaturePad);
        Controls.Add(statusLabel);
    }

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

Example 2: Unsubscribing from Events on Disposal

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

public class CleanEventsForm : Form
{
    private SiticoneSignaturePad signaturePad;

    public CleanEventsForm()
    {
        signaturePad = new SiticoneSignaturePad
        {
            Location = new Point(10, 10),
            Size = new Size(400, 200)
        };

        // Subscribe using named methods for easy unsubscription
        signaturePad.StrokeStarted += OnStrokeStarted;
        signaturePad.StrokeCompleted += OnStrokeCompleted;

        Controls.Add(signaturePad);
    }

    private void OnStrokeStarted(object sender, SignaturePad.StrokeEventArgs e)
    {
        // Handle stroke start event
    }

    private void OnStrokeCompleted(object sender, SignaturePad.StrokeEventArgs e)
    {
        // Handle stroke complete event
    }

    protected override void OnFormClosing(FormClosingEventArgs e)
    {
        // Unsubscribe to prevent memory leaks
        signaturePad.StrokeStarted -= OnStrokeStarted;
        signaturePad.StrokeCompleted -= OnStrokeCompleted;
        base.OnFormClosing(e);
    }

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

Troubleshooting Tips

Tip	Explanation
Confirm All Subscriptions	Check that event handlers are attached immediately after control initialization to capture every user interaction.
Use Logging for Diagnostics	Insert logging within event handlers to verify that events are firing as expected and to trace the event flow.
Unsubscribe Correctly	Ensure that event handlers are removed when the control is disposed to avoid memory leaks in long-running applications.
Validate Event Data	Inspect the data provided by events like AnalyticsUpdated to ensure that analytics computations are accurate.

Review

Aspect	Review Comments
Integration	The events are easy to integrate, providing a direct way to receive feedback from the signature pad with minimal setup.
Responsiveness	Real-time events allow for immediate UI updates and enhanced user feedback, contributing to a dynamic user experience.
Flexibility	A broad range of events supports detailed tracking of signature activity, making it adaptable for various application needs.

Summary

The Events feature in the SiticoneSignaturePad control provides comprehensive notifications for signature-related activities. By subscribing to events such as ReplayStarted, ReplayCompleted, AnalyticsUpdated, StrokeStarted, StrokeCompleted, and SignatureCleared, developers can implement real-time feedback, logging, and UI updates that significantly enhance the responsiveness and interactivity of their applications.