Getting Started
The wijmo.gauge module includes the LinearGauge, RadialGauge, and
BulletGraph controls. They are used to display and optionally edit numeric
information graphically.
Here are the steps for getting started with the Gauge controls in AngularJS applications:
- Add references to AngularJS, Wijmo, and Wijmo's AngularJS directives.
-
Include the Wijmo directives in the app module:
var app = angular.module('app', ['wj']);
- Add a controller to provide data and logic.
- Add a Wijmo Gauge control to the page and set its value, min, and max properties.
- (Optional) Add some CSS to customize the gauge's appearance.
HTML
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" type="text/css" href="css/bootstrap.css" />
<link rel="stylesheet" type="text/css" href="css/wijmo.css" />
<link rel="stylesheet" type="text/css" href="css/app.css" />
<script src="scripts/angular.js" type="text/javascript"></script>
<script src="scripts/wijmo.js" type="text/javascript"></script>
<script src="scripts/wijmo.gauge.js" type="text/javascript"></script>
<script src="scripts/wijmo.angular.js" type="text/javascript"></script>
<script src="scripts/app.js" type="text/javascript"></script>
</head>
<body ng-app="app" ng-controller="appCtrl">
<!-- Wijmo LinearGauge directive -->
<wj-linear-gauge
value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
format="{{ props.format }}">
</wj-linear-gauge>
<!-- Wijmo RadialGauge directive -->
<wj-radial-gauge
value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
format="{{ props.format }}">
</wj-radial-gauge>
<!-- Wijmo InputNumber directive -->
<div>
<label>value</label>
<wj-input-number
value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
format="{{ props.format }}"
step="{{ props.step }}">
</wj-input-number>
</div>
</body>
</html>
JS
// declare app module
var app = angular.module('app', ['wj']);
// app controller provides data
app.controller('appCtrl', function appCtrl($scope) {
$scope.props = {
value: 50,
min: 0,
max: 100,
step: 10,
format: 'n0'
};
});
Editing (Gauges as Sliders)
In addition to displaying information graphically, gauges can be used as input controls
(in this case they are also known as "sliders").
To use gauge controls for input, set the isReadOnly property to false. This will
allow users to change the gauge's current value simply by clicking or tapping the gauge.
When using gauges as input controls, remember to set the step property to define
the precision of the changes applied by clicking or tapping, as well as the magnitude of
changes applied by spinning the mouse wheel.
You can also use the showTicks property to display tickmarks on the gauge.
The step property determines the spacing between tickmarks.
The example below demonstrates how to use the isReadOnly, step, and
showTicks properties with the LinearGauge and RadialGauge controls.
Showing the Thumb
By default, gauges indicate the current value by filling the control with color.
You can use the thumbSize property to add a visual element that highlights
the current value.
The example below demonstrates how to use the thumbSize property.
The example also reduces the thickness property of the gauge's face
and pointer ranges so the thumb becomes more visible.
HTML
<wj-linear-gauge
value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
step="{{ props.step }}"
format="{{ props.format }}"
is-read-only="false"
is-animated="false"
thumb-size="10">
<wj-range wj-property="face" thickness="0.25"></wj-range>
<wj-range wj-property="pointer" thickness="0.25"></wj-range>
</wj-linear-gauge>
<wj-radial-gauge
value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
step="{{ props.step }}"
format="{{ props.format }}"
is-read-only="false"
is-animated="false"
thumb-size="10">
<wj-range wj-property="face" thickness="0.08"></wj-range>
<wj-range wj-property="pointer" thickness="0.08"></wj-range>
</wj-radial-gauge>
<div class="app-input-group">
<label>value</label>
<wj-input-number
value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
format="{{ props.format }}"
step="{{ props.step }}">
</wj-input-number>
</div>
JS
// declare app module
var app = angular.module('app', ['wj']);
// app controller provides data
app.controller('appCtrl', function appCtrl($scope) {
$scope.props = {
value: 50,
min: 0,
max: 100,
step: 10,
format: 'n0'
};
});
Using Ranges
All Wijmo gauges have a ranges property that contains an array of Range objects.
By default, ranges are displayed on the face of gauge to indicate zones of interest; however,
you can use the showRanges property to hide the ranges. In this case, the gauge determines
which range contains the current value and applies that range's color to the gauge pointer.
You can customize each Range object using the min, max, and color properties.
The following example demonstrates how to use ranges with the LinearGauge and RadialGauge controls.
HTML
<wj-linear-gauge value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
format="{{ props.format }}"
show-ranges="{{ props.showRanges }}">
<wj-range
wj-property="pointer"
thickness="{{ props.ranges.pointerThickness }}"></wj-range>
<wj-range
min="{{ props.ranges.lower.min }}"
max="{{ props.ranges.lower.max }}"
color="{{ props.ranges.lower.color }}"></wj-range>
<wj-range
min="{{ props.ranges.middle.min }}"
max="{{ props.ranges.middle.max }}"
color="{{ props.ranges.middle.color }}"></wj-range>
<wj-range
min="{{ props.ranges.upper.min }}"
max="{{ props.ranges.upper.max }}"
color="{{ props.ranges.upper.color }}"></wj-range>
</wj-linear-gauge>
<wj-radial-gauge
value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
format="{{ props.format }}"
show-ranges="{{ props.showRanges }}">
<wj-range
wj-property="pointer"
thickness="{{ props.ranges.pointerThickness }}"></wj-range>
<wj-range
min="{{ props.ranges.lower.min }}"
max="{{ props.ranges.lower.max }}"
color="{{ props.ranges.lower.color }}"></wj-range>
<wj-range
min="{{ props.ranges.middle.min }}"
max="{{ props.ranges.middle.max }}"
color="{{ props.ranges.middle.color }}"></wj-range>
<wj-range
min="{{ props.ranges.upper.min }}"
max="{{ props.ranges.upper.max }}"
color="{{ props.ranges.upper.color }}"></wj-range>
</wj-radial-gauge>
<div class="app-input-group">
<label>value</label>
<wj-input-number
value="props.value"
min="{{ props.min }}"
max="{{ props.max }}"
format="{{ props.format }}"
step="{{ props.step }}">
</wj-input-number>
</div>
<label>
showRanges
<input type="checkbox" ng-model="props.showRanges" />
</label>
JS
// declare app module
var app = angular.module('app', ['wj']);
// app controller provides data
app.controller('appCtrl', function appCtrl($scope) {
$scope.props = {
format: 'p0',
value: 50,
min: 0,
max: 100,
step: 10,
showRanges: true,
ranges: {
pointerThickness: 0.5,
lower: { min: 0, max: 33, color: 'rgba(255,100,100,.5)' },
middle: { min: 33, max: 66, color: 'rgba(255,255,100,.5)' },
upper: { min: 66, max: 100, color: 'rgba(100,255,100,.5)' }
};
});
Layout and Appearance Properties
The gauge controls are designed to be styled mostly with CSS, but they do
have several properties that affect their layout and appearance:
-
thumbSize: Determines the size of the thumb element used to
display the current value.
-
showText: Determines whether the gauge should show min, max,
and/or current values as text elements.
-
hasShadow: Determines whether the gauge should add a shadow
effect to the face and value ranges.
-
isAnimated: Determines whether the gauge should use animation
when updating the current value.
-
autoScale: Determines whether radial gauges should be scaled
automatically to fill the control.
-
startAngle, sweepAngle: Determine the start and sweeping angles
for radial gauges. Angles are measured in degrees, clockwise, starting
from the 9 o'clock position.
-
direction: Determines the direction in which linear gauges are filled.
The example below shows the effect of these properties on linear and radial gauges:
HTML
<wj-linear-gauge
value="props.value"
is-read-only="false"
min="{{ props.min }}"
max="{{ props.max }}"
step="{{ props.step }}"
format="{{ props.format }}"
thumb-size="{{ props.thumbSize }}"
show-text="{{ props.showText }}"
has-shadow="{{ props.hasShadow }}"
is-animated="{{ props.isAnimated }}"
direction="{{ props.direction }}">
</wj-linear-gauge>
<wj-radial-gauge
value="props.value"
is-read-only="false"
min="{{ props.min }}"
max="{{ props.max }}"
step="{{ props.step }}"
format="{{ props.format }}"
thumb-size="{{ props.thumbSize }}"
show-text="{{ props.showText }}"
has-shadow="{{ props.hasShadow }}"
is-animated="{{ props.isAnimated }}"
auto-scale="{{ props.autoScale }}"
start-angle="{{ props.startAngle }}"
sweep-angle="{{ props.sweepAngle }}">
</wj-radial-gauge>
JS
// declare app module
var app = angular.module('app', ['wj']);
// app controller provides data
app.controller('appCtrl', function appCtrl($scope) {
$scope.props = {
value: 50,
min: 0,
max: 100,
step: 10,
format: 'n0',
thumbSize: null,
showText: 'All',
isAnimated: true,
hasShadow: true,
direction: 'Right',
autoScale: true,
startAngle: 0,
sweepAngle: 180
};
});
Result (live):
Common Properties
LinearGauge Properties
RadialGauge Properties
Displaying Text Values
The gauge controls have three properties that affect text display:
-
showText: Determines whether the gauge should show min, max,
and/or current values as text elements,
-
format: Sets the format string used to convert numeric values
into strings, and
-
getText: An optional callback function used to provide customized
strings to display for each type of value.
The example below shows how to use the getText callback to provide
custom strings for the gauge value. Click the gauge to change its value
and notice how the value displayed changes between "Empty", "Low", "Good",
and "Full".
The example also changes the font color and weight using CSS.
HTML
<wj-radial-gauge
class="text-gauge"
value="props.value"
is-read-only="false"
show-ranges="false"
get-text="getText">
<wj-range min="0" max="10" color="red"></wj-range>
<wj-range min="10" max="25" color="yellow"></wj-range>
<wj-range min="25" max="100" color="green"></wj-range>
</wj-radial-gauge>
JS
// getText callback to convert values into strings
$scope.getText = function (gauge, part, value, text) {
switch (part) {
case 'value':
if (value <= 10) return 'Empty!';
if (value <= 25) return 'Low...';
if (value <= 95) return 'Good';
return 'Full';
case 'min':
return 'EMPTY';
case 'max':
return 'FULL';
}
return text;
}
CSS
.text-gauge.wj-gauge text {
fill: #7c7cff;
font-weight: bold;
}
Result (live):
Styling
The appearance of the gauge controls is primarily defined in CSS. To customize it, copy the
CSS rules from the default theme to a new CSS file and modify the rules as needed.
In this example, we added a "custom-gauge" class to the gauges and defined some CSS rules to
customize the appearance of the gauge's "face" range and of the thumb. The custom CSS rules
also use the "wj-state-focused" class to increase the size of the thumb when the gauge has
the focus.
HTML
<h4>
Default Styles
</h4>
<wj-linear-gauge is-read-only="false" min="0" max="255" step="5" value="color.red">
<wj-range wj-property="pointer" color="red"></wj-range>
</wj-linear-gauge>
<wj-linear-gauge is-read-only="false" min="0" max="255" step="5" value="color.green">
<wj-range wj-property="pointer" color="green"></wj-range>
</wj-linear-gauge>
<wj-linear-gauge is-read-only="false" min="0" max="255" step="5" value="color.blue">
<wj-range wj-property="pointer" color="blue"></wj-range>
</wj-linear-gauge>
<h4>
Custom CSS
</h4>
<wj-linear-gauge class="custom-gauge" thumb-size="10" has-shadow="false"
is-read-only="false" min="0" max="255" step="5" value="color.red">
<wj-range wj-property="face" thickness="0.25"></wj-range>
<wj-range wj-property="pointer" thickness="0.25" color="red"></wj-range>
</wj-linear-gauge>
<wj-linear-gauge class="custom-gauge" thumb-size="10" has-shadow="false"
is-read-only="false" min="0" max="255" step="5" value="color.green">
<wj-range wj-property="face" thickness="0.25"></wj-range>
<wj-range wj-property="pointer" thickness="0.25" color="green"></wj-range>
</wj-linear-gauge>
<wj-linear-gauge class="custom-gauge" thumb-size="10" has-shadow="false"
is-read-only="false" min="0" max="255" step="5" value="color.blue">
<wj-range wj-property="face" thickness="0.25"></wj-range>
<wj-range wj-property="pointer" thickness="0.25" color="blue"></wj-range>
</wj-linear-gauge>
CSS
.custom-gauge.wj-gauge {
padding: 0px 10px;
}
.custom-gauge.wj-gauge .wj-face path {
fill: #d0d0d0;
stroke: none;
}
.custom-gauge.wj-gauge .wj-pointer path {
fill: #404040;
stroke: none;
}
.custom-gauge.wj-gauge circle.wj-pointer {
fill: #404040;
stroke: none;
}
.custom-gauge.wj-gauge.wj-state-focused circle.wj-pointer {
fill: red;
stroke: black;
stroke-width: 8px;
}
Result (live):
Use the gauges to edit this color:
Default Styles
Custom CSS