TRating

Source: source/classes/trating.prg

Inherits from: TControl

TRating is an interactive star-rating control that allows users to select a rating value by clicking on star images. It supports hover preview, click-to-set, half-star display, and configurable maximum values. The control uses three image states (empty, half, full) to render the visual rating.

Key DATA Members

DATA	Type	Default	Description
`nImages`	Numeric	`5`	Number of rating images/stars to display
`nCurrentValue`	Numeric	`0`	Current hover/preview value
`nSelectedValue`	Numeric	`0`	Last clicked (committed) value
`nPercentual`	Numeric	`100`	Maximum value for percentage calculation
`bChanged`	Block		Codeblock executed when rating changes (receives new value)
`bSetGet`	Block		SetGet codeblock for variable binding (read/write)
`lBorder`	Logical	`.F.`	Show border around the control
`nClrBorder`	Numeric		Border color

Methods

Method	Description
`New( nRow, nCol, oWnd, nWidth, nHeight, nRating, cEmptyImg, cHalfImg, cFullImg, lBorder, nClrBorder, nBackColor, lDesign, nInitialValue, nMaxValue, bChanged, bSetGet )`	Create a new TRating control
`SetValue( x )`	Set the rating value programmatically. If x is omitted, resets to 0.
`Reset()`	Reset the rating to 0 (calls SetValue() with no argument)
`Display()`	Begin paint, render, end paint
`Paint()`	Render the rating stars based on current and selected values
`MouseMove( nRow, nCol, nKeyFlags )`	Handle hover: update `nCurrentValue` for visual preview
`MouseLeave( nRow, nCol, nKeyFlags )`	Handle mouse leave: restore display to committed value
`LButtonUp( nRow, nCol, nKeyFlags, lTouch )`	Handle click: commit the hovered value and fire `bChanged`
`Destroy()`	Destroy the control and free image handles

Example: 5-Star Rating Control

#include "FiveWin.ch"

function Main()

   local oWnd, oRating, nRating := 0

   DEFINE WINDOW oWnd TITLE "Rate this App" SIZE 400, 250

   @ 60, 40 RATING oRating ;
      RATING 5 ;
      EMPTY   "star_empty.bmp" ;
      HALF    "star_half.bmp"  ;
      FULL    "star_full.bmp"  ;
      OF oWnd ;
      MAX 100 ;
      INITIAL 0 ;
      CHANGE ( nRating := oRating:nSelectedValue, ;
               oWnd:SetText( "Rating: " + Str( nRating ) ) )

   @ 140, 40 SAY "Click a star to rate" ;
      SIZE 200, 20 OF oWnd

   @ 180, 40 BUTTON "Reset" SIZE 60, 25 OF oWnd ;
      ACTION oRating:Reset()

   ACTIVATE WINDOW oWnd CENTERED

return nil

Notes

The RATING command requires three bitmap images for the three visual states: EMPTY (unselected), HALF (half-filled), and FULL (fully selected).
nRating specifies the number of star images displayed (e.g., 5 for a 5-star rating). MAX sets the maximum numeric value (default 100), and the control maps the visual position to a proportional value.
The CHANGE codeblock receives no parameter; read oRating:nSelectedValue inside the block to get the current rating.
Use bSetGet to bind the rating to a variable or database field. The codeblock is evaluated on creation to read the initial value and on click to write the new value.
Hover behavior is handled automatically: MouseMove updates nCurrentValue for real-time visual feedback, and MouseLeave restores the display to nSelectedValue.
The nPercentual data member controls the scaling factor. With the default of 100, clicking the last star sets the value to 100. Adjust this for different rating scales.

TRating

Key DATA Members

Methods

Example: 5-Star Rating Control

Notes

See Also