Connect IQ/Resource Compiler - api_programming @ ウィキ

http://developer.garmin.com/connect-iq/programmers-guide/resource-compiler/

下位ページ

Content

Resource Compiler

The resource compiler compiles images, text, and static data into a resource database that the application can access at run time. The resource compiler is tied into the Monkey C compiler. Its input is an XML file:

<resources>
    <bitmap id="bitmap_id" filename="path/for/image" />
    <font id="font_id" filename="path/to/fnt" />
    <string id="string_id">Hello World!</string>
</resources>

Eclipse のプラグインがリソースファイルを認識するために、パスは "resource" 名前のフォルダに入れる必要がある。

The Resource Module (a.k.a. Rez)

リソースコンパイラは Rez というMonkey C モジュールを自動生成する。このモジュール内の ID でリソースの参照を行う。

module Rez
{
    module Drawables
    { var bitmap_id = 123; }

    module Strings
    { var hello_id = 456; }

    module Fonts
    { var font_id = 789; }
}

ランライム中で、 Rez クラスを参照する。例えば、使用したいビットマップ画像があるとして、これを使用する際には、リソースファイルから読み込みを行わなければならない。

image = Ui.loadResource( Rez.Drawables.id_monkey );
dc.drawBitmap( 50, 50, image );

リソースは、他の Monkey C オブジェクトのようなものとして参照される。リソースの読み込みは拡張機能のようなもので、画面更新時にリソースを読み込むわけではない。

フォルダ階層構造

Referencing Resources Within Resource Files

リソースは他のリソースファイルから参照させることもできる。その場合は

@<module>.<id>.

と指定する。例えば、下記のように string リソースを menu リソースの定義で使うことができる。

<string id="menu_item_1_label">Item 1</string>

<menu id="MainMenu">
    <menu-item id="item_1">@Strings.menu_item_1_label</menu-item>
</menu>

上記のコードは menu_item_1_label を メニューアイテムのラベルとして定義している。

Bitmaps

Garmin devices have different form factors, screen sizes, and screen technologies, so bitmaps need to be explicitly converted for every device. The resource compiler will generate resources for every intended product, which allows the developer to have one set of resources for black and white products, one set for color products, one for larger screen sizes, etc.

リソースコンパイラがサポートしているファイル形式は以下のとおり。

• JPG/JPEG
• BMP/WBMP
• GIF
• PNG

While each device has a unique palette, the developer can specify a palette to use for an image. The resource compiler will map the colors that are defined in the developer’s palette to the closest match in the device palette and use only those colors. A palette can be defined using the following syntax:

<resources>

   <bitmap id="bitmap_id" filename="path/for/image">
       <palette disableTransparency="false">
           <color>FF0000</color>
           <color>FFFFFF</color>
           <color>0000FF</color>
       </palette>
   </bitmap>

</resources>

The table below shows all of the valid attributes for a <bitmap> definition.

Attribute	Definition	Valid Values	既定値	Notes
id	The handle for the layout, which is used to reference the layout in the Rez module	文字列（文字で始まること）	-	必須
filename	イメージファイルへの相対パス	（有効なパスへのファイルパス）	-	必須
dithering	画像のコンパイル時のディザリング	floyd_steinberg or none	floyd_steinberg

The valid attributes for a <palette> definition are in the table below.
Attribute Definition Valid Values Default Value Notes
disableTransparency Should the compiler allow transparent pixels in the image? Disabling transparency may save memory true or false false

Fonts

The resource compiler supports fonts from the BMFont tool (download it at http://www.angelcode.com/products/bmfont/). Use the BMFont tool to convert a font from many formats into BMFont format. The resource compiler reads fonts in TXT or PNG format. Currently only 1-bit color fonts are supported, so the color can be set using dc.setColor().
The BMFont Export Options
The BMFont Export Options

大きなビットマップフォントはメモリを大量消費する。時に、ある種の glyphs は watch face の数字のように、大きなサイズが必要になる。このようなときに filter 属性を使用し、特定の glyphs を読みこむようにする。

<!-- Only include digits from this large font -->
<font id="font_id" file="big_font.fnt" filter="0123456789:"/> <!-- 数字 と : だけ読み込む -->

App Settings

"app settings framework" にて、アプリ開発者がエンドユーザーに Garmin Connect Mobile and Garmin Express を通じてオプションを与えることができる。これにより、アプリのカスタマイズやセットアップができる。これは、特に watch faces や data field など、ユーザー入力を受け付けないアプリでは有効な手段となる。

アプリ設定を定義する

アプリの設定はプロパティと関連する設定で構成される。
プロパティは基本の値を格納するのに使われ、設定はどのようにプロパティがエンドユーザーに示されるかを記述するために使われる。
プロパティにはデフォルト値を設定し、関連した設定は定義しないが、
and not define an associated setting but you cannot define a setting without tying it to a property.

プロパティ(Properties)

プロパティ(Properties)は一つのリソースであり、リソースファイル内で定義される。よって、他のリソー不ファイルのように、オーバーライドすることもできる。

定義には <property> タグを使用する。

<properties>
    <property id="appVersion" type="string">1.0.3</property>
    <property id="myString" type="number">0</property>
    <property id="myNumber" type="number">500</property>
    <property id="screenSleep" type="boolean">true</property>
    <property id="username" type="string"></property>
</properties>

上記のように、<property> タグは２つの属性をサポートする。

• id 必須
  • 値のセットに用いるID
  • 文字で始まる文字列
• type 必須
  • セットされる値の定義。文字列の値は、他のIDと被らない文字列か、文字列リソースへの参照
  • string, number, float or boolean

設定(Settings)

設定(Settings) もまたリソースで定義する。<setting> タグを用いる。

<settings>
    <setting propertyKey="@Properties.appVersion" title="@Strings.AppVersionTitle">
        <settingConfig type="alphaNumeric" readonly="true" />
    </setting>

    <setting propertyKey="@Properties.myString" title="@Strings.MyStringTitle" prompt="@Strings.MyStringPrompt">
        <settingConfig type="list">
            <listEntry value="0">@Strings.HelloWorld</listEntry>
            <listEntry value="1">@Strings.Ackbar</listEntry>
            <listEntry value="2">@Strings.Garmin</listEntry>
        </settingConfig>
    </setting>

    <setting propertyKey="@Properties.myNumber" title="@Strings.MyNumberTitle" prompt="@Strings.MyNumberPrompt">
        <settingConfig type="numeric" errorMessage="@Strings.MyNumberError" />
    </setting>

    <setting propertyKey="@Properties.screenSleep" title="@Strings.ScreenSleepTitle">
        <settingConfig type="boolean" />
    </setting>

    <setting propertyKey="@Properties.username" title="@Strings.UsernameTitle">
        <settingConfig type="alphaNumeric" required="true" />
    </setting>

</settings>

以下に、設定にて有効な属性を示す。

• propertyKey 必須 : プロパティのキー。見つからないとコンパイラでエラーがスローされる。
• title　必須
  • Garmin Connect Mobile/Garmin Express に表示するタイトル when displaying hte list of settings/value of the setting. This must reference a string resource ID.
  • Required
• prompt 任意 : 値の設定時に表示されるメッセージ
  • Some settings will not display a prompt even if it’s provided (for example, readonly or boolean settings displayed as an on/off switch).
• helpUrl 任意 : ユーザにヘルプを示すWebページヘのURL

<settingConfig> タグは <setting>の要素であり、設定の追加詳細を与える。有効な属性は以下のとおり。

• type The display type of the setting.
  • list, boolean, numeric, alphaNumeric, phone, email, url, date or password
  • listの場合は、<listEntry> タグでリストの内容をセットする。
• readonly : 設定が読み取り専用かどうか。list, password では使えない
  • true or false。デフォルトは false
  • Optional
• required : If the field is required. true or false Optional. Defaults to false.
• min : The minimum value to allow.
  • 整数値。数字か日付のみ有効
• max : The maximum value to allow.
  • 整数値。数字か日付のみ有効
• maxLength : 最大長さ。整数ち
  • 文字列にのみ有効
• errorMessage An error message to display if the value a user enters isn’t valid based on the type, min, max and maxLength values. A reference to a string resource.

<settingConfig> は 以下の property 型にのみ有効である。
Property Type Valid settingsConfig Types Notes

• string
  • alphaNumeric
  • phone
  • email
  • url
  • password
• number
  • list
  • numeric
  • date
• float
  • numeric
• boolean
  • boolean

<listEntry> 要素は以下のとおりに定義される。これらの値は文字列リソースへの参照として定義する。

Attribute	Value	Notes
value	ユーザに選択された時に格納する値	The type of the value should match the property it’s being saved to. もし一致しなかった場合、complile time error がすろーされる。

App Setting Valuesへのアクセス

アプリのプロパティへは Object Store へのアクセスと同様に行われる。プロパティへの値保存（プロパティからの値取り出し）は

var mySetting = Application.getApp().getProperty("mySetting");

Application.getApp().setProperty("mySetting", mySetting);

Garmin Connect Mobile/Garmin Express での値変更

エンドユーザはthe Garmin Connect Mobile or Garmin Express UIに定義した値をみることができる。もし、アプリの実行中に値が変更されたら、 AppBase.onSettingsChanged() 関数が呼ばれるので、ここに処理をオーバーライドしておく。

App Settingsをテストする

App settings editor tool は Eclipse plug-in で使用可能。このツールで Eclipseのプロジェクトに対して、定義した設定をみたり、値を選択したり、これらの値をシミュレータに渡すことができる。

リソースのオーバーライド

qualifiers を用いて、リソースをオーバーライドすることができる。同じIDを持っていながら、特定の qualifier を持つリソースで置き換える、という処理がされる。Resource qualifiers はベースのリソースフォルダに適用され、そのフォルダ内で見つかった全てのリソースに適用される。qualifier は、有効な qualifier の値に - （ハイフン）をつけたリソースフォルダで設定する。複数のqualifier を一つのフォルダに適用することもできるが、- で区切られ、下記にあるような順序で与えられなければならない。

All qualifiers are case insensitive.
Qualifier Type Qualifier Values Examples Description

• Device : A device code. Resources included in a folder with a device qualifier will override the resources with the same ID that are defined in the base resource folder when building for that specific device.
  • 例：square_watch or fr920xt
• Language and Region : ISO 639–2 language code followed by an optional ISO 3166–1 3-letter country code. To include a region code, append it after the language code with an underscore (_) separating the two. リージョン（region）は言語と切り離し単独で用いる、ということはできない。このqualifiersは文字列リソースにのみ適用可能。
  • fre, fre_FRA, and fre_CAN