Utility

Everything else: random numbers, converting a value from one range to another, working with bits, waiting until a time of day, running a program or opening a web page on the computer, loading a project, checking for an ARCx update, and shutting down or sleeping the computer.

Where to find it: type Utility. in a JavaScript script, or open the ARCx API view of the script editor and expand Utility

Commands

Details

Utility.browser

Opens a web address in the default web browser of the computer running ARCx, which may not be the browser you are viewing ARCx in.

Utility.browser(url)

Utility.checkForUpdate

Checks the Synthiam website for a newer version of ARCx. Waits for the reply (up to 4 seconds by default) and raises an error if the website cannot be reached.

Utility.checkForUpdate()

Gives back: boolean. Whether a newer version is available.

Utility.clearGlobalVariable

Deletes a global variable so it no longer exists. Nothing happens if there is no variable with that name.

Utility.clearGlobalVariable(globalVariableName)

Utility.exec

Starts a program on the computer running ARCx and carries on without waiting for it to finish. Raises an error if the program cannot be found.

Utility.exec(filename)
Utility.exec(filename, arguments)

Utility.getBit

Checks whether one bit of a number is set (1). Bit 0 is the lowest bit, worth 1, and bit 7 is worth 128.

Utility.getBit(value, bitPosition)

Gives back: boolean. Whether the bit is set.

Utility.getRandom

Returns a random whole number from min to max, both included. The two may be given either way round.

Utility.getRandom(min, max)

Gives back: number. The random number.

Utility.getRandomUnique

Returns a random whole number from min to max, both included, trying not to repeat the number it returned last time. Returns min when min and max are equal.

Utility.getRandomUnique(min, max)

Gives back: number. The random number.

Utility.loadProject

Stops this script, closes the current project and opens the given one, raising an error if it cannot be found or loaded. ".arcx" is added when missing, a bare name is looked up in the My Projects folder, and a password protected project needs its password to have been entered earlier this session.

Utility.loadProject(filename)

Utility.map

Converts a value from one range to another, such as 0 to 255 into 1 to 180, keeping the result inside the output range. Raises an error if inputMin and inputMax are equal.

Utility.map(input, inputMin, inputMax, outputMin, outputMax)

Gives back: number. The converted value.

Utility.setBits

Builds a byte from eight on/off bits, b7 being the highest bit (worth 128) and b0 the lowest (worth 1).

Utility.setBits(b7, b6, b5, b4, b3, b2, b1, b0)

Gives back: number. The byte, 0 to 255.

Utility.shutdownPC

Shuts down the computer running ARCx straight away, without saving the project or asking. Works on Windows, Linux and macOS, and raises an error if the operating system refuses (on Linux, ARCx's user needs permission to power off).

Utility.shutdownPC()

Utility.sleepPCHibernate

Hibernates the computer running ARCx: what is in memory is saved to disk and it powers off. On Windows the script carries on once the computer wakes up. Raises an error if hibernation is turned off or not allowed. A Mac goes to sleep instead, as it decides when to hibernate.

Utility.sleepPCHibernate(force, wake)

Utility.sleepPCSuspend

Puts the computer running ARCx to sleep. On Windows the script carries on once the computer wakes up. Raises an error if the operating system refuses.

Utility.sleepPCSuspend(force, wake)

Utility.waitUntilTime

Pauses the script until the computer's clock reaches the given hour and minute, checking once a second. If that time has already passed today it waits until tomorrow, and it returns early if the script is stopped.

Utility.waitUntilTime(hour, minute)