JS Main – Umajin Developer

Members

console

Use as in standard JS to log output, warnings and errors to the Umajin script console

print

print prints strings or objects to the output console. print is useful for debugging.
You can print as many items as you like with print( item1, item2, item3... );
Note: you can also use the standard JS console.log, .info, .warn and .error methods.

Example

print('Hello Umajin!'); 	// Hello Umajin!

Methods

addGlassShelfItem(glass_shelf, filename)

addGlassShelfItem this will programatically add another image to a glass shelf

Parameters:

Name	Type	Description
`glass_shelf`	object	an instance of a glass shelf component
`filename`	string	an image in the local project image folder

addMapMarker(map_view, name, address, zoom_to_marker, show_info)

addMapMarker adds a marker at address in the map_view control, and optionally zooms to the marker.

Parameters:

Name	Type	Description
`map_view`	object	an instance of a map_view control
`name`	string	unique name to identify the marker for other calls
`address`	string	an address to geocode and add to the map
`zoom_to_marker`	boolean	whether to zoom to the marker or not (true zooms to marker, false does not)
`show_info`	boolean	whether to show the address information

addMapMarkerLatLong(map_view, name, lat,long, title, desc, img, zoom_to_marker, show_info)

addMapMarkerLatLong adds a Map Marker at a specific lat/long.

Parameters:

Name	Type	Description
`map_view`	object	an instance of a map_view control
`name`	string	unique name to identify the marker for other calls
`lat,long`	real	latitude and longitude for the marker
`title`	string	Title of the marker
`desc`	string	Text for the information
`img`	string	Custom image for the pin
`zoom_to_marker`	boolean	whether to zoom to the marker or not (true zooms to marker, false does not)
`show_info`	boolean	whether to show the extra information

addMapMarkerWithInfo(map_view, name, address, title, desc, img, zoom_to_marker, show_info)

addMapMarkerWithInfo adds a Map Marker with custom information on the marker.

Parameters:

Name	Type	Description
`map_view`	object	an instance of a map_view control
`name`	string	unique name to identify the marker for other calls
`address`	string	address for the marker
`title`	string	Title of the marker
`desc`	string	Text for the information
`img`	string	Custom image for the pin
`zoom_to_marker`	boolean	whether to zoom to the marker or not (true zooms to marker, false does not)
`show_info`	boolean	whether to show the extra information

addMapRoute(map_view, start_address, end_address, zoom_to_marker, route_type, show_info)

addMapRoute adds a route between two routes in blue, and optionally zooms to the route.

Parameters:

Name	Type	Description
`map_view`	object	an instance of a map_view control
`start_address`	string	address to start the route
`end_address`	string	address to end the route
`zoom_to_marker`	int	-1: don't zoom, 0: zoom to start marker, 1: zoom to end marker
`route_type`	int	0:car, 1:walk, 2:cycling, 3:transit
`show_info`	boolean	whether to show the address information

addMapRouteLatLong(map_view, start_latitude, start_longitude, end_latitude, end_longitude, route_type, line_color, line_weight)

addMapRouteLatLong adds a route between two lat longs and specify line colour and weight.

Parameters:

Name	Type	Description
`map_view`	object	an instance of a map_view control
`start_latitude`	real	address to start the route
`start_longitude`	real	address to start the route
`end_latitude`	real	address to end the route
`end_longitude`	real	address to end the route
`route_type`	int	0:car, 1:walk, 2:cycling, 3:transit
`line_color`	color	e.g. 0x0000FFFF (blue)
`line_weight`	string	0:harline, 1:normal, 2:bold, 3:thick.. etc

apeConnect(channel, connect_function, data_function, error_function)

Opens up an AJAX Push Engine. This is a type of http based real time communication which uses the Umajin server as the central hub. Once a named channel is opened many applications can use this to send and receive broadcast messages.
DEPRECATED: The APE functions will be removed in a future release of Umajin. See socketIOConnect for a replacement.

Parameters:

Name	Type	Description
`channel`	string	a unique name for the communication channel
`connect_function`	string	the name of a JavaScript function to use as a callback upon successful connection. It takes no paramters.
`data_function`	string	the name of a JavaScript function to use as a callback when data is received through the channel. It takes two string parameters; the first parameter is the channel that data was received from and the second parameter is the data packet.
`error_function`	string	the name of a JavaScript function to use as a callback if a channel cannot be established. It takes no parameters.

Example

apeConnect("mychannel", "ape_on_connect", "ape_on_data", "")
function ape_on_connect() {
    apeSend("demo");
}
function ape_on_data(pubid, data_in) {
    callAction("show_popup", data_in);
}

apeSend(data)

apeSend sends data through an AJAX Push Engine session that has been esablished by apeConnect. See apeConnect for an example of how to use the AJAX Push Engine.
You are sending data to the channel established in the apeConnect function - you cannot send to another channel without reconnecting.
DEPRECATED: The APE functions will be removed in a future release of Umajin. See socketIOSend for a replacement.

Parameters:

Name	Type	Description
`data`	string	the data packet to send through the AJAX Push Engine channel.

aquirePermissions()

Finds out if you have permission or not for notfications.

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

Returns:

This returns true if your app currently has permission for notifications granted by the OS. It returns false if permission has never been asked for or if permission has been denied.

Type: bool

areAllAlarmPermissionsAlreadyGranted()

Finds out if you have permission or not for both exact alarms and notifications.

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

Returns:

This returns true if your app has been granted both exact alarm and notification permissions. False if either has not been granted.

Type: bool

base64Decode(s)

base64Decode will decode a base64 string back into a full unicode/ASCII string.

Parameters:

Name	Type	Description
`s`	string	the string to decode

Returns:

- the decoded string

base64Encode(s)

base64Encode is useful for when string data must be sent in emails, and for some protocols with 7 bit limitations. Pass a string to this function and it will encode it into base 64.

Parameters:

Name	Type	Description
`s`	string	the string to encode

Returns:

- the base64 encoded string

bindEvent(obj, event, callback)

bindEvent allows one of the supported events of the obj component to be handled by a custom event handler callback.
NOTE: For custom components, it is recommended that bindEvent() is called from the on_init function callback which is declared in registerComponent. For dynamically created components within custom components, bindEvent() should called on those components within the callback of on an "on_ready" event.
EventString has a list of the events you can bind to and the parameters passed.

Parameters:

Name	Type	Description
`obj`	object	a component object. May also be "self" to refer to the current instance of a custom object.
`event`	string	the string corresponding to one of the supported events. on_press - Callback params: x, y, touchId, mod. Fired when an object has a down followed by an up event in the same location (all components) on_down - Callback params: x, y, touchId, mod. (all components) on_up - Callback params: x, y, touchId, mod. (all components) on_move - Callback params: x, y, touchId, mod. (all components) on_drop - Callback params: x, y, touchId, mod. (all components) on_dwell - Callback params: x, y, touchId, mod. (all components) on_pinch - Callback params: centerX, centerY, distance, angle. (all components) on_mouse_enter - Callback params: x, y, mod. Mouse pointer is over the component (all components) on_mouse_leave - Mouse pointer is no longer over the component (all components) on_mouse_down - Callback params: x, y, mod. (all components) on_mouse_up - Callback params: x, y, mod. (all components) on_mouse_wheel - Callback params: x, y, mod, delta. (all components) on_tick - (Render Kit component) on_anim_complete - Callback params: modelId. 3d Model animation has reached the end. (Render Kit component) on_ready - Occurs when a custom component is made visible by explicit action - set visibility or animate. Does not occur when a page is shown. This is useful to call bindEvents on dynamically created components. (Custom component)
`callback`	function	Function that will be be called to handle future instances of event. The parameters passed to callback may vary based on the event being handled.

Example

bindEvent(self,"on_move", "slider_onMove");
bindEvent(self,"on_up", "slider_onUp");
bindEvent(self,"on_down", "slider_onDown");

browseFile(callback, file_types)

Opens a file dialog for the user to select an arbitrary file. This implemented differently on different platforms.
Note: If you want to select an image, use browseImage instead, which works on all platforms.
Desktop (Windows and MacOS): Opens a system dialog to select a file, filtered by filename filters.
iOS: Not implemented.
Android: Opens a picker to select a file, filtered by MIME type.

Required Permissions: READ_EXTERNAL_STORAGE, READ_MEDIA_AUDIO

Parameters:

Name	Type	Description
`callback`	string	the name of a JavaScript function which takes a filepath parameter (or blank if cancelled)
`file_types`	string	On desktop, this is a semi-colon separated list of file filters, such as ".txt;.html". On Android, this is a MIME type filter, such as "/" for any file, or "text/*" for text files

browseImage(successCallback, errorCallback)

Browses the device for a user image and copies it into the temp folder.
Note: on iOS and MacOS, this API supports HEIC/HEIF files that are produced with Live or HDR photos, by
converting them to a JPG.

Required Permissions: READ_EXTERNAL_STORAGE, READ_MEDIA_AUDIO

Parameters:

Name	Type	Description
`successCallback`	string	the name of a JavaScript function which takes a filepath parameter (or blank if cancelled)
`errorCallback`	string	Optional. The name of a JavaScript function which takes an error message in case of failure

Examples

registerAction("browseImg", "", "browseImg", "")
function browseImg() {
    browseImage('browseImgCallback', 'browseImgError');
}
 
function browseImgCallback(filename) {
    console.log("fn> " + filename);
    getImageSize(filename, 'browseImgDisplay')
    thumbnailImage(filename, "demo.jpg", 0.9, 0.5, 0.5, 100, 120);
}
function browseImgError(message) {
    console.log("Browse image failed: " + message );
}
 
function browseImgDisplay(x, y) {
    console.log('Image has a width = ' + x + ' height = ' + y)
}

// With an image component placed from the editor...
var im = findComponent('Page 1', "image", "Image 1");
 
registerAction('imagePickerExample', '', 'imagePickerExample', '');
function imagePickerExample() {
    browseImage('imagePickerExampleCallBack');
}
 
function imagePickerExampleCallBack(filename) {
    console.log(filename);
    setProperty(im, "filename", "file://" + filename);
}

cacheDbBeginTransaction(filename)

cacheDbBeginTransaction begins a transaction, this will speed up multiple INSERT / UPDATE queries, must callcacheDbCommitTransaction for the data to be saved

Parameters:

Name	Type	Description
`filename`	string	the same filename previously passed to cacheDbOpen

cacheDbClose(filename)

cacheDbClose closes the SQLite database at filename that was previously opened with cacheDbOpen.

Parameters:

Name	Type	Description
`filename`	string	the same filename previously passed to cacheDbOpen

Returns:

success - true for success

cacheDbCommitTransaction(filename)

cacheDbCommitTransaction commits a transaction to the database, this will speed up multiple INSERT / UPDATE queries, must call cacheDbBeginTransaction to start a transaction

Parameters:

Name	Type	Description
`filename`	string	the same filename previously passed to cacheDbOpen

cacheDbExec(filename, sql, bindings)

cacheDbExec executes a query on a SQLite DB that has already been opened with cacheDbOpen, which is not expected to return a result set. For SELECT queries, use cacheDbSelectRaw.

Parameters:

Name	Type	Description
`filename`	string	the same filename that has previously been passed to cacheDbOpen and uniquely identifies the DB
`sql`	string	a SQLite compatible query that is not expected to return a result set
`bindings`	object	Optional. Named parameters to bind to parameters in the SQL. Allows passing data without the need to escape special characters or risk of SQL injection attacks. Supported types are: numbers, strings, null, and ArrayBuffer for binary data. Parameter names should use alphanumeric and underscore characters only. Refer to them with a colon in the SQL, e.g :myparam

Returns:

success - true for success

Example

registerAction("dbDemo", "", "dbDemo", "")
function dbDemo() {
    var success = cacheDbOpen("mydb.db");
    // drop and create table
    cacheDbExec("mydb.db", "DROP TABLE IF EXISTS Company;");
    cacheDbExec("mydb.db", "CREATE TABLE Company(ID INT PRIMARY KEY NOT NULL,NAME TEXT, AGE INT, ADDRESS CHAR(50), SALARY REAL);");
    // insert data
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (1, 'Sally', 32, 'California', 200000.00 );");
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (2, 'Stan', 20, 'Sweden', 120000.00 );");
    var parameters = {
         'NewName': 'James',
         'NewAge': '17',
         'NewAddress': 'UK',
         'NewSalary': 11000,
    };
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (3, :NewName, :NewAge, :NewAddress, :NewSalary );", parameters);
}

cacheDbGetLastErrorMessage(filename)

cacheDbGetLastErrorMessage returns the error message from the last operation if it failed.

Parameters:

Name	Type	Description
`filename`	string	the file name of the db

Returns:

success - false if the last operation failed, true if it was successful

cacheDbGetLastSuccess(filename)

cacheDbGetLastSuccess checks if the last operation on an SQLite DB was successful.
If false, then the error message is available through cacheDbGetLastErrorMessage

Parameters:

Name	Type	Description
`filename`	string	the file name of the db

Returns:

success - false if the last operation failed, true if it was successful

cacheDbOpen(filename)

cacheDbOpen opens a SQLite DB on the devices local storage. If the DB does not exist it will be created.
An SQLite DB is used for local settings and won't normally be synced during an Editor project save.
The DB file can be set to sync on Editor save with the filename suffix "_sync.db" e.g, "sharemydb_sync.db". That, now populated, file will be downloaded to during a client project update. The updated file will overwrite the project-local DB file.
After a DB is opened, it may be accessed with cacheDbSelectRaw and cacheDbExec.
When done with a DB, it should be closed with cacheDbClose - however Umajin does it's best to clean this up for you if you forget.
This system uses the excellent SQlite database, find out more here https://www.sqlite.org/lang.html

Parameters:

Name	Type	Description
`filename`	string	this is the name of the db it will be stored in the local project cache folder and subfolders cannot be used If you use the special filename ":memory:" then an in-memory database will be created or opened - this type of database will be lost when the app finishes.

Returns:

true if the database was opened successfully, or was already open. False if the datbase cannot be opened or created

Example

var success = cacheDbOpen("mydb.db");

cacheDbSelect(filename, sql)

cacheDbSelect executes a SELECT query on a SQLite DB that has already been opened with cacheDbOpen.
The result is returned as a JSON string. We suggest using cacheDbSelectRaw instead for improved features and performance.

Parameters:

Name	Type	Description
`filename`	string	the same filename that has previously been passed to cacheDbOpen and uniquely identifies the DB
`sql`	string	a SQLite compatible SELECT statement

Returns:

JSON - a stringified JSON result set

cacheDbSelectRaw(filename, sql, bindings)

cacheDbSelectRaw executes a SELECT query on a SQLite DB that has already been opened with cacheDbOpen.
The results are returned as a Javascript array.
For queries that are not expected to return a result set, use cacheDbExec.

Parameters:

Name	Type	Description
`filename`	string	the same filename that has previously been passed to cacheDbOpen and uniquely identifies the DB
`sql`	string	a SQLite compatible SELECT statement
`bindings`	object	Optional. Named parameters to bind to parameters in the SQL. Allows passing data without the need to escape special characters or risk of SQL injection attacks. Supported types are: numbers, strings, null, and ArrayBuffer for binary data. Parameter names should use alphanumeric and underscore characters only. Refer to them with a colon in the SQL, e.g :myparam

Returns:

array - an array of objects containing row data.
Nulls will be represented as undefined.

Example

registerAction("dbDemo", "", "dbDemo", "")
function dbDemo() {
    var success = cacheDbOpen("mydb.db");
    // drop and create table
    cacheDbExec("mydb.db", "DROP TABLE IF EXISTS Company;");
    cacheDbExec("mydb.db", "CREATE TABLE Company(ID INT PRIMARY KEY NOT NULL,NAME TEXT, AGE INT, ADDRESS CHAR(50), SALARY REAL);");
    // insert data
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (1, 'Sally', 32, 'California', 200000.00 );");
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (2, 'Stan', 20, 'Sweden', 120000.00 );");
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (3, 'Jeff', 42, 'Texas', 82000.00 );");
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (4, 'Fred', 45, 'Norway', 110000.00 );");
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (5, 'Mary', 39, 'Texas', 90000.00 );");
    cacheDbExec("mydb.db", "INSERT INTO COMPANY (ID,NAME,AGE,ADDRESS,SALARY) VALUES (6, 'Ellen', 30, 'Texas', 98000.00 );");
    // perform query
    var results = cacheDbSelectRaw("mydb.db", "SELECT * FROM Company WHERE ADDRESS = 'Texas' ORDER by AGE");
    console.log(results);
    // perform query with bound parameter
    results = cacheDbSelectRaw("mydb.db", "SELECT * FROM Company WHERE ADDRESS = :AddressToFind ORDER by AGE", {'AddressToFind': 'Texas' } );
    console.log(results);
}
// The resulting data
// [{"ADDRESS":"Texas", "AGE":"30", "ID":"6", "NAME":"Ellen", "SALARY":"98000"},
// {"ADDRESS":"Texas", "AGE":"39", "ID":"5", "NAME":"Mary", "SALARY":"90000"},
// {"ADDRESS":"Texas", "AGE":"42", "ID":"3", "NAME":"Jeff", "SALARY":"82000"}]
//
// use it as below
// for ( var rowIndex = 0; rowIndex < results.length; rowIndex ++ ) {
//	console.log(results[ rowIndex ].ADDRESS);
// }

callAction(name)

callAction() calls a Umajin Action. You can look at all the actions and their details in the Editor. To view actions go to the actions tab in the properties inspector and click the plus button on an event as if to add an action to it. This will bring up the action selector popup and shows most of the actions you can call from JavaScript, sorted by category and searchable. Single click an action to highlight it and view its details on the panel to the right. There are some actions that only make sense to be called from JavaScript that are not in the Editor. These actions are described below. If an action has parameters these are required to be passed in to callAction(). Where a component is a parameter, use the get_component_uuid function to retrieve the correct reference.

The Editor's action help can also be useful in learning about the various actions: https://help.umajin.com/actions-help/

Note on actions that are not in Editor:
"set_popup_visibility_by_name" Is deprecated and you should use "set_popup_visibility" instead.
"show_popup_by_name" Is deprecated and you should use "show_popup" instead.
"set_feed_item_url" Is depricated and you should use "set_feed_url" instead which handles multiple component types.

Note on actions in Editor that are not useful to use from Javascript:
"noop" This is "No Operation" and is used for components to consume an event without doing anything. This does nothing and there is no reason to call it from JavaScript.
"print" Javascript has a print() function which also writes to the Editor console and not just the Umajin standard out.
"console_log" Just use the print() function in JS as it does the same thing.
"exec_js" There is no need to call this on the Editor from JavaScript. You can just run the JavaScript that it would call directly from JavaScript.
"condition" This is used to allow you to use programming conditional statements to determine if an action fires in the Editor. You can just put this logic into your Javascript code.
"condition_else" Conditional logic can be done in Javascript directly so no point in doing it through Editor.
"condition_end" Conditional logic can be done in Javascript directly so no point in doing it through Editor.
"wait" This forces the Editor to wait some specified time before executing the next action. You can do this directly from JavaScript.
"first_time_only" This is used from Editor to make sure the following action only runs once. Logic like this can just be done in JavaScript.
"hide_if_empty" This is conditional logic that can be done in Javascript directly so no point in doing it through Editor.
"hide_if_not_empty"

Parameters:

Name	Type	Description
`name`	string	the name of the action to call.
	parameters	Between 0 and 12 parameters to pass to the action, specifics for what parameters an action needs are in the Editor.

Examples

//webpage
callAction("show_webpage","http://www.umajin.com");

//show page by name
callAction("show_page_by_name","my_page_name",3);

//show popup
callAction("show_popup","my_message");

//play a sound
callAction("stop_all_sound");
callAction("play_sound","demo.mp3",0,1);

//set a feed item view custom index
//this needs an component converted to an ID
var view_id = getProperty(view_component,'unique_id')
callAction("set_feed_item", view_id, "0", "custom_index", i)

cameraCapture(return_function)

Takes a photo, using the native device user interface for camera on Android and iOS.
On the desktop a similar user interface is simulated using webcams.
Note: the returned image file will be outside the normal project image path.
To display it in an Image component, use the prefix 'file://' in front of the file path.

Required Permissions: CAMERA

Parameters:

Name	Type	Description
`return_function`	string	a callback function that gets called when the photo has been taken. The callback function is passed a filename of the image, or a blank string if the user cancelled.

Examples

cameraCapture('captureResult');
function captureResult(filePath) {
	if (filePath=='') {
		callAction('show_popup','Photo Cancelled!');
	} else {
		callAction('show_popup', 'Photo taken: ' + filePath);
	}
}

// Retrieve an image component placed from the editor... We will use this to set an image taken from the camera.
var im = findComponent('Page 1', "image", "Image 1");
registerAction('cameraExample', '', 'cameraExample', '');
function cameraExample() {
    cameraCapture('cameraCaptureExample'); // callback passes the filename
}
function cameraCaptureExample(filename) {
    console.log(filename); // The file is stored in the cache directory
    setProperty(im, "filename", "file://" + filename); // Need to prefix file:// to display the image.
}

cameraCodeScan(return_function, message, format)

cameraCodeScan allows the user to scan various code formats, including QR and bar codes, with the device camera
(including webcams on the desktop). The code is returned to a callback as a string.
If the scan is cancelled the callback is notified with a blank string.

Formats accepted are: QR Code, Barcode, Data Matrix, Aztec, and PDF417.
Barcode sub formats accepted are: UPC A, UPC E, EAN 13, EAN 8, Codabar, Code 39, Code 93, Code 128, ITF.

Required Permissions: CAMERA

Parameters:

Name	Type	Description
`return_function`	string	is a function with a single string paramter that represents the data encoded by the QR code or bar code.
`message`	string	the message displayed on the scanning window.
`format`	int	defines the code format that will be scanned for: 1 = QR Code, 2 = Any format

Example

cameraCodeScan("found_code", "Scan your QR code!", 1);
function found_code(code){
    console.log("Here is our QR code " + code)
}

cancelAllAlarms()

Cancels all alarms previously scheduled with notifyLater or notifyAtDateTime

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

cancelAllDelayedCalls()

cancelAllDelayedCalls cancels all waiting delayCall calls.

cancelAllNotifications()

DEPRECATED. Please use cancelAllAlarms

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

cancelDelayedCalls(delayed_function)

cancelDelayedCalls cancels all waiting delayCall calls that are supposed to call delayed_function.

Parameters:

Name	Type	Description
`delayed_function`	string	the name of a JavaScript function (that has previously been passed to delayCall)

Example

cancelDelayedCalls("function_to_call"); // function_to_call(args) {};

cancelGps(update_function)

cancelGps will cancel the GPS request identified by the update_function
(error function name does not matter)

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION

Parameters:

Name	Type	Description
`update_function`	string	the update function that was originally used to request the GPS location

cancelQuit()

In response to the on_quit_requested event, this tells the application that it should not exit.
Works on desktop only; on mobile devices quitting is mandatory.

cancelScheduledAlarm(id)

Cancels an alarm previously scheduled with notifyLater or notifyAtDateTime

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

Parameters:

Name	Type	Description
`id`	string	The id that was used to set the notification.

cancelScheduledNotification()

DEPRECATED. Please use cancelScheduledAlarm

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

cDecode(s)

cDecode This decodes a c langauge string back into Unicode.

Parameters:

Name	Type	Description
`s`	string	the c string to decode

Returns:

- the decoded Unicode string

cEncode(s)

cEncode This encodes a unicode string into a c langauge string. As an example a newline is encoded \n

Parameters:

Name	Type	Description
`s`	string	the Unicode string to encode

Returns:

- the c encoded string

checkBlePermission(onGrantedCallback, onDeniedCallback, onBluetoothError)

checkBlePermission must be called before any other Bluetooth methods are called. This permission check is for Bluetooth Low Energy. If you are using Bluetooth Classic, use checkBtcPermission

Required Permissions: PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN

Parameters:

Name	Type	Description
`onGrantedCallback`	string	the function to call if bluetooth permission is granted
`onDeniedCallback`	string	the function to call if bluetooth permission is denied
`onBluetoothError`	string	the function to call if an error occurs

checkBluetoothPermission()

DEPRECATED. Please use checkBlePermission for Bluetooth Low Energy, or checkBtcPermission for Bluetooth Classic.

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

checkBtcPermission(onGrantedCallback, onDeniedCallback, onBluetoothError)

checkBtcPermission must be called before any other Bluetooth methods are called. This permission check is for Bluetooth Classic. If you are using Bluetooth Low Energy, use checkBlePermission

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`onGrantedCallback`	string	the function to call if bluetooth permission is granted
`onDeniedCallback`	string	the function to call if bluetooth permission is denied
`onBluetoothError`	string	the function to call if an error occurs

checkFormValidation()

checkFormValidation This function checks all the "submit enabled" fields on a form and returns true if they are all valid.
Note that if validation fails, the form's On Validation Failed event does not fire; you need to fire that manually using raiseEvent()

Returns:

- true if all fields are valid.

Type: boolean

Example

registerAction('formSubmitAction', '', 'form Submition', 'component:Form:form');
function formSubmitAction(form) {
    var result = checkFormValidation(form)
    if (result == true) {
        // Validation was successful. Send off the form
    } else {
        console.log("Form failed validation");
        // Raise the form's "On Validation Fail" event; the same way the Umajin form submit button does. This event is known internally as on_validation_fail
        raiseEvent(form, "on_validation_fail", "{}");
    }
}

clearTempFolder(deleteFolders)

Deletes all files and optionally folders in the project temp folder.

Parameters:

Name	Type	Description
`deleteFolders`	boolean	only deletes temp directory inner folders if this is true;

Returns:

True if successful.

Type: boolean

compressFile(filename)

compressFile compresses a file using gzip adding a .gz extension and returning the new filename.

Parameters:

Name	Type	Description
`filename`	string	the combined path and name of the file to compress.

Returns:

string - The filename for the new compressed file (with an added .gz).

copyFile(fromPath, toPath)

Copy a file to a new location.

Parameters:

Name	Type	Description
`fromPath`	string	Path of the file to copy.
`toPath`	string	Destination path to copy the file to. The file name does not have to match the original files name.

Returns:

True if successful.

Type: boolean

createComponent(obj, className, x1, y1, x2, y2 [, componentName])

createComponent creates an instance of the className ComponentString inside your custom component, positioned at x1% from the left, x2% from the right,
y1% from the top and y2% from the bottom. The width and height of the component is automatically calculated based on the points provided.

Parameters:

Name	Type	Description
`obj`	object	the custom component or sub component you have created under which the component will be created.
`className`	string	the string name of the component class to create. animated_feed animation app_popup button carousel carousel_item dropdown_menu dynamic_article feed_item_view feed_list gallery renderkit glass_shelf group hamburger_menu html_article image image_zoomer layout_group map_view model_static_3d nine_slicer page particle rectangle scroll_panel_v2 text text_entry tiler toggle_button tool_bar tool_bar_item video
`x1`	number	the percent width to offset from the left edge of the parent component.
`y1`	number	the percent height to offset from the top edge of the parent component.
`x2`	number	the percent of the parent component's width to use for the width of the created component.
`y2`	number	the percent of the parent component's height to use for the height of the created component.
`componentName`	string	Name to give the new component

Returns:

- a reference to the newly created component (or null if there is an error)

Type: object

Example

//create a new renderkit component during initialisation of the custom component
function componentInit(width, height) {
    var rk = createComponent(self, "renderkit", 0, 0, 100, 100)
}

createDirectory(filename)

Create a new directory.

Parameters:

Name	Type	Description
`filename`	string	Path of the directory to create.

Returns:

True if successful.

Type: boolean

cropImage(local_filepath_in, local_filepath_out, quality_ratio, src_x, src_y, src_width, src_height, des_width, des_height)

cropImage is a function to resize and crop an image

Parameters:

Name	Type	Description
`local_filepath_in`	string	the path to the local input file
`local_filepath_out`	string	the path to the local output file
`quality_ratio`	number	Quality of compression of the new thumbnail (0-1)
`src_x`	number	the left in pixels of the source crop
`src_y`	number	the top in pixels of the source crop
`src_width`	number	the width in pixels of the source crop
`src_height`	number	the height in pixels of the source crop
`des_width`	number	the final crop width in pixels
`des_height`	number	the final crop height in pixels

decode(string, mode)

decode deodes the input string from the format specified by mode. Mode can be "xml", "url, or "c", and defines the decoding scheme to use.

Parameters:

Name	Type	Description
`string`	string	input string
`mode`	string	the decoding method to use

Returns:

- the decoded string

decompressFile(filename)

decompressFile decompressed a gzip (.gz) file and extracts it without the .gz extension and returns the new filename.

Parameters:

Name	Type	Description
`filename`	string	the combined path and name of the .gz file to decompress.

Returns:

string - The filename for the new decompressed file (without the .gz).

delayCall(delayed_function, delay)

delayCall calls a named function after a time delay specified in milliseconds.
delayCall calls can be canceled by cancelDelayedCalls or cancelAllDelayedCalls.
This has a similar function but different implementation to the standard browser function setTimeout()

Parameters:

Name	Type	Description
`delayed_function`	string	the name of a JavaScript function, optionally you can include stringified brackets and parameters
`delay`	int	the number of milliseconds to wait before calling delayed_function

Example

delayCall("function_to_call",100);
delayCall("function_to_call(parameter_to_pass)",100);

deleteCookie(key)

deleteCookie deletes the value stored at key. Future calls to hasCookie(key) will be false until setCookie(key) is called again.
Cookies can be set with setCookie, checked for existence with hasCookie, and retrieved with getCookie.

Parameters:

Name	Type	Description
`key`	string	is the key to check for existence

deleteDirectory(path)

Delete a directory and all of its contents. Directory must be in the projects temp or cache directory

Parameters:

Name	Type	Description
`path`	string	Path of the directory to delete.

Returns:

True if successful.

Type: boolean

deleteFile(filename)

Delete a file.

Parameters:

Name	Type	Description
`filename`	string	Path of the file to delete.

Returns:

True if successful.

Type: boolean

discoverDevices(onDeviceDiscoveredCallback, onDiscoverDevicesError)

Discovers bluetooth devices in range and gives a separate callback for each device as it is found.

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`onDeviceDiscoveredCallback`	string	the function to call when a device is found
`onDiscoverDevicesError`	string	the function to call if there was an error

discoverServicesBySdp(deviceName, servicesFoundCallback, errorCallback)

Returns a list of services for the specified bluetooth device

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`deviceName`	string	the name of the device to try and discover services on
`servicesFoundCallback`	string	the function to call when we find services
`errorCallback`	string	the function to call if there was an error

disperseFormData(form, data)

disperseFormData This function loads a JSON set of new field values to a form, where form field names match keys in the JSON.

Parameters:

Name	Type	Description
`form`	component	the Form component to load field data into
`data`	string	the new field values where the key is the form field name.

Example

registerAction('fillInForm', '', 'Fill in Form Data', 'component:Form:form');
function fillInForm(form){
    disperseFormData(form, '{"comment":"Add a comment","email_address":"example@umajin.com","first_name":"Enter first name","last_name":"Enter last name"}');
}

enableBle(onEnabledCallback, onDisabledCallback, onBluetoothError)

enableBle is for Bluetooth Low Energy. If you are using Bluetooth Classic, use enableBtc

Required Permissions: PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN

Parameters:

Name	Type	Description
`onEnabledCallback`	string	the function to call once bluetooth has been enabled
`onDisabledCallback`	string	the function to call if bluetooth has been disabled
`onBluetoothError`	string	the function to call if an error occurs

enableBluetooth()

DEPRECATED. Please use enableBlefor Bluetooth Low Energy, or enableBtc for Bluetooth Classic.

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

enableBtc(onEnabledCallback, onDisabledCallback, onBluetoothError)

enableBtc is for Bluetooth Classic. If you are using Bluetooth Low Energy, use enableBle

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`onEnabledCallback`	string	the function to call once bluetooth has been enabled
`onDisabledCallback`	string	the function to call if bluetooth has been disabled
`onBluetoothError`	string	the function to call if an error occurs

encode(string, mode)

encode encodes the input string in the format specified by mode. Mode can be "xml", "url, "c", or "md5", and defines the encoding scheme to use.

Parameters:

Name	Type	Description
`string`	string	input string
`mode`	string	the encoding method to use

Returns:

- the encoded string

Example

encode('a string', 'md5');

endProfileBlock(blockName)

Stop profiling the block that you previously started with `startProfileBlock`.

Parameters:

Name	Type	Description
`blockName`	string	The name of the block that you want to stop profiling. Must match the `blockName` from the `startProfileBlock` call.

externalFunctionProcess(library_name, payload)

Mac/Windows: Calls the umajinProcess function on the library with name "library_name".
This name must exactly match the name given to registerExternalFunction

Parameters:

Name	Type	Description
`library_name`	string	the name of the library to call.
`payload`	string	string data to pass to the library. This function passes a string only; use externalFunctionProcessBinary to send binary data.

externalFunctionProcessBinary(library_name, payload, binary_data)

Mac/Windows: Calls the umajinProcessBinary function on the library with name "library_name".
This name must exactly match the name given to registerExternalFunction

Parameters:

Name	Type	Description
`library_name`	string	the name of the library to call.
`payload`	string	string data to pass to the library.
`binary_data`	ArrayBuffer	binary data to pass to the library.

fileCacheRemove(name)

fileCacheRemove removes the specified filename from the file, image and textures caches.

Parameters:

Name	Type	Description
`name`	string	The name of the file.

fileExists(path)

fileExists Returns true if a file exists in either the cache or temp folders. ()
Due to platform limitations, only 'cache' and 'temp' folders are available.
If the filename or folder doesn't exist, false is returned.

Parameters:

Name	Type	Description
`path`	string	The path to the file, relative to the project folder

Example

var exists1 = fileExists('temp/test.jpg');
var exists2 = fileExists('./temp/test.jpg');
var exists3 = fileExists('./cache/test.jpg');
var exists3 = fileExists('./doesntexist/test.jpg'); // false

findComponent(page_name, component_type, component_name)

findComponent returns the first component given a page name, component type and component name.
or '' or 0 if no such component is found.

Parameters:

Name	Type	Description
`page_name`	string	is the display name of a page in the app
`component_type`	string	is the type of the component to return. Can be one of the elements of ComponentString.
`component_name`	string	is the name of the component to return

Returns:

- the matching component object or null if the component can't be found

Type: object

Example

// "Login" page has a text entry called 'username'
var username_text = findComponent('Login', 'text_entry', 'username');

findComponentInDialog(dialog_name, component_type, component_name)

findComponentInDialog returns the first component given a dialog name, component type and component name.

Parameters:

Name	Type	Description
`dialog_name`	string	the name of the dialog
`component_type`	string	the name of the type of component componentString
`component_name`	string	the name of the component

Returns:

- either null or the specific component

Type: object

Example

// "Greeting" dialog, has a button called 'OK'
var okButton = findComponentInDialog('Greeting Dialog', 'button', 'ok');

findComponentInForeground(foreground_name, component_type, component_name)

findComponentInForeground returns the first component given a foreground name, component type and component name.
This is very useful for getting access to toolbars and menus that are on the foreground layer that you want to modify.

Parameters:

Name	Type	Description
`foreground_name`	string	the name of the foreground to search
`component_type`	string	the name of the type of component componentString
`component_name`	string	the name of the component

Returns:

- either null or the specific component

Type: object

Example

// The foreground of "Login" page, "navBar", has a button called 'back'
var back = findComponentInForeground('navBar', 'button', 'back');

findPage(pagename)

findPage returns the page object with the name pagename. If no such page exists, 0 or '' is returned.

Parameters:

Name	Type	Description
`pagename`	string	the display name of the page object to return

Returns:

- the specified page object or null if the component can't be found

Type: object

gatherFormData(form)

gatherFormData This function collects all the "submit enabled" fields from a form and returns them as a JSON string; keys are the Form Field Names.

Parameters:

Name	Type	Description
`form`	component	the Form component to collect data from

Returns:

- the JSON containing the Form Field names and values.

Type: string

getBleCharacteristic(serviceId, characteristicId, callback)

getBleCharacteristic This will retrieve a characteristic from a bluetooth device. This is the equivalent of setting a characteristic which can be done with callAction like so callAction('set_ble_charcteristic', SERVICES.nfc.uuid, SERVICES.nfc.chars.read, 'on');
Note : BLE devices have UUID's stored as hex values in this format uuid: '0DEF1000-6656-11E5-A4E0-23D9BD6569A7'

Required Permissions: PERMISSION_COARSE_LOCATION, PERMISSION_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN

Parameters:

Name	Type	Description
`serviceId`	string	the uuid of the BLE parent service e.g. accelerometer.uuid: '0DEF5000-6656-11E5-A4E0-23D9BD6569A7'
`characteristicId`	string	The characteristic to query e.g. accelerometer.chars.acceleration: '0DEF5003-6656-11E5-A4E0-23D9BD6569A7'
`callback`	string	the function to call which takes two parameters: a value string and a value ArrayBuffer of binary data

Example

function init() {
    checkBlePermission("blePermissionGranted","blePermissionDenied","bleError")
}
function blePermissionGranted() {
    enableBle("bleEnabled","bleDisabled","bleEnabledError")
}
function blePermissionDenied() {
}
function bleError() {
}
function bleEnabled() {
    callAction('set_ble_frequency', 10000);
}
function bleDisabled() {
}
function bleEnabledError() {
}
 
function getMovements() {
    getBleCharacteristic(deviceId, SERVICES.accelerometer.uuid, SERVICES.accelerometer.chars.acceleration, 'getMovementsCallback');
}
 
function getMovementsCallback(string_value, binary_value) {
    if (!isCurrentPage(accelerometerPage)) return;
    try {
        var jsonString = '[' + value.split('}{').join('},{') + ']';
        var values = JSON.parse(jsonString);
 
        if (values[0].hasOwnProperty('x') && values[0].hasOwnProperty('y') && values[0].hasOwnProperty('z')) {
            setProperty(accelerometerTextfields.x, 'text', parseFloat(values[0].x).toFixed(2));
            setProperty(accelerometerTextfields.y, 'text', parseFloat(values[0].y).toFixed(2));
            setProperty(accelerometerTextfields.z, 'text', parseFloat(values[0].z).toFixed(2));
        } else {
            console.log('getMovementsCallback: no x, y, z found on "values"');
        }
    } catch (err) {
        console.log('Error (getMovementsCallback): ' + err);
    }
    delayCall('getMovements', movementsInterval);
}

getComponentByName(obj, component_name)

getComponentByName returns a sub component by it's name.

Parameters:

Name	Type	Description
`obj`	object	a component object
`component_name`	string	the name of the sub component to return

Returns:

- the named sub component or null if nothing was found

Type: object

getComponentByUniqueID(Unique)

getComponentByUniqueID returns a component by it's Unique ID.

Parameters:

Name	Type	Description
`Unique`	string	ID - the unique_id of the component

Returns:

- the component or null if nothing was found

Type: object

getComponentChild(obj, index)

getComponentChild returns the component that is the index-th child of the container obj.

Parameters:

Name	Type	Description
`obj`	object	a container component
`index`	int	the index of the child object to return

Returns:

the child component of container obj at the specified index.
or 0 if obj is not a container or there is no component at that index.

Type: object

Example

// "Login" page has a button and a text entry called 'username'. The index of component starts 0, the index of 'username' is 1.
// Get text entry by clicking the button.
// Assign the below action to 'on press' of button.
registerAction('getUsernameComponent', '', 'Get Username Text Entry', '', '', '');
function getUsernameComponent() {
    var parent = getComponentParent(self);
    var usernameTextEntry = getComponentChild(parent, 1);
    console.log(usernameTextEntry);
}

getComponentChildCount(obj)

getComponentChildCount returns the number of child components that have been placed inside of the container obj.
If a non-container is passed, the result will be 0.

Parameters:

Name	Type	Description
`obj`	object	a component

Returns:

- the number of child components of the container component obj, or 0 if obj is not a container

Type: int

Example

// "Login" page has a button and a text entry called 'username'.
// Get Component Count by clicking the button.
// Assign the below action to 'on press' of button.
registerAction('getComponentCount', '', 'Get Component Count', '', '', '');
function getComponentCount() {
  var parent = getComponentParent(self);
  var count = getComponentChildCount(parent);
  console.log(count);		// 2
}

getComponentParent(obj)

getComponentParent returns the container object that is the parent of the component obj. This will not return a parent beyond the component you are inspecting.

Parameters:

Name	Type	Description
`obj`	object	a component object

Returns:

- the parent container component of obj or null if there is an error

Type: object

Example

// "Login" page has a button and a text entry called 'username'.
// Get parent component by clicking the button.
// Assign the below action to 'on press' of button.
registerAction('getParentComponent', '', 'Get Parent Component', '', '', '');
function getParentComponent() {
    var parent = getComponentParent(self);
    console.log(parent);
}

getCookie(key)

getCookie returns the value of the persistent cookie that was stored at key.
Cookies can be set with setCookie, tested for existence with hasCookie, and deleted with deleteCookie.

Parameters:

Name	Type	Description
`key`	string	is the key whose value to return

Returns:

- the value stored at key

Type: string

getData(object, key)

getData returns the value that the data-bound component object has stored at key (using setData)

Parameters:

Name	Type	Description
`object`	object	a component object. "self" may be used to reference the current instance of a custom component.
`key`	string	the key to fetch data from.

getDataBulk(object)

getDataBulk returns JSON string of data stored against a component (using setDataBulk)

Parameters:

Name	Type	Description
`object`	object	a component object. "self" may be used to reference the current instance of a custom component.

Example

var allData = JSON.parse(getDataBulk(month_component));

getFeed(id, ttl, success_function, error_function)

getFeed asynchronously returns the contents of the feed with given ID to success_function. Calls error_function if an error is encountered.

Parameters:

Name	Type	Description
`id`	string	the id of the feed to retrieve
`ttl`	int	the number of ms to wait before timing out
`success_function`	string	the name of a JavaScript function to call after the feed contents is downloaded. This passes the url requested and the filename of the downloaded feed file within the cache. Use getGlobal( 'cache_path' ) to find the cache path.
`error_function`	string	the name of a JavaScript function to call if there is an error encountered during the download. This passes the url requested that was not able to be downloaded.

getFile(url, ttl, success_function, error_function)

getFile asynchronously returns the contents of the file at url to success_function. Calls error_function if an error is encountered.

Parameters:

Name	Type	Description
`url`	string	the URL of the file to retrieve
`ttl`	int	the number of ms to wait before timing out
`success_function`	string	the name of a JavaScript function to call after the file is downloaded. This passes the url requested and the filename of the downloaded file within the cache. Use getGlobal( 'cache_path' ) to find the cache path.
`error_function`	string	the name of a JavaScript function to call if there is an error encountered during the download. This passes the url requested that was not able to be downloaded.

getFilesInFolder(path)

getFilesInFolder Returns a pipe delimited string of filenames that exist in a given folder.

Parameters:

Name	Type	Description
`path`	string	the path in the project folder to enumerate

Returns:

files - string containing the files with a pipe character between

Type: string

Example

var fileString = getFilesInFolder('images/');
var fileList = fileString.split("|");

getFoldersInFolder(path)

getFoldersInFolder Returns a pipe delimited string of folder names that exist in a given folder.

Parameters:

Name	Type	Description
`path`	string	the path in the project folder to enumerate

Returns:

folders - string containing the folders with a pipe character between

Type: string

Example

var folderString = getFoldersInFolder('images/');
var folderList = folderString.split("|");

getForeground(page_name)

getForeground This returns the current foreground associated with the requested page.
Note : a page can only have one current foreground object (e.g. toolbar, menu etc).

Parameters:

Name	Type	Description
`page_name`	string	the name of the page to find the foreground

Returns:

foreground_name, a string- The name of the foreground, will be '' if no foreground was applied to the requested page

Example

getForeground('Login');

getGlobal(property)

//Dangerous function for David Brebner to use for making macros. Not a normal JS call. The results are permanent and don't revert when going back to edit mode.
function createEditableComponent(obj, className, x1, y1, x2, y2, component_name) {
return U_call_method("create_editable_component", global_script_object, obj, className, x1, y1, x2, y2, component_name);
}

//Dangerous function for David Brebner to use for making macros. Not a normal JS call. The results are permanent and don't revert when going back to edit mode.
function setEditableProperty(obj, prop, value) {
U_call_method("set_editable_property", global_script_object, obj, prop, value)
}

//Dangerous function for David Brebner to use for making macros. Not a normal JS call. The results are permanent and don't revert when going back to edit mode.
function createEditablePage() {
return U_call_method("create_editable_page", global_script_object);
}

//Dangerous function for David Brebner to use for making macros. Not a normal JS call. The results are permanent and don't revert when going back to edit mode.
function createEditableAction(obj, eventID, actionString) {
return U_call_method("create_editable_action", global_script_object, obj, eventID, actionString);
}

/// GET AND SET PROPERTIES ///

/**
getGlobal returns the value of a global property with the given name (these are not the same as global variables)
Some global properties can also be changed using setGlobal

Parameters:

Name	Type	Description
`property`	string	the name of the property to get from the following list.

Properties:

Name	Type	Description
`uptime`	number	time the app has been running in ms, with fractional part up to microseconds.
`tz_offset`	number	time zone offset from UTC in ms
`utc`	number	UTC time in ms
`os`	string	the operating system name and version: "Android...", "OS X...", "Windows..." or "iOS..."
`clipboard`	string	contents of clipboard as a string
`window_title`	string	the title of the Umajin Editor Lite window.
`latitude`	number	last known latitude of the user
`longitude`	number	last known longitude of the user
`device_id`	string	unique ID for this device. Android: returns ANDROID_ID iOS: returns IDFV MacOS: returns the Mac serial number Windows: returns a generated unique ID, which changes if app is reinstalled
`advertising_id`	string	platform advertising ID (IDFA or ADID) for use in advertisements or analytics. If the user has chosen to limit tracking (see advertising_tracking_limited below) then this will be blank. Note: this property only works in published apps on iOS and Android; in Editor or Editor Lite, and on Windows and Mac, it is always blank.
`advertising_tracking_limited`	boolean	whether the user has chosen to limit ad tracking (true = limited). Apps must respect this setting and not use other tracking methods - this is enforced by app store policies. Note: this property only works in published apps on iOS and Android; in Editor or Editor Lite, and on Windows and Mac, it is always true.
`user_agent_suffix`	string	the HTTP user agent that the operating system supplies, without any application/version on the front. You can use this to build your own custom user agents while including standard platform details such as OS version. For example an iPhone may return a string like "(iPhone; CPU iPhone OS 12_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148"
`user_agent`	string	returns the currently set user agent for JS HTTP calls. Defaults to published_app_name/published_app_version followed by user_agent_suffix (see above).
`project_token`	string	unique token for the app
`project_id`	number	unique id for the app
`width`	number	page width in pixels
`height`	number	page height in pixels
`http_spinner`	boolean	Will the spinner show for JS http requests, true or false
`http_blocker_alpha`	number	How transparent the JS http spinner will be (transparent 0-255 opaque)
`current_page`	string	current page name
`apeid`	string	your pubid on the ape channel
`version`	string	version of the editor / viewer, such as "3.1.0.0"
`pubid`	string	your pubid on the socketIO channel
`version`	string	version of the editor / viewer, such as "3.1.0.0"
`album_path`	string	fullpath to the Album or Photos folder
`cache_path`	string	fullpath to the cache folder. This folder is writable.
`temp_path`	string	fullpath to the temp folder. This folder is writable.
`project_path`	string	full path to the project folder. This folder is read-only on mobile devices.
`project_name`	string	name of the current project
`js_es6_modules`	boolean	project Javascript files are es6 modules if true.
`uses_bluetooth_editor_actions`	number	None/BLE/BT (Classic) editor actions are used by the project.
`project_version`	string	from the version.txt in the project folder eg 1.0.102
`app_mode`	number	what mode is the app running in. 0: Standalone, 1: Umajin Editor, 2: Umajin Editor Lite.
`play_mode`	boolean	returns true in a published app, in the viewer or portal, or in the editor in preview mode. Returns false in the editor in edit mode.
`is_published`	boolean	returns true in a published app (or a sideloaded, standalone app).
`published_app_version`	string	returns the version string used to publish the app.
`published_app_name`	string	returns the name used to publish the app.
`dpi`	number	dots per inch of the devices screen
`destination_page_name`	string	set during a page transition
`hostname`	string	the device network hostname
`allow_screen_saver`	boolean	whether the app is allowing the system to sleep
`battery_percentage`	number	the charge level of the device battery from 0 to 100
`scale_factor`	number	get OS scale factor for the current monitor (desktop only).
`zoom_level`	number	get the apps zoom level.
`window_state`	number	Get the window state. 0:Windowed, 1:Maximized, 2:Fullscreen, 3:Minimized. (desktop only)
`window_x`	number	current window x in pixels (desktop only).
`window_y`	number	current window y in pixels (desktop only).
`window_width`	number	current window width in pixels (desktop only).
`window_height`	number	current window height in pixels (desktop only).
`screen_x`	number	current screen x in pixels (desktop only).
`screen_y`	number	current screen y in pixels (desktop only).
`screen_width`	number	current screen width in pixels (desktop only).
`screen_height`	number	current screen height in pixels (desktop only).
`workarea_x`	number	current workarea x in pixels (desktop only).
`workarea_y`	number	current workarea y in pixels (desktop only).
`workarea_width`	number	current workarea width in pixels (desktop only).
`workarea_height`	number	current workarea height in pixels (desktop only).
`metrics_fps`	number	Number of frames per second. Updated each frame.
`metrics_cpu_usage`	number	CPU usage for the editor process (%). Updated every 5 seconds.
`metrics_virtual_memory_usage`	number	Amount of virtual memory reserved by the operating system for this process (Kb). Updated every 5 seconds.
`metrics_texture_memory_usage`	number	Amount of texture memory usage (Kb).
`metrics_object_count`	number	Number of objects. Updated as objects are created and deleted.
`metrics_draw_calls`	number	Number of draw calls. Updated each frame.
`metrics_handles`	number	The number of open handles (ports on OSX) for this process. Updated every 5 seconds.
`metrics_file_cache_length`	number	The number of entries in the file cache. Updated each frame.
`metrics_image_cache_length`	number	The number of entries in the image cache. Updated each frame.
`metrics_texture_cache_length`	number	The number of entries in the texture cache. Updated each frame.
`metrics_texture_transient_memory`	number	The amount of GPU memory allocated to transient textures in MB. Updated each frame.
`metrics_texture_streaming_memory`	number	The amount of GPU memory allocated to streaming textures in MB. Updated each frame.
`metrics_texture_render_target_memory`	number	The amount of GPU memory allocated to render targets in MB. Updated each frame.
`metrics_index_buffers_total`	number	The amount of index buffers that currently exist.
`metrics_index_buffer_updates`	number	The amount of index buffers updated this frame.
`metrics_vertex_buffers_total`	number	The amount of vertex buffers that currently exist.
`metrics_vertex_buffer_updates`	number	The amount of vertex buffers updated this frame.

Returns:

- the value of the property.

Type: object

getGlobalVar(var_name)

getGlobalVar gets the value of a Umajin global variable.

Parameters:

Name	Type	Description
`var_name`	string	the name of the variable

Example

getGlobalVar('aGlobalVar');

getGps(update_function, error_function, accuracy_metres, timeout_ms)

getGps will request a single GPS location to be returned.
Note: currently only one callback can be used at once

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION

Parameters:

Name	Type	Description
`update_function`	string	the function that is called with three parameters, latitude, longitude and accuracy
`error_function`	string	the function to receive an error message
`accuracy_metres`	real	the desired accuracy in metres, or -1 for any
`timeout_ms`	int	the maximum time in milliseconds to wait for the location with sufficient accuracy. After this time, if a location less accurate than accuracy_metres has been obtained, the update_function will be called with that location anyway.

getImageSize(local_filepath, success_function)

Loads an image from a file and calls back with the native width, height and data size of the image.

Parameters:

Name	Type	Description
`local_filepath`	string	the path to the local file
`success_function`	string	the name of a JavaScript function which takes the pixel width, height and size in bytes.

getName(component)

getName gets the display name of the specified component.

Parameters:

Name	Type	Description
`component`	object	The component you want to know the name of.

Returns:

- the name of the component.

Type: string

Example

// Assign "aTestAction" to "on press" of a button which called "start".
registerAction('aTestAction', '', 'test action', '', '', '');
function aTestAction() {
    getName(self) 	// start
}

getPage(index)

getPage returns you the page by index number from the application.

Parameters:

Name	Type	Description
`index`	number	the page index number

Example

registerAction("printPageNames", "", "printPageNames", "")
function printPageNames() {
	for (i = 0; i < getPageCount(); i++) {
		var page = getPage(i);
		console.log(getType(page) + " > " + getName(page));
	}
}

getPageCount()

getPageCount returns you the number of pages in the application.

Example

registerAction("printPageNames", "", "printPageNames", "")
function printPageNames() {
	for (i = 0; i < getPageCount(); i++) {
		var page = getPage(i);
		console.log(getType(page) + " > " + getName(page));
	}
}

getPairableDevices()

Returns a list of discovered devices that you could pair with

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

getPairedDevices()

Returns a list of devices that you are paired with

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

getProperty(object, property)

getProperty gets the value of a component's property.
To set the value of a property, use setProperty, setPropertyIn, or setPropertyInTween.

Parameters:

Name	Type	Description
`object`	object	the Component object whose property you want to get the current value of
`property`	string	the name of the property to get the current value of

Properties:

Name	Type	Description
`width`	string	any component
`height`	string	any component
`native_width`	string	text, html_article, image
`native_height`	string	text, html_article, image
`x`	string	any component
`y`	string	any component
`page_x`	string	any component (position relative to the page)
`page_y`	string	any component (position relative to the page)
`visible`	string	any component
`lock_left`	string	any component
`lock_width`	string	any component
`lock_right`	string	any component
`lock_top`	string	any component
`lock_height`	string	any component
`lock_bottom`	string	any component
`instance_display_name`	string	any component
`unique_id`	string	any component
`text`	string	text, text entry, html article
`font_color`	string	text, button
`json`	string	custom component, feedlist
`scroll_offset`	string	any feed list or scroll panel
`scroll_max`	string	feed list
`filename`	string	image, video, animation
`instance_display_name`	string	any component

Returns:

- the value of the property.

Type: object

getTextStyleList()

getTextStyleList returns a pipe | delimited list of style names for the current project

Returns:

styleList - The styles

Type: string

getType(component)

getType gets the type of the specified component.

Parameters:

Name	Type	Description
`component`	object	The component you want to know the type of.

Returns:

- the type of the component.

Type: string

Example

// Assign "aTestAction" to "on press" of a button.
registerAction('aTestAction', '', 'test action', '', '', '');
function aTestAction() {
    getType(self) 	// button
}

hasCookie(key)

hasCookie checks if a persistent cookie has been set for key.
Cookies can be set with setCookie, retrieved with getCookie, and deleted with deleteCookie.

Parameters:

Name	Type	Description
`key`	string	is the key to check for existence

Returns:

- true if a cookie has been set for key and false if it has not

Type: boolean

hideCombo()

hideCombo hides a full screen combo box.

hideDialog(name)

hideDialog Hides a currently visible dialog.

Parameters:

Name	Type	Description
`name`	string	The name of a dialog to hide.

Example

hideDialog("myDialog"); // Will hide a visible dialog named myDialog

hideSpinner()

Hides the standard project spinner

hmacSha1(key, secret)

hmacSha1 is a keyed-hash message authentication code (HMAC) this should be used instead of MD5 as it is much more secure.
This is a useful cryptographic function for implementing many secure token exchange protocols.

Parameters:

Name	Type	Description
`key`	string	any string
`secret`	string	any string

Returns:

- the HMAC string

httpAddFormData(ref, field_name, value)

Adds a field value to an HTTP form request that is to be posted with httpPostFromRef

This results in a multipart form post with Content-type: multipart/form-data.
Do not set Content-type in headers if you use this method.

Parameters:

Name	Type	Description
`ref`	string	the integer ID of the HTTP request from httpNew
`field_name`	string	the name of the form field
`value`	string	the value of the form field

httpAddFormFile(ref, field_name, local_file_path, content_type)

Adds a file to an HTTP form request that is to be posted with httpPostFromRef

This results in a multipart form post with Content-type: multipart/form-data.
Do not set Content-type in headers if you use this method.

Parameters:

Name	Type	Description
`ref`	string	the integer ID of the HTTP request from httpNew
`field_name`	string	the name of the form field to add the file to
`local_file_path`	string	path to the file, either in temp, cache or a relative project file
`content_type`	string	the MIME type for the file, passed to the server in Content-Type.

httpDeleteFromRef(ref, url, headers, success_function, errror_function, cookieJar, http_spinner)

Makes an asynchronous HTTP DELETE request to a specified URL. Upon success or failure, the appropriate is callback is called.
Takes in a reference to an existing HTTP object created with httpNew

Parameters:

Name	Type	Description
`ref`	string	the integer ID of the HTTP request from httpNew
`url`	string	the full URL to send DELETE request.
`headers`	string	the string headers to pass with the HTTP PATCH request. Headers should be in the format name:value, seperated by CRLF \r\n Note: do not set the Content-type header if using a multipart post (httpAddFormFile() or httpAddFormData())
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpDeleteHeaders(url, headers, success_function, error_function, cookieJar, http_spinner)

httpDeleteHeaders issues an asynchronous DELETE request to URL with the header data in headers. Upon success or failure, the appropriate callback is called.

Parameters:

Name	Type	Description
`url`	string	the full URL to DELETE
`headers`	string	the custom headers to include with the DELETE requests. Headers should be in the format name:value, seperated by CRLF \r\n
`success_function`	string	the name of a JavaScript function to call if the DELETE is successful
`error_function`	string	the name of a JavaScript function to call if the DELETE is unsuccessful. The error message is passed.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpGet(url, success_function, errror_function, http_spinner)

Makes an asynchronous HTTP GET request to a specified URL. Upon success or failure, the appropriate is callback is called.

Parameters:

Name	Type	Description
`url`	string	the full URL to GET; may include a querystring
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

Example

httpGet("http://test.com", "cur_success", "cur_failure");
function cur_success(returnvalue, responseHeaders, cookieJar) {}
function cur_failure(errormessage, httpStatusCode, responseBody, responseHeaders, cookieJar) {}

httpGetFile(url, ttl, success_function, error_function, progress_function, headers, local_path, http_spinner)

httpGetFile asynchronously returns the contents of the file at url to success_function downloaded to local_path. Calls error_function if an error is encountered.

Parameters:

Name	Type	Default	Description
`url`	string		the URL of the file to retrieve
`ttl`	int		the number of ms to wait before timing out
`success_function`	string		the name of a JavaScript function to call after the file is downloaded.
`error_function`	string		the name of a JavaScript function to call if there is an error encountered during the download. This passes the url requested that was not able to be downloaded.
`progress_function`	string		the name of a JavaScript function to call to indicate download progress.
`headers`	string		custom headers that can be used for the http call.
`local_path`	string		The local filename to save the file to (a directory is not sufficient).
`http_spinner`	bool	null	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpGetFromRef(ref, url, headers, success_function, errror_function, cookieJar, http_spinner)

Makes an asynchronous HTTP GET request to a specified URL. Upon success or failure, the appropriate is callback is called.
Similar to httpGet, except this takes in a reference to an existing HTTP object created with httpNew

Parameters:

Name	Type	Description
`ref`	string	the integer ID of the HTTP request from httpNew
`url`	string	the full URL to GET data from
`headers`	string	the string headers to pass with the HTTP POST request. Headers should be in the format name:value, seperated by CRLF \r\n Note: do not set the Content-type header if using a multipart post (httpAddFormFile() or httpAddFormData())
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpGetHeaders(url, headers, success_function, errror_function, cookieJar, http_spinner)

Make an asynchronous HTTP GET request to a specified URL, and pass a custom HTTP header. Upon success or failure, the appropriate is callback is called.
Note: to persist http cookies between requests you must store the cookieJar and pass it into the next request
Note: reponseHeaders are JSON formatted, if there were redirects in the request then multiple header groups will be present, "code" is used for response code eg [{"code": "HTTP/1.1 302", "content-length": "0", ... }]

Parameters:

Name	Type	Description
`url`	string	the full URL to GET; may include a querystring
`headers`	string	the string headers to pass with the HTTP GET request. Headers should be in the format name:value, seperated by CRLF \r\n
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

Examples

httpGetHeaders("http://test.com", "[possible header to pass]", "cur_success", "cur_failure", cookieJar);
function cur_success(returnvalue, responseHeaders, cookieJar) {}
function cur_failure(errormessage, httpStatusCode, responseBody, responseHeaders, cookieJar) {}

new Action("Activity Suggestions", activitySuggestions)
.register();
function activitySuggestions() { 
    //https://www.boredapi.com/documentation
    httpGetHeaders("https://www.boredapi.com/api/activity?type=recreational", "Accept-Language: en-US,en;q=0.5",  "cur_success", "cur_fail")
}
 
function cur_success(returnvalue, responseHeaders, cookieJar) {
    //return data is a JSON string so read it in
    var result = JSON.parse(returnvalue);
    var headerObj = JSON.parse(responseHeaders);
    console.log('cur_success')
    console.log(result)
}
 
function cur_fail(message, httpStatusCode, responseBody, responseHeaders, cookieJar) {
    console.log('cur_fail')
    console.log(message)
}

httpNew()

Requests a new HTTP request object to have data or files added before posting with httpPostFromRef

Returns:

(int) An integer reference to the HTTP object. Use this in subsequent operations.

httpPatchFromRef(ref, url, data, headers, success_function, errror_function, cookieJar, http_spinner)

Makes an asynchronous HTTP PATCH request to a specified URL and sends data with the request. Upon success or failure, the appropriate is callback is called.
Takes in a reference to an existing HTTP object created with httpNew, allowing you to add files or data
with httpAddFormFile and httpAddFormData.

Parameters:

Name	Type	Description
`ref`	string	the integer ID of the HTTP request from httpNew
`url`	string	the full URL to PATCH to
`data`	string	the data to post to the specified URL. leave empty if you have called httpAddFormData or httpAddFormFile
`headers`	string	the string headers to pass with the HTTP PATCH request. Headers should be in the format name:value, seperated by CRLF \r\n Note: do not set the Content-type header if using a multipart post (httpAddFormFile() or httpAddFormData())
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpPatchHeaders(url, data, headers, success_function, error_function, cookieJar, http_spinner)

httpPatchHeaders issues an asynchronous PATCH request to URL with the header data in headers and the data to PATCH in data. Upon success or failure, the appropriate callback is called.

Parameters:

Name	Type	Description
`url`	string	the full URL to PATCH to
`data`	string	the data to PATCH
`headers`	string	the custom headers to include with the PATCH requests. Headers should be in the format name:value, seperated by CRLF \r\n
`success_function`	string	the name of a JavaScript function to call if the PATCH is successful
`error_function`	string	the name of a JavaScript function to call if the PATCH is unsuccessful. The error message is passed.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpPost(url, data, success_function, errror_function, http_spinner)

Makes an asynchronous HTTP POST request to a specified URL and POSTs data with the request. Upon success or failure, the appropriate is callback is called.
If you need to add form data or files to the POST, then see httpNew and httpPostFromRef.

Parameters:

Name	Type	Description
`url`	string	the full URL to POST to
`data`	string	the data to post to the specified URL. For simple requests, this is the same as the GET querystring without the leading "?"
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

Example

httpPost("http://test.com/form.php", "username=name&password=pass", "cur_success", "cur_failure");
function cur_success(returnvalue, responseHeaders, cookieJar ){}
function cur_failure(errormessage, httpStatusCode, responseBody, responseHeaders, cookieJar) {}

httpPostBinary(url, local_file_path, success_function, errror_function, http_spinner)

Makes an asynchronous HTTP POST request to a specified URL and POSTs file contents with the request. Not as a multipart form though. Upon success or failure, the appropriate is callback is called.

Parameters:

Name	Type	Description
`url`	string	the full URL to POST
`local_file_path`	string	the path the load the file contents from as binary data to post to the specified URL. Recommend adding a header like 'Content-Type: application/octet-stream'
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

Example

httpPostBinary("http://apitest.umajin.com/form.php", "images/IMG_000001.png", "cur_success", "cur_failure");
function cur_success(returnvalue, responseHeaders, cookieJar ){}
function cur_failure(errormessage, httpStatusCode, responseBody, responseHeaders, cookieJar) {}

httpPostBinaryFromRef(ref, url, local_file_path, headers, success_function, errror_function, cookieJar, http_spinner)

Makes an asynchronous HTTP POST request to a specified URL and sends data with the request. Upon success or failure, the appropriate is callback is called.
Takes in a reference to an existing HTTP object created with httpNew

Parameters:

Name	Type	Description
`ref`	string	the integer ID of the HTTP request from httpNew
`url`	string	the full URL to POST to
`local_file_path`	string	the path the load the file contents from as binary data to post to the specified URL. Recommend adding a header like 'Content-Type: application/octet-stream'
`headers`	string	the string headers to pass with the HTTP PUT request. Headers should be in the format name:value, seperated by CRLF \r\n Note: do not set the Content-type header if using a multipart post (httpAddFormFile() or httpAddFormData())
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpPostFromRef(ref, url, data, headers, success_function, errror_function, cookieJar, http_spinner)

Makes an asynchronous HTTP POST request to a specified URL and POSTs data with the request. Upon success or failure, the appropriate is callback is called.
Similar to httpPost, except this takes in a reference to an existing HTTP object created with httpNew, allowing you to add files or data
with httpAddFormFile and httpAddFormData.

Parameters:

Name	Type	Description
`ref`	string	the integer ID of the HTTP request from httpNew
`url`	string	the full URL to POST to
`data`	string	the data to post to the specified URL. leave empty if you have called httpAddFormData or httpAddFormFile
`headers`	string	the string headers to pass with the HTTP POST request. Headers should be in the format name:value, seperated by CRLF \r\n Note: do not set the Content-type header if using a multipart post (httpAddFormFile() or httpAddFormData())
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpPostHeaders(url, data, headers, success_function, errror_function, cookieJar, http_spinner)

Makes an asynchronous HTTP POST request with a custom header to a specified URL, and POSTs data with the request. Upon success or failure, the appropriate is callback is called.

Parameters:

Name	Type	Description
`url`	string	the full URL to GET
`data`	string	the data to post to the specified URL. For simple requests, this is the same as the GET querystring without the leading "?"
`headers`	string	the string headers to pass with the HTTP POST request. Headers should be in the format name:value, seperated by CRLF \r\n
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

Example

httpPostHeaders("http://test.com/form.php", "username=name&password=pass", "If-Modified-Since: Sat, 29 Oct 2017 19:43:31 GMT\r\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==", "cur_success", "cur_failure", cookieJar);
function cur_success(returnvalue, responseHeaders, cookieJar){}
function cur_failure(errormessage, httpStatusCode, responseBody, responseHeaders, cookieJar) {}

httpPutFromRef(ref, url, data, headers, success_function, errror_function, cookieJar, http_spinner)

Makes an asynchronous HTTP PUT request to a specified URL and sends data with the request. Upon success or failure, the appropriate is callback is called.
Takes in a reference to an existing HTTP object created with httpNew, allowing you to add files or data
with httpAddFormFile and httpAddFormData.

Parameters:

Name	Type	Description
`ref`	string	the integer ID of the HTTP request from httpNew
`url`	string	the full URL to PUT to
`data`	string	the data to post to the specified URL. leave empty if you have called httpAddFormData or httpAddFormFile
`headers`	string	the string headers to pass with the HTTP PUT request. Headers should be in the format name:value, seperated by CRLF \r\n Note: do not set the Content-type header if using a multipart post (httpAddFormFile() or httpAddFormData())
`success_function`	string	the name of a JavaScript function that will be called upon a 200 response from the HTTP server. The function will be passed a single string parameter with the full text of the page retrieved.
`errror_function`	string	the name of a JavaScript function that will be called if a 200 response is not received. The function will be passed the error message.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpPutHeaders(url, data, headers, success_function, error_function, cookieJar, http_spinner)

httpPutHeaders issues an asynchronous PUT request to URL with the header data in headers and the data to PUT in data. Upon success or failure, the appropriate callback is called.

Parameters:

Name	Type	Description
`url`	string	the full URL to PUT to
`data`	string	the data to PUT
`headers`	string	the custom headers to include with the PUT requests. Headers should be in the format name:value, seperated by CRLF \r\n
`success_function`	string	the name of a JavaScript function to call if the PUT is successful
`error_function`	string	the name of a JavaScript function to call if the PUT is unsuccessful. The error message is passed.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpPutHeadersBinary(url, file_path, headers, success_function, error_function, cookieJar, http_spinner)

httpPutHeadersBinary issues an asynchronous PUT request to URL with the header data in headers and the file path of the binary data to PUT in data. Upon success or failure, the appropriate callback is called.

Parameters:

Name	Type	Description
`url`	string	the full URL to PUT to
`file_path`	string	the file data path to PUT
`headers`	string	the custom headers to include with the PUT requests. Headers should be in the format name:value, seperated by CRLF \r\n
`success_function`	string	the name of a JavaScript function to call if the PUT is successful
`error_function`	string	the name of a JavaScript function to call if the PUT is unsuccessful. The error message is passed.
`cookieJar`	string	Optional, String is in Netscape Cookie file format, same as that returned as success_function parameter
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

httpS3Upload(bucket, s3_file_path, local_filepath, s3_key, s3_secret, success_function, error_function, region, progress_function, http_spinner)

httpS3upload asynchronously uploads the file at local_filepath to s3_file_path within the provided S3 bucket. If successful, calls success_function, otherwise, calls error_function.

Parameters:

Name	Type	Default	Description
`bucket`	string		the S3 bucket to upload the file to
`s3_file_path`	string		the full path within the bucket to upload the file to (including the file name)
`local_filepath`	string		the path to the local file
`s3_key`	string		the Amazon S3 key for the account containing bucket
`s3_secret`	string		the Amazon S3 secret part associated wtih s3_key
`success_function`	string		the name of a JavaScript function that will be called if the upload is successful.
`error_function`	string		the name of a JavaScript function that will be called if the upload is unsuccessful. Error message will be passed.
`region`	string		(optional) - the name of the S3 region if it is not the default, eg "us-east-2" or ""
`progress_function`	string		(optional) the name of a JavaScript function that will be called during upload progress.
`http_spinner`	bool	null	Optional, a boolean value indicating whether a spinner shows for JS http requests

isAlarmPermissionAlreadyGranted()

Finds out if you have permission or not for exact alarms.

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

Returns:

This returns true if your app currently has permission for exact alarms granted by the OS. It returns false if permission has never been asked for or if permission has been denied.

Type: bool

isDialogVisible()

Returns boolean value to indicate if the named dialog is visible or not.

isNotificationPermissionAlreadyGranted()

Finds out if you have permission or not for notfications.

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

Returns:

This returns true if your app currently has permission for notifications granted by the OS. It returns false if permission has never been asked for or if permission has been denied.

Type: bool

JSArchiveCreate(folder, filename)

JSArchiveCreate Tool function to build a javascript archive from a folder of files

Parameters:

Name	Type	Description
`folder`	string	the folder to compress.
`filename`	string	the path of the .jsa archive created

Returns:

success - true for success

JSArchiveGetFileData(filename)

JSArchiveGetFileData Tool function to get a files data from a loaded archive

Parameters:

Name	Type	Description
`filename`	string	the filename to retrieve data from

Returns:

- the data from the file

Type: string

JSArchiveGetFiles()

JSArchiveGetFiles Tool function to get a list of pipe seperated filenames from a loaded archive

Returns:

- pipe delimited list of filenames

Type: string

JSArchiveLoad(filename)

JSArchiveLoad Tool function to open a javascript archive

Parameters:

Name	Type	Description
`filename`	string	the path of the .jsa archive to load

Returns:

count - count of files (0 is empty or missing archive)

md5(input)

md5 returns the md5 hash for a string.

Parameters:

Name	Type	Description
`input`	string	any string

Returns:

- the md5 hash of the input string

metricsBeginProfiling()

metricsBeginProfiling begins writing profiling data in a Perfetto compliant JSON file.
The timestamp of the start of the profiling will be appended to the filename.
The output file is in the Google Trace Event Format and can be viewed
with https://ui.perfetto.dev/ or by pasting `chrome://tracing/` into the address bar in Chrome.
Use `setGlobal("metrics_profiling_output", newPath)` to set the path of the output file. Defaults to projects `temp` directory.

metricsEndProfiling()

metricsEndProfiling stops writing profile data. See metricsBeginProfiling

metricsWriteRamStats()

metricsWriteRamStats writes current CPU and GPU RAM usage in a Perfetto compliant JSON file. Scale is 1 sec == 1 MB
Use `setGlobal("metrics_profiling_output", newPath)` to set the path of the output file. Defaults to projects `temp` directory.

moveWindow(x, y, width, height)

Move and resize the window. (desktop only).

Parameters:

Name	Type	Description
`x`	number	New x position of the window.
`y`	number	New y position of the window.
`width`	number	New width of the window.
`height`	number	New height of the window.

notifyAtDateTime()

DEPRECATED. Please use scheduleAlarmAtDateTime

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

notifyLater()

DEPRECATED. Please use scheduleAlarm

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

openSocket(deviceName, serviceUuid, openSuccessCallback, socketErrorCallback, readCallback, is_data_binary)

Tries to open the socket of the specified bluetooth device

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`deviceName`	string	the name of the device to try and open
`serviceUuid`	string	the name of the service you want on the device
`openSuccessCallback`	string	function to call if we succeed at opening the socket
`socketErrorCallback`	string	function to call if there is an error
`readCallback`	string	the function to call when we successfully read from socket
`is_data_binary`	bool	true indicates the data is in binary format

openURL(url)

Opens a URL in a browser or appropriate app.

Parameters:

Name	Type	Description
`url`	string	The URL to open. Possible protocols are: http, https, mailto, sms, tel, and file

Returns:

Whether the URL was opened successfully

Type: boolean

Example

openURL("https://www.stuff.co.nz");

pairToDevice(deviceName, onConnectedCallback, onPairErrorCallback, onUnpairedCallback, servicesFoundCallback, onDisconnectedCallback)

Pairs with a specified bluetooth device

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`deviceName`	string	the name of the device to attempt to pair with
`onConnectedCallback`	string	the function to call when we successfully pair to the device
`onPairErrorCallback`	string	the function to call if there was an error
`onUnpairedCallback`	string	the function to call if we unpair from the device
`servicesFoundCallback`	string	the function to call if services on the device are detetced
`onDisconnectedCallback`	string	the function to call when we disconnect from the device

playFullscreenVideo(filename, error_callback, complete_callback)

Plays a video in fullscreen mode

Parameters:

Name	Type	Description
`filename`	string	the name of the video to display.
`error_callback`	string	the name of the function to call when an error occurs loading the video.
`complete_callback`	string	the name of the function to call when the video has finished.

pollGps(update_function, error_function)

pollGps will request GPS location to be sent back whenever it changes.
Note previous versions supported accuracy and interval parameters - these are still allowed for compatibility but not used.

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION

Parameters:

Name	Type	Description
`update_function`	string	the function that is called with three parameters, latitude, longitude and accuracy
`error_function`	string	the function to receive an error message

positionComponent(obj, x1, y1, x2, y2)

positionComponent respositions the component obj relative to its parent container. It will be positioned at x1,y1 top left and x2,y2 bottom right.
The width and height of the component is automatically calculated based on the points provided.

Parameters:

Name	Type	Description
`obj`	object	the component to reposition
`x1`	number	the percent from the left of the container to the left of the component
`y1`	number	the percent from the top of the container to the top of the component
`x2`	number	the percent from the left of the container to the right of the component
`y2`	number	the percent from the top of the container to the bottom of the component

Example

// fill the whole container
positionComponent(self,0,0,100,100);
// be 10% from the edges of the container
positionComponent(self,10,10,90,90);

positionComponentControl(obj, left, left_mm, top, top_mm, width, width_mm, height, height_mm, right, right_mm, bottom, bottom_mm)

positionComponentControl respositions the component obj relative to its parent container. It will be positioned using all of the detailed properties which can be set including locking optionally as a percentage or in mm.
It is possible to specify invalid amounts so the results will be normalised.

Parameters:

Name	Type	Description
`obj`	object	the component to reposition
`left`	number	left margin
`left_mm`	boolean	percentage if false, mm if true
`top`	number	top margin
`top_mm`	boolean	percentage if false, mm if true
`width`	number	width margin
`width_mm`	boolean	percentage if false, mm if true
`height`	number	height margin
`height_mm`	boolean	percentage if false, mm if true
`right`	number	right margin
`right_mm`	boolean	percentage if false, mm if true
`bottom`	number	bottom margin
`bottom_mm`	boolean	percentage if false, mm if true

positionHorizontal(object, left_lock, left_size, width_lock, width_size, right_lock, right_size)

positionHorizontal allows you to set any of the horizontal positioning properties on a component. The lock properties can be 0=% 1=mm. The size is the value as a % or mm as appropriate.

Parameters:

Name	Type	Description
`object`	object	a component object.
`left_lock`	real
`left_size`	real
`width_lock`	real
`width_size`	real
`right_lock`	real
`right_size`	real

positionVertical(object, top_lock, top_size, height_lock, height_size, bottom_lock, bottom_size)

positionVertical allows you to set any of the vertical positioning properties on a component. The lock properties can be 0=% 1=mm. The size is the value as a % or mm as appropriate.

Parameters:

Name	Type	Description
`object`	object	a component object.
`top_lock`	real
`top_size`	real
`height_lock`	real
`height_size`	real
`bottom_lock`	real
`bottom_size`	real

profileTag(tagName)

Add a tag at a single point in time to your profiling.

Parameters:

Name	Type	Description
`tagName`	string	The name of the tag that you want to appear in the profiling data.

raiseEvent(component, eventid, mydata)

raiseEvent fires an event of a custom component or built-in Umajin component. It passes the mydata parameter to any actions that call the event.
For custom components: The stringified eventid param needs to match an event declared in the registerComponent function, or EventString.
For Umajin's built-in components: the stringifed eventid needs to be the name of the event in the editor converted to lower case with spaces replaced by '_'. e.g. "On Submit" would convert to "on_submit"
The mydata parameter can be used to marshall any values to be exposed to the user of this action by adding them as named values in a stringified JSON packet in the style of "{"value":3, "color":"red"}". These will be available to users as [value] and [color] in any actions they apply to this event.

Parameters:

Name	Type	Description
`component`	object	an instance of a component object. "self" refers to the current instance of a custom component from within that component's code.
`eventid`	string	the string that identifies the event. For custom component you may use a property of EventString or a custom eventid. For built-in umajin components, it needs to be the Event name in the editor converted to lower case and spaces replaced with underscores.
`mydata`	string	a JSON formatted object, with properties that correspond to the parameters that the event handler for eventid are expected to receive. To pass in no parameters, pass in a blank stringified JSON object, "{}"

Examples

// this passes the value varaible to the Action that handles the on_press event
raiseEvent(self, 'on_press','{"value":' + value + '}');

var value = "hello";
raiseEvent(comp, "my_custom_event", "{mykey:" + value + "}"); // The mydata parameter needs to be stringified JSON. This can be accessed in an action (such as a text field) by using the variable [mykey]
& @example
raiseEvent(umajinButtonComp, "on_press", "{}"); // For an existing built in component. Note how the editor name is "On Press", however to correctly work we must use "on_press".

readBinaryFile(filename)

readBinaryFile reads in a file and returns the data as an ArrayBuffer.

Parameters:

Name	Type	Description
`filename`	string	the path of the text filename to read, relative to the project folder e.g. "images/myfile.json", or a fully specified path to the temp or cache folders.

Returns:

ArrayBuffer - The data bytes in the file.

readTextFile(filename)

readTextFile reads in a text file and returns it as a string.

Parameters:

Name	Type	Description
`filename`	string	the path of the text filename to read, relative to the project folder e.g. "images/myfile.json", or a fully specified path to the temp or cache folders.

Returns:

string - The text in the file.

Examples

// load a string from the project files using a relative path
var local_text = readTextFile("images/demo.txt")
console.log("local_text = " + local_text)

// load a string from cache using absolute path
var cache_text = readTextFile(getGlobal("cache_path") + "/244EDAE546E9A64427371792E3EA3100.json")
console.log("cache_text = " + cache_text)

refreshComponent(component)

refreshComponent refreshes a component

Parameters:

Name	Type	Description
`component`	object	the component to refresh

refreshFeed(title)

refreshFeed Tells the Umajin editor that the feed with the given title should be refreshed; typically because your code knows it has changed.
All the components that are referencing the feed will update their contents.

Parameters:

Name	Type	Description
`title`	string	the name of the feed used in registerFeed

registerAction(name, icon, title, params)

registerAction registers a new Action with Umajin. It is required that register or registerAction
be called to make a custom action accessible from within the Umajin editor.

Parameters:

Name	Type	Description
`name`	string	the JavaScript function to call with the parameters defined by params. Must adhere to JavaScript naming conventions.
`icon`	string	this will be the path to a custom icon in a future release
`title`	string	the friendly name of the Action within the editor. This is what gets presented to the user within the editor.
`params`	string	a comma-seperated list of parameters for the action. These are shown in the editor for the user to set, and the selected values are passed to the function "name". Parts in square brackets can be omitted. bool:label[:default_value] Shows a checkbox. default_value can be: true, false, on, off, yes, no Examples: “bool:Expand” or “bool:With particles:yes”. string:label[:default_value] Shows a textbox int:label[:default_value]:min:max Shows a slider ranging from min to max integer values real:label[:default_value]:min:max Shows a slider ranging from min to max floating point values component:label[:type] Shows a component selector. Type is the internal type of component allowed. All component types (including custom) are supported. If type is ommitted, any type of component can be selected.

Example

registerAction('functionNameInJS', '', 'Title in Umajin Editor', 'component:result:text');

registerComponent(name, icon, title, description, callback_init, callback_resize, callback_refresh, property_list, event_list, help_url, x1, y1, x2, y2, callback_reset)

registerComponent registers a new developer-defined Component with Umajin. It is required that registerComponent
be called to make a custom component defined in a JavaScript file accessible from within the Umajin editor.
Components can be added to projects using the visual editor, and expose properties that can be set without coding.
Components are required to handle init, resize, and refresh events, but may also fire custom events that can be attached
to actions within the editor.

Parameters:

Name	Type	Description
`name`	string	a unique name for the component which should not have spaces or special characters
`icon`	string	the relative path to the icon file from the root of the project folder. Forward slashes are used (even on windows systems).
`title`	string	this is the human readable version of the name
`description`	string	a text description of the component that gets displayed in the right panel of the umajin editor when the user highlights a component to add to the project.
`callback_init`	string	the name of a JavaScript function that gets called when the component is first initialized. The function gets called with two parameters (width, height). Width is the width of the component in local coordinate space. Height is the height of the component in local coordinate space.
`callback_resize`	string	the name of a JavaScript funciton that gets called when the component is resized by the user in the editor, or triggered at runtime. The function gets called with two parameters (width, height). Width is the width of the component in local coordinate space. Height is the height of the component in local coordinate space.
`callback_refresh`	string	the name of a JavaScript function that gets called when the component is refreshed by changing a property in the property panel. The function gets called with two parameters (width, height). Width is the width of the component in local coordinate space. Height is the height of the component in local coordinate space.
`property_list`	string	this is a list of comma seperated properties. The types of properties are bool:title[:default_value] string:title[:default_value] imagepicker:filename:default animationpicker:filename:default videopicker:filename:default color:name:0x3345543 real:title[:default_value]:min_value:max_value int:title[:default_value]:min_value:max_value enum:title:default:v0\|v1\|v2\|v3\|v4 combo:title:default:v0\|v1\|v2\|v3\|v4 enum_callback:title:default:jsFunctionCallback combo_callback:title:default:jsFunctionCallback section:title - creates a section header within the properties. Following properties will go under this section. beginstyle:title - creates a style section. After this, provide properties for the elements of the style as follows: basestyle:property name:default e.g. default alignment:property name:default 0=left, 1=center, 2=right, 3=full [Optional] color:property name:default e.g. 0xFFFFFFFF size:property name:default e.g. 12 font:property name:default e.g. vera.ttf tracking:property name:default e.g. 1.0 All properties must be provided, except alignment which is optional. The base style property must be provided, but your component code doesn't need to do anything with it. Unlike other properties, the property names are internal only; the titles displayed in the editor are fixed. The properties should be applied e.g. to a text component's font_size, font_color, font_filename, font_align and tracking properties. Although defaults are optional, to make a useful intial style requires default values for all the properties. endstyle:title - Marks the end of the style section.
`event_list`	string	a comma separated list of event names that get called when the matching raiseEvent is fired from within the component's code. The event_list names must match the names of the events that are fired. Umajin editor users can then attach Actions to these events from within the editor.
`help_url`	string	optional - A web URL pointing at a help page
`x1`	number	optional - the percent from the left of the container to the left of the component
`y1`	number	optional - the percent from the top of the container to the top of the component
`x2`	number	optional - the percent from the left of the container to the right of the component
`y2`	number	optional - the percent from the top of the container to the bottom of the component
`callback_reset`	string	the name of a JavaScript function that gets called when the component is reset. This occurs after playing and stopping a project.

Examples

registerComponent("slider", "icons/cog2.png", "Slider", "Slider control", "slider_init", "", "slider_refresh", "imagepicker:filename,number:steps:0,number:min:0,number:max:100", "on_slide")

// register a component with a frequency slider which will contain a renderkit
// on the renderkit we will make an animating Sin curve
registerComponent("rk_shape", "", "rk_shape", "rk Shape", "rk_shape_init", "rk_shape_resize", "rk_shape_refresh", "real:frequency:1:1:5", "")
 
function rk_shape_init(width, height) {
     // create a renderkit
     var rk = createComponent(self, "renderkit", 0, 0, 100, 100)
     // create a shape
     var id = renderkitShapeCreate(rk, "");
     setData(rk, "shape_id", id);
     // register for the per frame tick event
     bindEvent(rk, "on_tick", "rk_shape_on_tick");
 }
 
 var cnt = 0;
 function rk_shape_on_tick() {
     rk_shape_draw(self);
     //increment the offset into the Sin curve
     cnt += 0.1;
 }
 
 function rk_shape_resize(width, height) {
     // get the renderkit from the parent and draw
     var rk = getComponentChild(self, 0);
     rk_shape_draw(rk);
 }
 
 function rk_shape_refresh(width, height) {
     //set the frequency value into the internal renderkit and draw
     var frequency = getData(self, "frequency");
     var rk = getComponentChild(self, 0);
     setData(rk, "frequency", frequency);
     rk_shape_draw(rk);
 }
 
 function rk_shape_draw(rk) {
     // check size of renderkit in local units
     var width = getProperty(rk, "width");
     var height2 = getProperty(rk, "height") / 2.0;
     var frequency = getData(rk, "frequency");
     var id = getData(rk, "shape_id");
 
     // clear the shape
     renderkitShapeClear(rk, id);
 
     //setup the start of the curve
     var y = height2 + Math.sin(cnt + ((a * 0.0628) * frequency)) * height2;
     renderkitShapeDoMove(rk, id, y, 100);
 
     // draw the lines of a sin curve
     for (var a = 0; a < 101; a++) {
         var y = height2 + Math.sin(cnt + ((a * 0.0628) * frequency)) * height2;
         renderkitShapeDoLine(rk, id, a * width / 100.0, y);
     }
 }

registerEventHandler(event, name)

registerEventHandler lets you lodge a JavaScript function against a number of global events.
Events include:
on_resize: the application window has changed size.
on_activate: the application has been activated, ie become the foreground window.
on_deactivate: the application has been deactivated, ie is no longer the foreground window.
on_resume: the application has resumed from sleep (mobile only).
on_suspend: the application is being suspended (mobile only).
on_push_notification(message): a push notification has been received.
on_edit_mode: when running in the editor, the stop button has been pressed.
on_device_motion(x,y,z): the device has moved according to it's accelerometer (mobile only).
on_button_press(buttonName, pageName): a button has been pressed with the given name.
on_alarm(message, background): a date-time alarm has fired.
on_notification(id, payload, origin): the user clicked on a notification that was shown.
on_key_down(key, mod): a key has been pressed.
on_key_up(key, mod): a key has been released.
on_mouse_down(x, y, mod): a mouse button has been pressed.
on_mouse_up(x, y, mod): a mouse button has been released.
on_mouse_move(x, y, mod): the mouse has moved.
on_mouse_wheel(x, y, mod, delta): the mouse wheel has been moved.
on_quit_requested: the user has tried to close the application (e.g. clicking the close button on the window).
If you don't want the application to close now, then call cancelQuit. Does not work while in the editor.
on_tick: callback will be executed once per frame.

Parameters:

Name	Type	Description
`event`	string	the name of one of the supported events that can be handled
`name`	string	the name of a JavaScript function that will be called when the event is fired. Supported events may pass parameters to the handler function.

Examples

registerEventHandler('on_activate', 'onActivate');
function onActivate() {
    console.log('onActivate');
}

registerEventHandler('on_deactivate', 'onDeactivate');
function onDeactivate() {
    console.log('onDeactivate');
}

registerExternalFunction(library_name, on_string_data_callback, on_error_callback, on_binary_data_callback)

Mac/Windows only: Loads a native library with the name "library_name".
For full information, see https://developer.umajin.com/native-libraries/

Parameters:

Name	Type	Description
`library_name`	string	the name of the library to load.
`on_string_data_callback`	function	called when the library returns string data from umajinPoll
`on_error_callback`	function	called when an error occurs loading the library
`on_binary_data_callback`	function	(optional) called when the library returns string and/or binary data from umajinPollBinary This function receives two parameters, string payload, and binary data as an ArrayBuffer

Returns:

the library name if successful, blank if loading failed

Type: string

registerFeed(callback, title)

registerFeed registers a Custom Feed in the Umajin editor.
This code can make network or database calls and generate the data as you see fit.
You supply a callback function, which is called once for each component using the feed,
and should call the setCustomFeed function to supply data.

 function myFeedCallback( component [, parameter...] )
 {
    ...
    setCustomFeed( component, data );
 }

The first parameter to the callback function is the component which needs data.
Any additional parameters you supply in the "Custom Feed Parameters" property of a component, will be passed to the function.

Parameters:

Name	Type	Description
`callback`	string	the name of a callback function that gets called when data is required.
`title`	string	the friendly name of the feed that gets displayed in the Umajin editor

Examples

// A simple example with no parameters
registerFeed('demoFeedCallback', 'Title in Editor');
function demoFeedCallback(component) {
    setCustomFeed(component, [{"message":"Adam"},{"message":"Michael"},{"message":"Jenny"},{"message":"Ally"}]);
}

// An example which needs an address and optional order by key
// The parameters should be entered into the 'Custom Feed Parameters' property of your component
// and do not require speech marks or escape characters.
// e.g. Texas,AGE
// generates [{"ADDRESS":"Texas", "AGE":"30", "ID":"6", "NAME":"Ellen", "SALARY":"98000"}, {"ADDRESS":"Texas", "AGE":"39", "ID":"5", "NAME":"Mary", "SALARY":"90000"}, {"ADDRESS":"Texas", "AGE":"42", "ID":"3", "NAME":"Jeff", "SALARY":"82000"}]
registerFeed('demoFeed2Callback', 'Title in Editor');
function demoFeed2Callback(component, address, sortkey) {
    cacheDbOpen("mydb.db");
    var mysql = "SELECT * FROM Company WHERE ADDRESS = '" + address + "'";
    if (sortkey.length) {
        mysql += " ORDER by " + sortkey;
    }
    var data = cacheDbSelectRaw("mydb.db", mysql)
    setCustomFeed(component, data);
    cacheDbClose("mydb.db");
}

registerMenuItem(callback, displayName)

registerMenuItem creates a new menu item in the "Debug" menu of the OS's File menu.
When you click on this menu item, your callback will be executed.
Menu items created using `registerMenuItem` are available during edit and play mode.

Parameters:

Name	Type	Description
`callback`	function	The function to run when the menu item is clicked.
`displayName`	string	The text that is displayed for the new menu item.

removeGlassShelfItem(glass_shelf, index)

removeGlassShelfItem this will programatically remove and item from a glass shelf

Parameters:

Name	Type	Description
`glass_shelf`	object	an instance of a glass shelf component
`index`	int	an item to remove from the glass shelf

removeMapMarker(map_view, name)

removeMapMarker removes a Map Marker with the specified name.

Parameters:

Name	Type	Description
`map_view`	object	an instance of a map_view control
`name`	string	unique name of the marker to remove

removeMapRoute(map_view)

removeMapRoute removes the current route from the map.

Parameters:

Name	Type	Description
`map_view`	object	an instance of a map_view control

renameFile(fromPath, toPath)

Rename a file. Can also move a file to a new directory.

Parameters:

Name	Type	Description
`fromPath`	string	Path of the file to copy.
`toPath`	string	Destination path to copy the file to.

Returns:

True if successful.

Type: boolean

resetScrollPanel(scroll_panel)

resetScollPanel resets the position of the scroll_panel scroll panel component back to the top. If scroll_panel is not a scroll panel component, this function does nothing.

Parameters:

Name	Type	Description
`scroll_panel`	object	an instance of a scroll panel component

S3Link(url, region, s3_key, s3_secret, expiry_seconds)

S3Link Generates an authV4 url to an Amazon S3 hosted file, it does not check the validity of the link so make sure your bucket and region are correct.
Note: make sure that the forward slashes are not url encoded but the path names are

Parameters:

Name	Type	Description
`url`	string	the url to the s3 file eg https://.s3..amazonaws.com/some%20path/some%20file.ext
`region`	string	the name of the S3 region if it is not the default, eg "us-east-2"
`s3_key`	string	the Amazon S3 key for the account containing bucket
`s3_secret`	string	the Amazon S3 secret part associated wtih s3_key
`expiry_seconds`	int	how long the link is valid for, AWS allows a max of 7 days eg 7*86400

saveAsImage(component, width, filename, quality)

saveAsImage allows you to render a component into an image. This is useful for making snapshots of charts or perhaps users drawings.

Parameters:

Name	Type	Description
`component`	component	the component to save as an image
`width`	string	the width of the image in pixels (the height is calculated from the width)
`filename`	string	the name of the file including a .png, .jpg or .tga extension. The image is saved into the temp folder.
`quality`	string	This value is only used for jpg images to determine the compression. 0.8 to 0.9 are probably suitable compression values.

Example

// Use getGlobal( 'album_path' ) to find the Photos path, to save out there.
register("saveComponentToImage", "saveComponentToImage", "component:component,string:width,string:filename,string:quality");
function saveComponentToImage(object, width, filename, quality) {
    var album_path = getGlobal('album_path');
    saveAsImage(object, width, album_path + '/' + filename, quality);
}

scanWifi(on_complete_callback)

scanWifi will scan for all nearby access points and return metainformation about them.
It returns the results of this scan as stringified JSON to the on_complete_callback after a few seconds.
An example result is: [{"age":"78","capabilties":"[WPA2-PSK-CCMP][ESS]","frequency":"2442","mac":"b8:27:eb:90:9c:ad","rssi":"-52","ssid":"exampleAP"}, ...]
If an error occurs, such as Wifi being disabled, a blank result will be returned to the callback.
NOTE:

scanWifi only works on Android devices; Apple does not permit wifi scanning on iOS.
This API will request permission from the user to access their location
(since Wifi scanning is considered a means of finding location). If the user denies permission, a blank result will be returned.

Required Permissions: ACCESS_COARSE_LOCATION, PERMISSION_FINE_LOCATION, ACCESS_NETWORK_STATE, ACCESS_WIFI_STATE, CHANGE_WIFI_STATE

Parameters:

Name	Type	Description
`on_complete_callback`	string	The callback function that will execute when the phone has finished a wifi scan, or an error occurs. Is passed a single string parameter, empty for errors, otherwise stringified JSON.

Example

registerAction('scanTheWifi', '', 'scanTheWifi', '');
function scanTheWifi() {
    scanWifi('onWifiScanComplete'); // Tell the phone to start a wifi scan and send the JSON string results to the callback.
}
 
function onWifiScanComplete(resultJson) {
    if (resultJson === '') {
        console.log('Scan error');
        return;
    }
    console.log(resultJson); // Will be in stringified JSON.
    var parsedJson = JSON.parse(resultJson); // You can also parse the JSON for further code access.
    console.log(parsedJson[0].ssid); // Accesses the first access point's ssid.
}

scheduleAlarm(title, body, id, offsetSeconds, payload)

Sets an alarm to occur at the specified number of seconds in the future

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

Parameters:

Name	Type	Description
`title`	string	The title of the alarm to be shown to the user
`body`	string	The body text of the alarm to be shown to the user
`id`	string	An identifier for the alarm; will be given to the app when the alarm is acted on by the user, and can be used to cancel the alarm
`offsetSeconds`	string	How far into the future the alarm should be
`payload`	string	JSON string that contains data delivered with the alarm

scheduleAlarmAtDateTime(title, body, id, dateTime, payload)

Sets a alarm to occur at the specified date-time.

Required Permissions: POST_NOTIFICATIONS, SCHEDULE_EXACT_ALARM

Parameters:

Name	Type	Description
`title`	string	The title of the alarm to be shown to the user
`body`	string	The body text of the alarm to be shown to the user
`id`	string	An identifier for the alarm; will be given to the app when the alarm is acted on by the user, and can be used to cancel the alarm
`dateTime`	int64	The date-time to fire the alarm, as a UTC time_t (seconds since 1970)
`payload`	string	JSON string that contains data delivered with the alarm This can be calculated with date.getTime() / 1000 + date.getTimezoneOffset() * 60

serialClose()

serialClose This closes the currently open serial port.

serialEnumeratePorts()

serialEnumeratePorts This finds any serial ports and returns a JSON list.

Returns:

string - This returns a JSON string you can read to see the serial ports e.g. ["Com1","Com2"]

Example

var ports = JSON.parse(serialEnumeratePorts());
var first_port = ports[0];

serialOpen(port_name, baud_rate, flow_control, parity, stop_bits, buffer_ms, read_function, error_function, open_function, close_function)

serialOpen This opens a serial port with the specified parameters. Enumerate helps you find the ports serialEnumeratePorts

Parameters:

Name	Type	Description
`port_name`	string	the port name to open
`baud_rate`	int	the speed (e.g. 9600 bps)
`flow_control`	int	Flow control 0:none, 1:software, 2:hardware
`parity`	int	Parity 0:none, 1:odd, 2:even
`stop_bits`	int	Stop bits can be 0:One, 1:One and a half, 2:Two
`buffer_ms`	int	the number of miliseconds of no new data to consider the buffer completed. e.g. 1ms is a short buffer timeout, 100ms is a long buffer timeout.
`read_function`	string	read callback (passed in a JavaScript buffer)
`error_function`	string	called when an error occurs (takes a numeric error type and a string message)
`open_function`	string	called when the serial port is opened
`close_function`	string	called when the serial port is closed

Example

serialOpen("Com1", 9600, 0, 0, 0, 100, "serial_success", "serial_error", "serial_open", "serial_close");
 
function serial_success(buffer) {
   var s = "";
   const view = new Uint8Array(buffer);
   for (var i = 1; i < view.length; i++) {
       if (view[i] > 20) s += String.fromCharCode(view[i]);
   }
   console.log("received " + s );
}
 
function serial_error(type, message) {
    console.log("error " + message);
}
 
function serial_open() {
    console.log("open serial");
}
 
function serial_close() {
    console.log("close serial");
}

serialWrite(data)

serialWrite This writes to the current open serial port serialOpen

Parameters:

Name	Type	Description
`data`	buffer	this data is a JavaScript buffer.

Example

var serial_buffer_size_in_bytes = 20;
//declare buffer
var serial_buffer = new ArrayBuffer(serial_buffer_size_in_bytes);
//declare view into buffer
var serial_dataview = new DataView(serial_buffer);
//add data
serial_dataview.setUint8(cnt++, 0xA0)
serial_dataview.setUint8(cnt++, 0x04)
serial_dataview.setUint8(cnt++, 0xB0)
//add crlf
serial_dataview.setUint8(cnt++, 0x0D)
serial_dataview.setUint8(cnt++, 0x0A)
//add null
serial_dataview.setUint8(cnt++, 0x00)
//send
serialWrite(serial_buffer)

setCookie(key, value)

setCookie sets the string stored at key to value. A cookie is persistent across sessions and is only deleted upon a subsequent call to deleteCookie.
Cookies can be checked for existence with hasCookie, retrieved with getCookie, and deleted with deleteCookie.

Parameters:

Name	Type	Description
`key`	string	is the key to check for existence
`value`	string	the string value to store at key

setCustomFeed(object, array)

setCustomFeed sends data to a data bound component (feed list, feed item or animated feed). Before using this method you should register using registerFeed.
NOTE: You need to execute this function with your JSON before mapping options are visible in the editor.

Parameters:

Name	Type	Description
`object`	object	a feed list, feed item or animated feed
`array`	string	or JSON - an array of data rows, or the same as stringified JSON . This should be in the format [{"name":"value"}].

Example

registerFeed('demoFeed', 'demoFeed', '');
function demoFeed(component) {
    setCustomFeed(component, [{"message":"Adam"},{"message":"Michael"},{"message":"Jenny"},{"message":"Ally"}]);
}

setCustomFeedSingleRow(object, row, object)

setCustomFeedSingleRow sends data to a data bound component (feed list, feed item or animated feed). Before using this method you should register using registerFeed.
NOTE: You need to execute this function with your JSON before mapping options are visible in the editor.

Parameters:

Name	Type	Description
`object`	object	a feed list, feed item or animated feed
`row`	string	the zero-based row index you want to update the data on.
`object`	string	or JSON - a data row object (recommended), or the same as stringified JSON. This should be in the format {"name":"value"}.

Example

registerFeed('demoFeed', 'demoFeed', '');
function demoFeed(component) {
    setCustomFeedSingleRow(component, 4, {"message":"Allison"});
}

setData(object, key, value)

setData sets the value that the data-bound component object has stored at key. This data can be returned using getData.

Parameters:

Name	Type	Description
`object`	object	a component object. "self" may be used to reference the current instance of a custom component.
`key`	string	the key to store the value at. Subsequent calls to setData with the same key overwrite the data stored at that key.
`value`	object	the value to store at key which can be a base type (string, number etc)

setDataBulk(object, json_str)

setDataBulk sets multiple values for a data-bound component object. This data can be returned using getDataBulk.

Parameters:

Name	Type	Description
`object`	object	a component object. "self" may be used to reference the current instance of a custom component.
`json_str`	string	key value pairs as a JSON string.

Example

for (var i = 0; i < 3; i++){
	for(var j = 0; j < 4; j++){
		var month_button = createComponent(months_group, "button", j * wth, i * hgt, (j+1) * wth, (i+1) * hgt);
 
		setDataBulk(month_button, JSON.stringify({
			"index" : month_index,
			"month" : month_value,
			"first_selected": "0",
			"selected": "0",
			"last_selected": "0"
		}));
 
		month_index++;
		month_value++;
		if (month_value === 12){
			month_value = 0; // Dec = 11.. reset to Jan
			year_offset = 1; // Should have the value of the next year.
		}
	}
}

setFocus(object)

setFocus sets the focus on a component.

Parameters:

Name	Type	Description
`object`	object	a component object. "self" may be used to reference the current instance of a custom component.

Example

// "Login" page has a button and a text entry called 'username'.
// Set focus on text entry by clicking the button.
// Assign the below action to 'on press' of button.
registerAction('activateUsername', '', 'Activate Username', '', '', '');
function activateUsername() {
    var usernameTextEntry = findComponent('Login', 'text_entry', 'username');
    setFocus(usernameTextEntry);
}

setForeground(page_name, foreground_name)

setForeground This sets the current foreground for the specified page name.
Note : a page can only have one current foreground object (e.g. toolbar, menu etc).

Parameters:

Name	Type	Description
`page_name`	string	the name of the page
`foreground_name`	string	the name of the foreground to apply to the page

Example

setForeground('Login', 'navigationBar');

setGlobal(property, value)

setGlobal sets the value of a global property. See also getGlobal

Parameters:

Name	Type	Description
`property`	string	the name of the property to set from the following list.
`value`	object	the value to set the property to.

Properties:

Name	Type	Description
`allow_screen_saver`	boolean	controls whether the system is allowed to sleep (when the app is in the foreground on mobile platforms)
`clipboard`	string	contents of clipboard
`window_title`	string	sets the title of the Umajin Editor Lite window.
`http_spinner`	string	Will the spinner show for JS http requests, true or false
`http_blocker_alpha`	number	How transparent the JS http spinner will be (transparent 0-255 opaque)
`cancel_page_navigation`	boolean	if set to true in an "On Before Page Hide" event, will prevent the page transition.
`user_agent`	string	sets user agent used for JS HTTP calls. The default set by Umajin should be sufficient in most cases. However if you need to customise (such as for analytics tools) your user agent, make sure you include the platform user_agent_suffix from getGlobal
`zoom_level`	number	zoom the entire app. Default zoom level is 1.
`window_state`	number	Set the window state. 0:Windowed, 1:Maximized, 2:Fullscreen, 3:Minimized. (desktop only)

setGlobalVar(var_name, value)

setGlobalVar sets the value of a Umajin global variable. This is accesible by users of the editor to use in their action parameters simply by putting the key name in square brackets.

Parameters:

Name	Type	Description
`var_name`	string	the name of the variable
`value`	string	the value to write to the variable

Example

setGlobalVar('aGlobalVar', "I'm a string");

setProperty(object, property, value)

setProperty sets a specified property of a component object to value.
Some of these properties can be retrieved with getProperty.

Parameters:

Name	Type	Description
`object`	object	the component to update
`property`	string	a string property that is supported by this component
`value`	object	the new value to assign

Properties:

Name	Type	Description
`hitmode`	string	any component ("off", "on", "aabb", "bb")
`x`	string	any component
`y`	string	any component
`page_x`	string	any component (position relative to the page)
`page_y`	string	any component (position relative to the page)
`width`	string	any component
`height`	string	any component
`angle`	string	any component
`scale`	string	any component
`scale_width`	string	any component
`scale_height`	string	any component
`origin_x`	string	any component (a ratio, 0 = left, 0.5 = halfway, 1 = right)
`origin_y`	string	any component (a ratio, 0 = top, 0.5 = halfway, 1 = bottom)
`visible`	string	any component
`alpha`	string	any component
`tint`	string	any component
`crop_mode`	string	image (0=fill, 1=fit, 2=stretch)
`font_size`	string	text component
`font_color`	string	text component (0x0000FFFF) blue
`font_filename`	string	text component
`font_align`	string	text component (0=left, 1=center, 2=right, 3=full)
`resize_type`	string	text component (0=mm, 1=scale)
`slice_left`	string	nine slicer component, button
`slice_top`	string	nine slicer component, button
`slice_bottom`	string	nine slicer component, button
`slice_right`	string	nine slicer component, button
`border_scale`	string	nine slicer component, button
`text`	string	text, text_entry, button, html_article
`fill_color`	string	rectangle (0x0000FFFF) blue
`scroll_offset`	string	feed_list, scroll_panel
`scroll_animate_y`	string	feed_list
`enabled`	string	button, text_entry
`spritesheet`	string	renderkit
`clip`	string	custom or group component
`align_x`	string	image
`align_y`	string	image
`default_filename`	string	text_entry, button
`disabled_filename`	string	text_entry, button
`down_filename`	string	button
`icon_filename`	string	button
`icon_scale`	string	button
`icon_x_pos`	string	button
`icon_y_pos`	string	button
`caption_x_pos`	string	button
`caption_y_pos`	string	button
`filename`	string	image, video, nine_slicer, html article, gallery, 3d model
`effect`	string	3d model
`feedid`	string	any dynamic component
`data_url`	string	any dynamic component
`json`	string	any dynamic component e.g. feedlist
`mapping`	string	any dynamic component. In the format: 'Field Name 1="Component Name A","Component Name B";Field Name 2="Component Name C" ...'.
`template`	string	any dynamic component
`speed`	string	carousel component

setPropertyBulk(object, propertiesJson)

setPropertyBulk sets property values and keys of a component. The data parameter needs to be formated in stringified JSON.
setPropertyBulk is more efficient than setProperty. An example is a text component that changes font color and font size every frame. It is more efficient to call setPropertyBulk() once than 2 setProperty() calls.
These properties can be retrieved with getProperty.

Parameters:

Name	Type	Description
`object`	object	the component to update
`propertiesJson`	string	a stringify json

Example

var buttonJSON = {}; // create blank JSON
buttonProperties.text = "Click Me!"; // Set key:value properties in the JSON.
buttonProperties.enabled = false;
// So now buttonJSON looks like: {"text":"Click Me!", "enabled":false}
setPropertyBulk(buttonComponent, JSON.stringify(bulk)); // pass in the componentObj and Stringified JSON

setPropertyIn(object, property, value, ms)

setPropertyIn sets a speicified property of a component object to value; it is similar to setProperty. For non-numeric properties, it waits ms milliseconds before making the change, while numeric properties are adjusted over ms milliseconds to produce an animation effect.
To get the value of a property, use getProperty.

Parameters:

Name	Type	Description
`object`	object	a Component object
`property`	string	a string property that is supported by object
`value`	object	the new value to set property to. Value must be of the type supported by property of object.
`ms`	int	an integer number of milliseconds (either a delay for non-numeric properties or the time period to animate the transition for numeric properties)

Properties:

Name	Type	Description
`x`	string	any component
`y`	string	any component
`width`	string	any component
`height`	string	any component
`angle`	string	any component
`scale`	string	any component
`scale_width`	string	any component
`scale_height`	string	any component
`visible`	string	any component
`alpha`	string	any component
`tint`	string	any component
`align_x`	string	image
`align_y`	string	image
`filename`	string	image, video, nine_slicer, html article, gallery, 3d model
`scroll_offset`	string	feed list

Example

// Assign "aTestAction" to "on press" of a button.
registerAction('aTestAction', '', 'test action', '', '', '');
function aTestAction() {
    setPropertyIn(self, 'y', 50, 500) 	// change the 'y' of the button with animation
}

setPropertyInTween(object, property, value, ms, tween)

setPropertyInTween sets a speicified property of a component object to value; it is similar to setProperty. For non-numeric properties, it waits ms milliseconds before making the change, while numeric properties are adjusted over ms milliseconds to produce an animation effect. The tween variable defines how the animation should appear. WARNING: tweening width or height properties has to resize the component every frame and could be slow for complex components.

Parameters:

Name	Type	Description
`object`	object	a Component object
`property`	string	a string property that is supported by object (see list on setPropertyIn)
`value`	object	the new value to set property to. Value must be of the type supported by property of object.
`ms`	int	an integer number of milliseconds (either a delay for non-numeric properties or the time period to animate the transition for numeric properties)
`tween`	int	the transition type. The allowable values of tween are 0:none, 1:linear, 2:ease_in, 3:ease_out, 4:ease_both, 5:ease_rev, 6:cubic_in, 7:cubic_out, 8:cubic_in_out, 9:cubic_out_in, 10:ease_in_strong, 11:ease_out_strong, 12:ease_both_strong, 13:ease_both_strong_rev ,14:quint_in, 15:quint_out, 16:quint_in_out, 17:quint_out_in, 18:sine_in, 19:sine_out, 20:sine_in_out, 21:sine_out_in, 22:expo_in, 23:expo_out, 24:expo_in_out, 25:expo_out_in, 26:circ_in, 27:circ_out, 28:circ_in_out, 29:circ_out_in, 30:elastic_in, 31:elastic_out, 32:elastic_in_out, 33:elastic_out_in, 32:elastic_both, 34:back_in, 35:back_out, 36:back_in_out, 37:back_out_in, 36:back_both, 38:bounce_in, 39:bounce_out, 40:bounce_in_out, 41:bounce_out_in, 40:bounce_both, 42:simplex16, 43:curve_in, 44:curve_out, 45:curve_sine, 46:curve_cosine

setTextStyle(text, styleName)

setTextStyle Sets a style by name from the current style list on a text component

Parameters:

Name	Type	Description
`text`	object	the text component to apply the style to
`styleName`	string	the string name of the style to apply

share(filename, message)

Shares an image and/or text message, using Android or iOS native sharing abilities.
Note: Many social media Platforms (such as Facebook) do not allow a combination of both text and image.
Sharing an image only is the most compatible.

Parameters:

Name	Type	Description
`filename`	string	the image file to share To only share a text message, leave the filename blank. To share a file from the project images folder, use the relative path within the images folder. To share a file outside the project images folder, e.g. from camera, use the absolute path with file:// prefix. For example "file:///users/temp/blah.jpg"
`message`	string	text message, blank if none.

Returns:

success - false if the share failed, true if it was successful

Example

share('file://' + filename, 'Here is the image');

shellExecute(path, parameters, minimised)

Desktop (Windows and MacOS) function.
shellExecute allows you to launch a new process from the Umajin Viewer / Portal / Editor.
Note: For backwards compatibility, you can also open URLs with this function, but you should use openURL instead.

Parameters:

Name	Type	Description
`path`	string	A path to the file to run, this must be relative to the project folder for security purposes
`parameters`	string	List of space seperated parameters for the process
`minimised`	int	start the process minimised 0 = false, 1 = true (note: only supported on Windows currently)

Returns:

whether the process was started successfully (or URL opened successfully)

Type: boolean

Example

//Launch an executable process
shellExecute("mybatchfile.bat", "23", 0);

showCombo(callback, options)

showCombo displays a full screen combo box with the pipe delimited options provided.

Parameters:

Name	Type	Description
`callback`	string	the name of a JavaScript function that will be called when the event is fired - this callback will have two parameters, the index and the value.
`options`	string	a string with a list of items seperated by vertical pipe characters

Example

showCombo("callback_function", "red|blue|green");
function callback_function(index, value) {}

showDialog(name)

showDialog Displays a dialog which overlaps the content on the screen.

Parameters:

Name	Type	Description
`name`	string	The name of a dialog to show.

Example

showDialog("myDialog"); // need to have a dialog named myDialog

showMyLocation(map_view, zoom_level)

showMyLocation locates the map on your location.

Parameters:

Name	Type	Description
`map_view`	object	an instance of a map_view control
`zoom_level`	int	the zoom level to set

showPopup(message, ok_text, cancel_text)

showPopup will use the global popup component to display a message. This can be useful for alerting a user, or debugging on device.

Parameters:

Name	Type	Description
`message`	string	The text to show in the popup.
`ok_text`	string	Optional. Text to display on the ok button. Omitting this will result in a default 'ok' text.
`cancel_text`	string	Optional. If not specificed, there will be no cancel button.

Examples

// This will add in a default 'ok' button and the cancel button is hidden.
// This can be useful for quick debugging on device.
showPopup("My Message");

// This will add in both ok and cancel buttons.
showPopup("My Message", "ok!", "cancel :(");

showSpinner()

Shows the standard project spinner to indicate the app is busy

socketIOConnect(channel, on_connect_function, on_disconnect_function, on_data_function, on_user_join, on_user_leave, on_error_function)

Opens up an Websocket based chat Engine. This is a type of real time communication which uses the Umajin SocketIO server as the central hub. Once a named channel is opened many applications can use this to send and receive broadcast messages.

Parameters:

Name	Type	Description
`channel`	string	a unique name for the communication channel
`on_connect_function`	string	the name of a JavaScript function to use as a callback upon successful connection. It takes no parameters.
`on_disconnect_function`	string	the name of a JavaScript function to use as a callback upon disconnection. It takes no parameters.
`on_data_function`	string	the name of a JavaScript function to use as a callback when data is received through the channel. It takes two string parameters; the first parameter is the users pubid that data was received from and the second parameter is the data packet.
`on_user_join`	string	the name of a JavaScript function to use as a callback when a user joins the channel. It has a string parameter of the pubid of the user joining.
`on_user_leave`	string	the name of a JavaScript function to use as a callback when a user leaves the channel. It has a string parameter of the pubid of the user leaving.
`on_error_function`	string	the name of a JavaScript function to use as a callback if a channel cannot be established. It takes no parameters.

Example

socketIOConnect("mychannel", "my_on_connect", "my_on_disconnect", "my_on_data", "my_on_user_join", "my_on_user_leave", "my_on_error");
function my_on_connect() {
    socketIOSend("demo");
}
function my_on_data(pubid, data_in) {
    callAction("show_popup", data_in);
}

socketIOSend(data, pubid)

socketIOSend sends data through an SocketIO session that has been esablished by socketIOConnect.

Parameters:

Name	Type	Description
`data`	string	the data packet to send through the socketIO channel.
`pubid`	string	(optional) the pubid of the user to send the message to.

soundClearAll()

soundClearAll This clears all audio files from the cache.

soundPlay(filename, looping, volume, pitch, pan, msOffset, multi)

soundPlay This plays and automatically mixes sound files such as mp3, ogg, wav.

Parameters:

Name	Type	Description
`filename`	string	the sound to play
`looping`	bool	false by default to not loop the sound
`volume`	real	the volume as a multiple, e.g. 0.0 as none, 0.5 half, 1.0 as full and default
`pitch`	real	the pitch as a multiple, e.g. 0.5 as half pitch, 1.0 as normal and default, 2.0 as double the pitch
`pan`	real	the pan in stero, e.g. 0.0 as the default and none, -1 as fully left, +1 as fully left
`msOffset`	real	the milliseconds offset to start into the sound, default is zero
`multi`	bool	false by default, when true multiple copies of same sound can be played at the same time

soundRecord(filename, max_ms)

soundRecord This saves an mono wav audio file from the default microphone into the project temp folder by default.

Required Permissions: RECORD_AUDIO

Parameters:

Name	Type	Description
`filename`	string	the name of the sound to record; format can be either .wav or .opus (see https://en.wikipedia.org/wiki/Opus_(audio_format)). Rate is 16bits @ 48kHz.
`max_ms`	int	the maximum ms to record if soundRecordStop isn't called (10,000 by default)

Returns:

- the full path to the opus audio

Type: string

soundRecordStop()

soundRecordStop This stops the current audio recording (there can be only one at a time!)

Required Permissions: RECORD_AUDIO

soundStop(filename)

soundStop This stops a specific sound, or all sounds if you dont specify a file.

Parameters:

Name	Type	Description
`filename`	string	the sound to stop, or stop all sounds if you dont specify a file

soundUpdateVolume(filename, volume)

soundUpdateVolume This sets the volume of a specific sound, or all sounds if you dont specify a file.

Parameters:

Name	Type	Description
`filename`	string	the sound to adjust the volume (no name for all sounds)
`volume`	real	this specifies the volume as a multiple, e.g. 0.0 as none, 0.5 half, 1.0 as full

startProfileBlock(blockName)

Begin profiling a block with a given name. Make sure to close the block using `endProfileBlock`.

Parameters:

Name	Type	Description
`blockName`	string	The name of the block that you want to appear in the profiling data.

stopDeviceDiscovery()

Stops attempting to find new deices

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

stopGps()

stopGps will cancel all GPS requests started by getGps or pollGps

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION

subscribeForBleCharacteristicChange(deviceId, serviceId, characteristicId, callback, subscribes)

subscribeForBleCharacteristicChange This will subscribe and report on a change in status of a BLE characteristic.

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`deviceId`	string	platform specific unique device ID.
`serviceId`	string	the uuid of the BLE parent service e.g. accelerometer.uuid: '0DEF5000-6656-11E5-A4E0-23D9BD6569A7'
`characteristicId`	string	The characteristic to query e.g. accelerometer.chars.acceleration: '0DEF5003-6656-11E5-A4E0-23D9BD6569A7'
`callback`	string	the function to call which takes a value string
`subscribes`	boolean	the flag to enable or disable this subscription

subscribeForBleDeviceConnected(callbackMethod, subscribes)

subscribeForBleDeviceConnected This will fire a callback function when a device connects.

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`callbackMethod`	string	the function to call which takes the device ID as a string
`subscribes`	boolean	the flag to enable or disable this subscription

subscribeForBleDeviceDisconnected(callbackMethod, subscribes)

subscribeForBleDeviceDisconnected This will fire a callback function when a device disconnects.

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`callbackMethod`	string	the function to call which takes the device ID as a string
`subscribes`	boolean	the flag to enable or disable this subscription

thumbnailImage(local_filepath_in, local_filepath_out, quality_ratio, align_x, align_y, des_width, des_height)

thumbnailImage is a simple function to resize and crop an image with a minimum of parameters

Parameters:

Name	Type	Description
`local_filepath_in`	string	the path to the local input file
`local_filepath_out`	string	the path to the local output file. If a filename without any path is given, the file is written to the temp folder (getGlobal('temp_path'))
`quality_ratio`	number	Quality of compression of the new thumbnail (0-1)
`align_x`	number	alignment from left to right for cropping (0-1)
`align_y`	number	alignment from top to bottom for cropping (0-1)
`des_width`	number	the width in pixels of the thumbnail
`des_height`	number	the height in pixels of the thumbnail

toggleDialog(name)

toggleDialog will show or hide a dialog based on its current visibility state.

Parameters:

Name	Type	Description
`name`	string	The name of a dialog to toggle.

Example

toggleDialog("myDialog"); // if hidden, it will show it. If visible, it will hide it.

unpairDevice(deviceName, unpairedJsCallback, unpairedErrorJsCallback)

Unpairs with a specified bluetooth device

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`deviceName`	string	the name of the device to attempt to pair with
`unpairedJsCallback`	string	the function to call when we successfully unpair from the device
`unpairedErrorJsCallback`	string	the function to call if there was an error

updateEditorSceneTree()

Updates the scene tree in the editor to show any newly created editable components.

Example

updateEditorSceneTree();

uploadFile(local_filepath, dashboard_folder, success_function, error_function, progress_function, http_spinner)

uploadFile asynchronously uploads a file to Umajin's cloud server. If successful, calls success_function, otherwise, calls error_function.

Parameters:

Name	Type	Description
`local_filepath`	string	The path of your file. This can be an absolute path, or a filename located in the cache or temp folders.
`dashboard_folder`	string	a folder on the Umajin dashboard. IMPORTANT: The default is to store the files outside the app project files i.e, not visible in Umajin Cloud dashboard Media Files and won't be cloned To make files visible in Umajin Cloud dashboard Media Files and be cloned, the path must start with 'cloud' '' = [s3]/uploads/{pid}/ 'ned/me' = [s3]/uploads/{pid} /ned/me/ 'cloud' = [s3]/projects/{pid} /cloud/ 'cloud/jim' = [s3]/projects/{pid} /cloud/jim
`success_function`	string	(optional) - the name of a JavaScript function that will be called if the upload is successful.
`error_function`	string	(optional) - the name of a JavaScript function that will be called if the upload is unsuccessful. Error message will be passed.
`progress_function`	string	(optional) - the name of a JavaScript function that will be called on progress reporting during uploading.
`http_spinner`	bool	Optional, a boolean value indicating whether a spinner shows for JS http requests

urlDecode(s)

urlDecode takes a URL encoded string and returns the decoded version of the same content.

Parameters:

Name	Type	Description
`s`	string	the URL encoded string to decode

Returns:

- the unencoded represntation of the string

Example

var name = "John%20Smith";
var decodedname = urlDecode(name) // decodedname = "John Smith"

urlEncode(s)

urlEncode takes a string parameter that will be passed as part of a URL querystring and properly encodes it.

Parameters:

Name	Type	Description
`s`	string	an individual parameter to URL encode (and subsequently inlcude as part of a URL)

Returns:

- the url encoded representation of the string

Example

var name = "John Smith";
var url = "http://www.test.com/script.php?name=" + urlEncode(name) // url = "http://www.test.com/script.php?name=John%20Smith"

webViewRunJavascript(web_view, script)

webViewRunJavascript runs a JavaScript function call in the context of a Web View component's current displayed page.
This allows performing updates to the web view without reloading it completely.
Notes:

There is no way to return data. A workaround for this is to change page #anchor in the URL, by setting
window.location.hash; and handle the Web View's On URL Change (on_url_change) event.
Although some platforms may support more complex JS, a simple function call is the most widely supported.
Therefore, you should wrap all the logic for the changes you wish to make into a JS function inside the
displayed web page, and then call that using this function.

Parameters:

Name	Type	Description
`web_view`	object	an instance of a Web View component
`script`	string	the JavaScript function call to run.

writeBinaryFile(data, filename)

writeBinaryFile saves an ArrayBuffer of data into a file.

Parameters:

Name	Type	Description
`data`	ArrayBuffer	data to write
`filename`	string	the path of the text filename to write. If no folder is specified, the temp folder is assumed; otherwise specify a full path in the temp or cache folders. Only the temp and cache folders are available for writing files.

Returns:

True if successful.

Type: boolean

writeTextFile(text, filename)

writeTextFile saves a string into a text file.

Parameters:

Name	Type	Description
`text`	string	the string to write
`filename`	string	the path of the text filename to write. If no folder is specified, the temp folder is assumed; otherwise specify a full path in the temp or cache folders. Only the temp and cache folders are available for writing files.

Returns:

True if successful.

Type: boolean

writeToSocket(deviceName, data, onWriteCallback, onWriteErrorCallback)

Tries to write to the bluetooth device

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`deviceName`	string	the name of the device to try and write to
`data`	string	data to write
`onWriteCallback`	string	function to call once writing is complete
`onWriteErrorCallback`	string	function to call if there is an error

writeToSocketBinary(deviceName, data, onWriteCallback, onWriteErrorCallback)

Tries to write binary data to the bluetooth device

Required Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, PERMISSION_BLUETOOTH, PERMISSION_BLUETOOTH_ADMIN, PERMISSION_BLUETOOTH_SCAN, PERMISSION_BLUETOOTH_CONNECT, FEATURE_BLUETOOTH_LE

Parameters:

Name	Type	Description
`deviceName`	string	the name of the device to try and write to
`data`	string	data to write
`onWriteCallback`	string	function to call once writing is complete
`onWriteErrorCallback`	string	function to call if there is an error

wsDisconnect(ref)

wsDisconnect Disconnects the socket

Parameters:

Name	Type	Description
`ref`	int	the socket reference

wsNew()

wsNew returns a new web socket ref (reference).

Example

var ws = -1;
registerAction("wsEchoDemo", "", "wsEchoDemo", "")
 
function wsEchoDemo() {
    ws = wsNew();
    wsOpen(ws, 'ws://echo.websocket.org', '');
    wsSetCallbacks(ws, 'wsOnError', 'wsOnConnected', '', '', '', '', 'wsTxtReceived', '');
}
 
function wsOnError(error) {
    console.log("> Error = " + error);
}
 
function wsOnConnected() {
    console.log("> Connected to Echo server");
    wsSendText(ws, 'I sent this text to the echo server');
}
 
function wsTxtReceived(message) {
    console.log("> Echo message = " + message);
}

wsOpen(ref, url, protocol)

wsOpen opens a web socket client. This connection can send and receive text or binary data using the wsSendText and wsSendBinary methods along with receiving using the callbacks on_text_received and on_binary_received you can configure with wsSetCallbacks.
Note : with the OOP API we provide a fully browser compliant version of this API able to run libraries like the mosquitoJS MQTT implementation.

Parameters:

Name	Type	Description
`ref`	int	the socket reference
`url`	string	the url of the websocket
`protocol`	string	the protocol to use, not required

wsSendBinary(ref, message)

wsSendBinary sends binary data, this is an ArrayBuffer in JavaScript.

Parameters:

Name	Type	Description
`ref`	int	the socket reference
`message`	ArrayBuffer	the buffer to send

Example

var bytearray = new Uint8Array(100);
for (var i = 0; i < 100; i++) {
    bytearray[i] = i;
}
wsSendBinary(wsRef, bytearray.buffer);

wsSendText(ref, message)

wsSendText sends text

Parameters:

Name	Type	Description
`ref`	int	the socket reference
`message`	string	the text to send

wsSetCallbacks(ref, on_error, on_connected, on_connect_failed, on_disconnected, on_disconnect_failed, on_send_failed, on_text_received, on_binary_received)

wsSetCallbacks sets up the methods to raise when connections, errors, disconnections or data is received on a web socket. In this case of the on_disconnected event the list of codes can be found here https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes

Parameters:

Name	Type	Description
`ref`	int	the socket reference
`on_error`	string	event which will pass an error string
`on_connected`	string	event when connecting no parameters
`on_connect_failed`	string	event which will pass an error string
`on_disconnected`	string	event which will pass an error code, error string and error reason string
`on_disconnect_failed`	string	event which will pass an error string
`on_send_failed`	string	event which will pass an error string
`on_text_received`	string	event which will pass a message string
`on_binary_received`	string	event which will pass a JavaScript ArrayBuffer

xmlDecode(s)

xmlDecode decodes a string from XML.

Parameters:

Name	Type	Description
`s`	string	an XML string

Returns:

- a decoded string

xmlEncode(s)

xmlEncode encodes a string suitably for including in an XML document. This will encode tab, newline and other characters outside the valid range XML accepts.

Parameters:

Name	Type	Description
`s`	string	incoming string

Returns:

- XML representation of s