# FTRRating ## Overview `FTRRating` is a Windows Forms star-rating control provided by FTR Controls. It allows users to select and display ratings using a configurable number of stars and fractional rating values. The control supports mouse interaction, hover preview, keyboard navigation, read-only display, RTL layouts, and integration with the FTR Controls theme system. The control is available in the `FTRControls` namespace and inherits from `FTRControls.BaseClasses.FTRBaseControl`. ### Key Features * Star-based rating input * Fractional ratings * Configurable star count * Configurable star size and spacing * Hover preview * Read-only mode * Keyboard navigation * Right-to-left (RTL) support * Theme integration * `ValueChanged` event * Premium features protected by the FTR Controls license --- ## Adding FTRRating to a Windows Forms Application After adding the FTR Controls assembly to your project: 1. Add a reference to the FTR Controls assembly. 2. Build the project. 3. Open the Windows Forms Designer. 4. Locate **FTR Controls** in the Toolbox. 5. Drag **FTRRating** onto your form. 6. Configure the control through the Properties window. The default property of the control is `Value`. The default event is `ValueChanged`. --- # Properties ## Value **Type:** `float` **Default:** `0` Gets or sets the currently selected rating. The value is automatically constrained between `0` and `StarCount`. The value is also rounded to the nearest configured `RatingStep`. For example, with the default `RatingStep` of `0.25`: ```csharp rating.Value = 3.67f; ``` The resulting value is rounded to the nearest valid step. You can also clear the rating by setting: ```csharp rating.Value = 0f; ``` ### Example ```csharp var rating = new FTRRating(); rating.Value = 4f; ``` --- ## StarCount **Type:** `int` **Default:** `5` **License:** Premium when changed from the default value Specifies the total number of stars displayed by the control. The default configuration uses five stars. Changing `StarCount` from `5` requires an active FTR Controls license. ### Example ```csharp rating.StarCount = 10; ``` If the required license is not available, the control does not apply the requested non-default value and displays the FTR Controls activation prompt. If `StarCount` is reduced below the current rating, the current `Value` is automatically adjusted so that it does not exceed the new maximum. --- ## StarSize **Type:** `int` **Default:** `30` Specifies the width and height of each star in pixels. The minimum value is `10`. ### Example ```csharp rating.StarSize = 40; ``` Increasing `StarSize` also increases the overall size of the control. --- ## Spacing **Type:** `int` **Default:** `5` Specifies the spacing, in pixels, between adjacent stars. The minimum value is `0`. ### Example ```csharp rating.Spacing = 8; ``` --- ## RatingStep **Type:** `float` **Default:** `0.25` **License:** Premium when changed from the default value Specifies the precision used for rating values. The default step is `0.25`, which allows values such as: * `0` * `0.25` * `0.5` * `0.75` * `1` * `1.25` * and so on up to the configured `StarCount`. The control limits the configured step to a maximum of `1.0`. Changing `RatingStep` from the default `0.25` requires an active FTR Controls license. ### Example ```csharp rating.RatingStep = 0.5f; ``` This allows half-star increments. For example: ```text 0 0.5 1 1.5 2 2.5 ... ``` ### Important The control does not restrict the licensed value to only `0.5` or `1.0`. A licensed application can use other positive step values up to `1.0`. --- ## ReadOnly **Type:** `bool` **Default:** `false` Determines whether the rating can be changed by the user. When `ReadOnly` is `true`: * Mouse interaction does not change the rating. * Hover preview is disabled. * Keyboard interaction does not change the rating. * The current value is displayed without an interactive hover state. ### Example ```csharp rating.ReadOnly = true; ``` This is useful when the control is being used to display an existing rating rather than collect user input. --- ## StarColor **Type:** `Color` Specifies the color used for selected stars during normal display. This property can be used to customize the appearance of the control. ### Example ```csharp rating.StarColor = Color.Gold; ``` --- ## HoverColor **Type:** `Color` Specifies the color used for the rating preview while the mouse is hovering over the control. ### Example ```csharp rating.HoverColor = Color.Orange; ``` --- ## EmptyStarColor **Type:** `Color` Specifies the color used for unselected portions of the stars. ### Example ```csharp rating.EmptyStarColor = Color.LightGray; ``` --- # User Interaction ## Mouse Interaction When the control is interactive, the user can move the mouse across the stars to preview a rating. The preview follows the configured `RatingStep`. For example, with: ```csharp rating.RatingStep = 0.5f; ``` the user can preview: ```text 0.5, 1.0, 1.5, 2.0, ... ``` Clicking the control selects the currently previewed rating. The control uses the `Hand` cursor while the user is interacting with it. If `ReadOnly` is enabled, mouse interaction does not change the rating. --- # Keyboard Navigation `FTRRating` supports keyboard interaction when the control has focus. ### Left Arrow Decreases the rating by one `RatingStep`. ### Right Arrow Increases the rating by one `RatingStep`. ### Home Sets the rating to: ```text 0 ``` ### End Sets the rating to the maximum value: ```text StarCount ``` ### Space Increases the rating by one `RatingStep`. The value is capped at `StarCount`. --- # Right-to-Left (RTL) Support The control supports Windows Forms `RightToLeft` behavior. When: ```csharp rating.RightToLeft = RightToLeft.Yes; ``` the visual order and keyboard direction are adjusted for RTL usage. For example, the Left and Right arrow keys operate according to the RTL direction of the control. This makes the control suitable for applications using languages such as Arabic or Hebrew. --- # Events ## ValueChanged Raised whenever the selected rating value changes. The event is useful when the application needs to save, validate, display, or otherwise react to the user's rating. ### Example ```csharp var rating = new FTRRating(); rating.ValueChanged += (_, _) => { SaveRating(rating.Value); }; ``` The event is raised when `Value` actually changes. For example: ```csharp rating.Value = 4f; ``` will raise the event if the previous value was different from `4`. --- # Theme Integration `FTRRating` integrates with the FTR Controls theme system. The control provides an `ApplyTheme()` method that applies the colors associated with the currently selected FTR theme. The control supports the following theme modes: * Dark * Light * Color * Duotone ### Example ```csharp rating.ApplyTheme(); ``` In a normal FTR Controls application, the control can use the application's current FTR theme colors. If your application changes the FTR Controls theme at runtime, call `ApplyTheme()` when the rating control needs to refresh its colors. --- # Common Usage Scenarios ## Collecting a User Rating ```csharp var rating = new FTRRating { Value = 0f, RatingStep = 0.5f }; rating.ValueChanged += (_, _) => { var selectedRating = rating.Value; SaveRating(selectedRating); }; ``` This configuration provides half-star increments and saves the rating whenever the user changes it. --- ## Displaying an Existing Rating For display-only scenarios: ```csharp var rating = new FTRRating { Value = 4.5f, ReadOnly = true }; ``` The control displays the rating without allowing the user to modify it. --- ## Using a Custom Number of Stars A licensed application can configure a different number of stars: ```csharp var rating = new FTRRating { StarCount = 10, Value = 8f }; ``` Changing `StarCount` from the default value of `5` requires an active FTR Controls license. --- ## Customizing Appearance ```csharp var rating = new FTRRating { StarSize = 36, Spacing = 6, StarColor = Color.Gold, HoverColor = Color.Orange, EmptyStarColor = Color.LightGray }; ``` --- # Recommended Configuration For a standard five-star customer rating: ```csharp var rating = new FTRRating { Value = 0f, RatingStep = 0.5f, ReadOnly = false }; ``` For displaying an existing rating: ```csharp var rating = new FTRRating { Value = 4.5f, ReadOnly = true }; ``` --- # Licensing FTRRating includes premium functionality. By default, the control uses: ```text StarCount = 5 RatingStep = 0.25 ``` These default values can be used without changing the premium configuration. The following changes require an active FTR Controls license: * Changing `StarCount` from `5` * Changing `RatingStep` from `0.25` If a premium property is changed without a valid license, the control invokes the FTR Controls activation flow and does not apply the requested premium configuration. For licensing and activation instructions, refer to the FTR Controls licensing documentation supplied with the product. --- # Property Summary | Property | Type | Default | License Required | Purpose | | ---------------- | ------- | ------------: | --------------------------- | ------------------------- | | `Value` | `float` | `0` | No | Current rating | | `StarCount` | `int` | `5` | Yes, when changed from 5 | Number of stars | | `StarSize` | `int` | `30` | No | Star dimensions in pixels | | `Spacing` | `int` | `5` | No | Space between stars | | `RatingStep` | `float` | `0.25` | Yes, when changed from 0.25 | Rating precision | | `ReadOnly` | `bool` | `false` | No | Disables user interaction | | `StarColor` | `Color` | Theme-defined | No | Selected-star color | | `HoverColor` | `Color` | Theme-defined | No | Hover-preview color | | `EmptyStarColor` | `Color` | Theme-defined | No | Unselected-star color | --- # Event Summary | Event | Description | | -------------- | --------------------------------------- | | `ValueChanged` | Raised when the selected rating changes | --- # Supported Interaction | Interaction | Supported | | --------------------- | --------- | | Mouse hover preview | Yes | | Mouse selection | Yes | | Fractional ratings | Yes | | Keyboard navigation | Yes | | Home / End navigation | Yes | | Space key increment | Yes | | RTL layout | Yes | | Read-only display | Yes | | FTR theme integration | Yes | --- # Important Notes * `Value` is always constrained to the range `0` through `StarCount`. * `Value` is rounded according to `RatingStep`. * `StarSize` cannot be less than `10`. * `Spacing` cannot be less than `0`. * `RatingStep` cannot be greater than `1.0`. * `StarCount` cannot be less than `1`. * Changing `StarCount` from the default `5` requires a license. * Changing `RatingStep` from the default `0.25` requires a license. * `ReadOnly = true` disables interactive rating changes. * The control automatically updates its size when `StarCount`, `StarSize`, or `Spacing` changes. * The control supports both left-to-right and right-to-left layouts.