Siticone Rating Control

The SiticoneRating control is a highly customizable, interactive rating component for Windows Forms. It supports extensive visual styling, custom shapes (hearts, thumbs up, etc.), smooth animations, and precision rating (including half-stars). Designed for modern UIs, it allows users to provide feedback, vote, or display scores with ease.

Core Values & Behavior

Properties that control the fundamental data and interaction model of the rating control.

Property	Type	Description & Usage Example
`Rating`	float	rating.Rating = 4.5f; The current value of the rating. Must be between 0 and `StarCount`. Setting this property triggers an animation to the new value.
`StarCount`	int	rating.StarCount = 5; The total number of rating symbols (stars) to display.
`AllowHalfStars`	bool	rating.AllowHalfStars = true; If true, users can select half-steps (e.g., 3.5). If false, ratings snap to whole numbers.
`ReadOnly`	bool	rating.ReadOnly = true; When true, the control displays the rating but does not accept mouse or keyboard input. Useful for displaying aggregate scores.

Appearance & Styling

Customize the visual presentation of the rating symbols, including colors, shapes, and custom images.

Property	Type	Description & Usage Example
`StarColor`	Color	rating.StarColor = Color.Gold; The fill color for the "active" or filled portion of the stars.
`EmptyColor`	Color	rating.EmptyColor = Color.LightGray; The color used for the unfilled background of the stars.
`HoverColor`	Color	rating.HoverColor = Color.Orange; The color applied dynamically when the mouse pointer hovers over the control.
`StarShape`	StarShapeType	rating.StarShape = StarShapeType.Heart; Selects the geometric shape to draw. Options: `Star`, `Heart`, `ThumbUp`, `Circle`, `Square`.
`StarImage`	Image	rating.StarImage = Properties.Resources.CustomIcon; If set, this custom image is used instead of the vector shapes defined by `StarShape`.
`FocusCueEnabled`	bool	rating.FocusCueEnabled = true; Draws a focus rectangle around the control when it has input focus.
`FocusCueColor`	Color	rating.FocusCueColor = Color.Blue; The color of the focus rectangle.

Layout & Responsive

Properties that control the sizing and positioning of the rating symbols.

Property	Type	Description & Usage Example
`StarSize`	float	rating.StarSize = 30f; The diameter/size of each individual symbol in pixels.
`StarSpacing`	float	rating.StarSpacing = 5f; The gap in pixels between adjacent symbols.

Animation

Controls the smooth transitions when the rating value changes.

Property	Type	Description & Usage Example
`AnimationDuration`	int	rating.AnimationDuration = 300; The time in milliseconds for the rating fill animation to complete.
`AnimationSteps`	int	rating.AnimationSteps = 30; The number of frames/steps used in the animation. Higher values are smoother but consume more CPU.
`AnimationEasing`	AnimationEase	rating.AnimationEasing = AnimationEase.Bounce; The mathematical easing function for the transition. Options: `Linear`, `EaseIn`, `EaseOut`, `EaseInOut`, `Bounce`.
`CustomEasingFunction`	Func<float,float>	rating.CustomEasingFunction = (t) => t * t * t; Allows providing a custom C# function to calculate animation progress, overriding the built-in enum.

The control features a built-in right-click context menu. These properties determine which options are available to the end-user at runtime.

Property	Type	Description & Usage Example
`AllowUserToSetNumberOfStars`	bool	rating.AllowUserToSetNumberOfStars = true; Adds a context menu option for the user to change the `StarCount` at runtime.
`AllowUserToChangeStarColor`	bool	rating.AllowUserToChangeStarColor = true; Allows the user to pick a new `StarColor` via a color dialog.
`AllowUserToChangeHoverColor`	bool	rating.AllowUserToChangeHoverColor = true; Allows the user to pick a new `HoverColor` via a color dialog.
`AllowUserToChangeEmptyColor`	bool	rating.AllowUserToChangeEmptyColor = true; Allows the user to pick a new `EmptyColor` via a color dialog.

Events

Hooks for responding to user actions.

Events Wiring

// RatingChanged Event
// Fires whenever the Rating property changes, either by user click or programmatic assignment.
ratingControl.RatingChanged += (s, e) => 
{
                Console.WriteLine($"Rating changed from {e.OldValue} to {e.NewValue}");
    
                // Update a label or database
    lblScore.Text = e.NewValue.ToString("F1");
};

Designer & Smart Tags

The SiticoneRating control offers a robust Smart Tag menu for rapid configuration within Visual Studio.

Feature Description

Feature	Description
`Theme Presets`	Instantly apply pre-configured visual styles: Default Gold Stars: Classic yellow stars (Default). Material Blue: Modern blue styling with focus cues. Modern Red: Vibrant red theme with ease-in-out animation. Pink Hearts: Sets shape to Heart with pink palette and bounce animation. Green Circles / Purple Squares: Geometric shapes with flat colors. Teal Thumbs Up: Like/Dislike style using the ThumbUp shape. High Contrast: Accessible Black/White theme.
`Copy/Paste Settings`	Easily copy the entire configuration of one rating control and paste it onto another instance.

Theme Presets

Instantly apply pre-configured visual styles:

Default Gold Stars: Classic yellow stars (Default).
Material Blue: Modern blue styling with focus cues.
Modern Red: Vibrant red theme with ease-in-out animation.
Pink Hearts: Sets shape to Heart with pink palette and bounce animation.
Green Circles / Purple Squares: Geometric shapes with flat colors.
Teal Thumbs Up: Like/Dislike style using the ThumbUp shape.
High Contrast: Accessible Black/White theme.

Copy/Paste Settings Easily copy the entire configuration of one rating control and paste it onto another instance.

Detailed Usage Examples

Example 1: Basic Product Rating

Standard setup for a product review system allowing half-star precision.

C# - Basic Setup

private void SetupProductReview()
{
    ratingProduct.StarCount = 5;
    ratingProduct.AllowHalfStars = true;
    ratingProduct.Rating = 0f;
    
                // Visuals
    ratingProduct.StarColor = Color.Gold;
    ratingProduct.EmptyColor = Color.LightGray;
    ratingProduct.HoverColor = Color.Orange;
    
                // Handle user input
    ratingProduct.RatingChanged += (s, e) => 
    {
                MessageBox.Show($"You rated this product {e.NewValue} stars!");
    };
}

Example 2: "Love It" Heart Animation

Using the Heart shape and Bounce easing for a playful "Like" interaction.

C# - Custom Shape & Animation

private void SetupLoveMeter()
{
    ratingLove.StarShape = SiticoneRating.StarShapeType.Heart;
    ratingLove.StarCount = 5;
    
                // Colors
    ratingLove.StarColor = Color.HotPink;
    ratingLove.HoverColor = Color.DeepPink;
    ratingLove.EmptyColor = Color.FromArgb(255, 200, 200);
    
                // Bouncy Animation
    ratingLove.AnimationDuration = 600;
    ratingLove.AnimationEasing = SiticoneRating.AnimationEase.Bounce;
    
                // Larger Size
    ratingLove.StarSize = 40f;
    ratingLove.StarSpacing = 10f;
}

Example 3: Read-Only Dashboard Display

Displaying an aggregate score (e.g., 4.7) on a dashboard where user interaction is disabled.

C# - Read-Only Display

private void DisplayAverageScore(float averageScore)
{
    ratingDisplay.ReadOnly = true;
    ratingDisplay.AllowHalfStars = true; // Allows precise display like 4.5
    
                // Set the value (Animation still plays by default)
    ratingDisplay.Rating = averageScore;
    
                // Optional: Disable animation for instant update
                // ratingDisplay.AnimationDuration = 0; 
    
                // Accessible colors
    ratingDisplay.StarColor = Color.Teal;
    ratingDisplay.EmptyColor = Color.WhiteSmoke;
}