appendix b touchdevelop services - · pdf fileappendix b touchdevelop services | 161. purple :...

Appendix B

TouchDevelop Services

This appendix reproduces material found on the TouchDevelop website at

https://www.touchdevelop.com/help/api. It is provided here to make the

book more self-contained. Appendix B covers the objects (known as

resources or services) provided by the API. The datatypes are covered in

Appendix C.

B.1 bazaar Browse and review scripts from the bazaar.

leaderboard score : Number Gets the current score for the current script

post leaderboard score(score :

Number) : Nothing

Posts the current game score to the script

leaderboard

post leaderboard to wall : Nothing Posts the current game leaderboard to the wall

B.2 collections Create collections of items.

create link collection : Link Collection Creates an empty link collection

create location collection : Location

Collection

Creates an empty location collection

create message collection : Message

Collection

Creates an empty message collection

create number collection : Number

Collection

Creates an empty number collection

create number map : Number Map Creates an empty number map

create place collection : Place Collection Creates an empty place collection

create string collection : String Collection Creates an empty string collection

create string map : String Map Creates an empty string map (case and

culture sensitive)

https://www.touchdevelop.com/help/api

160 | TouchDevelop services Appendix B

B.3 colors Access predefined colors or create new colors.

accent : Color Gets the accent color in the current theme

background : Color Gets the background color in the current

theme

black : Color Gets the color that has the ARGB value of

#FF000000

blue : Color Gets the color that has the ARGB value of

#FF0000FF

brown : Color Gets the color that has the ARGB value of

#FFA52A2A

chrome : Color Gets the chrome color in the current theme

(control background)

cyan : Color Gets the color that has the ARGB value of

#FF00FFFF

dark gray : Color Gets the color that has the ARGB value of

#FFA9A9A9

foreground : Color Gets the foreground color in the current theme

from ahsb(alpha : Number, hue :

Number, saturation : Number,

brightness : Number) : Color

Creates a color from the alpha, hue, saturation,

brightness channels (0.0-1.0 range)

from argb(alpha : Number, red :

Number, green : Number, blue :

Number) : Color

Creates a color from the alpha, red, green, blue

channels (0.0-1.0 range)

from hsb(hue : Number, saturation :

Number, brightness : Number) :

Color

Creates a color from the hue, saturation,

brightness channels (0.0-1.0 range)

from rgb(red : Number, green :

Number, blue : Number) : Color

Creates a color from the red, green, blue

channels (0.0-1.0 range)

gray : Color Gets the color that has the ARGB value of

#FF808080

green : Color Gets the color that has the ARGB value of

#FF008000

is light theme : Boolean Indicates if the user is using a light theme in

his phone

light gray : Color Gets the color that has the ARGB value of

#FFD3D3D3

linear gradient(c1 : Color, c2 : Color,

alpha : Number) : Color

Computes an intermediate color

magenta : Color Gets the color that has the ARGB value of

#FFFF00FF

orange : Color Gets the color that has the ARGB value of

#FFFFA500

Appendix B TouchDevelop services | 161

purple : Color Gets the color that has the ARGB value of

#FF800080

random : Color Picks a random color

red : Color Gets the color that has the ARGB value of

#FFFF0000

sepia : Color Gets the color that has the ARGB value of

#FF704214

subtle : Color Gets the subtle color in the current theme

(light gray)

transparent : Color Gets the color that has the ARGB value of

#00FFFFFF

white : Color Gets the color that has the ARGB value of

#FFFFFFFF

yellow : Color Gets the color that has the ARGB value of

#FFFFFF00

B.4 home Interact with devices in the home network. Devices must be UPnP™

compatible.

choose player : Media Player Choose a media player on the current wireless

network

choose printer : Printer Choose a printer on the current wireless

network

choose server : Media Server Choose a media server on the current wireless

network

players : Media Player Collection Gets the media players on the current wireless

network

printers : Printer Collection Gets the printers on the current wireless

network

servers : Media Server Collection Gets the media servers on the home network

B.5 invalid Create an invalid value for any datatype.

appointment : Appointment Creates an invalid Appointment instance

appointment collection :

Appointment Collection

Creates an invalid Appointment Collection

instance

board : Board Creates an invalid Board instance

boolean : Boolean Creates an invalid Boolean instance


camera : Camera Creates an invalid Camera instance

color : Color Creates an invalid Color instance

contact : Contact Creates an invalid Contact instance

contact collection : Contact

Collection

Creates an invalid Contact Collection instance

datetime : DateTime Creates an invalid DateTime instance

device : Device Creates an invalid Device instance

device collection : Device

Collection

Creates an invalid Device Collection instance

json object : Json Object Creates an invalid Json Object instance

link : Link Creates an invalid Link instance

link collection : Link Collection Creates an invalid Link Collection instance

location : Location Creates an invalid Location instance

location collection : Location

Collection

Creates an invalid Location Collection instance

map : Map Creates an invalid Map instance

media link : Media Link Creates an invalid Media Link instance

media link collection : Media Link

Collection

Creates an invalid Media Link Collection instance

media player : Media Player Creates an invalid Media Player instance

media player collection : Media

Player Collection

Creates an invalid Media Player Collection

instance

media server : Media Server Creates an invalid Media Server instance

media server collection : Media

Server Collection

Creates an invalid Media Server Collection

instance

message : Message Creates an invalid Message instance

message collection : Message

Collection

Creates an invalid Message Collection instance

motion : Motion Creates an invalid Motion instance

number : Number Creates an invalid Number instance

number collection : Number

Collection

Creates an invalid Number Collection instance

number map : Number Map Creates an invalid Number Map instance

page : Page Creates an invalid Page instance

page button : Page Button Creates an invalid Page Button instance

page collection : Page Collection Creates an invalid Page Collection instance

picture : Picture Creates an invalid Picture instance

picture album : Picture Album Creates an invalid Picture Album instance

picture albums : Picture Albums Creates an invalid Picture Albums instance

pictures : Pictures Creates an invalid Pictures instance

place : Place Creates an invalid Place instance

place collection : Place Collection Creates an invalid Place Collection instance

playlist : Playlist Creates an invalid Playlist instance

playlists : Playlists Creates an invalid Playlists instance

printer : Printer Creates an invalid Printer instance


printer collection : Printer

Collection

Creates an invalid Printer Collection instance

song : Song Creates an invalid Song instance

song album : Song Album Creates an invalid Song Album instance

song albums : Song Albums Creates an invalid Song Albums instance

songs : Songs Creates an invalid Songs instance

sound : Sound Creates an invalid Sound instance

sprite : Sprite Creates an invalid Sprite instance

sprite set : Sprite Set Creates an invalid Sprite Set instance

string : String Creates an invalid String instance

string collection : String

Collection

Creates an invalid String Collection instance

string map : String Map Creates an invalid String Map instance

textbox : TextBox Creates an invalid TextBox instance

tile : Tile Creates an invalid Tile instance

vector3 : Vector3 Creates an invalid Vector3 instance

web request : Web Request Creates an invalid Web Request instance

web response : Web Response Creates an invalid Web Response instance

xml object : Xml Object Creates an invalid Xml Object instance

B.6 languages Translation, and speech to text services.

current language : String Gets the current language code, to be used in

the 'translate' method

detect language(text : String) :

String

Automatically detects the language of a given

text using Bing.

picture to text(lang : String, pic :

Picture) : String

Extracts text in the picture using Project Hawaii

from Microsoft Research

record text : String Converts the microphone dictation to text

using Project Hawaii from Microsoft Research

speak(lang : String, text : String) :

Sound

Speaks the text in the specified language using

Bing

speech to text(lang : String, speech

: Sound) : String

Converts a sound to a text using Project

Hawaii from Microsoft Research

translate(source lang : String, target

lang : String, text : String) : String

Translates some text between two languages

using Bing. Empty source language to auto-

detect


B.7 locations Geo coordinates services.

create location(latitude : Number,

longitude : Number) : Location

Creates a new geo coordinate location

create location list : Location

Collection

Creates an empty list of locations

describe location(location : Location)

: String

Looks for an address near a location using

Bing

search location(address : String,

postal code : String, city : String,

country : String) : Location

Looks for the coordinate of an address using

Bing

B.8 maps Maps, location to address and address to location services.

create full map : Map Creates a full screen Bing map. Use 'post to

wall' to display it.

create map : Map Creates a Bing map. Use 'post to wall' to

display it.

directions(from : Location, to :

Location, walking : Boolean) :

Location Collection

Calculates the directions between two

coordinates using Bing.

open directions(start search :

String, start loc : Location, end

search : String, end loc : Location) :

Nothing

Shows the directions in the Bing map

application. If search term is provided, location

is ignored. Provide search term or location for

start and end.

open map(center : Location, search

: String, zoom : Number) : Nothing

Opens the Bing map application. zoom

between 0 (close) and 1 (far)

B.9 math Mathematical constants, operators, and functions such as cos, sin etc.

∞₋ : Number Returns negative infinity

∞₊ : Number Returns positive infinity

abs(x : Number) : Number Returns the absolute value of a number

acos(x : Number) : Number Returns the angle whose cosine is the specified

number


asin(x : Number) : Number Returns the angle whose sine is the specified

number

atan(x : Number) : Number Returns the angle whose tangent is the

specified number

atan2(y : Number, x : Number) :

Number

Returns the angle whose tangent is the quotient

of two specified numbers

ceiling(x : Number) : Number Returns the smallest integral value greater than

or equal to the specified number

cos(angle : Number) : Number Returns the cosine of the specified angle

cosh(angle : Number) : Number Returns the hyperbolic cosine of the specified

angle

create vector3(x : Number, y :

Number, z : Number) : Vector3

Creates a 3D vector

deg to rad(degrees : Number) :

Number

Converts degrees into radians

e : Number Returns the natural logarithmic base, specified

by the constant, e

exp(x : Number) : Number Returns e raised to the specified power

floor(x : Number) : Number Returns the largest integer less than or equal to

the specified number

gravity : Number Returns the value of standard gravity (9.80665)

in meters/sec2

ieee remainder(x : Number, y :

Number) : Number

Returns the remainder resulting from the

division of a specified number by another

specified number

is ∞(x : Number) : Boolean Indicates whether number evaluates to negative

or positive infinity

is ∞₋(x : Number) : Boolean Indicates whether number evaluates to negative

infinity

is ∞₊(x : Number) : Boolean Indicates whether number evaluates to positive

infinity

is nan(x : Number) : Boolean Indicates that value cannot be represented as a

number, i.e. Not-a-Number. This usually

happens when the number is the result of a

division by zero.

log(x : Number, base : Number) :

Number

Returns the logarithm of a specified number in

a specified base

log10(x : Number) : Number Returns the base 10 logarithm of a specified

number

loge(x : Number) : Number Returns the natural (base e) logarithm of a

specified number

max(x : Number, y : Number) :

Number

Returns the larger of two numbers

min(x : Number, y : Number) :

Number

Returns the smaller of two numbers


mod(x : Number, y : Number) :

Number

Returns the modulus resulting from the division

of one number by another number

pow(x : Number, y : Number) :

Number

Returns a specified number raised to the

specified power

rad to deg(radians : Number) :

Number

Converts rad into degrees

random(max : Number) : Number Returns a random integral number x: 0 ≤ x <

max

random normalized : Number Returns a random floating-point number x: 0 ≤

x < 1

round(x : Number) : Number Rounds a number to the nearest integral value

round with precision(x : Number,

digits : Number) : Number

Rounds a number to a specified number of

fractional digits.

sign(x : Number) : Number Returns a value indicating the sign of a number

sin(angle : Number) : Number Returns the sine of the specified angle

sinh(angle : Number) : Number Returns the hyperbolic sine of the specified

angle

sqrt(x : Number) : Number Returns the square root of a specified number

tan(angle : Number) : Number Returns the tangent of the specified angle

tanh(angle : Number) : Number Returns the hyperbolic tangent of the specified

angle

ε : Number Returns the smallest positive number greater

than zero.

π : Number Returns the constant Pi

B.10 media Pictures and music.

choose picture : Picture Chooses a picture from the media library

create board(height : Number) :

Board

Creates a new game board

create landscape board(width:

Number, height : Number) : Board

Creates a new game board in landscape mode.

On rotatable devices it will take the entire

screen when posted.

create picture(width : Number,

height : Number) : Picture

Creates a new picture of the given size

create portrait board(width:

Number, height : Number) : Board

Creates a new game board in portrait mode.

On rotatable devices it will take the entire

screen when posted.

icon(name : String) : Picture Gets a 48x48 icon picture. Use 'media→icon

names' to retrieve the list of names available.

icon names : String Collection Gets the list of built-in 48x48 icon names. You

can see the icon list in the script settings.


large icon(name : String) : Picture Gets a 96x96 icon picture. Use 'media→icon

names' to retrieve the list of names available.

picture albums : Picture Albums Gets the picture albums

pictures : Pictures Gets the pictures on the phone

playlists : Playlists Gets the playlists on the phone

saved pictures : Pictures Gets the saved pictures on the phone

search marketplace(terms : String,

type : String) : Nothing

Searches the Windows Phone Marketplace

(type in applications or music)

song albums : Song Albums Gets the song albums on the phone

songs : Songs Gets the songs on the phone

B.11 phone Phone numbers, vibrate, etc.

choose address : Link Chooses an address from the contacts

choose phone number : Link Chooses a phone number from the contact list

dial phone number(number :

String) : Nothing

Starts a phone call

power source : String Indicates if the phone is on 'battery' or

'external' power source.

save phone number(phone number

: String) : Nothing

Allows the user to save the phone number

vibrate(seconds : Number) :

Nothing

Vibrates the phone for a number of seconds

(0.02 minimum)

B.12 player Play, stop or resume songs

active song : Song Gets the active song if any

is muted : Boolean Indicates if the player is muted

is paused : Boolean Indicates if the player is paused

is playing : Boolean Indicates if the player is playing a song

is repeating : Boolean Indicates if the player is repeating

is shuffled : Boolean Indicates if the player is shuffled

is stopped : Boolean Indicates if the player is stopped

next : Nothing Moves to the next song in the queue of

playing songs

pause : Nothing Pauses the currently playing song

play(song : Song) : Nothing Plays a Song


play home media(media : Media

Link) : Nothing

Plays an audio/video file from the home

network

play many(songs : Songs) : Nothing Plays a collection of songs

play position : Number Gets the position in seconds within the active

song

previous : Nothing Moves to the previous song in the queue of

playing songs

resume : Nothing Resumes a paused song

set repeating(repeating : Boolean) :

Nothing

Sets the repeating on and off

set shuffled(shuffled : Boolean) :

Nothing

Sets the shuffling on and off

set sound volume(x : Number) :

Nothing

Sets the sound volume level from 0 (silent) to 1

(current volume)

sound volume : Number Gets the sound volume for sounds from 0

(silent) to 1 (current volume)

stop : Nothing Stops playing a song

B.13 radio Access to the radio.

frequency : Number Gets the frequency

is playing : Boolean Indicates if the radio is on

link frequency(name : String,

frequency : Number) : Link

Creates a link to a radio frequency

set frequency(frequency : Number) :

Nothing

Sets the frequency

signal strength : Number Gets the signal strength

start : Nothing Turns on the radio

stop : Nothing Turns off the radio

B.14 records Lists objects, tables and indexes defined in the current script. The records

section is a component of every script, not an API resource.

B.15 senses Camera, location, microphone and other sensors.


acceleration quick : Vector3 Gets filtered accelerometer data using a

combination of a low-pass and threshold triggered

high-pass on each axis to eliminate the majority of

the sensor low amplitude noise while trending very

quickly to large offsets (not perfectly smooth signal

in that case), providing a very low latency. This is

ideal for quickly reacting UI updates.

acceleration smooth : Vector3 Gets filtered accelerometer data using a 1 Hz first-

order low-pass on each axis to eliminate the main

sensor noise while providing a medium latency. This

can be used for moderately reacting UI updates

requiring a very smooth signal.

acceleration stable : Vector3 Gets filtered and temporally averaged accelerometer

data using an arithmetic mean of the last 25

'optimally filtered' samples, so over 500ms at 50Hz

on each axis, to virtually eliminate most sensor

noise. This provides a very stable reading but it has

also a very high latency and cannot be used for

rapidly reacting UI.

camera : Camera Gets the primary camera

current location : Location Gets the current phone location. The phone

optimizes the accuracy for power, performance, and

other cost considerations.

current location accurate :

Location

Gets the current phone location with the most

accuracy. This includes using services that might

charge money, or consuming higher levels of battery

power or connection bandwidth.

front camera : Camera Gets the front facing camera

has gyroscope : Boolean Indicates if the gyroscope is available on the device

heading : Number Gets the compass heading, in degrees, measured

clockwise from the Earth’s geographic north.

is device stable : Boolean Indicates whether the device is 'stable' (no

movement for about 0.5 seconds)

motion : Motion Gets the current phone motion that combines data

from the accelerometer, compass and gyroscope.

orientation : Vector3 Gets the current orientation in degrees if available.

(x,y,z) is also called (pitch, roll, yaw) or (alpha, beta,

gamma).

record microphone : Sound Records audio using the microphone

rotation speed : Vector3 Gets the gyroscope rotational velocity around each

axis of the device, in degrees per second.

take camera picture : Picture Takes a picture and returns it. This picture does not

contain the gps location.


B.16 social Emails, sms, contacts, and calendar services.

choose contact : Contact Chooses a contact from the contact list

choose email : Link Chooses an email from the contact list

create contact(nickname : String) : Contact Creates a new contact

create message(message : String) :

Message

Creates a message to share

create place(name : String, location :

Location) : Place

Creates a place

link email(email address : String) : Link Creates a link from an email

link phone number(phone number :

String) : Link

Creates a link from a phone number

save contact(contact : Contact) : Nothing Saves a new contact

save email(email address : String) :

Nothing

Allows the user to save the email

address (email)

search(network : String, terms : String) :

Message Collection

Searches for recent messages in a social

network (twitter, facebook)

search appointments(start : DateTime, end

: DateTime) : Appointment Collection

Searches for appointments in a given

time range

search contacts(prefix : String) : Contact

Collection

Searches for contacts by name.

search places nearby(network : String,

terms : String, location : Location, distance

: Number) : Place Collection

Searches for places nearby. The distance

is in meters.

send email(to : String, subject : String,

body : String) : Nothing

Opens the mail client

send sms(to : String, body : String) :

Nothing

Opens the short message client (to,

body)

B.17 tags 2D barcode generation and scanning services.

tag text(text : String, size : Number,

bw : Boolean) : Picture

Generates a 2D barcode pointing to the text

using Microsoft Tag. text must be less than

1000 character long and size must be between

0.75 and 5 inches.

tag url(url : String, size : Number,

bw : Boolean) : Picture

Generates a 2D barcode pointing to the url

using Microsoft Tag. url must be less than

1000 character long and size must be between

0.75 and 5 inches


B.18 time Time and date operations.

create(year : Number, month :

Number, day : Number, hour :

Number, minute : Number, second :

Number) : DateTime

Creates a new date instance

fail if not(condition : Boolean) :

Nothing

Aborts the execution if the condition is false.

log(message : String) : Nothing Appends this message to the debug log. Does

nothing when the script is published.

now : DateTime Gets the current time

sleep(seconds : Number) : Nothing Waits for a specified amount of seconds

stop : Nothing Stops the execution and stays on the wall.

stop and close : Nothing Stops the execution and leaves the wall.

today : DateTime Gets today's date without time

tomorrow : DateTime Gets tomorrow's date without time

B.19 wall Ask for or display values on the wall.

add button(icon : String, text :

String) : Page Button

Add a new button. icon must be the name of a

built-in icon, text must be non-empty.

ask boolean(text : String, caption :

String) : Boolean

Prompts the user with ok and cancel buttons

ask number(text : String) : Number Prompts the user to input a number

ask string(text : String) : String Prompts the user to input a string

button icon names : String

Collection

Gets the list of available page button names.

clear : Nothing Clears the entries

clear buttons : Nothing Clears the application bar buttons and hides

the bar

create text box(text : String, font

size : Number) : TextBox

Creates an updatable text box

current page : Page Gets the current page displayed on the wall

display search(on : Boolean) :

Nothing

Indicates whether to show or hide the search

icon

pages : Page Collection Returns the current back stack of pages,

starting from the current page to the bottom

page.


pick date(text : String, caption :

String) : DateTime

Prompts the user to pick a date. Returns a

datetime whose date is set, the time is

12:00:00.

pick string(text : String, caption :

String, values : String Collection) :

Number

Prompts the user to pick a string from a list.

Returns the selected index.

pick time(text : String, caption :

String) : DateTime

Prompts the user to pick a time. Returns a

datetime whose time is set, the date is

undefined.

pop page : Boolean Pops the current page and restores the

previous wall page. Returns false if already on

the default page.

prompt(text : String) : Nothing Prompts the user with an ok button

push new page : Page Pushes an empty page on the wall

screenshot : Picture Takes a screenshot of the wall

set background(color : Color) :

Nothing

Sets the wall background color

wall→set background camera(

camera : Camera) : Nothing

Sets the wall background camera

set background picture(picture :

Picture) : Nothing

Sets the wall background picture. The picture

will be resized and clipped to the screen

background as needed

set foreground(color : Color) :

Nothing

Sets the wall foreground color of elements

set reversed(bottom : Boolean) :

Nothing

Reverses the elements on the wall and inserts

new ones at the bottom.

set subtitle(title : String) : Nothing Sets the subtitle of the wall

set title(title : String) : Nothing Sets the title of the wall

set transform matrix(m11 : Number,

m12 : Number, m21 : Number, m22

: Number, offsetx : Number, offsety

: Number) : Nothing

Sets the 3x3 affine matrix transformation

applied to the wall

B.20 web Search and browse the web.

base64 decode(text : String) : String Decodes a string that has been base64-

encoded

base64 encode(text : String) : String Converts a string into an base64-encoded

string

browse(url : String) : Nothing Opens a web browser to a url

connection name : String Gets a name of the currently connected

network servicing Internet requests


connection type : String Gets the type of the network servicing Internet

requests (unknown, none, ethernet, wifi,

mobile)

create request(url : String) : Web

Request

Creates a web request

download(url : String) : String Downloads the content of an internet page

(http get)

download json(url : String) : Json

Object

Downloads a web service response as a JSON

data structure (http get)

download picture(url : String) :

Picture

Downloads a picture from internet

download song(url : String, name :

String) : Song

Create a streamed song file from internet

(download happens when playing)

download sound(url : String) :

Sound

Downloads a WAV sound file from internet

feed(value : String) : Message

Collection

Parses the newsfeed string (RSS 2.0 or Atom

1.0) into a message collection

html decode(html : String) : String Decodes a string that has been HTML-encoded

html encode(text : String) : String Converts a text string into an HTML-encoded

string

is connected : Boolean Indicates whether any network connection is

available

json(value : String) : Json Object Parses the string as a json object

json array : Json Object Returns an empty json array

json object : Json Object Returns an empty json object

link image(url : String) : Link Creates a link to an internet image

link media(url : String) : Link Creates a link to an internet audio/video

link url(name : String, url : String) :

Link

Creates a link to an internet page

open connection settings(page :

String) : Nothing

Opens a connection settings page

(airplanemode, bluetooth, wiki, cellular)

play media(url : String) : Nothing Plays an internet audio/video in full screen

search(terms : String) : Link

Collection

Search the web using Bing

search images(terms : String) : Link

Collection

Search for images using Bing

search images nearby(terms :

String, location : Location, distance :

Number) : Link Collection

Search for images near a location using Bing.

Distance in meters, negative to ignore.

search nearby(terms : String,

location : Location, distance :


Searching the web near a location using Bing.


search news(terms : String) : Link

Collection

Search for news using Bing


search news nearby(terms : String,

location : Location, distance :


Search for news near a location using Bing.


upload(url : String, body : String) :

String

Uploads text to an internet page (http post)

upload picture(url : String, pic :

Picture) : String

Uploads a picture to an internet page (http

post)

url decode(url : String) : String Decodes a string that has been url-encoded

url encode(text : String) : String Converts a text string into an url-encoded

string

xml(value : String) : Xml Object Parses the string as a xml element

appendix b touchdevelop services - · pdf fileappendix b touchdevelop services | 161. purple :...

Documents