# Badge Display & Formatting

## Overview

The Badge Display & Formatting feature allows developers to integrate a taskbar badge into their .NET WinForms applications. The badge can display a numeric value or a notification, and it scales automatically based on Windows settings. When the badge type is set to Notification, no numeric value is displayed; instead, a static or flashing notification is shown based on the BlinkNotification property. The badge value can be dynamically updated by setting the `BadgeValue` property when the badge type is not Notification, and when the value reaches 0, the badge is automatically hidden. It is critical to override the parent's OnShown method and set the parent form property of the taskbar badge there—this is the only appropriate location to set it.

***

### Key Points

<table><thead><tr><th width="226">Key Point</th><th>Description</th></tr></thead><tbody><tr><td>Badge Value Visibility</td><td>Numeric values are displayed only when BadgeType is not Notification; a value of 0 causes the badge to disappear.</td></tr><tr><td>Notification Mode</td><td>When BadgeType is Notification, the control shows a static or flashing notification instead of a numeric value.</td></tr><tr><td>Dynamic Updates</td><td>Changing the <code>BadgeValue</code> property dynamically updates the badge display in real time.</td></tr><tr><td>Automatic Sizing</td><td>Badge sizing is managed by the operating system, ensuring proper scaling across different screen resolutions.</td></tr><tr><td>Parent Form Integration</td><td>The ParentForm property must be set in the OnShown method of the parent form; do not set it elsewhere.</td></tr></tbody></table>

***

### Best Practices

<table><thead><tr><th width="298">Best Practice</th><th>Description</th></tr></thead><tbody><tr><td>Override OnShown in Parent Form</td><td>Always override the parent's OnShown method to set the ParentForm property of the taskbar badge component.</td></tr><tr><td>Set ParentForm Once</td><td>Set the ParentForm property only in the OnShown method to ensure proper lifecycle management and avoid errors.</td></tr><tr><td>Use Dynamic Badge Updates</td><td>Update the badge dynamically using the <code>BadgeValue</code> property when not in Notification mode to provide real-time feedback.</td></tr><tr><td>Maintain Clear Badge Modes</td><td>Clearly differentiate between numeric and notification badge modes to avoid confusion in UI behavior.</td></tr><tr><td>Leverage OS Scaling</td><td>Rely on Windows for automatic scaling of badge icons; avoid hardcoding sizes in your application.</td></tr></tbody></table>

***

### Common Pitfalls

<table><thead><tr><th width="329">Pitfall</th><th>How to Avoid It</th></tr></thead><tbody><tr><td>Setting ParentForm in the Constructor</td><td>Do not set the ParentForm property in the constructor or elsewhere; it must only be set in the parent's OnShown method.</td></tr><tr><td>Misinterpreting Notification Mode</td><td>Understand that when BadgeType is Notification, the badge value is not shown—only a notification is displayed.</td></tr><tr><td>Not Handling Zero Badge Value</td><td>Ensure that a BadgeValue of 0 is properly handled so that the badge disappears automatically.</td></tr><tr><td>Overriding System Sizing</td><td>Avoid manually setting badge sizes; rely on Windows' automatic scaling to ensure consistency across devices.</td></tr></tbody></table>

***

### Usage Scenarios

<table><thead><tr><th width="238">Scenario</th><th>Description</th></tr></thead><tbody><tr><td>Real-Time Notifications</td><td>Use when the application needs to alert users to changes, such as new messages or updates, using a flashing notification.</td></tr><tr><td>Dynamic Badge Counters</td><td>Employ dynamic updates to the badge value to indicate the number of pending items (e.g., unread emails or messages).</td></tr><tr><td>Adaptive UI Elements</td><td>Integrate the badge to provide visual cues on the taskbar icon, enhancing user awareness of application status.</td></tr></tbody></table>

***

### Real Life Usage Scenarios

<table><thead><tr><th width="229">Scenario</th><th>Description</th></tr></thead><tbody><tr><td>Email Client Application</td><td>Dynamically update the badge to reflect the number of unread emails, switching to notification mode during critical alerts.</td></tr><tr><td>Social Media Dashboard</td><td>Display notifications for new interactions (likes, comments) without showing the exact count in notification mode.</td></tr><tr><td>Task Management App</td><td>Use the badge to indicate the number of pending tasks and flash the badge on significant updates or deadlines.</td></tr></tbody></table>

***

### Troubleshooting Tips

<table><thead><tr><th width="268">Tip</th><th>Description</th></tr></thead><tbody><tr><td>Verify ParentForm Setup</td><td>Ensure that the ParentForm property is only set within the OnShown override of the parent form to prevent initialization issues.</td></tr><tr><td>Check BadgeType Settings</td><td>Confirm that BadgeType is correctly set to either Counter, Numeric, or Notification to achieve the desired behavior.</td></tr><tr><td>Monitor BadgeValue Changes</td><td>Use logging or debugging to track updates to the BadgeValue property, ensuring that dynamic updates are reflected.</td></tr><tr><td>Validate Timer Intervals</td><td>If using notifications or animations, verify that timer intervals are set to appropriate values for smooth operation.</td></tr></tbody></table>

***

### Code Examples and Demos

#### Integration in Parent Form

Override the OnShown method of your parent form and set the ParentForm property for the badge component:

```csharp
public partial class MainForm : Form
{
    private SiticoneTaskbarBadgeSystem taskbarBadge;

    public MainForm()
    {
        InitializeComponent();
        taskbarBadge = new SiticoneTaskbarBadgeSystem();
    }

    protected override void OnShown(EventArgs e)
    {
        base.OnShown(e);
        // Set the ParentForm property here
        taskbarBadge.ParentForm = this;
    }
}
```

#### Updating Badge Value Dynamically

Use button event handlers to add or subtract from the badge value:

```csharp
private void btnIncreaseBadge_Click(object sender, EventArgs e)
{
    // Increase badge value when not in Notification mode
    if (taskbarBadge.BadgeType != BadgeType.Notification)
    {
        taskbarBadge.BadgeValue += 1;
    }
}

private void btnDecreaseBadge_Click(object sender, EventArgs e)
{
    // Decrease badge value; if reaches 0, badge disappears automatically
    if (taskbarBadge.BadgeType != BadgeType.Notification && taskbarBadge.BadgeValue > 0)
    {
        taskbarBadge.BadgeValue -= 1;
    }
}
```

#### Setting Notification Mode

Switch the badge to Notification mode and enable flashing notifications:

```csharp
private void btnSetNotificationMode_Click(object sender, EventArgs e)
{
    // When BadgeType is Notification, the numeric value is not displayed
    taskbarBadge.EnableNotification = true;
    taskbarBadge.BlinkNotification = true;
}
```

***

### Review

<table><thead><tr><th width="234">Aspect</th><th>Description</th></tr></thead><tbody><tr><td>ParentForm Requirement</td><td>The ParentForm property must be set in the OnShown method of the parent form, ensuring proper initialization.</td></tr><tr><td>Mode Differentiation</td><td>Understand that numeric badge display and notification mode behave differently, with Notification mode hiding the value.</td></tr><tr><td>Automatic Sizing</td><td>The control leverages Windows automatic scaling, simplifying integration across various display environments.</td></tr><tr><td>Dynamic Updates</td><td>The BadgeValue property enables real-time updates when in Counter or Numeric mode, enhancing responsiveness.</td></tr></tbody></table>

***

### Summary

<table><thead><tr><th width="237">Summary Aspect</th><th>Description</th></tr></thead><tbody><tr><td>Feature Purpose</td><td>Provides a flexible badge display system that adapts to different UI requirements through numeric counters or notifications.</td></tr><tr><td>Implementation Focus</td><td>Ensure correct ParentForm setup in OnShown, and choose the appropriate BadgeType to meet application needs.</td></tr><tr><td>Developer Considerations</td><td>Follow best practices for setting dynamic badge values and avoid common pitfalls such as improper initialization.</td></tr><tr><td>Benefit</td><td>Enhances user experience by providing a visually integrated taskbar badge that communicates status updates effectively.</td></tr></tbody></table>

***

### Additional Useful Sections

#### Integration Checklist

<table><thead><tr><th width="342">Step</th><th>Details</th></tr></thead><tbody><tr><td>1. Create Badge Component Instance</td><td>Instantiate the SiticoneTaskbarBadgeSystem in your main form.</td></tr><tr><td>2. Override OnShown</td><td>Override the parent's OnShown method to set the ParentForm property for the badge component.</td></tr><tr><td>3. Configure Badge Settings</td><td>Set properties such as BadgeType, BadgeValue, BadgeColor, and TextColor based on your application requirements.</td></tr><tr><td>4. Implement Dynamic Update Handlers</td><td>Add event handlers (e.g., button clicks) to modify the BadgeValue dynamically during runtime.</td></tr><tr><td>5. Test Notification Mode</td><td>Set the BadgeType to Notification and configure BlinkNotification to verify flashing/static notification behavior.</td></tr></tbody></table>

#### Demo Application Flow

```csharp
public partial class MainForm : Form
{
    private SiticoneTaskbarBadgeSystem taskbarBadge;

    public MainForm()
    {
        InitializeComponent();
        taskbarBadge = new SiticoneTaskbarBadgeSystem();
    }

    protected override void OnShown(EventArgs e)
    {
        base.OnShown(e);
        // Set ParentForm in the OnShown method only
        taskbarBadge.ParentForm = this;
    }

    private void btnIncreaseBadge_Click(object sender, EventArgs e)
    {
        if (taskbarBadge.BadgeType != BadgeType.Notification)
        {
            taskbarBadge.BadgeValue += 1;
        }
    }

    private void btnDecreaseBadge_Click(object sender, EventArgs e)
    {
        if (taskbarBadge.BadgeType != BadgeType.Notification && taskbarBadge.BadgeValue > 0)
        {
            taskbarBadge.BadgeValue -= 1;
        }
    }

    private void btnSetNotificationMode_Click(object sender, EventArgs e)
    {
        taskbarBadge.EnableNotification = true;
        taskbarBadge.BlinkNotification = true;
    }
}
```

***

This comprehensive documentation for the Badge Display & Formatting feature covers key aspects, integration steps, dynamic updates, and practical usage scenarios. Following these guidelines and examples will help developers integrate the SiticoneTaskbarBadgeSystem component efficiently and effectively into their .NET WinForms applications.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/utility-controls/siticone-taskbarbadges./badge-display-and-formatting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.