stsRating

Version 1.0

Sons of Thunder Software, Inc.

Description

The DropTool provides a general purpose rating and choice selection control. It can be used for a "star" rating system, to display a thermometer, or even used in questionnaires to have the user make a selection from a number of choices. The control can be oriented vertically or horizontally, and draw from any origin point (left, right, top, or bottom).

Images that are used with stsRating are called "image sets" because you need to have at least two images. In addition to the image sets that come bundled with the stsRating DropTool, you can also create your own image sets), or just use existing image objects "on-the-fly".

Kind of DropTool

Behavior-based

Interface Support

Unless specifically stated, this control will function properly on all platforms, although its look-and-feel is intended for the platforms listed in the table to the left.

Extra Features

	"About" Stack
	"Inspector" Stack

Screenshots

Left-to-Right Right-to-Left	Top-to-Bottom Bottom-to-Top	Numbered Spheres (Rating Example)	Numbered Spheres (Choice Example)

Other Image Sets

The stsRating DropTool comes with a bunch of image sets that you can use in your projects, which are listed below. If you don't like any of those, you can make your own image set.

Image Set Name	Preview	Notes
Automatically Installed on First Drop
Basic Stars (16px)
Inset Stars (16px)
iTunes Music (13px)		This is what is used for rating music in iTunes.
iTunes Apps (13px)		This is what is used for rating applications in iTunes and the Mac App Store.
Additional Ratings Image Sets
Basic Stars (32px)
Windows Music Player (WMP) Stars (13px)
Hearts (32px)
Hearts (16px)
Hearts (10px)
Blue Sphere (32px)
Blue Sphere (16px)
Red Sphere (32px)
Red Sphere (16px)
Yellow Sphere (32px)
Yellow Sphere (16px)
Specialty Image Sets
Numbered Sphere (32px)
Questionnaire
Thermometer

Usage Notes

It is recommended that you use the stsRating Inspector to set up/manipulate your stsRating control unless you are providing your own images. However to better work with the control, it is important to understand some basic concepts:

Construction

The stsRating control is built as a combination of image and group objects, and is put together in this fashion:

Image Sets, Slots, and Layers

The images that are used to display the front and back of the control are collectively referred to as an "image set", and the number of images that the user sees are called "slots". The images are grouped into two separate layers: the front layer and the back layer. So when the user sees an stsRating control that has five possible stars, there are five slots in the control.

There are a minimum of two images used for an image set - one to represent all the slots in the front layer and one to represent all the slots in the back layer; the stsRating control knows to duplicate these images for each slot in the appropriate layer. This "single image" approach is the most common (in fact all of the image sets installed on the first drag-drop are "single image" image sets).

You are not restricted to one image for each layer, however - you can have a series of different images that can be displayed in a given layer. Here's a comparison of the two (just looking at the front images):

Single Front Image (Duplicated)	Series of Front Images (Unique)

As you can see, there are six total images being used for the "Series" image set - one for all the back slots and one for each front slot. This shows that you can mix-and-match the approach used for each layer: you could have both front and back be single, both of them be series or use one of each. Here's an example of the three different kinds:

Front: Single Image Back: Single Image	Front: Series Back: Series	Front: Series Back: Single Image

You may be wondering: why is the middle example above use a series for the front layer? Since the front layer is just green checkmarks, couldn't the front layer in this case be a single image? You've just hit the "Same Size" rule:

"Same Size" Rule: Regardless of whether you use single images or series, the size of the front image and the size of the back image in a given slot must be the same; you can't have a front image that is 40x20 and a back image that is 41x15 in the same slot. They must both be the same within a slot, but can be different between slots: one slot can be 40x20 and another slot can be 41x15.

So although the front image in the middle example above looks like it's just a green checkmark, it's really a green checkmark in a larger image object that is mostly transparent and matches the dimensions of the "Fair" back image (in this case).

Using a Series of Images

One thing to be aware of though, and that is that if you use an image set that uses a series of images for a given layer, the maximum number of slots that can be displayed will be based on the maximum number of images that are provided for that layer. So in the "series" picture shown above, if there were only five front images provided, the stsRating control could only be set to show from 1 to 5 slots in the control.

If you use an image set that uses series of images for both front and back layers, then the maximum number of slots that can be displayed is controlled by the layer with the smallest number of provided images (so if the back layer had 5 images and the front layer only had 4, the maximum number of slots for the control would be 4).

Using the Inspector

Unless you are providing your own images, you will be using the stsRating Inspector. The Inspector lets you configure your instance of the stsRating control and set the various custom properties that are used by the control:

ImageSets folder:

This field shows that path to the folder that contains your image sets. By default it will be the "(stsRating ImageSets)" folder in the same folder that the stsRating DropTool stack is in, but you can point it elsewhere if you like.

Image Set:

This dropdown menu displays the image set for the currently selected stsRating instance, but you can change the image set you want to use by dropping down the menu:

Image sets that are above the separator line are ones that were installed automatically when you dropped the first instance of an stsRating control onto a stack. Any image sets that are installed have a diamond symbol in front of them. If you want to use one of the other sets, just select it and if it does not have a diamond in front of it, you will be asked if you want to install it. If you say "yes", the image(s) or group(s) are copied to the same place as the other stsRating resources and the selected stsRating control changes to use that image set. The next time you drop down the menu, it will have a diamond in front of the image set you just installed.

If you are having trouble with an image set for some reason and want to reinstall it, or if you had previously installed an image set but no longer need it, you can select that image set from the dropdown menu and the "Remove" button next to it will be enabled. You can then click that button to remove the images. (Make sure you aren't using them in another instance of the control, otherwise you'll end up with an stsRating control that has no front or back images in it!)

Type:

This option menu allows you to set the "type" for the selected stsRating control instance, which can be either "Rating" or "Choice". The "type" affects how the front images are displayed based the current value of the control, which is set by setting the property of the control (for more info on the property, see Public Properties, but for now, just know that if the control displays 4 stars out of 5 then the of the control is "4").

If the control has a "Rating" type, then all of the front images from 1 to its current value are shown; if it is a "Choice" type, then only a single front image is shown, equivalent to the control's value. For example, look at the two controls below. Both have a of "3":

"Rating"	"Choice"

Interactive

This checkbox determines whether the user can click on the control and change its value or not. This defaults to false (display only). (See the notes on the uSTSRating["increment"] and uSTSRating["interactive"] properties for more info.)

Number of Images:

This slider lets you set the number of slots to display, from 1 to 10. The default is 5. (If you want to show more than 10 you can set the of the control to an integer value greater than 1.)

Space between:

This slider lets you set number of pixels of space between the slots in the control, from 1 to 20 pixels. The default is 4 pixels. (If you want a larger gap than 20 pixels you can set the of the control to an integer value greater than 20.)

Orientation:

This option menu lets you pick whether you want to display the control in a horizontal or vertical orientation. The default is "Horizontal". Note that the choice here also affects the "Origin" (see below).

Origin:

This option menu lets you pick the direction from which to draw the slots. If the Orientation is "Horizontal", then your choices here are "Left" or "Right". If the Orientation is "Vertical", your choices are "Top" or "Bottom". The default is "Left".

Creating Your Own Image Set

If you don't want to use any of the supplied image sets, you can "roll your own". To do so you will need to determine if you want to use a single image for your front/back layer(s) or whether you want to use a series of images. Remember that you can make both layers the same kind, or you can have one layer be "single image" and the other layer be "series"; it's up to you.

An image set is composed of an outer group object that encloses either two image objects (for a "single/single" image set), two group objects, each with a series of images (for a "series/series" image set), or one image and one group object (for a "single/series" image set).

The rules are:

1. The outer group can be named whatever you like.
2. The outer group must have a custom prop named
   uSTSRatingType
   with a value of "ImageSet".
3. The outer group must have two additional custom properties -
   uBackObj
   and
   uFrontObj
   - that identify the image or group that will be used for the back and front layers (respectively).
4. The custom properties use the syntax:
   {image|group},shortObjectName
5. The outer group must contain two image objects, two group objects, or one of each.
6. If you have an inner group object, the images it contains must be named the same as the inner group object, plus a number corresponding to its sequence order (starting with "1")
7. You must adhere to the "Same Size" rule for a given slot, otherwise your results will be wonky.

Examples

In the examples below, the red and blue rectangles are just there to indicate inner and outer group relationships and really don't exist in the actual image sets. I'm also using real image sets for the examples, but I'm shortening the object names for clarity.

"Single/Single" Image Set Example

I'm using the "Basic Star (32px)" image set for this example:

Preview	Object Hierarchy	Custom Property	Value
	group "Basic Stars (32px)"	uBackObj	image,BasicStars32-B
		uFrontObj	image,BasicStars32-F
	image "BasicStars32-B"     image "BasicStars32-F"

"Series/Series" Image Set Example

I'm using the "Questionnaire" image set as an example:

Preview	Object Hierarchy	Custom Property	Value
	group "Questionnaire Checkboxes"	uBackObj	group,QACB-B
		uFrontObj	group,QACB-F
	group "QACB-B"         image "QACB-B1"         image "QACB-B2"         image "QACB-B3"         image "QACB-B4"
	group "QACB-F"         image "QACB-F1"         image "QACB-F2"         image "QACB-F3"         image "QACB-F4"

"Series/Single" Image Set Example

I'm using the "Numbered Spheres" image set as an example (the object names are sligh:

Preview	Object Hierarchy	Custom Property	Value
	group "Numbered Spheres (32px)"	uBackObj	image,NumSphere32-B
		uFrontObj	group,NumSphere32-F
	image "NumSphere32-B"
	group "NumSphere32-F"         image "NumSphere32-F1"         image "NumSphere32-F2"         image "NumSphere32-F3"         image "NumSphere32-F4"         image "NumSphere32-F5"

Putting It All Together

To make an image set, you just:

1. Create a brand new stack (it doesn't matter what it's internal name or title is)
2. Import/copy your image(s) onto the card
3. Name and group them according to the rules above
4. Set the
   uFrontObj
   and
   uBackObj
   of the outer group with the proper references to the image/group used for the front and back layers of the image set
5. Set the
   uSTSRatingType
   of the outer group to "ImageSet"
6. Save the stack with whatever name you want to give it

Finally, move it into your Image Sets folder and then open the stsRating Inspector (or close and reopen it if it was already open) and your image set should appear under the "Image Set:" dropdown menu.

One final note: The convention is to include the size of the image used in a single/single image set after the name to help you (and others, if you intend to distribute your image set) get an idea what the size is before actually installing it. So if you use 20x20 images of teddy bears, you may want to name your outer group "Teddy Bears (20px)".

Using Images "On the Fly"

If you don't want to go to the trouble of making your own image set, you can just use existing images or groups of images. To do so, you simply need to set the and of the control to point to the image or group you want to use for the given layer. (See the Public Properties section below for info on what identifiers you can use.)

After you have set those properties, you just need to send the command to the instance of the control and it will redraw using your images.

Custom Properties

Property	Possible Values	Notes
Inspector-Settable Properties
uSTSRating["gapSize"]	An integer	This holds the number of pixels of space to use between slots. The default is 4 pixels.
uSTSRating["interactive"]	"true" or "false"	If this is "true", then the user can click on the control and its uRating will automatically be assigned based on the current increment and where they clicked. The control will be displayed as though the calculated uRating was assigned by script. If this is "false", the control will be used for display purposes only. (This is the default.)
uSTSRating["numImages"]	An integer > 0	This holds the number of images to display in the set. The default is 5.
uSTSRating["orientation"]	Either "horizontal" or "vertical"	This is the orientation of the images displayed in the control. The default is "horizontal".
uSTSRating["origin"]	One of: "left", "right", "top", "bottom"	This is where to star "filling" the control. If the uSTSRating["orientation"] is "horizontal", you can only assign "left" or "right" (any other value is treated as "left"). If the uSTSRating["orientation"] is "vertical" then you can only assign "top" or "bottom" (any other value is treated as "top").
uSTSRating["type"]	Either "rating" or "choice"	This determines whether the control shows all of the front images from 0 through the current uRating value ("rating") or whether to show only the front image that corressponds to the uRating value in the control ("choice"). The default is "rating". For example, if you're showing stars in the control, the uRating of the control was "3", and the uSTSRating["type"] was "rating", the front images for stars #1, #2, and #3 would be shown; if it was "choice" then only the front image for star #3 would be shown.
Private Properties (Not exposed through the Inspector)
uSTSRating["imageHeight"]	An integer	This holds the height value to be used for both front and back images in the image set. This is normally not set; it is calculated based on the provided image objects.
uSTSRating["imageWidth"]	An integer	This holds the width value to be used for both front and back images in the image set. This is normally not set; it is calculated based on the provided image objects.
uSTSRating["increment"]	0 > n <= 1	This value indicates how the assigned uRating is rounded and represented. For example, if the uSTSRating["increment"] is "0.25" and the control is assigned a uRating of "2.3", it will be rounded to "2.25". All rounding is down to the closest increment. This defaults to a value of "1".
Internal Properties (For internal use only, but documented for completeness)
uSTSRating["imageSet"]	The name of an installed imageSet	This is set and used by the stsRating Inspector only to keep track of what image set was assigned to the control.
Public Properties
uRating	A number >= 0	This determines how many of the front images to show in the control to make it appear "filled in". When the value is assigned, it is automatically rounded down to the nearest number that corresponds to the control's uSTSRating["increment"] value, and affected by the uSTSRating["type"] of the control. For example if the uSTSRating["increment"] of the control was "0.5", and the uSTSRating["type"] of the control was "rating", then attempting to set the uRating of the control to "2.9" would actually set the value to "2.5" and show 2 and a half of the front images (e.g. "2 1/2 stars").
uSTSRating["backImage"]	The short ID of an image object The short name of an image object The long id of an image object The long id of a group object	If you choose to assign either a short ID or short name of an image object, that image object must reside on the same card as the control, otherwise use a long id to the image object (or better yet, use the DropTools_TruncID function to assign a "truncated id" to make it more portable). If you assign an image object, it will be used for every instance of the "back" image in the control. If you assign a group object, it will be treated like a "series" and should hold all of the properly-named images to display as "back" images.
uSTSRating["frontImage"]	The short ID of an image object The short name of an image object The long id of an image object The long id of a group object	This is the same as uSTSRating["backImage"] , except that it applies to the "front" images.

Commands/Functions

These commands must be "sent" to the instance of the control or triggered from the script of the control itself.

Command	Parameters	Notes
stsRating_Init	(none)	Redraws the control using the existing custom property values assigned to it.

Version History

Version	Release Date	What's Changed
1.0	07-16-2011	First public version.