Notification Badge

Notification Badge provides a customizable numeric overlay for the button, enabling developers to display dynamic notifications and updates directly on the control.

Overview

The Notification Badge feature of the SiticoneDashboardButton control allows developers to overlay a badge on the button, displaying numeric information such as notifications or message counts. With properties controlling visibility, color, size, and padding, as well as events to handle clicks and updates, this feature supports interactive and real-time updates in your WinForms applications.

---

Properties Table

Property	Type	Default Value	Description
ShowBadge	bool	false	Controls the visibility of the notification badge overlay on the button.
BadgeCount	int	0	The numeric value displayed on the badge; values above 99 are displayed as "99+".
BadgeColor	Color	Color.FromArgb(255, 62, 62)	Specifies the background color of the badge.
BadgeTextColor	Color	Color.White	Specifies the text color displayed on the badge.
BadgeSize	int	20	Determines the diameter (in pixels) of the circular notification badge (typically between 16 and 32).
BadgePadding	int	8	Defines the spacing (in pixels) between the badge and the button's edge.

---

Events Table

Event	Delegate	Description
BadgeClicked	EventHandler	Occurs when the badge area is clicked, allowing custom handling of badge interactions.
BadgeUpdateRequested	EventHandler<BadgeUpdateEventArgs>	Raised to request a badge update, giving developers a chance to modify the new count and animation options.

---

Code Examples

Basic Integration

The following example demonstrates how to enable the Notification Badge and set an initial badge count on the SiticoneDashboardButton control:

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

public class NotificationBadgeDemoForm : Form
{
    public NotificationBadgeDemoForm()
    {
        // Instantiate the SiticoneDashboardButton control
        SiticoneDashboardButton dashboardButton = new SiticoneDashboardButton
        {
            Text = "Messages",
            Size = new Size(250, 45),
            Location = new Point(50, 50),
            // Enable the notification badge
            ShowBadge = true,
            // Set the initial badge count
            BadgeCount = 5,
            // Customize badge appearance
            BadgeColor = Color.Red,
            BadgeTextColor = Color.White,
            BadgeSize = 24,
            BadgePadding = 10
        };

        // Subscribe to the badge clicked event for custom actions
        dashboardButton.BadgeClicked += DashboardButton_BadgeClicked;

        // Add the button to the form
        Controls.Add(dashboardButton);
    }

    private void DashboardButton_BadgeClicked(object sender, EventArgs e)
    {
        MessageBox.Show("Badge was clicked!");
    }

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

Advanced Badge Update Handling

This example shows how to update the badge count dynamically and handle the BadgeUpdateRequested event to implement custom logic or animations during badge updates:

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

public class AdvancedBadgeUpdateForm : Form
{
    private SiticoneDashboardButton dashboardButton;
    private int messageCount = 0;

    public AdvancedBadgeUpdateForm()
    {
        dashboardButton = new SiticoneDashboardButton
        {
            Text = "Inbox",
            Size = new Size(250, 45),
            Location = new Point(50, 50),
            ShowBadge = true,
            BadgeCount = messageCount,
            BadgeColor = Color.DarkGreen,
            BadgeTextColor = Color.White,
            BadgeSize = 22,
            BadgePadding = 8
        };

        // Handle badge update requests to log or customize badge changes
        dashboardButton.BadgeUpdateRequested += DashboardButton_BadgeUpdateRequested;

        // Add the button to the form
        Controls.Add(dashboardButton);

        // Simulate receiving messages
        Timer updateTimer = new Timer { Interval = 2000 };
        updateTimer.Tick += (s, e) => UpdateBadgeCount();
        updateTimer.Start();
    }

    private void DashboardButton_BadgeUpdateRequested(object sender, BadgeUpdateEventArgs e)
    {
        // Optionally modify the new count or whether the update should animate
        Console.WriteLine("Badge update requested. New count: " + e.NewCount);
        // For instance, you could enforce a maximum count or log the change
    }

    private void UpdateBadgeCount()
    {
        messageCount++;
        // Update the badge with the new count; animation is enabled by default
        dashboardButton.UpdateBadge(messageCount, animate: true);
    }

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

---

Key Points

Aspect	Details
Dynamic Updates	The badge can be updated dynamically using the BadgeCount property and the UpdateBadge method.
Visibility Control	The ShowBadge property enables or hides the badge based on the application’s needs.
Customizable Appearance	BadgeColor, BadgeTextColor, BadgeSize, and BadgePadding provide full control over the badge’s styling.
Interaction Handling	BadgeClicked and BadgeUpdateRequested events allow developers to hook into badge interactions and updates.

---

Best Practices

Practice	Recommendation
Consistent Notification Design	Align badge colors and sizes with the overall application theme to maintain a cohesive design.
Timely Updates	Ensure that the badge updates reflect real-time information and do not lag behind user interactions.
Event Handling	Leverage the BadgeClicked event to provide users with actionable feedback or to navigate to detailed views.
Validate Badge Values	Ensure that the BadgeCount is non-negative and use the built-in handling for values over 99 (displaying as "99+").

---

Common Pitfalls

Pitfall	How to Avoid
Overloading with Notifications	Avoid displaying too many badge updates at once, which can overwhelm the user; throttle updates if necessary.
Inconsistent Badge Sizing	Use a consistent BadgeSize value across similar controls to maintain a uniform look throughout your application.
Neglecting User Interaction	Ensure that the BadgeClicked event is properly handled to make the badge interactive and meaningful.
Ignoring Animation Effects	Overlooking the animation can make badge updates seem abrupt; allow for smooth transitions with UpdateBadge.

---

Usage Scenarios

Scenario	Example Use Case
Notification of New Messages	Use the badge to show the count of unread messages or new notifications in a messaging or email application.
Real-Time Data Updates	Display dynamic metrics such as pending tasks, alerts, or live updates in dashboard-style applications.
Interactive User Alerts	Provide immediate feedback by allowing users to click the badge to view more details or trigger actions.

---

Review

The Notification Badge feature integrates directly into the SiticoneDashboardButton control, providing a flexible and dynamic way to display numeric notifications. By exposing multiple customizable properties and events, developers can tailor the badge to meet the specific needs of their applications. The extensive code examples and tables help to quickly understand the functionality, correct integration patterns, and common pitfalls, ensuring a smooth implementation.

---

Summary

Notification Badge in the SiticoneDashboardButton control is a robust feature designed to overlay dynamic numeric information on the button. With properties for appearance and behavior along with events for handling clicks and update requests, it enables developers to build interactive and responsive notification systems in their WinForms applications. Following best practices and usage scenarios detailed in this documentation will help ensure that the feature is implemented effectively and seamlessly.

---

Additional Resources

Resource	Description	Link/Reference
Control Source Code	Detailed code implementation for the Notification Badge feature.	Refer to the provided source code documentation.
.NET WinForms Documentation	Official Microsoft documentation on creating custom WinForms controls.	https://docs.microsoft.com/dotnet/desktop/winforms/

This comprehensive documentation should assist developers in understanding, integrating, and customizing the Notification Badge feature of the SiticoneDashboardButton control in their .NET WinForms applications.