# A2. リソースについて

この章では、PVNS が外観・動作を設定するために使用する「リソース」について説明します。

## A2.1 リソースとは

リソースとは、PVNS の設定情報や、アイコン、メニュー文字列などのデータです。PVNS ではリソースを XML ファイル中に記述します。

PVNS では、リソースを格納したリソースファイルを 5 種類使用します。各リソースファイルの用途・説明については、「5. PVNS のカスタマイズ」を参照してください。

## A2.2 記述形式

### A2.2.1 リソース ID

リソースは ID によって識別されます。ID には階層構造があり、次の形式で定義されます。

    (親カテゴリ名).(子カテゴリ名).〜(略)〜.(リソース名)

カテゴリとカテゴリ(またはリソース名)の間は「`.`」`(半角ピリオド: \u002E)`で区切ります。

例えば、シナリオ固有の設定として、キャンバスの、テキストキャンバスに関する設定で、テキストキャンバスの表示タイプを設定するリソースのリソース ID は `peko.canvas.text.view-type` となります。

### A2.2.2 XML ファイルへの記述

XML 形式のリソースファイルでは、リソースは、`http://tsukuba-bunko.org/ns/resource` ネームスペースで定義される `resources` 要素の内容として記述されます。`resources` タグには、リソースを表すタグと明確に区別するために通常 XML namespace prefix を使用します。

基本的な XML 形式のリソースファイルの例を以下に示します。

    <?xml version="1.0" encoding="Shift_JIS"?>
    <res:resource xmlns:res="http://tsukuba-bunko.org/ns/resource">
      <scenario>
        <title>テスト！</title>
        <producer>つくば文庫</producer>
              ：
        （その他のリソース）
              ：
      </scenario>
    </res:resource>

図A2.2.2.1: XML 形式のリソースファイルの例

XML 形式のリソースファイルにリソースを記述する場合、リソース ID を構成するカテゴリ名(またはリソース名)が、そのまま XML のタグ名になります。

例えば、`peko.canvas.text.view-type` の場合、次のように記述されます。

    <peko>
      <canvas>
        <text>
          <view-type>window</view-type>
        </text>
      </canvas>
    </peko>

図A2.2.2.2: リソースの XML マッピングの例(1)

親カテゴリが同一であるリソースは、XML 上でも親カテゴリに対応する要素を共有することが出来ます。

例えば、`scenario.canvas.text.view-type` と `scenario.canvas.canvas-size` は、`scenario.canvas.` までを共有していますので、次のように記述することが出来ます。

    <scenario>
      <canvas>
        <canvas-size>640,480</canvas-size>
        <text>
          <view-type>window</view-type>
        </tet>
      </canvas>
    </scenario>

図A2.2.2.3: リソースの XML マッピングの例(2)

## A2.3. データ形式

リソースの値は単なる文字列データではなく、固有のデータの型(種別)を持っています。PVNS で定義されているリソースとそのデータ型については「5. PVNS のカスタマイズ」を参照してください。

型名 | boolean
解説 | 論理値(真／偽)を表すデータ型です。値が `true`、`yes`、`on` の場合「真」に、それ以外の場合「偽」になります。大文字小文字は区別しません。

型名 | integer
解説 | 32bit の整数値を表すデータ型です。指定可能な範囲は `-2147483648` 〜 `2147483647` です。途中に桁を示すカンマやピリオドを入れることは出来ません(エラーになります)。詳しくは The Java Language Specification の 3.10.1 Integer Literals を参照してください。

型名 | float
解説 | 32bit の浮動小数値を表すデータ型です。詳しくは The Java Language Specification の 3.10.2 Floating-Point Literals を参照してください。

型名 | string
解説 | 文字列を表すデータ型です。文字列を構成する文字としては、Unicode で定義されている文字であれば使用することが可能です。ただし、XML ファイル形式やプロパティファイル形式中に記述する場合は、特定の文字についてはエスケープする必要があります。

型名 | message-format
解説 | 文字列のテンプレートを表すデータ型です。置換したい箇所に「`{n}`」という形式のトークンを埋め込むことでテンプレートを構築できます。詳しくは、Java API Specification の MessagFormat を参照してください。

型名 | date-format
解説 | 日時の表記法のテンプレートを表すデータ型です。詳しくは、Java API Specification の SimpleDateFormat を参照してください。

型名 | list/string
解説 | 文字列のリストを表すデータ型です。XML 形式では、リストの各要素は、`http://tsukuba-bunko.org/ns/resource` 名前空間に定義された `item` 要素の値として記述します。次に、例として、`list/string` 型のリソース `samle.list` の記述の例を示します。
    <res:resource xmlns:res="http://tsukuba-bunko.org/ns/resource">
      <sample>
        <list>
          <res:item>string1</res:item>
          <res:item>string2</res:item>
          <res:item>string3</res:item>
        </list>
      </sample>
    </res:resource>
図A2.3.1: list/string の例

型名 | peko:dimension
解説 | 矩形のサイズを表すデータ型です。width(幅)と height(高さ)から構成され、それぞれの値をカンマで区切った一つの文字列として記述します。カンマや width、height の前後に空白(\u0020:半角スペース)が任意の数含まれてもかまいません。width と height は、それぞれ 0 以上の 32bit 整数値です。次に、例として、`peko:dimesion` 型のリソース `samle.dimension` の記述の例を示します。
    <res:resource xmlns:res="http://tsukuba-bunko.org/ns/resource">
      <sample>
        <dimension>640, 480</dimension>
      </sample>
    </res:resource>
図A2.3.2: peko:dimension の例

型名 | peko:point
解説 | 2 次元の座標を表すデータ型です。x 座標値と y 座標値から構成され、それぞれの値をカンマで区切った一つの文字列として記述します。カンマや x 座標値、y 座標値 の前後に空白(\u0020:半角スペース)が任意の数含まれてもかまいません。x 座標値 と y座標値 は、それぞれ 0 以上の 32bit 整数値です。次に、例として、`peko:point` 型のリソース `samle.point` の記述の例を示します。
    <res:resource xmlns:res="http://tsukuba-bunko.org/ns/resource">
      <sample>
        <point>0, 100</point>
      </sample>
    </res:resource>
図A2.3.2: peko:point の例

型名 | peko:insets
解説 | ある矩形の境界線と、その矩形を囲む矩形の境界線との間の距離を表すデータ型です。矩形のパディング領域を指定するのに使用されます。top、right、bottom、left の4つの値で構成され、それぞれの値をカンマで区切った一つの文字列として記述します。カンマや top、right、bottom、left の前後に空白(\u0020:半角スペース)が任意の数含まれてもかまいません。top、right、bottom、left は、それぞれ 0 以上の 32bit 整数値です。次に、`peko:insets` 型のリソースの記述の例を示します。
    <res:resource xmlns:res="http://tsukuba-bunko.org/ns/resource">
      <sample>
        <insets1>0, 1, 2, 3</insets1>
        <insets2>0, 1, 2</insets2>
        <insets3>0, 1</insets3>
        <insets4>0</insets4>
      </sample>
    </res:resource>
図A2.3.3: peko:insets の例 peko:insets型のリソース値には、省略記法が使用できます。上記の例では、次のように解釈されます。
表A2.3.1: peko:insets の記法と解析結果の例
リソース値 | 解析結果
--- | ---
0,1,2,3 | top=0, right=1, bottom=2, left=3
0,1,2 | top=0, right=1, bottom=2, left=1
0,1 | top=0, right=1, bottom=0, left=1
0 | top=0, right=0, bottom=0, left=0

型名 | peko:color
解説 | 色を表すデータ型です。色の記述には、色名または RGB 指定の２種類の方法があります。次に色指定の例を示します。
    <res:resource xmlns:res="http://tsukuba-bunko.org/ns/resource">
      <sample>
        <color1>red</color1>
        <color2>#FFBBAA</color2>
      </sample>
    </res:resource>
図A2.3.4: peko:color の例 使用可能な色名は次の 13 種類です。
表A2.3.2: 色名一覧
black | blue | cyan | darkGray | gray
green | lightGray | magenta | orange | pink
red | white | yellow |  |
RGB 指定では、「#」(\u0023) に続けて、R値、B値、G値を 2 桁の 16 進数で記述します。RGB の各値は 8 bit の符号なし整数で、0 〜 255 の範囲になります。例えば、R=8 G=255 B=127 の場合、「#08FF7F」と記述します。

型名 | peko:font
解説 | フォントを表すデータ型です。フォントは、family (フォントファミリ名)、size (サイズ)、style (スタイル)、weight (ウェイト) から構成されます。family, size, style, weight の各項目は XML 形式の場合、子要素の値として記述します。次にフォント型のリソース `sample.font` の記述の例を示します。
    <res:resource xmlns:res="http://tsukuba-bunko.org/ns/resource">
      <sample>
        <font>
          <family>SansSerif</family>
          <size>25</size>
          <style>italic</style>
          <weight>bold</style>
        </font>
      </sample>
    </res:resource>
図A2.3.5: peko:font の例 family, size, style, weight の各項目は省略することができます。省略は任意の項目で行うことができ、4 項目のうち 2 項目を省略したり、あるいは全部省略したりすることもできます。次に、省略した場合に適用される各項目のデフォルト値を示します。
表A2.3.3: フォント設定のデフォルト値
項目名 | 型 | デフォルト値
--- | --- | ---
family | string | Serif
size | float | 20.0
style | `italic` or `normal` | `normal`
wight | `bold` or `normal` | `normal`
style には `italic` または `normal` のいずれかを、weight には `bold` または `normal` のいずれかを指定します。どちらの項目でも、大文字小文字は区別され、前述の値以外が指定された場合はデフォルト値を使用します(エラーにはなりません)。 family に使用できないフォントファミリ名を指定した場合、または、size に不正な値を記述した場合、PVNS の初期化時に警告が表示されます。