User Guide

Overview

The wijradialgauge widget allows you to create common radial gauges, including dials and speedometers. Use simple options to customize their start and sweep angles, tick marks, ranges, and pointer. The image below illustrates several main elements that allow you to customize the appearance and behavior of the gauge:

You'll see descriptions and examples of each of these elements in the following documentation.

NOTE: Please check the Version History for an outline of new features, improvements, and changes to the Wijmo widgets.

Markup and Scripting

Markup for a wijradialgauge looks like this:

<div id="gauge"></div>

The following script initializes the wijradialgauge widget:

<script type="text/javascript">
        $(document).ready(function () {
            $("#gauge").wijradialgauge({
                value: 100,
                max: 150,
                min: 0,
                startAngle: -45,
                sweepAngle: 270,
                radius: "auto",
                islogarithmic: false,
                origin: {
                    x: 0.5, y: 0.5
                },
                labels: {
                    offset: 27, //4F6B82
                    style: {
                        fill: "#1E395B",
                        "font-size": 12,
                        "font-weight": "800"
                    }
                },
                tickMinor: {
                    position: "inside",
                    offset: 30,
                    style: {
                        "height": 3,
                        "width": 10,
                        fill: "#1E395B",
                        stroke: "#E7EFF8"
                    },
                    interval: 5,
                    visible: true
                },
                tickMajor: {
                    position: "inside",
                    offset: 27,
                    style: {
                        fill: "#1E395B",
                        "height": 4,
                        "width": 20,
                        stroke: "#E7EFF8",
                        "stroke-width": "1.5"
                    },
                    interval: 25,
                    visible: true
                },
                ranges: [
				{
				    startWidth: 2,
				    endWidth: 5,
				    startValue: 0,
				    endValue: 10,
				    startDistance: 1,
				    endDistance: 0.98,
				    style: {
				        fill: "#7BA0CC",
				        stroke: "#7BA0CC",
				        "stroke-width": "0"
				    }
				},
				{
				    startWidth: 5,
				    endWidth: 20,
				    startValue: 10,
				    endValue: 125,
				    startDistance: 0.98,
				    endDistance: 0.9,
				    style: {
				        fill: "0-#B4D5F0-#B4D5F0",
				        stroke: "#FFFFFF",
				        "stroke-width": "0"
				    }
				},
                {
                    startWidth: 20,
                    endWidth: 25,
                    startValue: 125,
                    endValue: 150,
                    startDistance: 0.9,
                    endDistance: 0.86,
                    style: {
                        fill: "#7BA0CC",
                        stroke: "#7BA0CC",
                        "stroke-width": "0"
                    }
                }
                ],
                face: {
                    style: {

                        fill: "r(0.9, 0.60)#FFFFFF-#D9E3F0",
                        stroke: "#7BA0CC",
                        "stroke-width": "4"
                    }
                },
                pointer: {
                    length: 0.8,
                    offset: 0,
                    shape: "rect",
                    width: 6,
                    style: {
                        fill: "#1E395B",
                        stroke: "#1E395B"
                    }
                },
                cap: {
                    radius: 10,
                    style: {
                        fill: "#1E395B",
                        stroke: "#1E395B"
                    }
                }
            });
        });	
    </script>

The markup and script featured here results in the following:

Quick Start

This quick start helps you to create a Web page, add the wijradialgauge widget, and customize the appearance and behavior of the widget.

1. In Notepad, to create a new HTML page, add the following code and save the document with an .html extension.

   <!DOCTYPE HTML>
   <HTML>
   <head>
   </head>
   <body>
   </body>
   </HTML>
   

2. To reference the latest dependencies from the CDN, see http://wijmo.com/downloads/#wijmo-cdn. Add them to your HTML page within the <head> tags. For example:

   <!--jQuery References-->
   <script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script>
   <script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
    
   <!--Theme-->
   <link href="http://cdn.wijmo.com/themes/aristo/jquery-wijmo.css" rel="stylesheet" type="text/css" />
    
   <!--Wijmo Widgets CSS-->
   <link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css" rel="stylesheet" type="text/css" />
    
   <!--Wijmo Widgets JavaScript-->
   <script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script>
   <script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>
   
   

   This adds jQuery and Wijmo references as well as theme and CSS links.

3. Within the <body> tags, add markup like the following.

   <div id="radialgauge1"></div>
   

   The <div> element creates the RadialGauge widget; its id option is set to 'radialgauge1', which we call in the jQuery script to initialize the widget.
4. Within the <head> tags, below the references, add the following script to initialize the jQuery widget.

       <script type="text/javascript">
           $(document).ready(function () { 
               $("#radialgauge1").wijradialgauge({ 
                   value: 180, 
                   max: 200, 
                   min: 0, 
                   ranges: [{ 
                       startWidth: 20, 
                       endWidth: 20, 
                       startValue: 160, 
                       endValue: 200, 
                       startDistance:0.5, 
                       endDistance: 0.5, 
                       style: { 
                           fill: "red", 
                           stroke: "blue"
                       } 
                   }] 
               }); 
          });
   </script>
   

   This script initializes the Radial Gauge widget and customizes it.
   

   • The value shown by the pointer is set to 180.
   • The maximum value for the gauge is set to 200.
   • The minimum value for the gauge is set to 0.
   • One 20-pixel-wide range is drawn showing a red zone from 160 to 200.
5. Save your HTML file and open it in a browser. The wijradialgauge widget appears like the following.

Sample Code

Here is some code to make a more complex Radial Gauge:

Within the <body> tags, add markup like the following.

<div id="radialgauge1"></div>

Within the <head> tags, below the references, add the following script to initialize the jQuery widget.

    
    <script type="text/javascript">
        $(document).ready(function () { 
            $("#radialgauge1").wijradialgauge({ 
                radius: "auto", 
                value: 90, 
                max: 100, 
                min: 0, 
                startAngle: 300, 
                sweepAngle: 300, 
                labels: { 
                    style: { 
                        "font-size": 15, 
                        fill: "#000", 
                        stroke: "none"
                    }, 
                    offset: 42 
                }, 
                pointer: { 
                    length: 0.8, 
                    width: 4, 
                    style: { fill: "180-rgb(255,255,255)", stroke: "rgb(255,255,255)", "stroke-width": 1.5 } 
                }, 
                cap: { 
                    style: { 
                        fill: "270-#777d8d-#555b6b", 
                        stroke: "#555b6b"
                    } 
                }, 
                tickMajor: { 
                    factor: 4, 
                    offset: 44, 
                    position: "inside", 
                    style: { fill: "#555b6b", stroke: "#555b6b", "stroke-width": 4 } 
                }, 
                tickMinor: { 
                    visible: true, 
                    offset: 44, 
                    interval: 2, 
                    position: "inside", 
                    style: { fill: "#606779", stroke: "#606779", "stroke-width": 1.5 } 
                }, 
                face: { 
                    style: {}, 
                    template: function (ui) { 
                        var set = ui.canvas.set(); 
                        var circle = ui.canvas.circle(ui.origin.x, ui.origin.y, ui.r); 
                        circle.attr({ "stroke": "#8f8f8f", "stroke-width": 3, fill: "#e2e2e2" }); 
                        set.push(circle); 
                        var circle2 = ui.canvas.circle(ui.origin.x, ui.origin.y, ui.r - 14); 
                        circle2.attr({ "stroke": "#717171", "stroke-width": 2, fill: "270-#a6a6a6-#efefef" }); 
                        set.push(circle2); 
                        return set; 
                    } 
                }, 
                ranges: [{ 
                    startWidth: 10, 
                    endWidth: 10, 
                    startValue: 0, 
                    endValue: 100, 
                    startDistance:0.64, 
                    endDistance: 0.64, 
                    style: { 
                        fill: "#555b6b", stroke: "none"
                    } 
                }, { 
                    startWidth: 10, 
                    endWidth: 10, 
                    startValue: 40, 
                    endValue: 60, 
                    startDistance: 0.58, 
                    endDistance: 0.58, 
                    style: { 
                        fill: "90-rgb(248,255,1)-rgb(248,255,39)", stroke: "rgb(249,255,73)", "stroke-width": 1.5 
                    } 
                }, { 
                    startWidth: 10, 
                    endWidth: 10, 
                    startValue: 60, 
                    endValue: 80, 
                    startDistance: 0.58, 
                    endDistance: 0.58, 
                    style: { 
                        fill: "90-rgb(255,158,1)-rgb(255,177,53)", stroke: "rgb(255,195,101)", "stroke-width": 1.5 
                    } 
                }, { 
                    startWidth: 10, 
                    endWidth: 10, 
                    startValue: 80, 
                    endValue: 100, 
                    startDistance: 0.58, 
                    endDistance: 0.58, 
                    style: { 
                        fill: "180-rgb(255,15,3)-rgb(212,10,0)", stroke: "rgb(255,15,3)", "stroke-width": 1.5 
                    } 
                }] 
            }); 
        });
</script>

The script customizes the appearance and behavior of the wijradialgauge widget. The script sets the size, value, and angles of the widget as well as customizing the appearance of the labels, tick marks, pointer, face, cap, and ranges. The wijradialgauge widget that you create with the code sample above appears like the following:

Concepts

Adaptive for Mobile Use

This widget is an adaptive widget in v3. If you are running v2.3.x, it is not adaptive. You can download v3 2013 1 here: Downloads Page.

An adaptive widget is different from a jQuery UI widget in that you can use it in both mobile and non-mobile web applications. To use it in non-mobile applications, just use the regular help. To use it in mobile applications:

• Use jQuery Mobile instead of jQuery UI references
• Do not initialize the widget in script (unless you need to for complex widgets like charts)
• Use the data-role attribute to create the widget in markup

These steps are demonstrated in the Adaptive Widgets for jQuery Mobile topic.

API

Options

The following options are included in wijradialgauge:

animation

The animation option, inherited from the jquery.wijmo.wijgauge.js base class, defines the animation effect, controlling aspects such as duration and easing.

Type: Object

Default:

{enabled: true, duration: 2000, easing: ">"}

Code Example:

<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            animation:{
                enabled: true, 
                duration: 1000,
                easing: "elastic"
            }
        }); 
    });
</script>

enabled

A value that determines whether to show animation.

Type: Boolean

Default: true

duration

The duration option defines the length of the animation effect in milliseconds.

Type: Number

Default: 2000

easing

The easing option uses Raphael easing formulas to add effects to the animation, such as allowing an item to bounce realistically.

Type: String

Default: ">" (this is a shortcut for "easeOut" or "ease-out")

Valid Values (see http://raphaeljs.com/easing.html for easing demos):

• “linear”
• “<” or “easeIn” or “ease-in”
• “>” or “easeOut” or “ease-out”
• “<>” or “easeInOut” or “ease-in-out”
• “backIn” or “back-in”
• “backOut” or “back-out”
• “elastic”
• “bounce”

cap

Sets the size, color, and other properties of the circle at the center of the gauge that anchors the pointer.

Type: Object

Default:

 
{ radius: 15, style: {fill: "#1E395B", stroke: "#1E395B"}, 
behindPointer: false, visible: true, template: null }

Code Example:

 
        $(document).ready(function () { 
            $("#radialgauge1").wijradialgauge({ 
                cap: { 
                    radius: 25, 
                    style: {fill: "purple", stroke: "blue"}, 
                    behindPointer: true
                }
            }); 
       });

behindPointer

A value that indicates whether the cap shows behind the pointer or in front.

Type: Boolean

Default: false

radius

A value that indicates the radius of the cap in pixels.

Type: Number

Default: 15

style

A value that contains the fill color and outline color (stroke) of the cap. For information on other style options that you can use, please see Style Options.

Type: Object

Default:

{fill: "#1E395B", stroke: "#1E395B"}

template

A JavaScript callback value that returns a Raphael element (or set) that draws the cap for the pointer. If you are only using one shape, the function returns a Raphael element. If you define multiple shapes, have the function create a Raphael set object, push all of the Raphael elements to the set, and return the set to wijradialgauge.

In order to use the template, you must know how to draw Raphael graphics. For more information, see the Raphael documentation.

Use this option to customize the cap.

The cap template's callback contains one argument with two properties:

• origin -- The starting point from which to draw the center of the cap. This argument is defined by x and y coordinates.
• canvas -- A Raphael paper object that you can use to draw the custom graphic to use as the cap.

Type: Function

Default: null

Code example:

<script type="text/javascript">
        $(document).ready(function () { 
            $("#radialgauge1").wijradialgauge({ 
                value: 180, 
                max: 200, 
                min: 0, 
                cap: {
                    template: function (ui) {
                        var origin = ui.origin;
                        return ui.canvas.rect(origin.x - 10, origin.y - 10, 20, 20).attr({fill:"purple", stroke:"none"});
                    }
                }
            }); 
       });
</script>

This example creates a rectangular cap that begins 10 pixels to the left of and 10 pixels above the origin, and is 20 pixels wide by 20 pixels tall. The cap is filled with purple and has no outline (stroke).

visible

A value that indicates whether to show the cap.

Type: Boolean

Default: true

face

Sets or draws the image or shape to use for the face of the gauge and the background area. The origin is the center of the gauge, but the image draws from the top left, so we first calculate the starting point of the top left based on the origin, and we calculate the width and height based on the radius of the face. The radius of the face is half of the min of the width and height.

Type: Object

Default:

 
 {fill: ""r(0.9, 0.60)#FFFFFF-#D9E3F0"", stroke: "#7BA0CC", "stroke-width": "4"}, template: null}

Note: The fill property is defined using the Raphael framework. Please see the Raphael Element attr method for more information. The face can be filled with a simple color, or a gradient. The default fill is a radial gradient, indicated by the r in the fill property.

style

A value that indicates the fill color (or gradient), and the outline color and width of the gauge face. For information on other style options that you can use, please see Style Options.

Type: Object

Default:

{
    fill: ""r(0.9, 0.60)#FFFFFF-#D9E3F0"", 
    stroke: "#7BA0CC", "stroke-width": "4"
}

template

A JavaScript callback value that returns a Raphael element (or set) that draws the gauge face. If you are only using one shape, the function returns a Raphael element. If you define multiple shapes, have the function create a Raphael set object, push all of the Raphael elements to the set, and return the set to wijradialgauge.

In order to use the template, you must know how to draw Raphael graphics. For more information, see the Raphael documentation.

The face template's callback contains one argument with the following parameters:

• origin -- The starting point from which to draw the center of the face. This argument is defined by x and y coordinates.
• canvas -- A Raphael paper object that you can use to draw the custom graphic to use as the face.

Type: Function

Default: null

Code Example:

This example uses a custom image for the face of the gauge. The argument that we name ui in the example is a JSON object. This object has a canvas, which is a Raphael paper object, and we use the image method of the Raphael paper that takes five parameters: source, x, y, width, and height. See the Raphael documentation for more information.

We also set the radius to 120 pixels to render it inside the white area of the image.

 
<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            radius: 120,
            face: {
                style: {},
                template: function (ui) {
                    var url = "images/customGaugeFace.png";
                    return ui.canvas.image(url, ui.origin.x - ui.r, ui.origin.y - ui.r, ui.r * 2, ui.r * 2);
                }
            }
        }); 
    });
</script>

This example, using a photo of a dinner plate, creates a gauge like the following:

Code Example:

This example initializes the widget and then draws a custom Raphael background for the face of the gauge.

 
<script type="text/javascript">
        $(document).ready(function () { 
            $("#radialgauge1").wijradialgauge({ 
                value: 180, 
                max: 200
            }); 
       });
</script>

<script type="text/javascript">
$("#selector").wijradialgauge("option", "face", {
    style: {fill: "#000555"}, 
    template: function(ui){
        var set = ui.canvas.set();
        var circle = ui.canvas.circle(ui.origin.x, ui.origin.y, 24);
        circle.attr({
            fill: "90-#2A292D-#4F4D50",
            stroke: "#9899A0"
        });
        set.push(circle);
        var circle2 = ui.canvas.circle(ui.origin.x, ui.origin.y, 19);
        circle2.attr({
            fill: "90-#4F4D50:1-#2A292D-#2A292D-#4F4D50:99",
            stroke: "#9899A0"
        });
        set.push(circle2);
        return set;
    }
})
</script>

You can see another example of how to use a template for the face of the RadialGauge in the samples included in your installation on a path like this: ...\Wijmo-Complete\development-bundle\samples\radialgauge\templated.html

height

The height option, inherited from the jquery.wijmo.wijgauge.js base class, sets the height of the gauge area in pixels.

Type: Number

Default: 400

Code Example:

<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            height: 200
        }); 
    });
</script>

This code yields a gauge like that in the following image.

isInverted

The isInverted option, inherited from the jquery.wijmo.wijgauge.js base class, determines whether to render the gauge in reverse order, with the numbering going from highest to lowest.

Type: Boolean

Default: false

Code Example:

<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            isInverted: true
        }); 
    });
</script>

This code yields a gauge like that in the following image.

islogarithmic

The islogarithmic option, inherited from the jquery.wijmo.wijgauge.js base class, indicates whether to use logarithmic scaling for gauge label numeric values. This adds space between tick marks that corresponds to the percentage of change between those numbers rather than absolute arithmetic values. You would want to use logarithmic scaling if you were displaying really high numbers, because it goes higher much more quickly. A linear scale is more difficult to use if you are displaying really high numbers.

Note: By default, Wijmo uses a logarithmic base of 10, the common logarithm. See logarithmicBase for information on changing this value.

Type: Boolean

Default: false

Code Example:

The following code creates a gauge with the number labels and tick marks arranged as in the following image.

<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            islogarithmic: true
        }); 
    });
</script>

labels

The labels option, inherited from the jquery.wijmo.wijgauge.js base class, sets all of the appearance options of the numeric labels that appear around the edge of the gauge.

Type: Object

Default:

 
{format: "", style: {fill: "#1E395B", "font-size": "12pt",
"font-weight": "800"}, visible: true, offset: 30}

Code Example:

This example sets the color for the labels to purple, and the font to 14 point, bold, Times New Roman.

 
<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            labels: {
                style: {
                    fill: "purple", 
                    "font-size": "14pt", 
                    "font-weight": "bold", 
                    "font-family": "Times New Roman"
                }
            }
        }); 
   });
</script>

This example creates a gauge with numeric labels like the following:

format

A value that indicates the globalized format to use for the labels. For more information on using jQuery globalize with Wijmo, please see Localizing Wijmo.

Note: If the value is a function rather than a string, the function formats the value and returns it to the gauge.

Type: String

Default: ""

offset

A value in pixels that indicates the distance of the numeric labels from the outer reach of the pointer. A value of 50 pixels renders the labels outside the circular gauge area, cutting off the numbers along the top. A value of 0 pixels renders the labels just inside the tick marks.

Type: Number

Default: 30

style

A value that indicates the color, weight, and size of the numeric labels. To use a different font, add "font-family" to the style, as in the example code. For information on other style options that you can use, please see Style Options.

Type: Object

Default:

{fill: "#1E395B", "font-size": "12pt", "font-weight": "800"}

visible

A value that indicates whether to show the numeric labels.

Type: Boolean

Default: true

Code Example:

 $("#selector").wijradialgauge("option", "labels", {visible: false})

logarithmicBase

The logarithmicBase option, inherited from the jquery.wijmo.wijgauge.js base class, indicates the logarithmic base to use if the islogarithmic option is set to true. The logarithmic base is the number to raise to produce the exponent.

For example, with the default base 10, a logarithm of 3 produces 1000, or 10 to the power of 3, or 10³ = 10 x 10 x 10 = 1000.

If you change the base to 2, a logarithm of 3 produces 8, or 2³ = 2 x 2 x 2 = 8.

You can use the natural logarithm (using a base of ≈ 2.718) by specifying the value Math.e.

Type: Number

Default: 10

Code Example:

$("#radialgauge").wijradialgauge({
logarithmicBase: Math.e
})

marginBottom

The marginBottom option, inherited from the jquery.wijmo.wijgauge.js base class, sets a value in pixels that indicates where to render the bottom edge of the gauge face.

• A setting of 0 renders the bottom edge of the gauge face just inside the lower edge based on the height of the gauge.
• A setting of 200 renders the bottom edge of the gauge face halfway up the gauge area, based on the default height of 400 pixels.

Note: If the radius of the gauge is too large to fit within the rectangle defined by the width and height less the specified margins, and the radius is set to the default value of "auto," Wijmo automatically resizes the gauge to fit.

Type: Number

Default: 0

Code Example:

$("#radialgauge").wijradialgauge("option", "marginBottom", 200)

marginLeft

The marginLeft option, inherited from the jquery.wijmo.wijgauge.js base class, sets a value in pixels that indicates where to render the left edge of the gauge face.

• A setting of 0 renders the left edge of the gauge face 100 pixels inside the left edge based on the width of the gauge.
• A setting of 300 renders the left edge of the gauge face halfway across the gauge area, based on the default width of 600 pixels.

Note: If the radius of the gauge is too large to fit within the rectangle defined by the width and height less the specified margins, and the radius is set to the default value of "auto," Wijmo automatically resizes the gauge to fit.

Type: Number

Default: 0

Code Example:

$("#radialgauge").wijradialgauge("option", "marginLeft", 300)

marginRight

The marginRight option, inherited from the jquery.wijmo.wijgauge.js base class, sets a value in pixels that indicates where to render the right edge of the gauge face.

• A setting of 0 renders the right edge of the gauge face 100 pixels inside the right edge based on the width of the gauge.
• A setting of 300 renders the right edge of the gauge face halfway across the gauge area, based on the default width of 600 pixels.

Note: If the radius of the gauge is too large to fit within the rectangle defined by the width and height less the specified margins, and the radius is set to the default value of "auto," Wijmo automatically resizes the gauge to fit.

Type: Number

Default: 0

Code Example:

$("#radialgauge").wijradialgauge("option", "marginRight", 300)

marginTop

The marginTop option, inherited from the jquery.wijmo.wijgauge.js base class, sets a value in pixels that indicates where to render the top edge of the gauge face.

• A setting of 0 renders the top edge of the gauge face just inside the upper edge based on the height of the gauge.
• A setting of 200 renders the top edge of the gauge face halfway down the gauge area, based on the default height of 400 pixels.

Note: If the radius of the gauge is too large to fit within the rectangle defined by the width and height less the specified margins, and the radius is set to the default value of "auto," Wijmo automatically resizes the gauge to fit.

Type: Number

Default: 0

Code Example:

$("#radialgauge").wijradialgauge("option", "marginTop", 200)

max

The max option, inherited from the jquery.wijmo.wijgauge.js base class, sets the maximum value of the gauge. Use this option along with min to set the numeric scale of values that are shown on the gauge. This setting limits your valid values for other options, such as value and ranges.

Type: Number

Default: 100

Code Example:

 $("#selector").wijradialgauge("option", max, 150)

min

The min option, inherited from the jquery.wijmo.wijgauge.js base class, sets the minimum value of the gauge. Use this option along with min to set the numeric scale of values that are shown on the gauge. This setting limits your valid values for other options, such as value and ranges.

Type: Number

Default: 0

Code Example:

$("#selector").wijradialgauge("option", min, 10)

origin

Sets the starting point for the center of the radial gauge.

Results of some common settings:

Type: Object

Default: { x: 0.5, y: 0.5 }

Code Example:

$("#selector").wijradialgauge("option", "origin", { x: 0.5, y: 0.6 })

pointer

A value that includes all settings of the gauge pointer.

Type: Object

Default:

 
{length: 0.8, style: { fill: "#1E395B", stroke: "#1E395B"},
width: 8, offset: 0.15, shape: "tri", visible: true, template: null}

Code Example:

 
<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            cap: {visible: true},
            pointer: {
                length: 1.25, 
                offset: 0.5, 
                shape: "rect", 
                style: { fill: "blue", stroke: "purple"},
                width: 10
            }
        }); 
   });
</script>

The example above renders the pointer as a purple-outlined blue rectangle of 125% the length of the radius by 10 pixels wide, offset back through the cap by 50% of the length of the radius, as pictured below:

length

Sets the length of the pointer as a percentage of the radius of the gauge. You can set the length to be greater than the radius.

Type：Number

Default: 0.8

offset

Sets the percentage of the pointer that is shoved backward through the cap.

A setting of 0.5 (when the length of the pointer is 1) shoves half of the pointer backward through the cap, as in the image below.

A setting of 0 renders the back end of the pointer exactly at the origin of the gauge.

Type: Number

Default: 0.15

shape

Sets the shape in which to render the pointer: triangular or rectangular.

Type: String

Default: 'tri'

Valid Values: 'rect', and 'tri'

style

Sets the fill and outline (stroke) colors of the pointer. For information on other style options that you can use, please see Style Options.

Type: Object

Default:

{fill: "#1E395B", stroke: "#1E395B"}

template

A JavaScript callback value that returns a Raphael element that draws the pointer. Use this option to customize the pointer.

In order to use the template, you must know how to draw Raphael graphics. For more information, see the Raphael documentation.

The pointer template's callback contains two arguments:

• startLocation -- The starting point from which to draw the pointer. This argument is defined by x and y coordinates.
• pointerInfo -- A JSON object that extends the gauge's pointer options:
  • offset -- Sets the percentage of the pointer that is shoved backward through the origin.
  • length -- Sets the absolute value in pixels of the length of the pointer.
  • gaugeBBox -- An object that sets the bounding box of the gauge, as defined by x and y coordinates and width and height options.

Type: Function

Default: null

You can see an example of how to use a template for the RadialGauge pointer in the samples included in your installation on a path like this: ...\Wijmo-Complete\development-bundle\samples\radialgauge\templated.html

visible

A value that indicates whether to show the pointer.

Type: Boolean

Default: true

width

Sets the width of the pointer in pixels.

Type: Number

Default: 8

radius

A value that indicates the radius of the radial gauge in pixels, or use "auto" to have the gauge indicators fill the gauge area. Values between 50 and 200 are most useful when you use the default size for the gauge area.

Type: Number

Default: "auto"

Code Example:

 $("#selector").wijradialgauge("option", "radius", 170)

ranges

The ranges option, inherited from the jquery.wijmo.wijgauge.js base class, allows you to create an array of ranges to highlight where values fall within the gauge, for example, a red range, a yellow range, and a green range. Each range is drawn in the form of a curved bar. You can control every aspect of each range with the settings detailed below.

Options available for each range include:

• startWidth – Sets the thickness of the left side of the range bar in pixels.
• endWidth – Sets the thickness of the right side of the range bar in pixels.
• startValue – Sets the value at which to begin drawing the range bar. This value must fall between the max and min values you set for the gauge.
• endValue – Sets the value at which to end the range bar. This value must fall between the max and min values you set for the gauge.
• startDistance – Sets the distance from the center of the gauge to draw the left side of the range bar.
• endDistance – Sets the distance from the center of the gauge to draw the right side of the range bar.
• style – Sets the colors to use in drawing the range bar with the following options:

• fill – Sets the color with which to fill the range bar.
• stroke – Sets the color with which to outline the range bar.

Type: Array

Default: []

Code Example:

<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            ranges: [{
                startWidth: 20,
                endWidth: 20,
                startValue: 90,
                endValue: 100,
                startDistance: 0.5,
                endDistance: 0.5,
                style: {
                    fill: "red", 
                    stroke: "yellow"
                }
            }]
        }); 
   });
</script>

startAngle

A value that indicates in degrees where to start the lowest number in the numeric labels and tickMarks around the face of the RadialGauge.

• The default value of 0 degrees renders the lowest number to the left of the origin.
• A value of -90 degrees renders the lowest number below the origin.
• A value of 90 degrees renders the lowest number above the origin.
• A value of 180 degrees renders the lowest number to the right of the origin.

Type: Number

Default: 0

Code Example:

 
$("#selector").wijradialgauge("option", "startAngle", -20)

Code Example:

<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            startAngle: -90
        }); 
    });
</script>

This code example renders the labels and tickmarks starting below the origin, as in the image below.

sweepAngle

A value that indicates in degrees where to render the highest number in the numeric labels and tickMarks in relation to the startAngle.

• The default value of 180 degrees renders the highest number halfway around the face of the gauge clockwise from the lowest number.
• A value of 270 degrees renders the highest number three quarters of the way around the face of the gauge clockwise from the lowest number.

Type: Number

Default: 180

Code Example:

 
$("#selector").wijradialgauge("option", "sweepAngle", 200)

Code Example:

<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            startAngle: -45,
            sweepAngle: 270
        }); 
    });
</script>

This code example renders the labels and tickmarks from a starting angle of -45 degrees to a sweep angle of 270 degrees, so that the numbers render three quarters of the way around the face, as in the image below.

File:RadialSweepAngle.png

tickMajor

Sets appearance options for the major tick marks that appear next to the numeric labels around the face of the gauge.

Type: Object

Default:

  
{position: "inside", style: { fill: "#1E395B", stroke:"none"
}, factor: 2, visible: true, marker: "rect", offset: 27, interval: 10}

Code Example:

 
<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            tickMajor: {
                position: "inside", 
                style: { fill: "purple", stroke: "#1E395B"}, 
                factor: 2.5, 
                marker: 'diamond',
                visible: true, 
                offset: 27, 
                interval: 20
            }
        }); 
    });
</script>

This example renders the major tick marks as slightly larger purple filled diamonds with blue outlines, at an interval of once every 20 numbers, as shown in the image below.

factor

A value that indicates how long to draw the major tick marks as a factor of the default length of the minor tick marks.

• A setting of 2 renders them twice as long as the minor tick marks.
• A setting of 1 renders them the same length as the minor tick marks.
• A setting of .5 renders them half the length of the minor tick marks.
• A setting of 2.5 renders them two and a half times as long as the minor tick marks.

Type: Number

Default: 2

interval

A value that indicates the frequency of the major tick marks and their numeric labels.

• A setting of 1 renders a major tick mark for every number between the min and max. This setting is useful when the spread between min and max is small.
• The default setting of 10 renders a major tick mark once every 10 numbers between the min and the max.
• A setting of 100 renders a major tick mark once every 100 numbers between the min and max. This setting is useful when the spread between min and max is very large.

Type: Number

Default: 10

marker

A value that indicates the shape to use in drawing major tick marks.

Type: "String"

Default: "rect"

Valid Values:

	'rect'		'tri'
	'circle'		'invertedTri'
	'box'		'diamond'
	'cross'

Important: In order to use the 'cross' marker shape, you must specify a color for the stroke setting of the style option. The other shapes use the fill setting, but since the cross is not a closed shape, fill has no effect, and we must use the outline (stroke) color.

offset

A value that indicates the distance in pixels from the edge of the face to draw the major tick marks. The numeric labels are drawn a few pixels outside of the major tick marks.

• An offset of 0 renders the major tick marks exactly on the edge of the face, with the numeric labels outside the face.
• An offset of 5 renders the major tick marks just inside the edge of the face, with the numeric labels outside the face.
• An offset of 27 (default) renders the major tick marks and the numeric labels just inside the edge of the face.
• An offset of 50 renders the major tick marks and the numeric labels well inside the edge of the face.

Type: Number

Default: 27

position

A value that indicates the position of the major tick marks in relation to the edge of the face.

Type: "String"

Default: "inside"

Valid Values:

• "inside" -- Draws the major tick marks inside the edge of the face.
• "outside" -- Draws the major tick marks outside the edge of the face.
• "cross" -- Draws the major tick marks centered on the edge of the face.

style

A value that indicates the fill color and outline (stroke) of the major tick mark. For information on other style options that you can use, please see Style Options.

Type: Object

Default:

 {fill: "#1E395B", stroke:"none"}

visible

A value that indicates whether to show the major tick mark.

Type: Boolean

Default: true

tickMinor

Sets appearance options for the minor tick marks that appear between the numeric labels around the face of the gauge, indicating numeric values between the major tick marks.

Type: Object

Default:

 
{position: "inside", style: { fill: "#1E395B", stroke:"none"
}, factor: 1, visible: true, marker: "rect", offset: 30, interval: 5}

Code Example:

 
<script type="text/javascript">
    $(document).ready(function () { 
        $("#radialgauge1").wijradialgauge({ 
            value: 90,
            tickMinor: {
                position: "inside", 
                style: { fill: "#1E395B", stroke: "purple"}, 
                factor: 2, 
                marker: 'cross',
                visible: true, 
                offset: 30, 
                interval: 2
            }
        }); 
    });
</script>

This example renders the minor tick marks as purple crosses, at an interval of once every 2 numbers, as shown in the image below.

factor

A value that indicates how long to draw the minor tick marks as a factor of the default length of the minor tick marks, which is half the default length of the major tick marks.

• A setting of 2 renders them the same length as the major tick marks.
• A setting of 1 renders them half the length of the major tick marks.
• A setting of .5 renders them one quarter the length of the major tick marks.

Type: Number

Default: 1

interval

A value that indicates the frequency of the minor tick marks.

• A setting of 1 renders a minor tick mark for every number between the min and max. This setting is useful when the spread between min and max is small.
• The default setting of 5 renders a minor tick mark once every 5 numbers between the min and the max.
• A setting of 100 renders a minor tick mark once every 100 numbers between the min and max. This setting is useful when the spread between min and max is very large.

Type: Number

Default: 5

marker

A value that indicates the shape to use in drawing minor tick marks.

Type: "String"

Default: "rect"

Valid Values:

	'rect'		'tri'
	'circle'		'invertedTri'
	'box'		'diamond'
	'cross'

Important: In order to use the 'cross' marker shape, you must specify a color for the stroke setting of the style option. The other shapes use the fill setting, but since the cross is not a closed shape, fill has no effect, and we must use the outline (stroke) color.

offset

A value that indicates the distance in pixels from the edge of the face to draw the minor tick marks. By default, they are three pixels in from the major tick marks.

• An offset of 0 renders the minor tick marks exactly on the edge of the face.
• An offset of 5 renders the minor tick marks just inside the edge of the face.
• An offset of 27 renders the minor tick marks at the same distance from the edge as the default major tick marks.
• An offset of 30 (default) renders the minor tick marks a little further inside the edge of the face than the major tick marks.
• An offset of 50 renders the minor tick marks well inside the edge of the face.

Type: Number

Default: 30

position

A value that indicates the position of the minor tick marks in relation to the edge of the face.

Type: "String"

Default: "inside"

Valid Values:

• "inside" -- Draws the minor tick marks inside the edge of the face.
• "outside" -- Draws the minor tick marks outside the edge of the face.
• "cross" -- Draws the minor tick marks centered on the edge of the face.

style

A value that indicates the fill color and outline (stroke) of the minor tick mark. For information on other style options that you can use, please see Style Options.

Type: Object

Default:

{fill: "#1E395B", "stroke": "none"}

visible

A value that indicates whether to show the minor tick mark.

Type: Boolean

Default: true

value

The value option, inherited from the jquery.wijmo.wijgauge.js base class, sets the value of the gauge, indicated by the pointer. This value must fall between the min and max values that you set.

Type: Number

Default: 5

Code Example:

$("#selector").wijradialgauge("option", value, 20)

width

The width option, inherited from the jquery.wijmo.wijgauge.js base class, sets the width of the gauge area in pixels.

Type: Number

Default: 600

Code Example:

$("#selector").wijradialgauge("option", width, 500)

Events

The following events are included in wijradialgauge:

beforeValueChanged

Fires before the value changes, this event can be called.

Default: null

Type: Function

Parameters:

• e: jQuery.Event object
• arg
• arg.oldValue: the gauge's old value.
• arg.newValue: the value to be set.

Code Example:

Supply a function as an option.

$("#gauge").wijgauge({
beforeValueChanged: function(e, arg){}
})

Bind to the event by type: wijgaugebeforevaluechanged.

$("#gauge").bind("wijgaugebeforevaluechanged", function (e, arg) {});

painted

Fires before the canvas is painted. This event can be cancelled. "return false;" to cancel the event.

Default: null.

Type: Function.

Parameters:

• e: jQuery.Event object

Code Example:

Supply a function as an option.

$("#gauge").wijgauge({
painted: function(e){}
});

Bind to the event by type: wijgaugepainted.

$("#gauge").bind("wijgaugepainted", function(e){});

valueChanged

Fires when the value has changed.

Default: null.

Type: Function.

Parameters:

• e: jQuery.Event object
• arg
• arg.oldValue: the gauge's old value.
• arg.newValue: the value to be set.

Code Example:

Supply a function as an option.

$("#gauge").wijgauge({
valueChanged: function(e, arg){}
})

Bind to the event by type: wijgaugevaluechanged.

$("#gauge").bind("wijgaugevaluechanged", function (e, arg) {});

Methods

The following methods are included in wijradialgauge:

destroy

Removes the functionality completely. This returns the element to its pre-init state.

Code Example:

$("#radialgauge").wijradialgauge("destroy");

disabled

Disables the wijradialgauge.

Code Example:

$("#radialgauge").wijradialgauge("disabled");

enabled

Enables the wijradialgauge.

Code Example:

$("#radialgauge").wijradialgauge("enabled");

getCanvas

Returns a reference to the Raphael canvas object. You can use this method to draw on the canvas of a radial gauge.

Code Example:

<script type="text/javascript">        
$(document).ready(function () {
    $("#radialgauge1").wijradialgauge({                
        value: 180,  
        max: 200,                 
        min: 0, 
    }); 
    var canvas = $("#radialgauge1").wijradialgauge("getCanvas");
    canvas.text(50, 12, 'Bye Bye Circle!');
});
</script>

option

Get or set any wijradialgauge option. If no value is specified, it acts as a getter.

Parameters:

• optionName (string): Represents the name of the option to get or set.
• value (number): Represents the value to set.

Code Example:

$("#radialgauge").wijradialgauge("width");
$("#radialgauge").wijradialgauge("width", 600);

option

Set multiple wijradialgauge options at once by providing an options object.

Parameters:

• Options: Represents the options value to set.

Type: Object.

Code Example:

$("#radialgauge").wijradialgauge("option", {width: 800, height: 600});

redraw

Redraws the gauge.

Code Example:

$("#radialgauge").wijradialgauge("redraw");

widget

Returns the wijradialgauge element.

Code Example:

$("#radialgauge").wijradialgauge("widget");