syncfusion-winforms-rating

Implementing Syncfusion WinForms Rating Control

The Rating Control provides an intuitive visual rating experience that allows users to select a number of stars (or other shapes) to represent a rating value. This control is ideal for user feedback, product reviews, quality ratings, and any scenario requiring visual rating input.

When to Use This Skill

Use this skill when the user needs to:

• Star Rating Systems: Product ratings, reviews, user feedback with 1-5 stars
• Custom Rating Shapes: Hearts for favorites, diamonds for quality, circles for simplicity
• Half-Star Ratings: Fine-grained precision (3.5 stars, 4.5 stars) for detailed feedback
• Feedback Forms: Customer satisfaction, service quality, experience ratings
• Review Interfaces: Movie ratings, book reviews, app store ratings
• Rating Display: Show read-only ratings or interactive rating input
• Themed Rating Controls: Office 2007/2010/2016 styles with consistent UI appearance
• Vertical/Horizontal Layouts: Adapt rating orientation to form design

Component Overview

RatingControl (Syncfusion.Windows.Forms.Tools.RatingControl) is a versatile rating input control supporting:

• 6 Built-in Shapes: Star, Circle, Triangle, Heart, Diamond, Kite
• Custom Images: Use your own image assets for unique rating indicators
• Precision Modes: Standard (full shapes) or Half (half-shape granularity)
• Office Themes: Office2007, Office2010, Office2016 (Colorful, DarkGray, White, Black), Metro
• Flexible Orientation: Horizontal or Vertical layout
• Tooltip Support: Display additional information on hover
• Custom Styling: Gradient colors, highlight/selection colors, border customization

Key Namespace: Syncfusion.Windows.Forms.Tools

Assembly: Syncfusion.Tools.Windows.dll (and dependencies)

---

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

When to read: User needs to install, configure, or create their first Rating control.

Topics covered:

• Assembly deployment and NuGet package installation
• Adding Rating control via designer (toolbox)
• Adding Rating control via code
• Setting rating values with the Value property
• Built-in shapes quick overview
• Basic implementation examples

Shapes and Customization

📄 Read: references/shapes-and-customization.md

When to read: User wants built-in shapes (star, heart, circle) or needs custom image-based rating indicators.

Topics covered:

• 6 Built-in shapes: Star, Circle, Triangle, Heart, Diamond, Kite
• Changing shapes with the Shape property
• Custom image shapes using CustomImageCollection
• NormalImage, HoverImage, SelectedImage configuration
• Custom image fallback behavior
• Half-image support for precision modes

Precision and Values

📄 Read: references/precision-and-values.md

When to read: User needs half-star ratings (3.5 stars) or wants to control rating granularity.

Topics covered:

• Precision modes: Standard vs Half
• Half-star/half-shape rating configuration
• Value property for setting and retrieving ratings
• Precision with built-in shapes
• Precision with custom images (requires half-images)
• Rating value ranges and increments

Styling and Appearance

📄 Read: references/styling-and-appearance.md

When to read: User wants Office themes, custom colors, gradient effects, or visual style customization.

Topics covered:

• Visual styles: Default, Office2007, Office2010, Metro
• Office2016 variants: Colorful, DarkGray, White, Black
• OfficeColorScheme property (Blue, Silver, Black)
• Custom gradient coloring with ApplyGradientColors
• ItemHighlight and ItemSelection color properties
• BackColor and BorderColor customization

Orientation and Tooltips

📄 Read: references/orientation-and-tooltips.md

When to read: User needs vertical rating layout or wants tooltips on rating items.

Topics covered:

• Horizontal and Vertical orientation modes
• Orientation property configuration
• Tooltip enablement with ShowTooltip
• Tooltip appearance customization
• Layout considerations for vertical ratings

---

Quick Start Example

Basic Star Rating (5 Stars)

using Syncfusion.Windows.Forms.Tools;

// Create rating control
RatingControl productRating = new RatingControl();
productRating.Location = new Point(20, 20);
productRating.Size = new Size(150, 30);

// Set initial value (3 out of 5 stars)
productRating.Value = 3;

// Add to form
this.Controls.Add(productRating);

Half-Star Precision Rating

// Enable half-star precision
RatingControl preciseRating = new RatingControl();
preciseRating.Precision = PrecisionMode.Half;
preciseRating.Value = 3.5f; // 3.5 stars

Custom Shape (Hearts for Favorites)

// Use heart shapes instead of stars
RatingControl favoriteRating = new RatingControl();
favoriteRating.Shape = Shapes.Heart;
favoriteRating.Value = 4;

Office 2016 Themed Rating

// Apply Office 2016 Colorful theme
RatingControl themedRating = new RatingControl();
themedRating.VisualStyle  = RatingControl.Style.Office2016Colorful;
themedRating.Value = 5;

---

Common Patterns

Product Review Rating (Read-Only Display)

// Display average rating (read-only)
RatingControl avgRating = new RatingControl();
avgRating.Value = 4.5f;
avgRating.Precision = PrecisionMode.Half;
avgRating.Enabled = false; // Read-only

When to use: Displaying aggregated ratings on product listings.

Interactive Feedback Form

// User can select rating
RatingControl feedbackRating = new RatingControl();
feedbackRating.Value = 0; // No initial selection
feedbackRating.Precision = PrecisionMode.Half;

// Handle rating changes
feedbackRating.RatingChanged  += (s, e) => {
    float rating = feedbackRating.Value;
    MessageBox.Show($"User rated: {rating} stars");
};

When to use: Customer feedback forms, surveys, review submission.

Vertical Rating Layout

// Vertical orientation for sidebar layouts
RatingControl verticalRating = new RatingControl();
verticalRating.Orientation = Orientationmode.Vertical;
verticalRating.Size = new Size(50, 200);
verticalRating.Value = 3;

When to use: Sidebar designs, narrow column layouts.

Custom Color Gradient Rating

// Custom gradient colors (green to yellow)
RatingControl customRating = new RatingControl();
customRating.ApplyGradientColors = true;
customRating.ItemHighlightStartColor = Color.Green;
customRating.ItemHighlightEndColor = Color.YellowGreen;
customRating.ItemSelectionStartColor = Color.Gold;
customRating.ItemSelectionEndColor = Color.Orange;
customRating.Value = 4;

When to use: Branded color schemes, matching application themes.

Custom Image Rating

// Use custom images for rating
RatingControl customImageRating = new RatingControl();
customImageRating.Shape = Shapes.CustomImages;

CustomImageCollection images = new CustomImageCollection();
images.NormalImage = Properties.Resources.rating_normal;
images.HoverImage = Properties.Resources.rating_hover;
images.SelectedImage = Properties.Resources.rating_selected;

customImageRating.Images = images;
customImageRating.Value = 3;

When to use: Unique branding, custom icons, non-standard rating indicators.

---

Key Properties

Core Properties

Property	Type	Description	When to Use
Value	float	Current rating value (0 to number of items)	Set/get rating selection
Precision	PrecisionMode	Standard or Half precision	Enable half-star ratings
Shape	Shapes	Star, Circle, Triangle, Heart, Diamond, Kite, CustomImages	Change rating indicator shape
Orientation	Orientationmode	Horizontal or Vertical	Vertical layout for sidebars
ShowTooltip	bool	Enable tooltips on rating items	Show rating values on hover

Styling Properties

Property	Type	Description	When to Use
VisualStyle	RatingControl.Style	Visual style (Office2007/2010/2016, Metro)	Apply Office themes
OfficeColorScheme	OfficeColorSchemes	Blue, Silver, Black color scheme	Office theme color variants
ApplyGradientColors	bool	Enable gradient color properties	Custom gradient effects
ItemHighlightColor	Color	Hover state color	Custom hover appearance
ItemSelectionColor	Color	Selected state color	Custom selection appearance

Custom Image Properties

Property	Type	Description	When to Use
Images	CustomImageCollection	Custom image collection	Use custom rating images
Images.NormalImage	Image	Unselected state image	Custom default appearance
Images.HoverImage	Image	Hover state image	Custom hover appearance
Images.SelectedImage	Image	Selected state image	Custom selected appearance

---

Common Use Cases

1. Product Rating Display

Scenario: E-commerce product listing with average ratings.

• Use Value to display average (e.g., 4.3 stars)
• Set Precision = PrecisionMode.Half for accurate display
• Set Enabled = false for read-only
• Read: precision-and-values.md

2. Customer Feedback Form

Scenario: Service quality rating in feedback form.

• Use Value = 0 for no initial selection
• Handle ValueChanged event to capture user input
• Apply Office2016 theme for professional appearance
• Read: getting-started.md, styling-and-appearance.md

3. Multi-Criteria Rating

Scenario: Rate multiple aspects (Quality, Service, Value).

• Create multiple RatingControl instances
• Use descriptive labels for each rating
• Consistent shape and style across all ratings
• Read: shapes-and-customization.md

4. Favorite/Like System

Scenario: Heart-based favorites (1-5 hearts).

• Set Shape = Shapes.Heart
• Use custom colors for romantic/favorite themes
• Read: shapes-and-customization.md

5. Branded Rating UI

Scenario: Custom images matching brand identity.

• Use Shape = Shapes.CustomImages
• Provide NormalImage, HoverImage, SelectedImage
• Include HalfImages for precision support
• Read: shapes-and-customization.md

6. Vertical Rating Sidebar

Scenario: Sidebar with vertical rating display.

• Set Orientation = Orientationmode.Vertical
• Adjust Size for vertical layout
• Use tooltips for value display
• Read: orientation-and-tooltips.md

---

Events

RatingChanged: Raised when the rating value changes (user interaction).

ratingControl1.RatingChanged  += (sender, e) => {
    float newRating = ratingControl1.Value;
    // Process rating change
};

---

Best Practices

1. Precision for Averages: Use PrecisionMode.Half when displaying aggregated ratings (4.5 stars)
2. Read-Only Display: Set Enabled = false for non-interactive rating displays
3. Consistent Shapes: Use the same shape across related rating controls
4. Tooltips for Clarity: Enable ShowTooltip to show numeric values
5. Custom Images: Provide all image states (Normal, Hover, Selected, HalfNormal, HalfSelected) for complete custom experience
6. Theme Consistency: Match rating style to application theme (Office2016 variants)
7. Value Initialization: Set Value = 0 for new ratings, specific value for defaults

---

See Also

• Syncfusion Rating Control Documentation
• RatingControl API Reference