Connect IQ SDK

Entry Points and the Manifest File

All Connect IQ apps require a manifest file. The manifest file is an XML file that specifies application properties like the application type and the supported products. The manifest file is created for you automatically by the Eclipse plug-in, but you can create it by hand as well.

<iq:manifest version="1">
  <iq:application entry="CommExample" id="a3421feed289106a538cb9547ab12095" name="AppName" launcherIcon="LauncherIcon" type="widget">
              
    <iq:products>
      <iq:product id="square_watch"/>
    </iq:products>

    <iq:permissions>
      <iq:uses-permission id="Communications"/>
    </iq:permissions>
            
  </iq:application>
</iq:manifest>

The application element has a number of important attributes. The id field is a 128 bit UUID identifier. You can generate your own identifier online, or use standard tools.

App Type

The type field specifies what kind of application you are developing. Currently Connect IQ supports four types of apps:

  1. watch face
  2. datafield
  3. widget
  4. watch-app

Where your app appears on the device and what APIs you can call depend on the app type selected in the manifest file.

The name and launcherIcon attributes must specify a resource ID that is defined in the app resources. If a launcherIcon isn’t specified a default icon will be compiled into the application.

The entry attribute must specify the Toybox.Application.AppBase object for your application. Every application must include an Application object, which serves as the entry point for your application.

//! AppBase is the base class for an app. All apps shall inherit
//! from this class. It is used to manage the lifecycle of an app.
//! For widgets and watch-apps, the functions are called in the
//! following order: onStart(), getInitialView() and onStop().
//! For watchfaces and datafields, only getInitialView() is called.
//! Every AppBase object has access to an object store to persist
//! data.
class AppBase
{
  //! Before the initial WatchUi.View is retrieved, onStart() is called.
  //! This is where app level settings can be initialized or retrieved from
  //! the object store before the initial View is created.
  function onStart();

  //! To retrieve the initial WatchUi.View and WatchUi.InputDelegate
  //! of the application, call getInitialView(). Providing a
  //! WatchUi.InputDelegate is optional for widgets and watch-apps. For
  //! watchfaces and datafields, an array containing just a WatchUi.View should
  //! be returned as input is not available for these app types.
  //! @return [Array] An array containing
  //! [ WatchUi.View, WatchUi.InputDelegate (optional) ]
  function getInitialView();
    
  //! When the system is going to terminate an application, onStop() is called.
  //! If the application needs to save state to the object store it should be
	    //! done in this function.
	    function onStop();
    
  //! To get the data associated with the given key from the object store,
  //! use getProperty().
  //! @param key Key of the value to retrieve from the object store
  //! (cannot be a Symbol)
  //! @return [Object] Content associated with the key, or null if the key
  //! is not in the object store
  function getProperty(key);
    
  //! Using a key, store the given data in the object by calling setProperty().
  //! @param key The key used to store and retrieve the value from the object
  //! store (cannot be a Symbol)
  //! @param [String] value The value to put into the object store
  function setProperty(key, value);
}

An application object should override getInitialView() to provide the view object they want to push initially. You have to return an array with either a View and a Delegate, or just a one element array with the View object.

return [ new MyView(), new MyDelegate() ];

The Eclipse plug-in will generate an Application object for you when creating a project.

Products

We make a variety of products for many use cases. Monkey C makes it easy to write for our all Connect IQ devices, but it is impossible what future product might be incompatible with your app. For this reason, Monkey C asks the developer what Connect IQ devices they choose to support. As new Connect IQ products appear on the market the simulator will be updated to support them, and you will have the option to support it or not.

You list which products you want in the Products block. The SDK currently supports two imaginary products: a round-watch and a square-watch. The round watch is button only, and the square watch is a touch screen product with less buttons.

<iq:products>
  <iq:product id="Product"/>
</iq:products>

Permissions

Certain modules expose personal information about the user or expose communication to the internet. To use these modules you must request permission from the user at installation time. To request permission, the module name must be added to the permissions list of the manifest file. The following modules require permission:

More modules may be added to this list as modules are added to the API. To request permission, use the following syntax in the manifest file:

<iq:permissions>
  <iq:uses-permission id="Module"/>
</iq:permissions>