UI_PieChart

   <task pointer> = UI_PieChart( <parent pointer>, <order>, <x>, <y>, <width>, <height>,
                              <image asset>, <start-angle>, <end-angle> [ , <anim time>, <initial-value> ])

引数

  • <parent pointer> 親UIのポインタ
  • <order> 表示プライオリティ
  • <x>, <y> 表示座標
  • <width>, <height> 円グラフ全体の表示域サイズ
  • <image asset> 円グラフ変化部の画像
  • <start-angle> 0.0点となる角度。単位はdegree(0～360)
  • <end-angle> 1.0点となる角度。単位はdegree(<start-angle>+360.0まで)
  • <anim time> 値を指定してから、実際にグラフの表示がその値に到達するまでのアニメーション時間(単位: [ms])。0を指定するとアニメーション無し。
  • <initial-value> 初期値。0.0～1.0の間で指定(デフォルト値: 0.0)

戻り値

  • <task pointer> 生成された UI_PieChart タスクのポインタ

解説

指定された長方形のテクスチャを中心点を頂点とし、指定角度で切り取って表示する。

表示される角度は別途propertyやsysCommandで指定されるvalueの値(0.0～1.0)に比例する。

通常は円グラフの表示に用いられるが、画像表示上の効果としても応用できるかもしれない。

<start-angle> <= <end-angle> の場合、<value>値の増加とともに円グラフは時計廻り方向に成長する。

<start-angle> >= <end-angle> の場合、<value>値の増加とともに円グラフは反時計廻り方向に成長する。

制約事項

このタスクを使用する上では下記の制約がある。

  • 使用される画像assetは、必ず4頂点かつ、頂点indexが左上から時計回りに割り当てられている必要がある。
  • <start-angle>から<end-angle>までの角度は絶対値が360度を越えてはならない(例: <start-angle> = 270.0, <end-angle> = 630.0 などは可)。
  • <start-angle>と<end-angle>の差の絶対値が315度を超えるとき、<start-angle>は45度単位で指定されねばならない。

上記の制約に抵触する値を指定した場合の動作は保証されない。

二番目、三番目の制約がつく理由は下記の通り。

UI_PieChart は、指定されたテクスチャを下記のように45°単位で8つの三角形に分割し、 それぞれの三角形を45°までのタンジェントを用い必要な角度分だけ表示することで実現されている。 たとえば、0°位置から68°分だけを表示するならば、45°の三角形と23°の三角形二枚分となる。

このため、表示角が360°を超えた場合、重複して表示する分の三角形を持たないため、 <start-angle>から<end-angle>の間の角度は360°以下に限られる。

また、一つの45°エリアには一つの三角形しか割り当てられていない。 このため、開始角が45°境界に無い状態で、<start-angle>から<end-angle>の間が315°を超えると、 下記のような問題が起こりうる。

下図において、右上の緑色に着色されたエリアには一つの三角形しかないが、 実際に描画すべき三角形が二つ分生じてしまう。このため、正しい表示を保証することができなくなる。

どうしてもこの制約に抵触する表現が必要な場合は、UI_PieChart の標準プロパティ .rot を使用して回転させることで実現できる。

コマンド

UI_PIE_SET_START
<start-angle>に相当する角度を指定する。
  • UI_PIE_SET_START 
       pPieChart = UI_PieChart(...)
   sysCommand(pPieChart, UI_PIE_SET_START, <start-angle>)
UI_PIE_SET_END
<end-angle>に相当する角度を指定する。
  • UI_PIE_SET_END 
       pPieChart = UI_PieChart(...)
   sysCommand(pPieChart, UI_PIE_SET_END, <end-angle>)
UI_PIE_SET_VALUE
円グラフの進捗を設定する。進捗は 0.0から 1.0の間(実数)で与える。
  • UI_PIE_SET_VALUE 
       pPieChart = UI_PieChart(...)
   sysCommand(pPieChart, UI_PIE_SET_VALUE, <value>)