The Morfik Rating package contains a single widget (Rating) that allows users to select the number of stars that represents their rating .
A Quick Walkthrough
To use the Morfik Rating package simply add the package to the project by utilizing the “Used Packages” command on the project ribbon (see Figure 1 Used Packages Command), or simply drag the package file onto the application main client area.
|Figure 1: Used Packages Command|
Once added a single widget (Rating) will appear on the home ribbon when the form designer is active (see Figure 2 Widgets List). This widget can be placed on an application form and provide immediate functionality with minimal coding.
|Figure 2: Widget list|
How to Use the Widget
After dropping a Rating widget on a form, you can use the Property Manager to configure the widget. Figure 3 Default Widget with Value Three shows the appearance of the widget when it is dropped on a form and has the Value property set to 3. Initially the widget displays 5 stars and the stars are continuously filled in from left to right, but many of the properties of the widget can be used to change its display and functionality. These properties are discussed below.
|Figure 3: Default Widget with Value Three|
Important Widget Properties
|Color||Determines the background color of the widget. The default value is None.|
|Data Field||If the form is assigned a Data Source, this property will determine the data field that is bound to the widget. Care must be taken that the data field be of an appropriate type to store the values returned by the widget which may be Integers or Floating Point Numbers, which is determined by the Precision property.|
|Direction||If the Direction is set to Standard the lower values will coincide with the left or top star positions and the higher values with the right or bottom positions. Setting the Direction to Reversed will associate the lower values with the right or bottom star positions. The default value is Standard.|
|Items||Each of the stars can be provided a caption by entering a line in the Items string list, with the first star corresponding to the first item in the list. The item caption is passed in the Events for the widgets discussed below and used if the property Show Value Hint is set to True.|
|Name||The unique name of the widget.|
|Orientation||If set to Horizontal, the default, the stars will be displayed left to right in a horizontal row. If changed to Vertical the stars will be arranged in a vertical column top to bottom. The display is also affected by the Direction property above.|
|Precision||The Precision property specifies whether or not parts of stars can be used and what types of numbers can be assigned to the Value property. In the default Whole Item, only whole stars can be selected and only Integer Values can be used. Switching to Half an Item allows whole and half stars to be selected and Double Values to be used. With Exact Precision selected any portion of any star can be selected and Double Values can be used.|
|Read Only||If this property is set to True the user cannot interact with the widget and change its Value.|
|Selection Mode||When Continuous mode is chosen, once a star or part of a star is selected, all preceding stars will be filled in depending on the Direction property. If the other available mode of Single is chosen, only the star or part of the star selected will be filled in. The default is Continuous.|
|Show Value Hint||When set to True the Caption from the Items list corresponding to the star below the cursor is displayed as a hint.|
|Star Count||The Star Count is an Integer that specifies the number of stars that are displayed in the widget. Setting this property to or from a large value can create a delay in the widget displaying the correct number. Also, the number should be at least 2.|
|Value||Sets or returns the current numeric value for the widget and corresponds to the number of stars or parts of stars filled in in the widget. If a Data Field is assigned the Value will come from the Data Source and can be updated using standard database procedure such as SubmitPage.|
|OnRated||This event fires when the Value property is changed at run time and occurs before the widget is redrawn. A TRating object (see below) is passed as a parameter.|
|OnRating||This event fires when the Value property is changed at run time and occurs after the widget is redrawn. A TRating object (see below) is passed as a parameter.|
|OnSelect||This event fires when the cursor moves over one of the stars in the widget and also when the cursor leaves the widget. A TRating object (see below) is passed as a parameter.|
The TRating Object
The TRating object is a simple class that has only two properties: a String Caption property and a Double Value property. The Caption will be set to the corresponding string in the Items property where the first string in the list corresponds to the first star. If there is no corresponding Item, a null string is returned. The Value property will be the same as the current Value property of the widget.
|Note:||The Values property of the widget can be set and runtime and the widget will repaint itself correctly.|