Connect IQ SDK

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:

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

Note: In order for the Eclipse plug-in to recognize a resource file its path must include a folder with the word resource in it.

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

The resource compiler auto-generates a Monkey C module named Rez that contains the resource IDs for the resource file. These identifiers are used to refer to your resources:

module Rez
    module Drawables
        var bitmap_id = 123;
    module Strings
       var hello_id = 456;
    module Fonts
       var font_id = 789;

The code can use the Rez class to reference the resources at run time. For example, let’s say you have a bitmap you want to use in your view. Before it can be used by the app, it must be loaded from the resource file:

image = Ui.loadResource( Rez.Drawables.id_monkey );

Now the bitmap can be drawn in the update handler:

dc.drawBitmap( 50, 50, image );

Resources are reference counted just like other Monkey C objects. Loading a resource can be an expensive operation, so do not load resources when handling screen updates.

Referencing Resources Within Resource Files

Resources can also be referenced from within another resource file. To do this use the syntax @<module>.<id>. For example, you could reference a String resource within a menu definition using the following code.

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

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

This code would use the string defined with an ID of menu_item_1_label as the label for the menu item.


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. The resource compiler supports JPG/JPEG, BMP/WBMP, GIF and PNG file formats.

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:

    <bitmap id="bitmap_id" filename="path/for/image">
        <palette disableTransparency="false">

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

Attribute Definition Valid Values Default Value Notes
id The handle for the layout, which is used to reference the layout in the Rez module Any value that starts with a letter NA Required
filename The relative path to the image file A valid, resolvable path to an image file NA Required
dithering The type of dithering to use when compiling the image 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


The resource compiler reads fonts in TXT or PNG format. You can use the BMFont tool (available at to convert a font from many different formats to a compatible format. Prior to export, ensure that BMFont’s Font Settings specify the Unicode character set. Recommended export options are shown in the image below:

The BMFont Export Options
The BMFont Export Options

The color can be set using dc.setColor(). Since bitmap fonts can take a lot of runtime memory, the font converter defaults to non-anti-aliased 1-bit fonts to save memory. If you know you will have the runtime RAM available, you can turn on font anti-aliasing with the antialias option.

<!-- Domo arigato mister font -->
<font id="font_id" filename="roboto.fnt" antialias="true" />

If you are creating a large font, sometimes, only particular glyphs need to be large-sized (like numbers for a watch face). Use the filter attribute to specify the particular glyphs to include:

<!-- Only include digits from this large font -->
<font id="font_id" filename="big_font.fnt" filter="0123456789:"/>


JSON data resources can store relatively large amounts of data in your app without having to keep it in memory at all times. This can be useful for storing something like a table of information that must be referenced at runtime, but will not be modified.

These resources are declared with the jsonData tag in a resource file, are read by the resource compiler, and loaded on demand at runtime. The jsonData tag supports the following attributes:

Attribute Definition Valid Values
id The identifier of the JSON resource Any string starting with a letter
filename The name of a file containing JSON data A valid, resolvable path to a data file

JSON data resources may be provided as either a jsonData value or as a file referenced by the filename attribute, depending on whether it’s easier to manage the data inside a resource file or in a separate JSON file. If using a file, it may only contain JSON data. Here are a few examples:

    <jsonData id="jsonDictionary">{"key":"value", "3":"three", "three":3}</jsonData>
    <jsonData id="jsonArray">[1,2,3,4,5,6]</jsonData>
    <jsonData id="jsonMix">[1,{"1":"one"},["a","b","c"]]</jsonData>
    <jsonData id="jsonPrimitive">5</jsonData>
    <jsonData id="jsonFile" filename="data.json"/>

The JSON data is loaded with the WatchUi.loadResource() method by passing in the jsonData ID. For example, to load the jsonArray data from the example above, the following code would be used:

var array = WatchUi.loadResource(Rez.JsonData.jsonArray);

Data Storage

Connect IQ is also able to save data from within an app at runtime. For example, an app may need to obtain or calculate data and store it for later use. This is accomplished by the use of Storage, Properties, and Settings.


Storage is used for saving and retrieving data from the file system of the device at run time as defined by the developer. This data is only available to the application and is not accessible by the end user. For example, this feature could be used to store a location from when an app was last used. The next time the app is launched, Storage can provide the last known location to the app.

The following data types may be stored:

It is important to note that an Array or Dictionary may only contain the data types listed above. For example, it is not possible to store a Symbol in an Array or Dictionary in Storage.

Accessing Storage: Application.Storage

Connect IQ 2.4 introduces the Application.Storage module, which manages persistent key-value pair data storage. Information is automatically saved on disk to a .IDX and .DAT file pair when Application.Storage.setValue() is called. Keys and values are limited to 8 KB each, and a total of 128 KB of storage is available.

For example, an application might save a location for later use with the code below:

Application.Storage.setValue("location", locationValue.toDegrees());

The next time the application is launched, the stored location value can be retrieved and displayed:

var myLastLocation = Application.Storage.getValue("location");
dc.drawText(x, y, Gfx.FONT_SMALL, "Last location: " + myLastLocation, Gfx.TEXT_JUSTIFY_LEFT);

Accessing Storage: Object Store

Prior to Connect IQ 2.4, storage was handled by the Object Store, which managed all Storage, Properties, and Settings. This functionality is still available, though use of the Application.Storage module is recommended on devices that support Connect IQ 2.4 or higher.

Unlike Application.Storage, Object Store information is not saved on disk to .STR files until Application.onStop() is called, which means modifications are not saved if the app crashes during execution. To get or set a storage value, use the Application.AppBase.getProperty() or Application.AppBase.setProperty() methods, respectively:

// Set an Object Store value
Application.getApp().setProperty("myObjectStoreItem", myObjectStoreItem);

// Get an Object Store value
var myObjectStoreItem = Application.getApp().getProperty("myObjectStoreItem");


Properties are considered a resource and are defined within a resource file. This means you can override them like any other resource file. To define a property use the <property> tag.

    <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>

The property tag supports two attributes: id and type. Both of these attributes are required.

Attribute Definition Valid Values
id The ID of the preference to set. Any string starting with a letter.
type The type of the value being set. A string value is the literal string value and not an ID or reference to a string resource. string, number, float or boolean


The app settings framework enables app developers to present options to end users for their apps within Garmin Connect Mobile and Garmin Express. This will allow app customization and setup, especially for watch faces and data fields, which have no way to receive user input.

An app setting is composed of a property and an associated setting. The property is used to store the underlying setting value. The setting is used to describe how the property should displayed to the end user. You can define a property as a default value and not define an associated setting but you cannot define a setting without tying it to a property.

Settings are also defined as a resource. Use the <setting> tag to define a setting.


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

    <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>

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

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

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


The table below shows all of the valid attributes for a setting.

Attribute Value Notes
propertyKey The key of the property that this setting will manage. An error will be thrown at compile time if the property key can’t be found. Required
title The title to display in Garmin Connect Mobile/Garmin Express when displaying the list of settings/value of the setting. This must reference a string resource ID. Required
prompt The message to display when prompting the user to set the value. This must reference a string resource ID. Optional. 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 A URL to a web page which will provide help for the user. Optional

A <settingConfig>, a child element of a <setting>, provides additional details about the setting. The valid attributes are given in the table below.

Attribute Value Valid Values Notes
type The display type of the setting. list, boolean, numeric, alphaNumeric, phone, email, url, date or password A value of list will require child <listEntry> elements to define the options which should be available within the list.
readonly If the setting is read only or not. This attribute is valid for all types except list and password. true or false Optional. Defaults to false.
required If the field is required. true or false Optional. Defaults to false.
min The minimum value to allow. An integer value Optional. Only valid for a type value of numeric or date.
max The maximum value to allow. An integer value Optional. Only valid for a type value of numeric or date.
maxLength The maximum allowed value length. An integer value Optional. Only valid for settings whose associated property’s type is string.
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> types are only valid for certain property types:

Property Type Valid settingsConfig Types Notes
string alphaNumeric, phone, email, url, password
number list, numeric, date
float numeric
boolean boolean

The <listEntry> element is defined in the table below. Its value must be a reference to a string resource.

Attribute Value Notes
value The value to save if this item is selected by the user. The type of the value should match the property it’s being saved to. If it doesn’t match a compile time error is thrown.

Accessing Properties and Settings: Application.Properties

Connect IQ 2.4 introduces the Application.Properties module, which provides an interface for accessing the values and properties of settings. Information is automatically saved on disk to a .SET file when Application.onStop() is called. To get or set a property value use the Application.Properties.getValue() or Application.Properties.setValue() methods, respectively:

// Set an Object Store app setting
Application.Properties.setValue("mySetting", mySetting);

// Get an Object Store app setting value
var mySetting = Application.Properties.getValue("mySetting");

Accessing Properties and Settings: Object Store

Prior to Connect IQ 2.4, properties and settings were accessed the same way Object Store storage values are accessed. This functionality is still available, though use of the Application.Properties module is preferred on devices that support Connect IQ 2.4 or higher.

Object Store properties and settings are saved on disk to a .SET file when Application.onStop() is called. To get or set a property value use the Application.AppBase.getProperty() or Application.AppBase.setProperty() functions respectively:

// Set an Object Store app setting
Application.getApp().setProperty("mySetting", mySetting);

// Get an Object Store app setting value
var mySetting = Application.getApp().getProperty("mySetting");

Changing Settings Within Garmin Connect Mobile/Garmin Express

End users will be able to view the settings you define within the Garmin Connect Mobile or Garmin Express UI. When app settings are changed while an app is running the Application.AppBase.onSettingsChanged() function is called. Apps can override this function and update accordingly. When dealing with date type settings that are set by Garmin Express or Connect Mobile, one should note that times are stored in UTC and that Gregorian.utcInfo() should be used in place of when working with such values to prevent unneeded local time conversion.

Testing App Settings

An app settings editor tool is available within the Eclipse plug-in. This tool will allow you to view the defined settings for a project in Eclipse, select values for each setting and send them to the simulator for testing.

Which API Should I Use?

If 2.4 compatible devices are targeted by an app, the Application.Storage and Application.Properties modules offer a superior solution for persisting application data compared to the Object Store. Using the newer APIs in an existing app is simply a matter of updating code to call the new methods, however there are a couple of important things of which to be aware:

  1. Object Store data files are not converted to the new format.

    If an app used storage prior to Connect IQ 2.4, existing .STR files will not automatically migrate to the .IDX/.DAT file format used by the Application.Storage module. If a conversion is needed, an app must include a routine to get the data from the old files and store it in the new format.

  2. Application.Properties will throw an exception if attempting to write to an undefined property.

    Prior to Connect IQ 2.4, an attempt to write to an undefined property would result in a value written to storage (the .STR file) since Application.AppBase.getProperty() and Application.AppBase.setProperty() were overloaded to function with each of Storage, Properties, and Settings. This behavior will no longer occur when using the Application.Properties module since it is distinct from Application.Settings. Instead, an InvalidKeyException is thrown.

To maximize the number of supported devices, use a has check to see if the Storage API is available and then call the appropriate methods based on what the device supports:

if ( Toybox.Application has :Storage ) {
    // use Application.Storage and Application.Properties methods
} else {
    // use Application.AppBase methods