Winwheel.js class reference: Winwheel


The Winwheel class contains the bulk of the properties and methods for creating prize wheels.


The properties of a Winwheel are normally set in the JSON structure passed to the object at time of its creation. See tutorial #2 Constructor Parameters for an example.


One of Winwheel.js features is you can add any additional properties you require to the Winwheel object because anything included in the JSON structure not a property of the wheel will be added as such. This may come in handy for advanced developers.



Properties


Note that many segment properties can be specified globally for all segments here on the parent wheel object, or may be set individually for each segment when defining them. An example of when you might want to set a segment property globally is the font family and size, and an example of when you might want to specify a segment's property individually is the fillStyle.


The properties listed the table below can be passed in to the constructor of the Winwheel object via the JSON structure (as seen in example below) and once the wheel has been created be accessed and altered via the dot operator e.g theWheel.fillStyle = 'aqua';

<script>
	var theWheel = new Winwheel({
		'canvasId'       : 'myCanvas',
		'numSegments'    : 12,
		'innerRadius'	 : 50,
		'fillStyle'      : '#e7706f',
		'lineWidth'      : 3.
		'textFontFamily' : 'Verdana',
		'textFontSize'   : 30
    });
</script>

Name Description Default
canvasId Id of the canvas which the wheel is to draw on to. If you give your canvas the id of 'canvas' the wheel code will use it automatically as that is the default.

See tutorial #2 Constructor Parameters for an example.
canvas
centerX X position of the center of the wheel. The default is null which causes the wheel to be placed in center of the canvas. The 0,0 position of the canvas is the top-left.

See tutorial #8 Wheel Radius and Center Point for an example.
null
centerY Y position of the center of the wheel. Default is null causing the wheel to be positioned in the center of the canvas.

See tutorial #8 Wheel Radius and Center Point for an example.
null
outerRadius The radius of the wheel from the center. If left null it will be set to the radius from the center of the canvas to its shortest side so the wheel fills the canvas.

See tutorial #8 Wheel Radius and Center Point for an example.
null
innerRadius Used to create hollow wheels (doughnuts). The larger the value the more hollow space inside the wheel.

See tutorial #8 Wheel Radius and Center Point for an example.
0
numSegments The number of segments the wheel is to have. In order for a wheel to be rendered it needs to have at least one segment.

See tutorial #3 Constructor Parameters for an example.
1
drawMode Specifies how the wheel is to be drawn. There is are 3 options 'code' where the wheel is created out of code drawn segments, 'image' where a single graphically rich image is used for the face of the wheel, and 'segmentImage' where a image can be used for each segment.

See tutorial #9 Creating a Wheel with an Image for an example.

See tutorial #17 Creating a Wheel with one Image per segment for an example.
code
rotationAngle The angle the wheel is rotated. The rotation angle is the property changed during spinning animations though you can set the rotation angle at any time including specifying this in the parameters passed to the constructor.

See tutorial #10 Prize Pointers and Wheel Backgrounds for an example.
0
textFontFamily Named font to be used in rendering the segment text. E.g. 'Verdana', 'Arial'.

See tutorial #7 Colours, Lines, and Fonts for an example.
Arial
textFontSize Size of the font in pixels. Value must be numeric, don't include 'px' on the end.

See tutorial #7 Colours, Lines, and Fonts for an example.
20
textFontWeight Named or numeric font weight such as 'bold', 'normal', 300.

See tutorial #7 Colours, Lines, and Fonts for an example.
bold
textOrientation The orientation of the text within the segments. Valid options are 'horizontal', 'vertical', 'curved'.

See tutorial #6 Text Alignment and Orientation for an example.
horizontal
textAlignment Alignment of the text within the segments. Options are 'inner', 'outer', 'center'.

See tutorial #6 Text Alignment and Orientation for an example.
center
textDirection Sets the direction of the text within the segments. Options are 'normal' and 'reversed'.

See tutorial #6 Text Alignment and Orientation for an example.
normal
textMargin Margin between the inner or outer of the wheel (depends on textAlignment). If the value is left null some is added by default based on the font size to push the text away from edge of wheel. If you don't want any specify 0.

See tutorial #6 Text Alignment and Orientation for an example.
null
textFillStyle Fill colour or style for the text. Can be any valid HTML5 fill style including solid colours, colours with alpha, or even gradients.

See tutorial #7 Colours, Lines, and Fonts for an example.
black
textStrokeStyle Line colour or style for the text. Can be any valid HTML5 stroke style. Line width must also be > 0 in order for lines to be rendered.

See tutorial #7 Colours, Lines, and Fonts for an example.
null
textLineWidth Numeric width of the lines around text in pixels. Do not include 'px' in the value. Note that even though this defaults to 1, textStrokeStyle must be specified before lines around text will be rendered.

See tutorial #7 Colours, Lines, and Fonts for an example.
1
fillStyle The fill colour or style for all segments of the wheel unless specified for a particular segment (which overrides global value).

See tutorial #7 Colours, Lines, and Fonts for an example.
sliver
strokeStyle The line colour or style for all segments of the wheel unless specified for a particular segment (which overrides global value).

See tutorial #7 Colours, Lines, and Fonts for an example.
black
lineWidth The width of lines around the segments. Specify 0 if you don't want lines.

See tutorial #7 Colours, Lines, and Fonts for an example.
1
clearTheCanvas When set to true the canvas on which the wheel is rendered is cleared before the wheel is drawn. Set to false if you are drawing other things on the canvas before the wheel is rendered otherwise what you have drawn will be wiped.

See tutorial #12 Animation - More Details for an example.
true
imageOverlay If set to true when the wheel has drawMode of image, the outline of the segments will be displayed over top of the image. Does nothing in code drawMode. Useful for when creating wheels using a image to ensure where the code thinks the segments are lines up with the graphic.

See tutorial #9 Creating a Wheel with an Image for an example.
false
drawText Controls if the text for segments is rendered. The default is true when creating code-drawn wheels (drawMode = code), but the default is false when drawMode is image or segmentImage.

See tutorial #9 Creating a Wheel with an Image for an example.
true for code wheels, false for image wheels
pointerAngle Angle around the wheel 0-360 where the prize pointer is located. You need to specify this to match where the pointer is displayed if you want to use the Winwheel feature which gets the prize pointed to when the spinning stops, or any other feature reliant on knowing where the thing which indicates the prize is.

See tutorial #13 Getting the segment (prize) pointed to for an example.
0 (so at the top / 12 o'clock position)
wheelImage Must be set to the image data of the image to be used for the face of wheel when trying to create a wheel using graphically rich images (drawMode = image)..

See tutorial #9 Creating a Wheel with an Image for an example.
null
imageDirection Used when creating wheels with one image per segment. Specifies globally what direction the segment image is orientated in which is important for the code to draw the wheel correctly. Valid values are N, S, E, W (Noth, South, East West).

See tutorial #17 Creating a Wheel with one Image per segment for an example.
N
segments Array of segment objects. Starts at 1 not 0 to avoid confusion when talking about (and accessing) particular segments. You can use this to access and manipulate the segments of a wheel after it has been created, for example: myWheel.segments[3].fillStyle = 'aqua';

See tutorial #13 Getting the segment (prize) pointed to for an example of using this property to change the colour of segments to help indicate the prize won.

Refer to the Segment class reference for details about an individual segment object.

See tutorial #3 Segment Colour and Text for how to specify the segments of the wheel at time of construction.
array of Segment objects
animation If an animation has been specified for the wheel then this property will be an instance of the Animation class. You can use this property to change properties of the animation after the wheel has been created, for example myWheel.animation.easing = 'power3.easeOut';

See the Animation class reference for details of Animation object.

See tutorial #11 Animation Introduction and Spinning Basics for how to specify the animation for the wheel in the JSON passed to the constructor.
Animation object
pointerGuide The pointer guide is a helpful little object which if specified draws a line out from the center of the wheel to where the code of the wheel thinks the prize pointer is. The location of the pointer is specified using the pointerAngle property of the wheel.

Useful during development or debugging to ensure location of the pointer in the code matches the location of it seen in any wheel background or other thing on the canvas used to indicate the prize.

Refer to the Pointer Guide class reference for details of the pointer guide object.

See tutorial #13 Getting the segment (prize) pointed to for an example of using the Pointer Guide.
PointerGuide object
Pins The pins are an optional visual element of the wheel, allowing you to create small circles around the outer of the wheel to represent the pins/pegs seen on may real life prize wheels.

To turn the pins on and use the default options just specify "pins: true" in the parameters sent to the Winwheel constructor.

If you want to control the number of pins, color, radius etc then see the Pins class reference for the properties that you can specify for the pins in the JSON parameters passed to the Winwheel constructor, rather than just setting Pins to true.

Refer to the Pin class reference for details of the Pin object.

See tutorial #18 Displaying Pins for an example.
Pin object



Methods


Constructor

Creates an object of the Winwheel class.

	var myWheel = new Winwheel(JSON options, boolean drawWheel=true);

Parameter Description Default
options JSON structure containing the properties of the wheel and sub-objects such as all the segments and the animation. Refer to list of Winwheel properties above.
drawWheel Controls if the wheel is drawn at time of creation on the canvas. Set to false to prevent this. true

See tutorial #2 Constructor Parameters for an example of passing the options.


addSegment

This function allows a new segment to be added to the wheel properly at the specified position in the segments array (default is at the end). The properties of the new segment can be passed in via the options JSON structure.

	var newSegment = myWheel.addSegment(JOSN options, int position=null);

Parameter Description Default
options JSON structure of properties for the segment just like those passed to the Winwheel constructor when specifying the segments.
position Position in the Winwheel.segments array the segment is to be added at. The default is at the end of the wheel so the new segment appears after the currently last segment. If another value is specified the new segment will be interested in to that location in the segments array after the existing ones are moved along to make a gap. Note the segments array starts at 1, not 0, so to put a segment first specify 1 as the location. The end of the wheel

Returns: a reference to the newly created segment object.


See tutorial #5 Adding and Removing Segments for an example.


clearCanvas

Completely clears the canvas the wheel is drawn on. Used internally to clear the canvas before the wheel is rendered on if the clearTheCanvas property is set to true.

	myWheel.clearCanvas();

computeAnimation

Called from the startAnimation() function before the animation is started to compute a number of properties based on the animation type specified.

	myWheel.computeAnimation();

degToRad

Helper function used internally to convert from degrees to radians during drawing.

	var radians = myWheel.degToRad(float d);

Parameter Description Default
d Value in degrees.

Returns: a number.


deleteSegment

Use this function to delete a segment from the wheel at the specified position in the Wheel's segments array. This function takes care up updating a number of things under the hood once the segment is removed.

	myWheel.deleteSegment(int position=null);

Parameter Description Default
position Position in the wheel's segments array to be deleted. Remember the segments array of the wheel starts at 1 not 0. The last segment

See tutorial #5 Adding and Removing Segments for an example.


draw

Draws the wheel on the canvas. You will need to call this to render any changes to the wheel after it has been created.

	myWheel.draw(boolean clearTheCanvas=true);

Parameter Description Default
clearTheCanvas When called manually if you don't want the canvas cleared pass false. When called internally the clearTheCanvas parameter is passed the value from the Winwheel.clearTheCanvas property. true

See tutorial #4 Altering Segment Properties for an example.


drawPointerGuide

Draws the pointer guide line on the canvas from the center of the wheel out to the edge at the angle specified in the Winwheel.pointerAngle property. Used during development and debugging to ensure the pointerAngle lines up with the visuals of any prize pointer.


Called internally from the wheel's draw function when the Winwheel.pointerGuide.display property is set to true. Can also be called manually after the creation of the wheel to display the pointer guide.

	myWheel.drawPointerGuide();

See tutorial #13 Getting the segment (prize) pointed to for more about the pointer guide.


drawSegments

Called from the draw() function of the wheel when drawMode = 'code' (the default) to draw all of the segments which make up the wheel. Loops through the segments array of the Winwheel and uses html canvas functions to draw lines and arcs to create the shapes and fill them.


If specified, uses the properties of the segment to draw it, or falls back to global values.

	myWheel.drawSegments();

drawSegmentText

Called from the draw() function of the wheel to draw the text in the segments. Segment text can be displayed when wheel is made of code drawn segments or a graphically rich image. The drawText property of the wheel controls if this function is called from the draw() function of the wheel.


If specified, uses the properties of the segment to draw the text, or falls back to global values.

	myWheel.drawSegmentText();

drawWheelImage

Called from the draw() function of the wheel when the wheel is rendered using a graphically rich image (drawMode = 'image').

	myWheel.drawWheelImage();

getIndicatedSegment

Returns a reference to the segment pointed to / indicated by the prize pointer (well actually just where the pointerAngle is). Useful after a spinning animation has stopped to get the prize indicated by the prize pointer so you can inform the user of what they have won, perhaps even do some further animation.

	var segment = myWheel.getIndicatedSegment();

See tutorial #13 Getting the segment (prize) pointed to for an example.


getIndicatedSegmentNumber

Similar to the above but returns the number / position of the segment in the wheel's .segments array of the indicated segment.

	var segmentNumber = myWheel.getIndicatedSegmentNumber();

See tutorial #13 Getting the segment (prize) pointed to for an example.


getRandomForSegment

Calculates and returns a random stop angle inside the specified segment of the wheel.

	var angle = myWheel.getRandomForSegment(int segmentNumber);

Parameter Description Default
segmentNumber The number / position of the segment in the Wheel's .segments array the random angle should be computed for.

See tutorial #14 Setting the Prize to be won before spinning for an example.


getRotationPosition

Returns the rotation angle of the wheel corrected to 0-360 (i.e. removes all the multiples of 360). Used in the the feature which works out the segment pointed to when the spinning has stopped.

	var angle = myWheel.getRotationPosition();

getSegmentAt

Returns a reference to the segment located at the specified x and y position or null if there is no segment located there. Can be used in conjunction with a click event to get the segment a user clicked.

	var segment = myWheel.getSegmentAt(int x, int y);

Parameter Description Default
x X coordinate of the mouse.
y Y coordinate of the mouse.

Returns: a reference to a segment object if one was found at that location, otherwise null.


See tutorial #15 Getting the segment clicked for an example.


getSegmentNumberAt

Similar to the above but only returns the number / position of the found segment in the Wheel's .segments array, if one was infact found.

	var segmentNumber = myWheel.getSegmentNumberAt(int x, int y);

Parameter Description Default
x X coordinate of the mouse.
y Y coordinate of the mouse.

Returns: if a segment was found at the x,y its position in the segments array of the wheel. Null if no segment found.


See tutorial #15 Getting the segment clicked for an example.


pauseAnimation

Pauses the Tween animation. Animations can then be resumed by calling resumeAnimation().

	myWheel.pauseAnimation();

See tutorial #12 Animation - More Details for an example.


resumeAnimation

Resumes a paused animation.

	myWheel.resumeAnimation();

See tutorial #12 Animation - More Details for an example.


setCanvasId

This function must be called if you want to change the canvas that the wheel is to be drawn on after the Winwheel object has been created. This function updates the .canvas and 2D context .ctx properties of the wheel to the new canvas so when .draw() is called the wheel draws on the different canvas.

	myWheel.setCanvasId(int canvasId);

Parameter Description Default
canvasId Id of the canvas DOM element on the page the wheel is to use for drawing.


setCenter

This function sets the center location of the wheel, saves a line of code as don't have to set the .centerX and then the .centerY properties of the wheel individually.

	myWheel.setCenter(int x, int y);

Parameter Description Default
x X coordinate, updates the centerX of the wheel.
y Y coordinate, updates the centerY of the wheel.

See tutorial #8 Wheel Radius and Center Point for an example.


startAnimation

Begins the animation by first computing any needed animation properties and configuring the GreenSock Tween, then sets the animation going.

	myWheel.startAnimation();

See tutorial #12 Animation - More Details for an example.


stopAnimation

Stops the animation, then if a callbackFinished function is specified calls that provided it is allowed to callback.

	myWheel.stopAnimation(boolean canCallback=true);

Parameter Description Default
canCallback If set to false then the code won't call the function specified as the callbackFinished on the animation. true

See tutorial #12 Animation - More Details for an example.


updateSegmentSizes

Works out the segment sizes so that unless there is a set size for a segment it gets a equal share of the 360 degrees (or less if there is some segments with set sizes) which makes up the wheel.


This function is called automatically in the Winwheel constructor and also from the addSegment() and deleteSegment() functions of the wheel to maintain the complete circle.


Only time you may ever need to call this function is if animating a segments size so the others in the wheel adjust appropriately.

	myWheel.updateSegmentSizes();

windowToCanvas

Used internally to work out where on the canvas the user's mouse is when an event such as a click happens. Converts the clientX and clientY from the event in to coordinates on the canvas which can then be used, for example, to work out which segment the user clicked inside of.

	var loc = myWheel.windowToCanvas(int x, int y);

Parameter Description Default
x X coordinate of the mouse.
y Y coordinate of the mouse.

Returns: an object containing an x and y property.



Previous:
< Documentation index
Next:
Segment Class Reference >