# Selection Markers and Indicator Customization

## Overview

This feature enables the control to display a visual indicator—a left-side bar—that highlights the currently selected button. The properties `ShowLeftIndicator`, `IndicatorWidth`, `IndicatorColor`, and `IndicatorGradientColor` allow for extensive customization of the indicator’s appearance. Whether using a solid color or a gradient effect, the indicator provides immediate, clear feedback on the control's selection state. This documentation outlines the configuration, best practices, usage scenarios, and troubleshooting tips for implementing selection markers in your .NET WinForms applications.

***

### Properties and Configuration

The table below summarizes the key properties related to Selection Markers and Indicator Customization:

| Property Name          | Description                                                                                              | Default Value / Range       | Sample Usage Example                                             |
| ---------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------- |
| ShowLeftIndicator      | Determines whether a selection indicator bar is displayed on the left side of the control when selected. | Boolean (default is false)  | `myButton.ShowLeftIndicator = true;`                             |
| IndicatorWidth         | Specifies the width of the selection indicator bar; typically a value between 0 and 8 pixels.            | 0–8 (default is 4)          | `myButton.IndicatorWidth = 4;`                                   |
| IndicatorColor         | Sets the primary color of the selection indicator bar.                                                   | Color.FromArgb(0, 123, 255) | `myButton.IndicatorColor = Color.FromArgb(0, 123, 255);`         |
| IndicatorGradientColor | Sets the secondary gradient color used for a gradient effect on the selection indicator bar.             | Color.FromArgb(0, 183, 255) | `myButton.IndicatorGradientColor = Color.FromArgb(0, 183, 255);` |

***

### Key Points

<table><thead><tr><th width="290">Key Point</th><th>Details</th></tr></thead><tbody><tr><td>Visual Feedback</td><td>The indicator bar provides a clear visual cue that a button is selected, enhancing the overall navigation and usability of the interface.</td></tr><tr><td>Customizable Appearance</td><td>Developers can adjust the indicator's width, primary color, and gradient color to match the application’s design scheme.</td></tr><tr><td>Dynamic Behavior</td><td>The indicator appears only when the control is selected or during the selection animation, ensuring a responsive user experience.</td></tr><tr><td>Integrated with State Changes</td><td>The indicator seamlessly integrates with other interactive states (such as hover and press), reinforcing visual consistency.</td></tr></tbody></table>

***

### Best Practices

| Best Practice                  | Description                                                                                                                                       | Example Code Snippet                                                                                                  |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Enable Only for Key Controls   | Use selection indicators on controls that require strong visual feedback to highlight the active element, rather than on every control in the UI. | `csharp<br>if(isPrimaryAction)<br>{<br> myButton.ShowLeftIndicator = true;<br>}<br>`                                  |
| Match Indicator with Theme     | Ensure that the chosen `IndicatorColor` and `IndicatorGradientColor` align with your overall color scheme to provide a consistent look and feel.  | `csharp<br>myButton.IndicatorColor = theme.PrimaryColor;<br>myButton.IndicatorGradientColor = theme.AccentColor;<br>` |
| Test Different IndicatorWidths | Experiment with different `IndicatorWidth` values to find the optimal balance between visibility and space utilization.                           | `csharp<br>myButton.IndicatorWidth = 6;<br>`                                                                          |

***

### Common Pitfalls

| Pitfall                                    | Description                                                                                                                  | How to Avoid                                                                                                   |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Overuse of Indicators                      | Displaying the indicator on every button can clutter the interface and reduce its effectiveness as a selection cue.          | Reserve indicators for key or grouped controls where selection is critical.                                    |
| Inadequate Contrast                        | Using indicator colors that do not contrast well with the control’s background can make the indicator hard to notice.        | Choose colors for `IndicatorColor` and `IndicatorGradientColor` that offer clear contrast with the background. |
| Misaligned Indicator Due to Padding Issues | Custom adjustments to the control’s padding may affect the placement of the indicator, resulting in a misaligned appearance. | Test indicator positioning after any layout or padding modifications.                                          |

***

### Usage Scenarios

| Scenario                 | Description                                                                                                                        | Sample Integration Code                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Navigation Menus         | Use the indicator to highlight the active menu item in a sidebar or toolbar, ensuring users know which section they are viewing.   | `csharp<br>// Creating a menu button with a left indicator<br>SiticoneGroupButton menuButton = new SiticoneGroupButton();<br>menuButton.Text = "Dashboard";<br>menuButton.ShowLeftIndicator = true;<br>menuButton.IndicatorWidth = 4;<br>menuButton.IndicatorColor = Color.FromArgb(0, 123, 255);<br>menuButton.IndicatorGradientColor = Color.FromArgb(0, 183, 255);<br>this.Controls.Add(menuButton);<br>`                             |
| Grouped Option Selectors | In forms where only one option can be selected at a time, the indicator clearly marks the active selection among multiple buttons. | `csharp<br>// Grouping option buttons<br>SiticoneGroupButton option1 = new SiticoneGroupButton();<br>SiticoneGroupButton option2 = new SiticoneGroupButton();<br>option1.Text = "Option 1";<br>option2.Text = "Option 2";<br>option1.ShowLeftIndicator = true;<br>option2.ShowLeftIndicator = true;<br>option1.IsSelected = true; // This will activate the indicator<br>this.Controls.Add(option1);<br>this.Controls.Add(option2);<br>` |

***

### Real Life Usage Scenarios

| Real Life Scenario   | Description                                                                                                                                       | Example Implementation                                                                                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dashboard Navigation | In enterprise dashboards, using a selection indicator helps users quickly identify the active module or section, streamlining navigation.         | `csharp<br>if(userNavigates)<br>{<br> dashboardButton.ShowLeftIndicator = true;<br> dashboardButton.IndicatorColor = Color.Green;<br> dashboardButton.IndicatorGradientColor = Color.LightGreen;<br>}<br>` |
| Settings Panels      | When multiple settings categories are displayed, the indicator can denote which category is currently active, improving usability in complex UIs. | `csharp<br>settingsButton.ShowLeftIndicator = true;<br>settingsButton.IndicatorWidth = 5;<br>settingsButton.IndicatorColor = Color.Purple;<br>`                                                            |

***

### Troubleshooting Tips

| Issue                        | Potential Cause                                                                                                  | Resolution                                                                                               |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Indicator Not Appearing      | The `ShowLeftIndicator` property may not be enabled or the control is not in a selected state.                   | Ensure that `ShowLeftIndicator` is set to true and that `IsSelected` is properly updated.                |
| Misaligned Indicator         | Incorrect `IndicatorWidth` or padding settings may cause the indicator to appear offset.                         | Adjust the `IndicatorWidth` and verify the control's padding and layout settings to align the indicator. |
| Inconsistent Gradient Effect | Improper values for `IndicatorColor` and `IndicatorGradientColor` can lead to a non-uniform gradient appearance. | Test and adjust the colors to ensure a smooth gradient transition across the indicator area.             |

***

### Integration Code Sample

The following example demonstrates how to integrate Selection Markers and Indicator Customization into a simple WinForms application:

```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Make sure the correct namespace is referenced

public class MainForm : Form
{
    public MainForm()
    {
        // Initialize and configure a SiticoneGroupButton with selection marker customization
        SiticoneGroupButton indicatorButton = new SiticoneGroupButton
        {
            Text = "Profile",
            Size = new Size(220, 50),
            Location = new Point(20, 20),
            // Enable the left-side selection indicator
            ShowLeftIndicator = true,
            IndicatorWidth = 4,
            IndicatorColor = Color.FromArgb(0, 123, 255),
            IndicatorGradientColor = Color.FromArgb(0, 183, 255),
            // Set other interactive properties
            NormalColor = Color.FromArgb(100, 100, 100),
            HoverColor = Color.FromArgb(80, 80, 80),
            PressColor = Color.FromArgb(50, 50, 50),
            TextColor = Color.LightGray,
            SelectedTextColor = Color.White,
            IsSelected = false  // Set to true when selection is required
        };

        // Set the button to selected on click to show the indicator
        indicatorButton.Click += (sender, e) =>
        {
            indicatorButton.IsSelected = true;
        };

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

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

***

### Review

<table><thead><tr><th width="308">Review Aspect</th><th>Details</th></tr></thead><tbody><tr><td>Visual Clarity</td><td>The indicator provides an immediate visual cue for the selected state, enhancing overall usability in navigation and grouped selections.</td></tr><tr><td>Ease of Customization</td><td>With simple property assignments, developers can quickly tailor the indicator's appearance to match the design requirements of their application.</td></tr><tr><td>Integration with Interactive States</td><td>The indicator works seamlessly with other interactive properties, ensuring that state transitions (selection, hover, press) are visually coherent.</td></tr><tr><td>Performance</td><td>The drawing and animation routines for the indicator are optimized to minimize performance overhead, even on resource-constrained devices.</td></tr></tbody></table>

***

### Summary

<table><thead><tr><th width="279">Summary Point</th><th>Description</th></tr></thead><tbody><tr><td>Enhanced Selection Feedback</td><td>The selection marker clearly indicates the active control, providing users with intuitive navigation cues.</td></tr><tr><td>Flexible Customization</td><td>Developers can easily customize the indicator’s width, primary color, and gradient effect to achieve the desired visual impact.</td></tr><tr><td>Seamless Integration</td><td>The indicator integrates naturally with the control’s other interactive states, ensuring a unified look and feel across the application.</td></tr><tr><td>Optimized User Experience</td><td>By offering clear, dynamic visual feedback on selection, this feature enhances usability and contributes to a more engaging user interface.</td></tr></tbody></table>

***

### Additional Useful Sections

#### Frequently Asked Questions (FAQ)

| Question                                      | Answer                                                                                                                               |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| How do I enable the selection indicator?      | Set `ShowLeftIndicator` to true to display the indicator when the control is selected.                                               |
| Can I change the indicator colors at runtime? | Yes, you can update `IndicatorColor` and `IndicatorGradientColor` dynamically to reflect theme changes or user preferences.          |
| What if the indicator does not appear?        | Verify that `IsSelected` is set to true when needed and check that the control’s layout does not override the indicator positioning. |

#### Integration Checklist

<table><thead><tr><th width="290">Checklist Item</th><th>Status</th></tr></thead><tbody><tr><td>Enable Selection Indicator</td><td>Confirm that <code>ShowLeftIndicator</code> is set to true for the desired controls.</td></tr><tr><td>Configure Indicator Appearance</td><td>Ensure <code>IndicatorWidth</code>, <code>IndicatorColor</code>, and <code>IndicatorGradientColor</code> are set to match your UI design.</td></tr><tr><td>Test Group Selection Behavior</td><td>Validate that only one control in a group shows the selection indicator when selected.</td></tr><tr><td>Verify Layout Alignment</td><td>Check that the indicator is properly aligned with the control’s edge across different screen sizes and resolutions.</td></tr><tr><td>Test Dynamic Updates</td><td>Ensure that updating selection properties at runtime reflects immediately in the UI.</td></tr></tbody></table>

***

By following this comprehensive documentation for Selection Markers and Indicator Customization, developers can integrate clear and attractive selection indicators into their .NET WinForms applications, thereby improving navigation, focus, and overall user experience.