LinearGauge

Contents

User Guide

Overview

The wijlineargauge widget delivers the exact graphical representation you need to display information. Choose from horizontal or vertical linear gauges. The image below illustrates several main elements that allow you to customize the appearance and behavior of the gauge:

Wijlineargaugeparts.png

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

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

Markup and Scripting

The markup used to create a wijlineargauge widget resembles the following:

<div id="gauge" class="ui-corner-all"></div>

You can also add a little CSS styling to the gauge. This example specifies the width of the gauge:

<style type="text/css">
        #gauge.wijlineargauge
        {
            width: 400;
        }
</style>

Now you need to initialize the widget, which you can do by adding the following script to the project:

<script id="scriptInit" type="text/javascript">
   $(document).ready(function () {
       $("#gauge").wijlineargauge({ width: 400, height: 100, value: 50, max: 100, min: 0,  });
   });    
</script>

The above markup and script will create a gauge that appears like the following:


Quick Start

This quick start helps you to create a Web page, add the wijlineargauge 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="lineargauge1"></div>
    The <div> element creates the LinearGauge widget; its id option is set to 'lineargauge1', 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 () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            max: 50, 
            min: 0, 
            ranges: [{ 
                startWidth: .25, 
                endWidth: .25, 
                startValue: 35, 
                endValue: 50, 
                startDistance: 0.75, 
                endDistance: 0.75, 
                style: { 
                    fill: "red", 
                    stroke: "blue"
                } 
            }] 
        }); 
   });
</script>

    This script initializes the Linear Gauge widget and customizes it.

    • The value shown by the pointer is set to 31.
    • The maximum value for the gauge is set to 50.
    • The minimum value for the gauge is set to 0.
    • One range with a width of 25% of the height of the gauge is drawn showing a red zone from 35 to 50.
  5. Save your HTML file and open it in a browser. The wijlineargauge widget appears like the following.
WijlinearaugeEasyquickstart.png

Sample Code

The following sample code helps you to create a linear gauge that takes advantage of many more of the options that allow you to customize your gauge.

  1. Add the following markup within <body> tags:
    <div id="lineargauge1" class="ui-corner-all"></div>
<p>Drag and release the slider to change the gauge's value:</p>
<div id="slider" style="width:400px"></div>

    The <div> HTML element is what creates the widget. The <div> element's id option is set to 'lineargauge1', which you'll call in jQuery to initialize the widget. The above markup also adds a slider, which will allow you to change the lineargauge's value at run time.

  2. Add the following script to initialize the jQuery widget. The script should appear under the references within the <head> tags:
        <script type="text/javascript">
        $(document).ready(function () {
            $("#lineargauge1").wijlineargauge({
                width: 400,
                height: 120,
                value: 70,
                max: 100,
                min: 0, 
                animation: {
                    enabled: true,
                    duration: 400,
                    easing: ">"
                },
                labels: {
                    style: {
                        fill: "#1E395B",
                        "font-size": 12,
                        "font-weight": "800"
                    }
                },
                tickMajor: {
                    position: "inside",
                    offset: -11,
                    interval: 20,
                    factor: 12,
                    style: {
                        fill: "#1E395B",
                        stroke: "none",
                        width: 2
                    }
                },
                tickMinor: {
                    position: "inside",
                    offset: -11,
                    visible: true,
                    interval: 4,
                    factor: 10,
                    style: {
                        fill: "#1E395B",
                        stroke: "none",
                        width: 1
                    }
                },
                pointer: {
                    shape: "rect",
                    length: 0.6,
                    style: {
                        fill: "#1E395B",
                        stroke: "#7BA0CC",
                        "stroke-width": 1,
                        opacity: 1
                    }
                },
                face: {
                    style: {
                        fill: "270-#FFFFFF-#D9E3F0",
                        stroke: "#7BA0CC",
                        "stroke-width": 2
                    }
                },
                ranges: [{
                    startValue: 80,
                    endValue: 100,
                    startDistance: 0.85, //A ratio value determine the location of the range at start value.
                    endDistance: 0.85, //A ratio value determine the location of the range at end value.
                    startWidth: 0.5,
                    endWidth: 0.5,
                    style: {
                        fill: "90-#3DA1D8-#3A6CAC",
                        opacity: 1,
                        stroke: "none"
                    }
                }]
            });

            $("#slider").slider({
            value: $("#lineargauge1").wijlineargauge("option", "value"),
                change: function (event, ui) {
                    $("#lineargauge1").wijlineargauge("option", "value", ui.value);
                }
            });
        });
</script>
    The script customizes the appearance and behavior of the wijlineargauge widget. The script sets the size, value, and animation used in the widget as well as customizing the appearance of the labels, tick marks, pointer, face, and ranges. It also initializes the wijlineargauge and slider widgets so that when the value of the slider changes, so dies the value of the wijlineargauge.
  3. Save and close your HTML file and open it in a browser. The wijlineargauge widget will appear similar to the following:
Wijlineargaugequickstart.png

Click and drag the slider to change the value of the gauge.

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 available in the wijlineargauge widget. Some of these options are inherited from the jquery.wijmo.wijgauge.js base class.

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 () { 
        $("#lineargauge1").wijlineargauge({ 
            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”


face

The face option, inherited from the jquery.wijmo.wijgauge.js base class, sets or draws the colors, image or shape to use for the face of the gauge and the background area.
Type: Object
Default:
{
style: { 
    fill: "270-#FFFFFF-#D9E3F0", 
    stroke: "#7BA0CC", 
    "stroke-width": "4"
    }, 
template: null
}
Parameters:
  • ui: An object that contains the parameters to use in drawing the face.
  • ui.width: The width of the face.
  • ui.height: The height of the face.
  • ui.x: The x value for the starting point from which to draw the face.
  • ui.y: The y value for the starting point from which to draw the face.
  • ui.canvas: A Raphael paper object that you can use to draw a custom graphic to use as the face.

style

A value that indicates fill color (or linear 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: "270-#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 wijlineargauge.
In order to use the template, you must know how to draw Raphael graphics. For more information, see the Raphael documentation.
Type: Function
Default: null
Code Example:
This example sets up a template to use as the face of the Linear Gauge. The template creates a rectangle with no outline (stroke: none) with a Raphael linear gradient from grey through white, as in the image below.
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            face: {
                style: {},
                template: function (ui) {
                    var set = ui.canvas.set();
                    var rect = ui.canvas.rect(ui.x, ui.y, ui.width, ui.height, 10);
                    rect.attr({ stroke: "none", fill: "90-#8E8E8F-#FBFBFB" });
                    set.push(rect);
                }
            }
        }); 
   });
</script>
LinearGaugeFaceTemplate.png

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: "auto"
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            height: 200
        }); 
    });
</script>
This code yields a gauge like that in the following image.
LinearGaugeHeight.png


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 () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            isInverted: true
        }); 
    });
</script>
This code yields a gauge like that in the following image.
LinearIsInverted.png

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 () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            max: 50,
            islogarithmic: true
        }); 
    });
</script>
LineargaugeIslogarithmic.png


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 along the edge of the gauge.
Type: Object
Default:
{format: "", style: {fill: "#1E395B", "font-size": 12, "font-weight": "800"}, visible: true, offset: 0}
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 () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            max: 50,
            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:
LinearLabels.png

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: ""
Code Example:
You can use most of the .NET Standard Numeric Format Strings in the format property. In this example, we set the first parameter, specified by 0:, to n2, where the numeric n format specifier adds commas and decimal symbols appropriate to the locale, and the number 2 specifies two decimal places. See the image below for the results of using this code.
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            max: 50,
            labels: {
                style: {fill: "purple"},
                format: "{0:n2}"
            }
        }); 
   });
</script>
LinearFormat.png

offset

A value in pixels that indicates the distance of the numeric labels from the top edge of the gauge face.
  • A value of 40 pixels renders the labels along the bottom edge of the gauge face (assuming you use the default value for height).
  • A value of 0 pixels renders the labels just inside the top edge.
Type: Number
Default: 0
Code Example:
This code renders the labels inside the tick marks, as in the image below.
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            max: 50,
            labels: {
                style: {fill: "purple"},
                offset: 40
            }
        }); 
   });
</script>
LinearGaugeLabelOffset.png

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": 12, "font-weight": "800"}
Code Example:
This code renders the labels in purple, 14 point, bold, Times New Roman text as in the image below.
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            labels: {
                style: {
                    fill: "purple", 
                    "font-size": "14pt", 
                    "font-weight": "bold", 
                    "font-family": "Times New Roman"
                }
            }
        }); 
   });
</script>
LinearGaugeLabelStyle.png

visible

A value that indicates whether to show the gauge label.
Type: Boolean
Default: true


logarithmicBase

The logarithmic base 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:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge").wijlineargauge({
            islogarithmic: true,
            logarithmicBase: Math.e
        });
    });
</script>
LinearGaugeLogarithmicBase.png

marginBottom

The marginBottom option, inherited from the jquery.wijmo.wijgauge.js base class, is a value in pixels that indicates where to render the bottom edge of the gauge face. In order to change the margin settings by more than a few pixels without clipping the gauge face edges, it may help to also change the height property.
Type: Number
Default: 5
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            marginBottom: 20
        }); 
   });
</script>

marginLeft

The marginLeft option, inherited from the jquery.wijmo.wijgauge.js base class, is a value in pixels that indicates where to render the left edge of the gauge face. In order to change the margin settings without compressing the gauge markers, it may help to also change the width option.
Type: Number
Default: 5
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            marginLeft: 100
        }); 
   });
</script>

marginRight

The marginRight option, inherited from the jquery.wijmo.wijgauge.js base class, is a value in pixels that indicates where to render the right edge of the gauge face. In order to change the margin settings without compressing the gauge markers, it may help to also change the width option.
Type: Number
Default: 5
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            marginRight: 100
        }); 
   });
</script>

marginTop

The marginTop option, inherited from the jquery.wijmo.wijgauge.js base class, is a value in pixels that indicates where to render the top edge of the gauge face. In order to change the margin settings by more than a few pixels without clipping the gauge face edges, it may help to also change the height property.
Type: Number
Default: 5
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            marginTop: 20
        }); 
   });
</script>


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.

Note: When setting values for min and max, keep in mind that the default interval values for tickMajor and tickMinor are 10 and 5 respectively. This can cause issues if you use a very large range of numbers for your gauge as it tries to render thousands of tick marks.

Type: Number
Default: 100
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 300,
            tickMajor: {interval: 100},
            tickMinor: {interval: 50},
            min: 100,
            max: 1000
        }); 
   });
</script>

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 max 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.

Note: When setting values for min and max, keep in mind that the default interval values for tickMajor and tickMinor are 10 and 5 respectively. This can cause issues if you use a very large range of numbers for your gauge as it tries to render thousands of tick marks.

Type: Number
Default: 0
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 300,
            tickMajor: {interval: 100},
            tickMinor: {interval: 50},
            min: 100,
            max: 1000
        }); 
   });
</script>

orientation

Sets the orientation of the gauge, with a setting of horizontal showing values across the gauge from left to right, and a setting of vertical showing values along the gauge from top to bottom.
Type: String.
Default: "horizontal"
Valid Values: "horizontal" and "vertical"
Code Example:
This code yields a gauge that looks like the following image.
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            orientation: "vertical"
        }); 
   });
</script>

LinearGaugeOrientation.png

pointer

The pointer option, inherited from the jquery.wijmo.wijgauge.js base class, creates an object that includes all settings of the gauge pointer.
Type: Object.
Default:
{length: 0.5, style: { fill: "#1E395B", stroke: "#1E395B"}, width: 4, offset: 0, shape: "tri", visible: true, template: null}
Code Example:
This code yields a gauge with a pointer like that in the image below.
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            pointer: {
                length: .2, 
                offset: .2, 
                shape: "tri", 
                style: { fill: "red", stroke: "black"},
                width: 10
            }
        }); 
   });
</script>

LinearPointer.png

length

Sets the length of the pointer as a percentage of the height of the gauge (or the width, if the orientation is set to vertical). You can set the length to be greater than the height (or width).
Type: Number
Default: 0.5

offset

Sets the percentage of the height of the gauge to move the pointer upward (or of the width if the orientation is vertical) from the bottom (or right) edge of the gauge.
A setting of 0.5 shoves the pointer upward so that it starts in the center of the gauge, as in the image below.
LinearPointerOffset.png
A setting of 0 renders the back end of the pointer exactly at the bottom edge of the gauge.
Type: Number
Default: 0

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 upward from the bottom edge.
    • 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

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: 4

ranges

The ranges option, inherited from the jquery.wijmo.wijgauge.js base class, is an array of objects containing all of the options used to draw range bars to highlight where values fall within the gauge. For example, you can create a red range, a yellow range, and a green range. Each range is drawn in the form of a bar. You can control every aspect of each range with the settings detailed below.
Type: Array
Default: []
Code Example:
This script creates a linear gauge with a range bar that appears like that in the image below, with a range bar 80% of the way down from the top, the left edge of the range bar at the 70 marker and 20% of the height of the gauge, the right edge at the 100 marker and 40% of the height, and rendered with an opacity of 50%, filled with green and outlined in blue.
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            ranges: [{
                startWidth: .2,
                endWidth: .4,
                startValue: 70,
                endValue: 100,
                startDistance: 0.8,
                endDistance: 0.8,
                style: {
                    fill: "green", 
                    opacity: .5,
                    stroke: "blue"
                }
            }]
        }); 
   });
</script>

LinearRanges.png

Options available for each range include:
LinearGaugeRanges.png

startWidth

Sets the thickness of the left side of the range bar as a percentage of the height of the gauge.
Type: Number

endWidth

Sets the thickness of the right side of the range bar as a percentage of the height of the gauge.
Type: Number

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.
Type: Number

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.
Type: Number

startDistance

Sets the distance from the top edge of the gauge to draw the left side of the range bar as a percentage of the height of the gauge.
Type: Number

endDistance

Sets the distance from the top edge of the gauge to draw the right side of the range bar as a percentage of the height of the gauge.
Type: Number

style

A value that indicates the fill color and outline color (stroke) of the range bar, as well as the opacity as a percentage. For information on other style options that you can use, please see Style Options.
Type: Object

tickMajor

The tickMajor option, inherited from the jquery.wijmo.wijgauge.js base class, creates an object that provides information for the major tick marks that appear next to the numeric labels along the gauge.
Type: Object
Default:
{
position: "inside", 
style: { 
    fill: "#1E395B", 
    stroke:"none" 
    }, 
factor: 2, 
visible: true, 
marker: "rect", 
offset: 0, 
interval: 10
}
Code Example
This sample code creates a LinearGauge with major tick marks like those in the image below.

<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            tickMajor: {
                factor: 3,
                marker: "diamond",
                offset: -15,
                style: {
                    fill: "blue", 
                    stroke: "red"
                }
            }
        }); 
   });
</script>

LinearTickMajor.png

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.
LinearTickMinorFactor.png
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:
LinearTickMarkerRect.png 'rect' LinearTickMarkerTri.png 'tri'
LinearTickMarkerCircle.png 'circle' LinearTickMarkerInvertedTri.png 'invertedTri'
LinearTickMarkerBox.png 'box' LinearTickMarkerDiamond.png 'diamond'
LinearTickMarkerCross.png 'cross'

offset

A value that indicates the distance in pixels from the center 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 (default) renders the major tick marks exactly centered in the gauge, with the numeric labels above (or to the left if the orientation is set to vertical).
  • An offset of 5 renders the major tick marks with their centers five pixels above the center of the gauge.
  • An offset of -5 renders the major tick marks with their centers five pixels below the center of the gauge.
  • An offset of -25 renders the major tick marks along the bottom edge of the gauge at the default height.
LinearMajorTickOffset.png
Type: Number
Default: 0

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"
  • "outside"
  • "cross"

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 major tick marks.
Type: Boolean
Default: true

tickMinor

A value that provides information for the minor tick.
Type: Object
Default:
{position: "inside", style: { fill: "#1E395B", stroke:"none"}, factor: 1, visible: false, marker: "rect", offset: 0, interval: 5}
Code Example:
This code yields a gauge with minor tick marks like those in the image below.
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            max: 50,
            value: 31,
            tickMinor: {
                factor: 1.5,
                interval: 2,
                marker: "diamond",
                style: {
                    fill: "purple"
                },
                visible: true
            }
        }); 
   });
</script>
LinearTickMinor.png

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.
LinearTickMinorFactor2.png
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:
LinearTickMinorRect.png 'rect' LinearTickMinorTri.png 'tri'
LinearTickMinorCircle.png 'circle' LinearTickMinorInverted.png 'invertedTri'
LinearTickMinorBox.png 'box' LinearTickMinorDiamond.png 'diamond'
LinearTickMinorCross.png 'cross'

offset

A value that indicates the distance in pixels from the center of the face to draw the minor tick marks.
  • An offset of 0 (default) renders the minor tick marks exactly centered in the gauge.
  • An offset of 5 renders the minor tick marks with their centers five pixels above the center of the gauge.
  • An offset of -5 renders the minor tick marks with their centers five pixels below the center of the gauge.
  • An offset of -25 renders the minor tick marks along the bottom edge of the gauge at the default height.
LinearMinorTickOffset.png
Type: Number
Default: 0

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"
  • "outside"
  • "cross"

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 minor tick.
Type: Boolean
Default: false

value

The value option, inherited from the jquery.wijmo.wijgauge.js base class, sets the current value of the gauge, indicated by the pointer. This value must fall between the min and max values that you set.
Type: Number
Default: 0
Code Example:
$("#selector").wijlineargauge("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: "auto"
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            width: 500
        }); 
    });
</script>
This code yields a gauge like that in the following image.
LinearGaugeWidth.png

xAxisLength

Sets the length of the X axis as a percentage of the width of the gauge.
Note: By default, the xAxisLocation option is set to begin the X axis 10% of the way across from the left edge of the gauge, so if you want to use a higher ratio for the xAxisLength, you must also adjust that option.
Type: Number
Default: 0.8
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            xAxisLength: .9,
            xAxisLocation: 0.05
        }); 
   });
</script>

xAxisLocation

Sets the starting location of the X axis as a percentage of the width of the gauge.
Note: By default, the xAxisLength option is set to draw the X axis 80% of the width the gauge, so if you want to center the axis within the gauge, you must also adjust that option.
Type: Number
Default: 0.1
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            xAxisLength: .9,
            xAxisLocation: 0.05
        }); 
   });
</script>

yAxisLocation

Sets the base vertical location of the pointer, tick marks and labels on the X axis as a percentage of the height of the gauge. (Note that there is no actual Y axis in the LinearGauge.) By default, it is centered in the gauge. A setting of 0.8 moves the pointer, tick marks, and labels toward the bottom edge of the gauge, as in the image below.
Type: Number.
Default: 0.5
Code Example:
<script type="text/javascript">
    $(document).ready(function () { 
        $("#lineargauge1").wijlineargauge({ 
            value: 31,
            yAxisLocation: 0.8
        }); 
   });
</script>
LinearYAxisLocation.png

Events

The following events are available in the wijlineargauge widget:

beforeValueChanged

Fires before the value changschanges, this event can be called.
Type: Function
Default: null
Parameters:
  • e: jQuery.Event object
  • arg
  • arg.oldValue: the gauge's old value.
  • arg.newValue: the value to be seted.
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 seted.
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 available in the wijlineargauge widget:

destroy

Removes the functionality completely. This will return the element back to its pre-init state.
Code Example:
$("#lineargauge").wijlineargauge("destroy");

disabled

Disables the wijlineargauge.
Code Example:
$("#lineargauge").wijlineargauge("disabled");

enabled

Enables the wijlineargauge.
Code Example:
$("#lineargauge").wijlineargauge("enabled");

getCanvas

Returns a reference to the Raphael canvas object.
Code Example:
$("lineargauge").wijlineargauge("getCanvas");

option

Gets or sets any wijlineargauge option. If no value is specified, it acts as a getter.
Parameters:
  • optionName: Represents the name of the option to get or set.
Type: String
  • value: Represents the value to set.
Code Example:
$("#lineargauge").wijlineargauge("width");
$("#lineargauge").wijlineargauge("width", 600);

option

Sets multiple wijlineargauge options at once by providing an options object.
Parameter:
  • options: Represents the options values to set.
Type: Object.
Code Example:
$("#lineargauge").wijlineargauge("option", {width: 800, height: 600});

redraw

Redraws the gauge.
Code Example:
$("#lineargauge").wijlineargauge("redraw");

widget

Returns the wijlineargauge element.
Code Example:
$("#lineargauge").wijlineargauge("widget");
Retrieved from "http://wijmo.com/wiki/index.php/LinearGauge"