CommandFusion iViewer
Scripting Documentation

Table of contents

Utilities API

Events

CF.DevicePropertyChangedEvent

This event is fired when one of the supported device properties changes. You can be notified when the screen brightness, sound output volume, battery level and battery charge status changes. Use CF.watch to start watching the changes. Your callback function is called with two parameters:

Example:

CF.userMain = function() {
    // Start watching all properties
    CF.watch(CF.DevicePropertyChangeEvent, CF.ScreenBrightnessProperty, onPropertyChange);
    CF.watch(CF.DevicePropertyChangeEvent, CF.SoundOutputVolumeProperty, onPropertyChange);
    CF.watch(CF.DevicePropertyChangeEvent, CF.BatteryLevelProperty, onBatteryChange);
    CF.watch(CF.DevicePropertyChangeEvent, CF.BatteryChargeStatusProperty, onBatteryChange);
};

function onPropertyChange(property, value) {
    if (property == CF.ScreenBrightnessProperty) {
        CF.log("New screen brightness: " + value);
    } else if (property == CF.SoundOutputVolumeProperty) {
        CF.log("New sound volume: " + value);
    }
}

function onBatteryChange(property, value) {
    if (property == CF.BatteryLevelProperty) {
        var percent = Math.floor(value * 100.0);
        CF.log("Battery level: " + percent + "%");
    } else {
        if (value == CF.CHARGE_UNPLUGGED) {
            CF.log("Device is now unplugged");
        } else if (value == CF.CHARGE_CHARGING || value == CF.CHARGE_FULL) {
            CF.log("Device is now plugged");
        }
    }
}

See also CF.setDeviceProperty().

CF.ApplicationCallbackEvent

This event is fired when the app is launched in one of two ways:

Your callback function is called with four parameters:

Example:

CF.userMain = function() {
    // Start listening to any app callback events
    CF.watch(CF.ApplicationCallbackEvent, function (path, fragment, query, params) {
        CF.log("Path: " + path);
        CF.log("fragment: " + fragment);
        CF.log("query: " + query);
        CF.log("params: " + params);
    });
};

CF.PushNotificationEvent

This event is fired when the app receives a push notification, either while open or whilst in the background. Your callback function is called with three parameters:

Example:

CF.userMain = function() {
    // Start listening to any push notifications
    CF.watch(CF.PushNotificationEvent, function (title, message, data) {
        CF.log("Push Notification Received: " + title);
        CF.log(message);
        CF.logObject(data);
    });
};

Constants

Device property constants

These constants are to be used to watch CF.DevicePropertyChangeEvent for specific properties. See CF.setDeviceProperty() for an example of use.

Hash type constants

CRC type constants

The CRC constants should be used for the crcType parameter to CF.crc(). Select the right one according with the type of CRC you want to generate:

Output format constants

The following output format constants determine the generated format for a CRC:

Battery charge constants

These constants refer to both the CF.device.batteryChargeStatus variable (updated by iViewer) and to the value you receive in your callback when monitoring CF.BatteryChargeStatusProperty:

Status bar constants

These constants define the status (top) bar appearance you can set with a call to CF.setDeviceProperty() using the CF.StatusBarAppearanceProperty device property type:

Note that on Android, you can't control the color of the status bar.

These contents define the visibility of the navigation (bottom) bar on Android. You can change it with a call to CF.setDeviceProperty() using the CF.NavigationBarAppearanceProperty device property type:

Keypress constants

These constants relate to intercepting hardware key presses on Android only, using CF.interceptHardwareKey():

There are a few predefined constants for hardware keys. A full list can be found in the core Android documentation for KeyEvent:

Functions

CF.log(msg)

General logging function that logs strings to either the Remote Debugging Monitor console (if connected), or to the webview on the current page that is marked as Use for script debugging output.

CF.logObject(object)

Dumps the details contents of an object. In JavaScript, the generic object.toString() method returns "[Object object]" for objects, which is not what you want to see the contents (all properties) of an object.

CF.crc(crcType, string, outputFormat, callback)

Compute a CRC for the given string. The crcType constants can be one of the CF.CRC_* constants listed in the Constants section. You pass a string to compute the CRC of, and an outputFormat that is one of the CF.OUTPUT_* contents listed in the Constants section.

Examples:

var s = "Hello, world!";

// Compute a 16-bit CRC, set a join with the string result
CF.crc(CF.CRC_16, s, CF.OUTPUT_STRING, function(crc) { CF.setJoin("s1", "The CRC is: 0x" + crc) });

// Compute a 32-bit CRC and assemble a binary packet sent to an external system
// the packet header and footer string generation is not shown here
CF.crc(CF.CRC_32, s, CF.OUTPUT_BINARY, function(crc) {
    var cmd = somePacketHeader + crc + s + somePacketFooter;
    CF.send("TEST-SYSTEM", cmd);
});

CF.hash(hashType, string, callback)

Compute a hash an call your callback function with the hash string. The hashType format should be one of the CF.Hash_* constants listed in the Constants section.

Example:

// Get the string from s701, compute several hashes then put the result in other joins
CF.getJoin("s701", function(join, value) {
	CF.hash(CF.Hash_MD5, value, function(hash) { CF.setJoin("s710", hash) });
	CF.hash(CF.Hash_SHA1, value, function(hash) { CF.setJoin("s711", hash) });
	CF.hash(CF.Hash_SHA256, value, function(hash) { CF.setJoin("s712", hash) });
	CF.hash(CF.Hash_SHA384, value, function(hash) { CF.setJoin("s713", hash) });
	CF.hash(CF.Hash_SHA512, value, function(hash) { CF.setJoin("s714", hash) });
});

CF.openURL(url)

Opens a URL, the same way iViewer does it when a button with an associated URL is being pressed. The URL can be a remote URL (http://, etc) which will trigger an application switch from iViewer to the device web browser. It can also be a URL with a specific scheme recognized by the OS, so as to open another application that supports URL schemes.

Examples:

// Open the apple.com web page directly in the web browser. If multitasking is turned off, this will quit iViewer
CF.openURL("http://www.apple.com");

// Call a phone number (iPhone) using the Phone application's URL scheme
// (note that phone numbers must have extra chars like spaces and parenthesis removed)
CF.openURL("tel:6501489654");

// Open the Mail application (iPhone, iPad) with pre-filled fields
var subject = "iViewer Rocks";
var body = "Dear CommandFusion team,\n\n We love iViewer JavaScript!";
var address = "support@commandfusion.com";
CF.openURL("mailto:" + address + "?subject=" + encodeURIComponent(subject) + "&body=" + encodeURIComponent(body));

CF.loadGUI(url, settings)

Loads another GUI (or reload the current GUI). This functionality was previously available using CF.openURL("cf://<url>"). This specialized API lets you override the current settings to customize them. In particular, you can use settings customization to force a reload of the GUI and / or assets even if the current settings don't mandate it.

If you pass an empty string for the url parameter, the current GUI will be reloaded.

If you pass null for the url parameter, the app will reset to the default GUI that comes as default when installing the app.

The settings parameter is an object which contains a number of properties that override the current settings. If a property is missing, the current setting will be used instead. Supported properties are:

Examples:

// Restart the current GUI, using all the current settings unmodified
CF.loadGUI("");

// Reload the current GUI and all assets from server then restart it
CF.loadGUI("", { reloadGUI: true, reloadAssets: true });

// Load another GUI, ensure all assets are preloaded
CF.loadGUI("http://192.168.0.100/my.gui", { preloadAllAssets: true });

CF.loadAsset(assetName, dataEncoding, callback, cache)

Loads an asset file from the designated assets folder of your GUI (or from the same folder as the GUI is no assets folder was defined). The data can be read either as binary (using dataEncoding value of CF.BINARY) or as a UTF-8 string (using dataEncoding value of CF.UTF8). Once the load is complete, your callback function is called with the asset file content. The callback function is optional: if you are using CF.loadASset() only to pre-cache asset, you may omit it.

This API can be used to:

If the GUI was originally loaded from a server and the asset is not found in the cache, iViewer will request the asset from the server, relative to the GUI URL and optionally to the asset folder at this location that you defned in guiDesigner, just like it does for other assets. If you provide a full URL, iViewer can still look in the cache first then fallback to downloading the asset (see cache options below).

Note that if your GUI was loaded in the form of a zip file, iViewer won't try to load an asset from the server if it was not found in the zip file. To load additional assets, you will have to provide a full URL.

The cache mode controls cache management for this asset:

Note that since extra assets are not themselves defined in the GUI, they are not subject to preloading like other assets (images, sounds, videos). If you need extra assets for your Javascript code, you may want to consider providing your GUI as a zip file.

Here is an example flow of what happens when you use CF.loadAsset:

CF.loadAsset flow

Examples:

// Load an IR codes definition file from our assets. The file is defined as JSON, so we
// can parse it with JavaScript JSON parser. The file must available on the server that provided the GUI, at the
// same location as other assets, as defined in the guiDesigner project
CF.loadAsset("ircodes.json", CF.UTF8, function(assetFileAsString) {
    // We receive the whole file as a string. Since we specified a UTF8 format, the
    // string can be immediately used
    var ircodesObject = JSON.parse(assetFileAsString);
    // ... do something with the ircodesObject ...
});

// Ensure an image is in the cache. We don't care about getting the result, just need to make sure
// that this asset (not directly referenced by an image in a page) is in cache
CF.loadAsset("someImage.png", CF.BINARY, null, CF.CACHE);

// Load an external asset into the cache for future use (for example in a list)
CF.loadAsset("http://mysite.com/myImage.png", CF.BINARY, null, CF.CACHE);

// Reload a cached copy of some asset. If it was locally cached, the local copy is wiped then
// a new one is downloaded
CF.loadAsset("someImage.png", CF.BINARY, null, CF.RECACHE);

// Pre-cache multiple assets
CF.loadAsset(["image1.png","image2.png","http://mysite.com/someImage.png"], CF.BINARY, null, CF.CACHE);

Compatibility notes:

A previous version of this API did not include the cache mode. It is still supported, and by default will operate with the CF.CACHE_READONLY mode.

CF.setDeviceProperty(property, value)

Change a device property to a new value. The only property currently supported by this call is CF.ScreenBrightnessProperty (on iOS 5 and later, and on Android), allowing you to tune the brightness of the device display. You can't turn it completely off: even if you set the brightness to 0.0 the backlight will stay somewhat visible.

The CF.ScreenBrightnessProperty value is a number between 0.0 and 1.0 (inclusive). The current screen brightness is being reflected by the CF.device.screenBrightness property. Changes can be observed by watching the CF.DevicePropertyChangedEvent with the CF.ScreenBrightnessProperty.

Note that on iOS, changes in display brightness triggered by the application do not generate a CF.DevicePropertyChangedEvent.

Example:

// Set the screen brightness to half
CF.setDeviceProperty(CF.ScreenBrightnessProperty, 0.5);

CF.interceptHardwareKey(keyCode, pressTime, mode, callback)

ANDROID ONLY

Set or cancel a hardware key redirection, so as to fully intercept one of the device's hardware keys, or perform actions while letting the OS process the action associated with the key.

Your callback function will receive the keyCode that was pressed, and the actual down time for the key.

Example:

// Intercept device's BACK key when pressed for more than 250 milliseconds
CF.interceptHardwareKey(CF.HARDWARE_KEY_BACK, 250, CF.KEYPRESS_INTERCEPT, function(keyCode, downTime) {
	CF.log("The BACK key has been pressed for " + downTime + " milliseconds. Take action here!");
});

// Cancel the above interception
CF.interceptHardwareKey(CF.HARDWARE_KEY_BACK, 250, CF.KEYPRESS_INTERCEPT, null);