ThingWorxのGauge Widgetの使いかた

ThingWorx の Gauge Widget（以下ゲージ・ウィジェット）は初期設定のまま使われていることをよく見かけますが、少しの設定を施すだけで大幅に見やすくなります。設定パネルでの指定方法が少々分かりづらいので、ここに解説します。

対象バージョンと有効期限:
この記事は 2018年 8月に、ThingWorx 8 を対象に書かれています。ThingWorx 9 以降では設定方法に互換性がない場合があります。

対象読者：
ThingWorx の Mashup Builder の使いかたを学んでいる人を対象としています。この記事では Mashup Builder の使いかたや Style Definition（以下スタイル定義）、State Definition（以下ステート定義）の詳しい説明はしません。

リソース：
本記事で作っているゲージのサンプルは、→ここからダウンロードできます。ダウンロードした XML ファイルを ThingWorx にインポートすることで利用できます。

ゲージ・ウィジェットの初期設定とカスタム設定例

下記画像の左側の青いゲージ・ウィジェットが、デフォルト設定の表示です。この記事では、右側にあるようなさまざまな表示をゲージ・ウィジェットに指定する方法を説明します。

まずはともあれ、ゲージ・ウィジェットの設定方法の基本を見ていきましょう。ゲージ・ウィジェットはその他のウィジットと同様に、表示のカスタマイズは設定パネルを通して行います。下記がゲージ・ウィジェットの設定パネルです。なお設定パネルでは初期値から変更したものは薄緑色にマークされますので、どの部分がカスタム値になっているかを見分ける参考にしてください。

また、ゲージはいくつかのパーツに別れています。大まかに分けてゲージの盤面（Face）、針（Needle）、枠（GaugeBorder)、リング（Ring)、基部（Center)、インデックス（Ticks / MinorTicks）となります。それぞれの部位がゲージのどの部分に相当するかは、下記の画像を参考にしてください。

範囲設定

最大値・最小値

項目	設定値
MinValue	ゲージの最小値。0 より小さくても構わなが、数値である必要がある。後述する ReferenceAngle が初期値（270)のときには、時計の7時くらいに位置する。
MaxValue	ゲージの最大値。100より大きくても構わないが、数値である必要がある。ReferenceAngle が初期値のときには、時計の5時くらいに位置する。

バインドされているプロパティの値が MinValue よりも小さい場合には、ゲージの針は左方向に振り切って表示されます。同様に MaxValue よりも大きい場合には、右方向に振り切ります。温度などの負の値を取りうるデータは、初期値の MinValue = 0, MaxValue = 100 では適しませんので、これらの値は積極的に調整することが望ましいです。

色の指定

項目	設定値
GaugeStyle	ゲージの全体的な色指定をおこないます。初期値では表示色・背景色・線色ともに指定されていません。通常はこの設定を変更する必要はありません。
GaugeBorderStyle	ゲージの縁取りの色を指定します。後述する GaugeBorder に指定したピクセル幅でゲージの幅が描画されます。
GaugeFaceStyle	ゲージの一番大きな面積を占める盤面（フェース）の色指定です。
NeedleStyle	ゲージの針の色指定です。
CenterStyle	ゲージの針の根元を占める基部（ピン）の色指定です。

CenterStyle の指定は注意が必要です。針の根元を覆い隠すように基部が配置されますので、CenterStyle を無色透明に指定してしまうと、針の根元が表示されてしまいます。基部が無いように見せかけるには、GaugeFaceStyle に指定した色と同じものを CenterStyle に指定します。

インデックスの間隔と長さの設定

項目	設定値
Intervals	ゲージの周囲に配置されるインデックスの、長いほうの数を指定します。
IntervalsPerLabel	ゲージ周囲に配置される数値表示を、長インデックスいくつごとに表示するかを指定します。
LabelStyle	ゲージの周囲に配置される数値の表示色を指定します。
LabelDisplayMode	ゲージの周囲に配置される数値の表示場所を指定します。Outside を指定すると、インデックスの外に表示されます。Insideを指定すると、インデックスの内側に表示されます。
TickStyle	長インデックスと短インデックスの表示色を指定します。
MinorTicks	長インデックスを短インデックスで分割する数を指定します。
TickLength	長インデックスの長さをピクセルで指定します。
MinorTickLength	短インデックスの長さをピクセルで指定します。

ゲージの周囲には、針の指している数値を読み取りやすくするためにインデックスと数値表示が配置されます。インデックスには長インデックス（Tick）と短インデックス（MinorTicks）があります。長インデックスは (MaxValue - MinValue) / Intervals ごとに表示されます。また、短インデックスは長インデックスを MinorTicks で割った単位ごとに表示されます。

たとえば、MinValue = 0, MaxValue = 100 のとき、Intervals を 10、MinorTicks を 5に指定すると、長インデックスは 10, 20, 30 と 10刻みで、短インデックスは 2 刻みで表示されます。

プロパティ値の表示設定

項目	設定値
ValueStyle	プロパティ値をデジタル表示するさいの表示色・背景色を指定します。
ValueDisplayMode	プロパティ値をどの場所に表示するかを指定します。Bottomではゲージの外側下部に、Inside ではゲージの内側下部に、Topではゲージの外側上部に、そして None では表示を行いません。
LabelDigits	この項目は ValueDisplay の後にあるので紛らわしいですが、上述の LabelDisplayMode で表示される、インデックスの数値表示の桁数を指定します。
LabelDecimals	インデックスの数値表示の小数点以下の桁数を指定します。
ValueDigits	プロパティ値のデジタル表示の桁数を指定します。
ValueDecimals	プロパティ値のデジタル表示の小数点以下の桁数を指定します。

下記画像は ValueDisplayMode の設定を、左から順番に "None", "Bottom", "Top", "Inside" に指定しています。

アングル・開口度・リング幅の設定

項目	設定値
ReferenceAngle	ゲージの MinValue を開始する位置を指定します。真上を 0度（360度）として時計回りに角度を指定します。たとえば左 90度からゲージを開始したい時には、270を指定します。
Aperture	ゲージの開く角度を指定します。ReferenceAngle からスタートして、時計回りに Aperture で指定した角度になるまで、ゲージが開きます。
NeedleDiameter	ゲージの針の、根元の直径を指定します。
CenterDiameter	ゲージの針の根元を覆う基部の直径を指定します。ここで指定したピクセル数ぶんだけ、CenterStyle で指定した色に塗りつぶされます。
GaugeBorder	ゲージの枠の幅を指定します。ここで指定したピクセル数ぶんだけ、GaugeBorderStyle に指定した色で塗りつぶされます。
RingWidth	ゲージの枠の内側にある領域の幅を指定します。

RingWidth には特殊な用途があります。ゲージ・ウィジェットにステート定義を割り当てた際、ステート定義内の各スタイル定義は二つの場所に適用されます。一つ目は針の色で、もう一つは RingWidth で指定された領域です。下記の画像は RingWidth を 10 にしてステート定義を設定した例です。グラデーションがかかっている部分が RingWidth で、その外側の灰色の部分が GaugeBorder になります。

サンプル画像のゲージを作ってみる。

それでは、下記画像のサンプルをゲージ・ウィジェットの標準機能だけで作っていきましょう。

レスポンシブと固定サイズについて

ゲージ・ウィジェットはレスポンシブ・ウィジェットです。配置する領域が固定サイズでない場合には自動的に大きさが調整されます。ゲージの微調整を行う場合には、この「自動調整される」機能が邪魔になることがあります。ここでは、説明を簡単にするためにレスポンシブではなく固定サイズのマッシュアップを作成し、ゲージ・ウィジェットも固定サイズで使用します。

1: マッシュアップを新規に作る

マッシュアップを固定サイズで作成します。上記サンプル画面のサイズは横 400ピクセル、縦 480ピクセルです。

2: マッシュアップにスタイルを適用する

スタイル定義を新たに作成します。

項目	設定値
Background Color	#686868
Secondary Background Color	禁止
Foreground Color	#ffffff
Line Color	禁止
Line Thickness	0
Line Style	Solid
Text Size	11px(M)

作成したスタイルを、マッシュアップのスタイルとして割り当てます。

3: ゲージ・ウィジェット用のスタイルを作成する

ゲージ用のスタイル定義をふたつ作成します。

GaugeFace用スタイル定義

項目	設定値
Background Color	#585858
Secondary Background Color	#686868
Foreground Color	禁止
Line Color	禁止
Line Thickness	0
Line Style	Solid
Text Size	11px(M)

マッシュアップの背景色（#686868）と GaugeFace の第二背景色が同じ色に設定されていることに注意してください。GaugeFace では、背景色から第二背景色に向かって、中央から円周部へグラデーションがかけられます。このため、ゲージの周辺はマッシュアップの背景色と同じ色で塗りつぶされ、結果としてゲージと周囲との境界が見えなくなります。（後述する GaugeBorder を非表示にする必要があります）。

CenterStyle用スタイル定義

項目	設定値
Background Color	#6f6f6f
Secondary Background Color	#686868
Foreground Color	禁止
Line Color	禁止
Line Thickness	0
Line Style	Solid
Text Size	11px(M)

CenterStyle は、ゲージの基部へ適用されますが、背景色から第二背景色へ向かって中央から周辺へグラデーションします。ゲージの基部周辺では #686868 で描画されますが、これは GaugeFace の周辺色と同じ色です。一方、基部が接するあたりの盤面の色は、#585858 から少しだけ明るくなった色です。

作成したふたつのスタイル定義を、GaugeFaceStyleとCenterStyleに割り当てます。

4: ゲージの表示形式を指定する

項目	設定値
ReferenceAngle	205
Aperture	310
NeedleDiameter	14
CenterDiameter	64
GaugeBorder	0
RingWidth	12

GaugeBorder = 0 の設定には注意が必要です。GaugeBorder を 0 に設定しても、上述の GaugeBorderStyle に指定しているスタイル定義の線幅が 1px 以上あって、線色が設定されている場合には、GaurgeBorder 部分に線色が描画されます。GaugeBorder を完全に無くしたい場合には、GaugeBorderStyle には「すべての色が禁止になっており、かつ線幅が 0px」のスタイルを指定し、かつ GaugeBorder を 0 に指定します。

5: ゲージの大きさを絶対値で指定する

項目	設定値
Width	200
Height	200

もしもゲージ・ウィジェットの設定項目として Width や Height が表示されていない場合は、ゲージ・ウィジェットがレスポンシブ・ウィジェットとして配置されています。マッシュアップを固定サイズにするか、パネル・ウィジェット（Panel）を配置して固定サイズに切り替えてください。

ここまでの設定で、下記のような表示になっているはずです。MinValueとMaxValueは、バインドする Thing のプロパティ値に合わせて適宜設定してください。サンプルでは MinValue = 0, MaxValue = 6000となっています。

6: リング周辺部にグラデーションを加える

サンプルには、リング周辺に緑から赤にグラデーションするリングが描かれています。これを作りましょう。

リングの周辺部は、RingWidth で設定したピクセル幅がとられています。この領域は、指定したステート定義に従って描画されます。初期値ではステート定義が指定されていないので、RingWidth に相当する領域は GaugeFaceStyle によって描画されます。

6.1: グラデーションに含まれる色のスタイル定義を作成する。

新しいスタイル定義を作ります。

項目	設定値
Background Color	#c6eddb
Secondary Background Color	禁止
Foreground Color	禁止
Line Color	禁止
Line Thickness	0
Line Style	Solid
Text Size	11px(M)

上記で作ったスタイル定義をコピーして、全部で10個ほどのスタイル定義を作ります。それぞれのスタイル定義は、Background Color が異なります。以下は、ここのスタイル定義で指定する Background Color の一覧になります。

スタイル定義	Background Color の値
Sample.Gradient.01.Style	#c6eddb
Sample.Gradient.02.Style	#d1f1cc
Sample.Gradient.03.Style	#eef5d3
Sample.Gradient.04.Style	#f8fad4
Sample.Gradient.05.Style	#fffbd5
Sample.Gradient.06.Style	#fef7d5
Sample.Gradient.07.Style	#fcf1d3
Sample.Gradient.08.Style	#f9dfd5
Sample.Gradient.09.Style	#f6d4d8
Sample.Gradient.10.Style	#f3d1d5

10個のスタイル定義が作成されたこと確認します。

なお、美しいグラデーションを作成するコツは、カラーホイール上で同じ同心円に属する隣り合う色を採用することです。カラーホイールは、HUE /360 The COlor Scheme Application などで参照できます。

6.2: ステート定義を作成する

さきほど作成した 10個のスタイル定義を使用して新たなステート定義を作成します。ステート定義の "States" には Numeric Range を指定し、"Add State" ボタンを押して上記ステップで作成したスタイル定義を読み込んでください。

6.3: ステート定義をゲージ・ウィジェットに適用する

ゲージ・ウィジェットの設定で、"ValueFormatter" の "State Formatting" ボタンをクリックして、ステート定義を割り当てます。

ステート定義を割り当てる際、Value は適切に設定します。ステート定義の作成時にセットした値で問題なければ、そのままでも構いません。

ここまでの作業で、ゲージは次のような見た目になっています。

7: ゲージを装飾する

さらに作業を進めましょう。ゲージ・ウィジェットにはもともと、針で数値を指し示す機能の他に、デジタル表示で数値を表示する機能が組み込まれています。デジタル表示は ValueDisplay を "None" 以外に設定すると利用できますが、残念なことに "Top", "Buttom", "Inside", "None" のいずれかの設定しかできません。この記事冒頭のゲージのように、ゲージの中央にデジタル表示する場合には、別の方法をとる必要があります。

今回は、ゲージの中央に LED を配置します。

7.1 LED用の追加のスタイル定義を作る。

下表の設定で、LED用の追加のスタイルを定義します。

項目	設定値
Background Color	禁止
Secondary Background Color	禁止
Foreground Color	#ffffff
Line Color	禁止
Line Thickness	0
Line Style	Solid
Text Size	11px(M)

これは、背景色・線色をすべて透明にし、描画色に白を指定しています。

7.2 LED をゲージの上に配置し、上記手順で作成したスタイルを適用する。

LEDウィジェットをゲージの上に配置し、ゲージ・ウィジェットと同じプロパティをバインドします。

LEDの設定は、下表のとおりです。

項目	設定値
Digits	4
Decimals	0
LEDSize	Extra Small
LEDStyle	上記で作成したLED用の追加スタイル

Digits と Decimals はバインドしているプロパティに即して調整します。今回のプロパティは 0 から 6,000までの値をとるので、Digits（整数部分桁数）を4、Decimals（小数部分桁数）を0にしています。

7.3 ラベルを配置する。

ゲージ・ウィジェットには設定パネルから "Legend" を指定できるようになっています。しかし、Legend も配置位置に自由度はあまりなく、"LegendDisplayMode" から "Top", "Bottom", "None" を選べるのみになっています。

ラベルを自由に配置するためには、ラベル・ウィジェットをゲージ・ウィジェットの上に重ねて配置します。

このとき、ラベル・ウィジェットの設定は下記のようになります。

項目	設定値
Text	RPM
Style	上記でLED用に追加作成したスタイル
Alignment	Center

ここまでの作業で、ゲージは次のように表示されています。

ゲージ・ウィジェットにいろいろな表現

その他、ゲージ・ウィジェトでいろいろと遊んでみましょう。
先ほど作成したゲージ・ウィジェットの設定を変えると、いろいろな表現が可能になります。

項目	設定値
MinValue	0
MaxValue	360
Intervals	12
LabelDisplayMode	None
MinorTicks	0
TickLength	2
MinorTickLength	0
LegendStyle	上記作成のLED用追加スタイル
Legend	Bottom
Legend	方角
ReferenceAngle	0
Aperture	360
GaugeBorder	2
RingWidth	0
Width	80
Height	80

ReferenceAngle ＝ 0 で、MinimalValue にセットされた値は12時に位置します。そこから時計回りに360度展開します。MaxValue = 360 なので、、バインドしているプロパティがMaxValueに到達すると、ゲージの針が一周します。Interval = 12 なので、長インデックスは 30 づつ切られます。

これは、方角や時刻のように切れ目のない針の位置を表現しなければならない時に使えるテクニックです。

項目	設定値
MinValue	0
MaxValue	100
Intervals	12
LabelDisplayMode	None
MinorTicks	0
TickLength	2
MinorTickLength	0
LegendStyle	上記作成のLED用追加スタイル
Legend	Bottom
Legend	電圧
ReferenceAngle	270
Aperture	180
GaugeBorder	2
RingWidth	0
Width	80
Height	80

ReferenceAngle = 270 なので、針のスタート位置は時計の9時の位置になります。またAperture = 180なので、終了位置は時計の3時の位置になります。

項目	設定値
MinValue	0
MaxValue	2
Intervals	2
LabelDisplayMode	None
MinorTicks	0
TickLength	2
MinorTickLength	0
LegendStyle	上記作成のLED用追加スタイル
Legend	Bottom
Legend	PTO
ReferenceAngle	270
Aperture	180
GaugeBorder	2
RingWidth	0
Width	80
Height	80

ReferenceAngle = 270, Aperture = 180 の設定により、針は時計の9時位置からスタートし、3時の位置で終了します。また、MinValue = 0, MaxValue = 2, Interval = 2 ですので、針の取りうる位置は時計の9時、12時、3時のいずれかになります。

ロータリースイッチのポジションを表現するような場合に有効となるテクニックです。

終わりに

以上、ThingWorx 8 のゲージ・ウィジェットの使い方を見てきました。ゲージ・ウィジェットは設定パネルから簡単に見た目が変更でき、その自由度が高いにも関わらず、いまいち「美しくないウィジェットの代表」のように思われている節があります。この記事が少しでもゲージ・ウィジェットが真価を発揮する役に立てるなら幸いです。

了。