Alexa Vector Graphics形式



Alexa Vector Graphics形式

Alexa Vector Graphics(AVG)は、ベクターグラフィックを定義するための形式です。AVGはScalable Vector Graphics(SVG)のパラメーター化されたサブセットであり、SVGを選択するとグラフィックを複数のオペレーティングシステムに移植できます。AVGで定義されたグラフィックは、VectorGraphicコンポーネントを使って表示できます。VectorGraphicコンポーネントでは、APLパッケージ、APLドキュメント、URLのいずれかからAVGオブジェクトを読み込めます。

プロパティ

AVGオブジェクトには以下のプロパティがあります。

プロパティ デフォルト 説明
description 文字列 "" このベクターグラフィックの任意の説明です。
height 絶対ディメンション 必須 グラフィックの高さです。
item/items AVG項目の配列 [] 描画項目の配列です。各項目はグループまたはパスのどちらかです。
parameters AVGパラメーターの配列 [] AVGオブジェクトに設定できるパラメーター値の配列です。
scaleTypeHeight none | grow | shrink | stretch none グラフィックの高さに応じて、viewportの高さがどのように変化するかを指定します。
scaleTypeWidth none | grow | shrink | stretch none グラフィックの幅に応じて、viewportの幅がどのように変化するかを指定します。
type "AVG" 必須 ベクターグラフィックの種類です。
version "1.0" 必須 AVG規格の現在のリリースバージョンです。
viewportHeight 数値 <height> viewportの高さです。
viewportWidth 数値 <width> viewportの幅です。
width 絶対ディメンション 必須 グラフィックの幅です。

以下の例では、赤で塗りつぶしたひし形を定義しています。

{
  "type": "AVG",
  "version": "1.0",
  "height": 100,
  "width": 100,
  "items": {
    "type": "path",
    "fill": "red",
    "stroke": "blue",
    "strokeWidth": 4,
    "pathData": "M 50 0 L 100 50 L 50 100 L 0 50 z"
  }
}

height

AVGオブジェクトのデフォルトの高さ(絶対位置)です。何らかの方法でオーバーライドまたはサイズ調整されない限り、AVGオブジェクトは画面上のこの高さに表示されます。これは絶対ディメンションでなければなりません。

item/items

AVG項目の配列です。配列は描画順であるため、後の項目が前の項目の上に表示されます。AVG項目には、作成されたAVG項目を指定するtypeプロパティがあります。現時点では、次の2つがあります。

parameters

AVGデータを評価する際にデータバインディングコンテキストに追加する、名前付きの値の配列です。各パラメーターは以下を含むオブジェクトです。

プロパティ 必須 説明
name 文字列 パラメーターの名前です。
description 文字列 パラメーターの任意の説明です。
type any | string | number | color パラメーターの型です。デフォルトは「any」です。
default any パラメーターに代入するデフォルト値です。デフォルトは、空白の文字列(typeが指定されていない場合)または型に該当する空白の値です。

次のAPLドキュメントでは、colorstrokeの幅のパラメーターを指定して、円形のベクターグラフィックを定義しています。このドキュメントのContainerは、さまざまなパラメーター設定を使用してグラフィックを3回インフレートします。

{
  "type": "APL",
  "version": "1.0",
  "graphics": {
    "parameterizedCircle": {
      "type": "AVG",
      "version": "1.0",
      "height": 100,
      "width": 100,
      "parameters": [
        {
          "name": "circleColor",
          "type": "color",
          "default": "black"
        },
        {
          "name": "circleBorderWidth",
          "type": "number",
          "default": 2
        }
      ],
      "items": [
        {
          "type": "path",
          "pathData": "M25,50 a25,25 0 1 1 50,0 a25,25 0 1 1 -50,0",
          "stroke": "${circleColor}",
          "strokeWidth": "${circleBorderWidth}",
          "fill": "none"
        }
      ]
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Container",
      "direction": "row",
      "items": {
        "type": "VectorGraphic",
        "source": "parameterizedCircle",
        "width": 100,
        "height": 100,
        "circleColor": "${data.color}",
        "circleBorderWidth": "${data.width}"
      },
      "data": [
        {
          "color": "red",
          "width": 5
        },
        {
          "color": "green",
          "width": 10
        },
        {
          "color": "blue",
          "width": 15
        }
      ]
    }
  }
}

便宜上、名前付きのパラメーターに名前しか指定されていない場合は、簡潔な文字列に短縮できます。

ユーザー定義のパラメーターに加えて、暗黙的に指定される2つのパラメーター、heightwidth(両方とも数値)があります。これらは、サイズ調整されたviewportWidth値とviewportHeight値です。たとえば、高さstartingPixelHeightのベクターグラフィックがContainerに配置され、新しいサイズのscaledPixelHeightに合わせてサイズ調整されるように指示されているとします。この場合、内部でバインドされるheightwidthの値は次の式で取得されます。

function calculateScale( double scale, ScaleType scaleType ) {
  switch (scaleType) {
    case "none":
      return 1.0;
    case "grow":
      return scale > 1.0 ? scale : 1.0;
    case "shrink":
      return scale < 1.0 ? scale : 1.0;
    case "stretch":
      return scale;
  }
}

height = viewportHeight * calculateScale( scaledPixelHeight / startingPixelHeight, scaleTypeHeight );
width = viewportWidth * calculateScale( scaledPixelWidth / startingPixelWidth, scaleTypeWidth );

scaleTypeHeightとscaleTypeWidth

scaleTypeHeightプロパティとscaleTypeWidthプロパティは、サイズ調整に応じてグラフィックの内部(viewport)の高さと幅をどのように変更するのかを制御します。有効なオプションは次のとおりです。

ScaleType 説明
none viewportのディメンションは変更されません(デフォルト)。
stretch viewportのディメンションは、描画ディメンションの変更に比例して拡大または縮小します。
grow viewportのディメンションは、描画ディメンションの変更に比例して拡大しますが、縮小はしません。
shrink viewportのディメンションは、描画ディメンションの変更に比例して縮小しますが、拡大はしません。

「錠剤型」のベクターグラフィック(縦型のスクロールバーやインジケーターなど)を例に挙げてみましょう。グラフィックのデザインは、上部と下部に丸みのある角を持つ縦長の長方形(塗りつぶしなし)です。ベクターグラフィックの縦方向の拡大縮小に応じて、丸みのある角の形状を維持しながら、中央の縦線を拡大縮小します。このグラフィックを簡単に定義するには、viewportが縦方向に拡大縮小するようにし、viewportの高さに応じてパスの縦方向のセグメントを描画する、パラメーター化された式を描画パスに挿入します。次に例を示します。

    {
      "type": "APL",
      "version": "1.0",
      "graphics": {
        "myPillShape": {
          "type": "AVG",
          "version": "1.0",
          "height": 100,
          "width": 100,
          "parameters": [ "myScaleType" ],
          "scaleTypeHeight": "${myScaleType}",
          "items": [
            {
              "type": "path",
              "pathData": "M25,50 a25,25 0 1 1 50,0 l0 ${height-100} a25,25 0 1 1 -50,0 z",
              "stroke": "black",
              "strokeWidth": 20
            }
          ]
        }
      },
      "mainTemplate": {
        "parameters": [
          "payload"
        ],
        "item": {
          "type": "Container",
          "direction": "row",
          "items": {
            "type": "VectorGraphic",
            "source": "myPillShape",
            "width": 100,
            "height": 200,
            "scale": "fill",
            "myScaleType": "${data}"
          },
          "data": [
            "none",
            "stretch"
          ]
        }
      }
    }
左側は非均等のサイズ調整、右側は「stretch」の動作を表します。
左側は非均等のサイズ調整、右側は「stretch」の動作を表します。

この例の左側の画像はviewportを拡大縮小できない場合の動作を示し、右側の画像はviewportが拡大される場合の動作を示しています。左側の画像では、viewportは100×100単位のviewportで描画され、画面上の100×200 dpの長方形に合うように拡大縮小されます。結果として、歪んだ円が作成されます。右側では、viewportのサイズ調整が拡大縮小に設定されているため、グラフィックは100×200単位のviewportで描画されます。heightプロパティはサイズ調整されたviewportの高さにコンテキスト内でバインドされるため、長さ${height - 100}または100単位の縦線のセグメントを追加で使用して、pathDataが描画されます。

type

AVGに設定する文字列です。

version

このベクターグラフィックで使用するAVG規格のバージョンに設定する文字列です。現時点では「1.0」に設定する必要があります。

viewportHeight

AVGオブジェクトの内部で使用される描画座標の高さです。指定しない場合、デフォルトはheightです。

viewportWidth

AVGオブジェクトの内部で使用される描画座標の幅です。指定しない場合、デフォルトはwidthです。

width

AVGオブジェクトのデフォルトの幅ディメンションです。何らかの方法でオーバーライドまたはサイズ調整されない限り、AVGオブジェクトは画面上にこのスペース幅で表示されます。これは絶対ディメンションでなければなりません。

AVGパス項目

AVGパス項目では、通常の塗りつぶしと線で表示される形状を1つ以上定義します。AVGパス項目には以下のプロパティがあります。

プロパティ デフォルト 説明
type "path" 必須 「path」に設定する必要があります。
fillOpacity 数値 1 パスの塗りつぶしの不透明度です。
fill transparent 塗りつぶしの色です。
pathData 文字列 必須 パスの描画データです。
strokeOpacity 数値 1 パスの線の不透明度です。
stroke transparent 線の描画に使用する色です。
strokeWidth 数値 1 パスの線の幅です。

少なくとも、fillまたはstrokeのいずれかを指定してください。fillstrokeのいずれかが指定されていない場合、グラフィックは描画されません。

fillOpacity

塗りつぶしに適用する不透明度です。塗りつぶしの色には不透明度も適用できます。最終的な塗りつぶしの不透明度は、fillOpacityと、前後のグループおよびホスティングコンポーネントのネストされたopacityプロパティの積になります。

fill

パスを塗りつぶすために使用する色です。指定しない場合、塗りつぶしは行われません。

pathData

SVGの「d」仕様で定義されている、1つ以上のパスコマンドを含む文字列です。パスコマンドを以下に簡単に説明します。

コマンド パラメーター 説明
M, m (x,y)+ 絶対座標で次のサブパスの先頭に移動します。追加のペアは暗黙的な「L」コマンドです。「m」バリアントでは相対座標を使用します。
L, l (x,y)+ 現在位置から新しい位置まで、絶対座標で線を描画します。追加の線でペアを反復処理させることができます。「l」バリアントでは相対座標を使用します。
H, h x+ 絶対座標(H)または相対座標(h)で横線を描画します。
V, v y+ 絶対座標(H)または相対座標(h)で縦線を描画します。
C, c (x1,y1,x2,y2,x,y)+ x1、y1、x2、y2を制御点として、現在の地点からx、yにベジェ曲線を描画します。絶対座標(C)または相対座標(c)を使用します。
S, s (x2,y2,x,y)+ x 2、y 2を曲線の終点の制御点として、現在の地点からx、yまで滑らかなベジェ曲線を描画します。絶対座標(S)または相対座標(s)を使用します。
Q, q (x1,y1,x,y)+ x1、y1を制御点として、x座標、y座標まで2次ベジェ曲線を描画します。絶対座標(Q)または相対座標(q)です。
T, t (x,y)+ x座標、y座標まで滑らかな2次ベジェ曲線を描画します。この場合、制御点は前の曲線から引き継がれます。絶対座標(T)または相対座標(t)です。
A, a Z, z (rx ry angle large-arc-flag sweep-flag x y)+ x座標、y座標まで楕円弧曲線を描画します。楕円の半径はrx、ryです。楕円の回転は角度です。フラグでは、描画する円弧の部分と方向を選択します。絶対座標(A)または相対座標(a)です。始点と終点の間の直線を使用して、現在のサブパスを閉じます。サブパスを閉じても塗りつぶしは影響を受けませんが、線は影響を受けます。

正式な定義については、SVGの仕様を参照してください。

strokeOpacity

線に適用する不透明度です。線の色には不透明度も適用できます。最終的な線の不透明度は、strokeOpacityと全体的なopacityの積になります。

stroke

パスの線に使用する色です。指定しない場合、線は描画されません。

strokeWidth

線の幅です。デフォルトは1です。線はパスの位置に相対して中央に配置されます。

AVGグループ項目

AVGグループは、子に変換を適用するために使用されます。AVGグループ項目には、以下のプロパティがあります。

プロパティ デフォルト 説明
type ”group” 必須 「group」に設定する必要があります。
opacity 数値 1.0 グループの不透明度です。
rotation 数値 0 グループの回転角度(度)です。
pivotX 数値 0 回転ピボット点のX座標(viewport座標)です。
pivotY 数値 0 回転ピボット点のY座標(viewport座標)です。
scaleX 数値 1.0 X軸方向の倍率係数です。
scaleY 数値 1.0 X軸方向の倍率係数です。
translateX 数値 0 X座標の移動(viewport座標)です。
translateY 数値 0 Y座標の移動(viewport座標)です。
item/items AVG項目の配列 [] 子の描画項目の配列です。

変換は、サイズ調整、回転、移動の順に適用されます。

opacity

このグループに適用する全体的な不透明度です。不透明度は、他の不透明度との積で表されます。

rotation、pivotX、 pivotY

pivotX地点、pivotY地点を中心とした、グループの回転角度(度)です。

scaleXとscaleY

グループの倍率です。

translateXとtranslateY

グループの移動です。

item/items

AVG項目の配列です。配列は描画順であるため、後の項目が前の項目の上に表示されます。AVG項目には、作成されたAVG項目を指定するtypeプロパティがあります。現時点では、次の2つがあります。

AVGインフレートアルゴリズム

AVGオブジェクトをインフレートするには、次の手順を行います。

  1. 新しいデータバインディングコンテキストを作成します。
  2. 作成したデータバインディングコンテキストに各パラメーターを追加します。パラメーター値は、最初の一致を使用して次の順序で計算されます。
    1. JSONインフレートロジックから渡されます。たとえば、ユーザーはfillを外部から渡すことができます。詳しくは、VectorGraphicを参照してください。
    2. 現在のスタイルから名前別に抽出されます。
    3. デフォルト値がパラメーターに代入されます。
  3. AVGオブジェクトについて計算されたviewportの幅と高さをデータバインディングコンテキストに追加します。詳しくは、scaleTypeHeightscaleTypeWidthを参照してください。
  4. データバインディングを適用して、AVG JSON定義をネストされたグループとパスにインフレートします。