Wijmo 5

Gauge 101 (Vue)

This page shows how to get started with Wijmo's Gauge controls.

Getting Started

The wijmo.gauge module includes the LinearGauge, RadialGauge, and BulletGraph controls. They are used to display and optionally edit numeric information graphically.

Steps for getting started with Gauge controls in Vue applications:

  1. Add references to Vue, Wijmo, and Wijmo's Vue interop module.
  2. Create a Vue object and give it a host element.
  3. Add Gauge controls to Vue's host element and bind them to the data.
<!DOCTYPE html> <html> <head> <!-- Vue --> <script src="https://cdnjs.cloudflare.com/ajax/libs/vue/1.0.26/vue.min.js"></script> <!-- Wijmo --> <link href="http://cdn.wijmo.com/5.latest/styles/wijmo.min.css" rel="stylesheet"/> <script src="http://cdn.wijmo.com/5.latest/controls/wijmo.min.js"></script> <script src="http://cdn.wijmo.com/5.latest/controls/wijmo.gauge.min.js"></script> <!-- Wijmo/Vue interop --> <script src="http://cdn.wijmo.com/5.latest/interop/vue/wijmo.vue.min.js"></script> <!-- app scripts and styles --> <link href="styles/app.css" rel="stylesheet" /> <script src="scripts/app.js"></script> </head> <body> <div id="app"> <wj-linear-gauge :value="value" :min="min" :max="max" :format="format"> </wj-linear-gauge> <wj-radial-gauge :value="value" :min="min" :max="max" :format="format"> </wj-radial-gauge> <div class="app-input-group"> <label>value</label> <wj-input-number :value.sync="value" :min="min" :max="max" :format="format" :step="step"> </wj-input-number> </div> </div> </body> </html>
var app = new Vue({ el: '#app', data: { value: 50, min: 0, max: 100, format: 'n0', step: 10, } });

Result (live):

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.

<wj-linear-gauge :value.sync="value" :min="min" :max="max" :format="format" :step="step" :show-ticks="showTicks" :is-read-only="isReadOnly"> </wj-linear-gauge> <wj-radial-gauge :value.sync="value" :min="min" :max="max" :format="format" :step="step" :show-ticks="showTicks" :is-read-only="isReadOnly"> </wj-radial-gauge> <label> isReadOnly <input type="checkbox" v-model="isReadOnly" /> </label> <br/> <label> showTicks <input type="checkbox" v-model="showTicks" /> </label>
// Vue application var app = new Vue({ el: '#app', data: { value: 50, min: 0, max: 100, format: 'n0', step: 10, showTicks: false, isReadOnly: false, } });

Result (live):


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.

<wj-linear-gauge :value.sync="value" :min="min" :max="max" :step="step" :format="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.sync="value" :min="min" :max="max" :step="step" :format="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.sync="value" :min="min" :max="max" :step="step" :format="format" > </wj-input-number> </div>
// Vue application var app = new Vue({ el: '#app', data: { value: 50, min: 0, max: 100, format: 'n0', step: 10, isReadOnly: false, } });

Result (live):

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.

<wj-linear-gauge :value="value" :min="min" :max="max" :format="format" :show-ranges="showRanges"> <wj-range wj-property="pointer" :thickness="ranges.pointerThickness"></wj-range> <wj-range :min="ranges.lower.min" :max="ranges.lower.max" :color="ranges.lower.color"></wj-range> <wj-range :min="ranges.middle.min" :max="ranges.middle.max" :color="ranges.middle.color"></wj-range> <wj-range :min="ranges.upper.min" :max="ranges.upper.max" :color="ranges.upper.color"></wj-range> </wj-linear-gauge> <wj-radial-gauge :value="value" :min="min" :max="max" :format="format" :show-ranges="showRanges"> <wj-range wj-property="pointer" :thickness="ranges.pointerThickness"></wj-range> <wj-range :min="ranges.lower.min" :max="ranges.lower.max" :color="ranges.lower.color"></wj-range> <wj-range :min="ranges.middle.min" :max="ranges.middle.max" :color="ranges.middle.color"></wj-range> <wj-range :min="ranges.upper.min" :max="ranges.upper.max" :color="ranges.upper.color"></wj-range> </wj-radial-gauge> <div class="app-input-group"> <label>value</label> <wj-input-number :value.sync="value" :min="min" :max="max" :step="step" :format="format" > </wj-input-number> </div> <label> showRanges <input type="checkbox" v-model="showRanges" /> </label>
// Vue application var app = new Vue({ el: '#app', data: { value: 50, min: 0, max: 100, format: 'n0', step: 10, isReadOnly: false, 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)' } } } });

Result (live):

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:

The example below shows the effect of these properties on linear and radial gauges:

<h5>Common Properties</h5> <dl class="dl-horizontal"> <dt>hasShadow</dt> <dd> <input type="checkbox" v-model="hasShadow" /> </dd> <dt>isAnimated</dt> <dd> <input type="checkbox" v-model="isAnimated" /> </dd> <dt>showText</dt> <dd> <wj-combo-box :text.sync="showText" :items-source="showTextValues"> </wj-combo-box> </dd> <dt>thumbSize</dt> <dd> <wj-input-number :value.sync="thumbSize" :is-required="false" :min="0" :max="50" :step="5" placeholder="(auto)"> </wj-input-number> </dd> <dt>Gauge Value</dt> <dd> <wj-input-number :value.sync="value" :min="min" :max="max" :step="step" :format="format" > </wj-input-number> </dd> </dl> <h5>LinearGauge Properties</h5> <dl class="dl-horizontal"> <dt>Direction</dt> <dd> <wj-combo-box :text.sync="direction" :items-source="directionValues"> </wj-combo-box> </dd> </dl> <wj-linear-gauge :style="getLinearGaugeStyle()" :value.sync="value" :is-read-only="false" :min="min" :max="max" :step="step" :format="format" :thumb-size="thumbSize" :show-text="showText" :has-shadow="hasShadow" :is-animated="isAnimated" :direction="direction"> </wj-linear-gauge> <h5>RadialGauge Properties</h5> <dl class="dl-horizontal"> <dt>autoScale</dt> <dd> <input type="checkbox" v-model="autoScale" /> </dd> <dt>startAngle</dt> <dd> <wj-input-number :value.sync="startAngle" :min="-360" :max="360" :step="45"> </wj-input-number> </dd> <dt>sweepAngle</dt> <dd> <wj-input-number :value.sync="sweepAngle" :min="0" :max="360" :step="45"> </wj-input-number> </dd> </dl> <wj-radial-gauge :value.sync="value" :is-read-only="false" :min="min" :max="max" :step="step" :format="format" :thumb-size="thumbSize" :show-text="showText" :has-shadow="hasShadow" :is-animated="isAnimated" :auto-scale="autoScale" :start-angle="startAngle" :sweep-angle="sweepAngle"> </wj-radial-gauge>
// Vue application var app = new Vue({ el: '#app', data: { // common properties value: 50, min: 0, max: 100, format: 'n0', step: 10, hasShadow: true, isAnimated: true, thumbSize: null, showText: 'All', showTextValues: 'All,None,Value,MinMax'.split(','), // LinearGauge properties direction: 'Right', directionValues: 'Up,Down,Left,Right'.split(','), // RadialGauge properties autoScale: true, startAngle: 0, sweepAngle: 180 }, methods: { // get the style for the LinearGauge depending on its direction getLinearGaugeStyle: function () { return this.direction == 'Up' || this.direction == 'Down' ? { height: '200px', width: '2em' } : { width: '200px' } } } });

Result (live):

Common Properties
hasShadow
isAnimated
showText
thumbSize
Gauge Value
LinearGauge Properties
Direction
RadialGauge Properties
autoScale
startAngle
sweepAngle

Displaying Text Values

The gauge controls have three properties that affect text display:

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.

<wj-radial-gauge class="text-gauge" :value.sync="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>
// Vue application var app = new Vue({ el: '#app', data: { value: 50, }, methods: { // getText callback used to convert values into strings 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; } } });
/* * Custom CSS rule for "Text" example */ .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.

<h4> Use the gauges to edit this color: <span :style="{ border:'1px solid #333', backgroundColor: 'rgb(' + color.red + ',' + color.green + ',' + color.blue + ')' }">       </span> </h4> <h4> Default Styles</h4> <wj-linear-gauge :value.sync="color.red" :min="0" :max="255" :step="5" :is-read-only="false"> <wj-range wj-property="pointer" color="red"></wj-range> </wj-linear-gauge> <wj-linear-gauge :value.sync="color.green" :min="0" :max="255" :step="5" :is-read-only="false"> <wj-range wj-property="pointer" color="red"></wj-range> <wj-range wj-property="pointer" color="green"></wj-range> </wj-linear-gauge> <wj-linear-gauge :value.sync="color.blue" :min="0" :max="255" :step="5" :is-read-only="false"> <wj-range wj-property="pointer" color="red"></wj-range> <wj-range wj-property="pointer" color="blue"></wj-range> </wj-linear-gauge> <h4> Custom CSS</h4> <wj-linear-gauge class="custom-gauge" :value.sync="color.red" :min="0" :max="255" :step="5" :thumb-size="10" :has-shadow="false" :is-read-only="false"> <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" :value.sync="color.green" :min="0" :max="255" :step="5" :thumb-size="10" :has-shadow="false" :is-read-only="false"> <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" :value.sync="color.blue" :min="0" :max="255" :step="5" :thumb-size="10" :has-shadow="false" :is-read-only="false"> <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>
// Vue application var app = new Vue({ el: '#app', data: { color: { red: 100, green: 100, blue: 100 }, ... } });
/* * Custom CSS rules for "Styling" example */ .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