Behavior Customization

This feature enables developers to modify the interactive behavior of the rating control, including how users input ratings and how the control responds to various input events.

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

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

---

Best Practices

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

---

Common Pitfalls

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

---

Usage Scenarios

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

---

Real Life Usage Scenarios

Scenario	Description
Product Review Sites	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.
Restaurant Rating Apps	Enable context menu options for users to customize the display (e.g., star color) during interactive review sessions.
Corporate Feedback Systems	Use the read-only mode in finalized reports to display ratings without enabling further modifications by end users.
Interactive Demos	Utilize the behavior customization properties to create dynamic demos that allow real-time modification of rating parameters for training purposes.

---

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

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

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

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

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

---

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.

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

---

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.

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

---

Additional Useful Sections

Integration Checklist

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

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.