NOTE! You are browsing legacy documentation. For latest visit docs.nativescript.org.

NativeScript Core

Utils

To use the functionality provided by the utils/utils module, first require/import the module:

const utilsModule = require("tns-core-modules/utils/utils");
import * as utils from "tns-core-modules/utils/utils";

isFileOrResourcePath() function

Verify if the specified path points to a resource or a local file. The function returns a boolean value of:

  • true - if the path has a valid path structure
  • false - if the path is not a file path
var path = "res://icon";
var value = utilsModule.isFileOrResourcePath(path);
const path: string  = "res://icon";
const value: boolean = utils.isFileOrResourcePath(path);

isDataURI() function

Checks if the specified URI is a data URI.

  • Returns true if the string is data URL, otherwise false
var url = "<url>";
var value = utilsModule.isDataURI(url);
const url: string = "<url>"; 
const value:boolean = utils.isDataURI(url);

openUrl() function

Open an URL on device with the default browser

utilsModule.openUrl("/core-concepts/utils")
utils.openUrl("/core-concepts/utils")

escapeRegexSymbols() function

Escapes special regex symbols (., *, ^, $, etc.) in string in order to create a valid regex from it.

var sampleString = "All of these should be escaped: ^ $ * ";
var newString = utilsModule.escapeRegexSymbols(sampleString);
var sampleString: string = "All of these should be escaped: ^ $ * ";
var newString: string = utils.escapeRegexSymbols(sampleString);

convertString() function

Converts a string value to a number or boolean;

var stringToBoolean = "true";
var booleanValue = utilsModule.convertString(stringToBoolean);

var stringToNumber = "23";
var numberValue = utilsModule.convertString(stringToNumber);
const stringToBoolean :string = "true";
const booleanValue :boolean = utils.convertString(stringToBoolean);

const stringToNumber: string = "23";
const numberValue :number = utils.convertString(stringToNumber);

getDisplayDensity() function

Returns the display density of the device.

var displayDensity = utilsModule.layout.getDisplayDensity();
const displayDensity = utils.layout.getDisplayDensity();

toDevicePixels() function

Converts value from device independent pixels to device pixels.

var devicePixels = utilsModule.layout.toDevicePixels(<dip>);
const devicePixels = utils.layout.toDevicePixels(<dip>);

toDeviceIndependentPixels() function

Convert value to device independent pixels.

var deviceIndependentPixels = utilsModule.layout.toDeviceIndependentPixels(<px>);
const deviceIndependentPixels = utils.layout.toDeviceIndependentPixels(<px>);

round() method

Rounds value used in layout.

var value = utilsModule.layout.round(<number_value>);
var value = utils.layout.round(<number_value>);

If we set 123.56px as a input the returned value will be 124px.

executeOnMainThread() method

The method checks if the current thread is the main thread. It will directly call the passed function if it is, or dispatches it to the main thread otherwise.

utilsModule.executeOnMainThread(() => {
    // ...
})
utilsModule.executeOnMainThread(() => {
    // ...
})

mainThreadify() method

The method returns a function wrapper which executes the supplied function on the main thread. The wrapper behaves like the original function and passes all of its arguments BUT discards its return value.

utilsModule.mainThreadify(() => {
    // ...
})
utilsModule.mainThreadify(() => {
    // ...
})

Platform specific methods

Android

getApplication() function

Returns an instance of native Android application The returned value will be of type android.app.Application.

var application = utilsModule.ad.getApplication();
const application = utils.ad.getApplication();

getApplicationContext() function

Returns the Android application context. The returned value will be of type android.content.Context.

var context = utilsModule.ad.getApplicationContext();
const context = utils.ad.getApplicationContext();

getInputMethodManager() function

Returns an instance of native Android input method manager. The returned value will be an android.view.inputmethod.InputMethodManager

var inputMethodManager = utilsModule.ad.getInputMethodManager();
const inputMethodManager = utils.ad.getInputMethodManager();

showSoftInput() function

Show keyboard for a specific element.

<TextField id="textfieldid" hint="Target field" />
<Button text="Show keyboard" tap="showKeyboard" class="btn btn-primary btn-active"/>
function showKeyboard(args) {
    var button = args.object;
    var page = button.page;
    var textField = page.getViewById("textfieldid");
    utilsModule.ad.showSoftInput(textField.android);
}
exports.showKeyboard = showKeyboard;
import { Page } from "tns-core-modules/ui/page";
import { TextField } from "tns-core-modules/ui/text-field";
import { Button } from "tns-core-modules/ui/button"

export function showKeyboard(args: EventData) {
    var button: Button = <Button>args.object;
    var page: Page = <Page>button.page;
    var textField: TextField = <TextField> page.getViewById("textfieldid");
    utils.ad.showSoftInput(textField.android);
}

dismissSoftInput() function

Hides the soft input method, usually a soft keyboard.

<TextField id="textfieldid" hint="Target field" />
<Button text="Hide keyboard" tap="dismissSoftInput" class="btn btn-primary btn-active"/>
function dismissSoftInput(args) {
    utilsModule.ad.dismissSoftInput();
}
exports.dismissSoftInput = dismissSoftInput;
export function dismissSoftInput(args: EventData) {
    utils.ad.dismissSoftInput();
}

stringArrayToStringSet() function

Converts a string array into a String hash set.

var stringArr = ["a", "b", "c"]
var stringSet = utilsModule.ad.collections.stringArrayToStringSet(stringArr);
const stringArr = ["a", "b", "c"]
const stringSet = utils.ad.collections.stringArrayToStringSet(stringArr);

stringSetToStringArray() function

Converts a string hash set into array of strings

var hashSet = new java.util.HashSet();
var string1 = new java.lang.String("item1");
var string2 = new java.lang.String("item2");
var string3 = new java.lang.String("item3");

hashSet.add(string1);
hashSet.add(string2);
hashSet.add(string3);

var stringArray = utilsModule.ad.collections.stringSetToStringArray(hashSet);
const hashSet = new java.util.HashSet();
const string1 = new java.lang.String("item1");
const string2 = new java.lang.String("item2");
const string3 = new java.lang.String("item3");

hashSet.add(string1);
hashSet.add(string2);
hashSet.add(string3);

var stringArray = utils.ad.collections.stringSetToStringArray(hashSet);

getDrawableId() function

Returns the drawable id from a given resource name

var drawableId = utilsModule.ad.resources.getDrawableId("icon");
const drawableId: number = utils.ad.resources.getDrawableId("icon");

getStringId() function

Returns the id of the string from the resources, while using its name

var stringId = utilsModule.ad.resources.getStringId("resource_string_name");
const stringId: string = utils.ad.resources.getStringId("resource_string_name");

getId() function

Returns the id from a resource, while passing string with resource type and name. eg: :drawable/<resource_name>, :string/<resource_name>

var id = utilsModule.ad.resources.getId("resource_name");
const id: number = utils.ad.resources.getId("resource_name");

getPalleteColor() function

Returns a color from the current theme using the resource color name.

var context = utilsModule.ad.getApplicationContext();
var currentThemeColor = utilsModule.ad.resources.getPalleteColor("resource_color_name", context);
const context = utils.ad.getApplicationContext();
const currentThemeColor: number = utils.ad.resources.getPalleteColor("resource_color_name", context);

iOS

jsArrayToNSArray() function

Converts a JavaScript array to a NSArray

var jsArray = ["item1", "item2", "item3"];
var nsArray = utilsModule.ios.collections.jsArrayToNSArray(jsArray);
const jsArray: Array<string> = ["item1", "item2", "item3"];
const nsArray = utils.ios.collections.jsArrayToNSArray(jsArray);

nsArrayToJSArray() function

Converts a NSArray to a JavaScript array.

var nsArray = new NSArray(["item1", "item2", "item3"]);
var jsArray = utilsModule.ios.collections.nsArrayToJSArray(nsArray);
const nsArray = new NSArray(["item1", "item2", "item3"]);
const jsArray: Array<any> = utils.ios.collections.nsArrayToJSArray(nsArray);

isLandscape() function

Returns true if current orientation is Landscape.

var value = utilsModule.ios.isLandscape();
const value: boolean = utils.ios.isLandscape()

MajorVersion() function

Returns a number with the iOS device major version(eg 8.1 will return 8).

console.log("iOS MajorVersion "+ utilsModule.ios.MajorVersion);
console.log("iOS MajorVersion "+ utils.ios.MajorVersion);

openFile() function

Opens file with associated application, while using file path.

utilsModule.ios.openFile(<file_path>);
utils.ios.openFile(<file_path>);