# Events

## Overview

The Events feature in the chip control encompasses a variety of notifications that are triggered by user actions or property changes. Key events include `ChipClicked`, `CloseClicked`, `SelectionChanged`, `StateChanged`, and `GroupChanged`. These events allow developers to implement custom behavior and maintain synchronization between the control’s visual state and the application logic. By subscribing to these events, developers can integrate the chip control into interactive applications with rich, dynamic responses.

***

### Key Points

<table><thead><tr><th width="229">Aspect</th><th>Details</th></tr></thead><tbody><tr><td>Primary Events</td><td><strong>ChipClicked</strong>: Fired when the chip (excluding the close button area) is clicked. <strong>CloseClicked</strong>: Fired when the close (X) button is clicked. <strong>SelectionChanged</strong>: Occurs when the chip's selection state (<code>IsSelected</code>) changes.</td></tr><tr><td>State and Group Events</td><td><strong>StateChanged</strong>: Provides detailed notifications when any property affecting the chip's state changes, including properties like Avatar, AccentColor, or FillColor. <strong>GroupChanged</strong>: Fired when the chip’s group assignment is modified, supporting group management logic.</td></tr><tr><td>Event Data</td><td>Custom event arguments (<code>GroupChangedEventArgs</code>, <code>GroupChipStateChangedEventArgs</code>) provide additional context such as the new group value or property name and new value when state changes occur.</td></tr><tr><td>Integration</td><td>These events enable fine-grained control over the chip's behavior, allowing developers to hook into user interactions and property updates to trigger application-specific logic, UI updates, or resource management actions.</td></tr></tbody></table>

***

### Best Practices

| Practice                                 | Explanation                                                                                                                                                                            |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Subscribe to events early                | Attach event handlers as soon as the chip control is instantiated to ensure that all user interactions and state changes are captured.                                                 |
| Leverage custom event arguments          | Utilize the provided event argument classes (e.g., `GroupChangedEventArgs` and `GroupChipStateChangedEventArgs`) to access context-specific data for more informed handling of events. |
| Avoid heavy processing in event handlers | Keep the logic inside event handlers lightweight to maintain UI responsiveness; delegate intensive tasks to background threads or use asynchronous patterns if necessary.              |
| Unsubscribe from events when disposing   | Prevent memory leaks by unsubscribing from events when the chip is disposed, especially in dynamic or long-running interfaces where chips may be frequently added and removed.         |

#### Code Example: Subscribing to Chip Events

```csharp
// Instantiate a new chip control.
var chip = new SiticoneGroupChip
{
    Text = "Eventful Chip",
    EnableSelection = true,
    ShowCloseButton = true
};

// Subscribe to ChipClicked to handle main area clicks.
chip.ChipClicked += (sender, e) =>
{
    // Toggle selection state and perform additional logic.
    chip.IsSelected = !chip.IsSelected;
    Console.WriteLine($"Chip clicked. New selection state: {chip.IsSelected}");
};

// Subscribe to CloseClicked to handle the close button action.
chip.CloseClicked += (sender, e) =>
{
    // Perform cleanup or update UI before disposing of the chip.
    Console.WriteLine("Close button clicked. Removing chip.");
    if (chip.AutoDisposeOnClose && chip.Parent != null)
    {
        chip.Parent.Controls.Remove(chip);
        chip.Dispose();
    }
};

// Subscribe to SelectionChanged to monitor changes in selection state.
chip.SelectionChanged += (sender, e) =>
{
    Console.WriteLine("Chip selection changed.");
};

// Subscribe to StateChanged to catch any property changes affecting state.
chip.StateChanged += (sender, e) =>
{
    Console.WriteLine($"Property '{e.PropertyName}' changed to: {e.NewValue}");
};

// Subscribe to GroupChanged to handle group modifications.
chip.GroupChanged += (sender, e) =>
{
    Console.WriteLine($"Chip group changed to: {e.NewGroup}");
};

// Add the chip to a container control.
this.Controls.Add(chip);
```

***

### Common Pitfalls

| Pitfall                                 | Explanation                                                                                                                                                                                                                           |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Missing event unsubscriptions           | Neglecting to unsubscribe from events when the chip is disposed can lead to memory leaks, especially in applications that frequently add and remove chip controls.                                                                    |
| Overcomplicating event handlers         | Writing extensive processing logic directly within event handlers can degrade UI responsiveness; it is better to offload complex processing to separate methods or background tasks.                                                  |
| Inconsistent event firing               | Failing to handle events in the expected order (for instance, not distinguishing between a chip click and a close button click) may cause unintended behavior; ensure your event logic clearly distinguishes between these scenarios. |
| Over-reliance on default event behavior | Relying solely on the default events without considering customization may limit the chip’s integration; use custom event arguments to tailor behavior according to application needs.                                                |

#### Code Example: Ensuring Proper Unsubscription

```csharp
// Example of properly unsubscribing from events in a custom disposal method.
public void DisposeChip(SiticoneGroupChip chip)
{
    // Unsubscribe from all events.
    chip.ChipClicked -= ChipClickedHandler;
    chip.CloseClicked -= CloseClickedHandler;
    chip.SelectionChanged -= SelectionChangedHandler;
    chip.StateChanged -= StateChangedHandler;
    chip.GroupChanged -= GroupChangedHandler;

    // Remove from parent and dispose.
    if (chip.Parent != null)
    {
        chip.Parent.Controls.Remove(chip);
    }
    chip.Dispose();
}

// Event handler methods.
private void ChipClickedHandler(object sender, EventArgs e)
{
    // Handler logic here.
}

private void CloseClickedHandler(object sender, EventArgs e)
{
    // Handler logic here.
}

private void SelectionChangedHandler(object sender, EventArgs e)
{
    // Handler logic here.
}

private void StateChangedHandler(object sender, GroupChipStateChangedEventArgs e)
{
    // Handler logic here.
}

private void GroupChangedHandler(object sender, GroupChangedEventArgs e)
{
    // Handler logic here.
}
```

***

### Usage Scenarios

<table><thead><tr><th width="250">Scenario</th><th>Description</th></tr></thead><tbody><tr><td>Dynamic UI Updates</td><td>Use the StateChanged event to update other parts of the UI immediately when a chip's appearance or properties change, ensuring consistency across the application.</td></tr><tr><td>User Interaction Feedback</td><td>Employ ChipClicked and SelectionChanged events to provide immediate feedback (e.g., changing colors or displaying a checkmark) when a user interacts with the chip.</td></tr><tr><td>Group Management</td><td>Utilize the GroupChanged event to trigger group-specific logic, such as enforcing single selection among chips in the same group or updating related data models.</td></tr><tr><td>Resource Management</td><td>Leverage the CloseClicked event in combination with AutoDisposeOnClose to remove and dispose of chips dynamically, streamlining the cleanup process in applications with many chips.</td></tr></tbody></table>

#### Code Example: Dynamic UI Update Scenario

```csharp
// Suppose you have a label that displays the current selection state of a chip.
Label statusLabel = new Label { Location = new Point(10, 10), AutoSize = true };
this.Controls.Add(statusLabel);

var interactiveChip = new SiticoneGroupChip
{
    Text = "Selectable Chip",
    EnableSelection = true
};

interactiveChip.SelectionChanged += (sender, e) =>
{
    // Update the label based on the chip's selection state.
    statusLabel.Text = interactiveChip.IsSelected ? "Chip is Selected" : "Chip is Not Selected";
};

this.Controls.Add(interactiveChip);
```

***

### Real Life Usage Scenarios

<table><thead><tr><th width="266">Real Life Scenario</th><th>Example</th></tr></thead><tbody><tr><td>Email Client Management</td><td>In an email client, chips can represent labels or categories; events like ChipClicked and CloseClicked allow users to select a label for filtering or remove unwanted labels, with StateChanged ensuring UI consistency.</td></tr><tr><td>Task Management Systems</td><td>Chips representing tasks or tags can trigger SelectionChanged events to update a task list view dynamically, while CloseClicked events remove completed or irrelevant tags.</td></tr><tr><td>Customizable Dashboards</td><td>Interactive chips on dashboards can be used for filtering data; grouping events ensure that only one filter is active at a time, and StateChanged events update visual feedback across the interface.</td></tr></tbody></table>

#### Code Example: Email Client Label Management

```csharp
// Create a chip representing an email label.
var labelChip = new SiticoneGroupChip
{
    Text = "Important",
    EnableSelection = true,
    ShowCloseButton = true,
    AutoDisposeOnClose = true
};

labelChip.ChipClicked += (sender, e) =>
{
    labelChip.IsSelected = !labelChip.IsSelected;
};

labelChip.CloseClicked += (sender, e) =>
{
    // Handle label removal logic.
    Console.WriteLine("Label removed.");
};

labelChip.StateChanged += (sender, e) =>
{
    // Update UI elements or log state changes.
    Console.WriteLine($"Property {e.PropertyName} changed to {e.NewValue}");
};

this.Controls.Add(labelChip);
```

***

### Troubleshooting Tips

| Tip                                         | Details                                                                                                                                                                               |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Verify event subscriptions                  | Ensure that all necessary events (ChipClicked, CloseClicked, SelectionChanged, StateChanged, GroupChanged) have appropriate handlers attached to avoid missing key user interactions. |
| Monitor performance of event handlers       | Use profiling tools to ensure that the logic inside event handlers does not adversely affect UI responsiveness, especially if multiple chips are involved in a dynamic interface.     |
| Debug using logging                         | Insert logging statements in each event handler to trace the sequence of events, which helps identify issues with event firing order or unintended duplicate event triggers.          |
| Check for conflicts in group event handling | When chips are grouped, ensure that group management events (like GroupChanged) do not conflict with individual chip events, leading to inconsistent selection states.                |

***

### Review

<table><thead><tr><th width="182">Review Aspect</th><th>Comments</th></tr></thead><tbody><tr><td>Functionality</td><td>The Events feature provides comprehensive and customizable event notifications that allow developers to fully integrate the chip control into dynamic, interactive applications.</td></tr><tr><td>Customization</td><td>With a range of events covering user actions and property changes, developers have fine-grained control over the chip's behavior, making it easier to synchronize UI updates and application logic.</td></tr><tr><td>Integration</td><td>The event model is straightforward to implement, with clear event names and supportive custom event argument classes that supply additional context, ensuring a seamless integration into various application scenarios.</td></tr></tbody></table>

***

### Summary

The Events feature of the chip control enables developers to capture and react to user interactions and property changes through a suite of events including ChipClicked, CloseClicked, SelectionChanged, StateChanged, and GroupChanged. By subscribing to these events, applications can dynamically update UI elements, enforce group behavior, and manage the lifecycle of the chip control effectively. This comprehensive event model ensures that the chip control remains interactive and responsive within a diverse range of usage scenarios.

***

### Additional Sections

#### Integration Checklist

<table><thead><tr><th width="288">Item</th><th>Check</th></tr></thead><tbody><tr><td>Subscribe to primary events</td><td>Ensure handlers are attached for ChipClicked, CloseClicked, and SelectionChanged to cover main interactive actions.</td></tr><tr><td>Utilize custom event arguments</td><td>Make use of GroupChangedEventArgs and GroupChipStateChangedEventArgs to obtain detailed information on state changes.</td></tr><tr><td>Unsubscribe on disposal</td><td>Implement proper unsubscription from all events when the chip is disposed to prevent memory leaks.</td></tr><tr><td>Test group-related events</td><td>Verify that GroupChanged events are correctly fired and handled when the chip's Group property is modified.</td></tr></tbody></table>

#### FAQ

| Question                                               | Answer                                                                                                                                                                                 |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What does the ChipClicked event do?                    | It is fired when the main body of the chip is clicked, allowing developers to toggle the selection state or trigger custom logic.                                                      |
| How can I detect a change in a chip’s selection state? | The SelectionChanged event notifies you whenever the IsSelected property changes, so you can update related UI elements or logic accordingly.                                          |
| Can I update the chip’s group dynamically?             | Yes, modifying the Group property fires the GroupChanged event, which provides the new group value in the event arguments, enabling dynamic group management.                          |
| Is it necessary to handle the StateChanged event?      | While optional, handling StateChanged can provide additional insights into property changes that affect the chip's appearance, ensuring that the UI stays in sync with the data model. |

***

This extensive documentation for the Events feature provides developers with detailed insights, best practices, and code examples to help integrate and customize the chip control's event-driven behavior in .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/chip-and-group-controls/siticone-groupchip/events.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.