# Behavior Customization

## Overview

The Behavior Customization feature provides properties that control the interaction model of the rating control. Developers can enable half-star ratings, toggle the control’s read-only mode, and configure right-click context menu options for end-user interactions. This flexibility allows the rating control to behave appropriately in different scenarios, whether for simple display or interactive feedback collection.

***

### Key Points

<table><thead><tr><th width="290">Aspect</th><th>Description</th></tr></thead><tbody><tr><td>AllowHalfStars</td><td>Enables or disables half-star increments when users interact with the control.</td></tr><tr><td>ReadOnly</td><td>Sets the control to a non-interactive state, preventing user input while still displaying ratings.</td></tr><tr><td>AllowUserToSetNumberOfStars</td><td>Allows end users to modify the number of stars via the right-click context menu.</td></tr><tr><td>AllowUserToChangeStarColor</td><td>Permits users to change the filled star color through the context menu.</td></tr><tr><td>AllowUserToChangeHoverColor</td><td>Permits users to modify the hover color for stars via the context menu.</td></tr><tr><td>AllowUserToChangeEmptyColor</td><td>Allows users to change the color of empty stars using the context menu.</td></tr></tbody></table>

***

### Best Practices

<table><thead><tr><th width="231">Area</th><th>Guidance</th></tr></thead><tbody><tr><td>Enabling Half-Star Input</td><td>Use <code>AllowHalfStars</code> when a more granular rating is desired; otherwise, disable for simplicity.</td></tr><tr><td>Read-Only Mode</td><td>Set <code>ReadOnly</code> to true for scenarios where ratings should be displayed without user modification (e.g., in reports).</td></tr><tr><td>Context Menu Options</td><td>Enable context menu options only if user interaction to change settings is required; otherwise, disable to avoid confusion.</td></tr><tr><td>Consistent Behavior</td><td>Maintain consistent behavior across the application by appropriately configuring these properties.</td></tr></tbody></table>

***

### Common Pitfalls

<table><thead><tr><th width="290">Issue</th><th>Description</th></tr></thead><tbody><tr><td>Unexpected Rating Changes</td><td>Failing to set <code>ReadOnly</code> when needed can result in accidental rating changes during user interactions.</td></tr><tr><td>Overcomplicating User Interface</td><td>Enabling too many context menu options (e.g., changing star color, hover color, number of stars) may confuse end users.</td></tr><tr><td>Inconsistent Interaction Models</td><td>Mixing half-star and full-star ratings without clear visual cues can lead to user frustration and misinterpretation.</td></tr><tr><td>Neglecting Event Subscriptions</td><td>Not properly handling events like <code>RatingChanged</code> can lead to incomplete integration of user behavior into business logic.</td></tr></tbody></table>

***

### Usage Scenarios

<table><thead><tr><th width="299">Scenario</th><th>Explanation</th></tr></thead><tbody><tr><td>Interactive Feedback Forms</td><td>Enable half-star ratings and context menu options to allow users to provide detailed feedback on services or products.</td></tr><tr><td>Display-Only Rating Widgets</td><td>Set <code>ReadOnly</code> to true to present ratings without allowing user modification, ideal for review summaries.</td></tr><tr><td>Customizable Rating Interfaces</td><td>Use context menu options to let advanced users change the number of stars or modify colors, providing a personalized experience.</td></tr><tr><td>Educational or Demo Applications</td><td>Enable interactive features to demonstrate rating behavior, such as half-star selections and on-the-fly color changes.</td></tr></tbody></table>

***

### Real Life Usage Scenarios

<table><thead><tr><th width="267">Scenario</th><th>Description</th></tr></thead><tbody><tr><td>Product Review Sites</td><td>Allow users to rate products with half-star increments and adjust their ratings easily while preventing accidental changes by setting read-only mode when necessary.</td></tr><tr><td>Restaurant Rating Apps</td><td>Enable context menu options for users to customize the display (e.g., star color) during interactive review sessions.</td></tr><tr><td>Corporate Feedback Systems</td><td>Use the read-only mode in finalized reports to display ratings without enabling further modifications by end users.</td></tr><tr><td>Interactive Demos</td><td>Utilize the behavior customization properties to create dynamic demos that allow real-time modification of rating parameters for training purposes.</td></tr></tbody></table>

***

### Code Examples

Below are several code examples demonstrating how to integrate and use the Behavior Customization features.

#### Example 1: Enabling Half-Star Ratings and Read-Only Mode

```csharp
using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace SampleRatingApp
{
    public class MainForm : Form
    {
        public MainForm()
        {
            // Create and configure the rating control for interactive use
            var ratingControl = new SiticoneRating
            {
                AllowHalfStars = true,  // Enable half-star increments
                ReadOnly = false,       // Allow user modifications
                Location = new System.Drawing.Point(10, 10)
            };

            // Subscribe to the RatingChanged event to handle changes
            ratingControl.RatingChanged += (sender, e) =>
            {
                MessageBox.Show($"Rating changed from {e.OldValue} to {e.NewValue}");
            };

            Controls.Add(ratingControl);

            // Example of setting the control to read-only after initialization
            // ratingControl.ReadOnly = true;
        }

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

#### Example 2: Configuring Right-Click Context Menu Options

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

namespace SampleRatingApp
{
    public class MainForm : Form
    {
        public MainForm()
        {
            // Create the rating control and enable context menu options for customization
            var ratingControl = new SiticoneRating
            {
                AllowHalfStars = true,
                ReadOnly = false,
                AllowUserToSetNumberOfStars = true,  // Enable changing star count via context menu
                AllowUserToChangeStarColor = true,    // Enable changing filled star color
                AllowUserToChangeHoverColor = true,   // Enable changing hover color
                AllowUserToChangeEmptyColor = true,   // Enable changing empty star color
                Location = new Point(10, 10)
            };

            // The context menu is automatically initialized when these properties are set
            Controls.Add(ratingControl);
        }

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

#### Example 3: Combining Multiple Behavior Customizations

```csharp
using System;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

namespace SampleRatingApp
{
    public class MainForm : Form
    {
        public MainForm()
        {
            // Create and configure the rating control with combined behavior customizations
            var ratingControl = new SiticoneRating
            {
                AllowHalfStars = true,
                ReadOnly = false,
                AllowUserToSetNumberOfStars = true,
                AllowUserToChangeStarColor = true,
                AllowUserToChangeHoverColor = false,  // Disable hover color change if not desired
                AllowUserToChangeEmptyColor = true,
                Location = new System.Drawing.Point(20, 20)
            };

            // Attach an event handler to update another UI element when rating changes
            ratingControl.RatingChanged += (sender, e) =>
            {
                Console.WriteLine($"Rating updated: {e.NewValue}");
            };

            Controls.Add(ratingControl);
        }

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

***

### Troubleshooting Tips

<table><thead><tr><th width="289">Issue</th><th>Troubleshooting Steps</th></tr></thead><tbody><tr><td>Accidental Rating Changes</td><td>If users change ratings unintentionally, set <code>ReadOnly</code> to true when the rating should not be modified.</td></tr><tr><td>Inconsistent Rating Increments</td><td>Verify that <code>AllowHalfStars</code> is set appropriately to enable half-star increments; disable if full stars are required.</td></tr><tr><td>Context Menu Not Appearing</td><td>Ensure that at least one of the context menu-related properties (<code>AllowUserToSetNumberOfStars</code>, <code>AllowUserToChangeStarColor</code>, <code>AllowUserToChangeHoverColor</code>, <code>AllowUserToChangeEmptyColor</code>) is enabled.</td></tr><tr><td>Event Handlers Not Firing</td><td>Confirm that the event subscription for <code>RatingChanged</code> is correctly implemented and not unsubscribed prematurely.</td></tr></tbody></table>

***

### Review

The Behavior Customization feature provides critical control over how users interact with the rating control, ensuring that the component can be tailored to suit both interactive and display-only scenarios.

<table><thead><tr><th width="145">Aspect</th><th>Review Comment</th></tr></thead><tbody><tr><td>Interactivity</td><td>Enables detailed control over user input, including half-star selection and context menu-based changes.</td></tr><tr><td>Flexibility</td><td>Offers multiple properties to fine-tune the user experience, allowing for both interactive and non-interactive modes.</td></tr><tr><td>Integration</td><td>Easy to integrate with event handling to update application logic based on user interactions.</td></tr><tr><td>Usability</td><td>Enhances usability by providing clear control over how ratings are input and modified by end users.</td></tr></tbody></table>

***

### Summary

The Behavior Customization feature enables developers to fine-tune the interactive elements of the rating control. Through properties such as `AllowHalfStars`, `ReadOnly`, and various context menu options, the control can be configured to behave in a manner that best fits the application’s requirements, ensuring both flexibility and a user-friendly experience.

<table><thead><tr><th width="216">Summary Aspect</th><th>Details</th></tr></thead><tbody><tr><td>Core Behavior</td><td>Control user input and interactivity via properties like <code>AllowHalfStars</code> and <code>ReadOnly</code>.</td></tr><tr><td>Context Menu Options</td><td>Enable or disable context menu options to let end users customize aspects of the rating control at runtime.</td></tr><tr><td>Integration Ease</td><td>Simple property settings and event subscriptions facilitate seamless integration into diverse applications.</td></tr><tr><td>Enhanced Usability</td><td>Provides a customizable interactive experience that adapts to various usage scenarios.</td></tr></tbody></table>

***

### Additional Useful Sections

#### Integration Checklist

<table><thead><tr><th width="306">Checklist Item</th><th>Status/Action Required</th></tr></thead><tbody><tr><td>Enable Correct Input Mode</td><td>Set <code>AllowHalfStars</code> based on desired rating precision.</td></tr><tr><td>Configure Read-Only Status</td><td>Toggle <code>ReadOnly</code> as needed for display-only or interactive scenarios.</td></tr><tr><td>Verify Context Menu Settings</td><td>Enable context menu properties only if user customization is intended.</td></tr><tr><td>Subscribe to RatingChanged Event</td><td>Attach event handlers to update application logic on rating changes.</td></tr></tbody></table>

#### FAQ

| Question                                            | Answer                                                                                                                     |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| How do I allow half-star ratings?                   | Set the `AllowHalfStars` property to true to enable half-star increments.                                                  |
| How can I prevent users from changing the rating?   | Set the `ReadOnly` property to true to display the rating without allowing modifications.                                  |
| How do I enable the context menu options?           | Enable properties such as `AllowUserToSetNumberOfStars`, `AllowUserToChangeStarColor`, etc., to show context menu options. |
| What event should I handle to track rating changes? | Subscribe to the `RatingChanged` event to receive notifications whenever the rating value is updated.                      |

***

This comprehensive documentation should assist developers in effectively integrating and customizing the Behavior Customization features of the rating control to create interactive, user-friendly applications that meet a variety of requirements.
