Interactions
Smart phones, tablets and computers provide calendars, e-mail, access to social media, some forms of instant messaging, SMS and phone calls. Even a computer might place a phone call through the use of a service like Skype. These are all forms of interaction which are covered in this chapter.
8.1 Social messages |
8.2 Locations, places, maps |
8.3 Emails |
8.4 Phone Calls |
8.5 2D barcodes |
8.6 SMS messages (WP8 only) |
8.7 Calendar and appointments (WP8 only) |
8.8 Contacts (WP8 only) |
Several websites, including Twitter and Facebook in particular, provide the ability to post messages for other people to read. These messages may have associated content, such as a picture or an audio clip. The TouchDevelop API provides facilities for downloading such messages and for posting new messages.
The social resource provides the two methods listed in Table 8-1 for creating a new message and for retrieving messages from a website. A simple example of obtaining messages from the two supported social networks and displaying them might be as follows.
var TD msgs := social → search(“twitter”, “#touchdevelop”)
var more msgs := social → search(“facebook”, “TouchDevelop”)
// combine the two collections into one
TD msgs → add many(more msgs)
// reorder and display the messages
TD msgs → sort by date
TD msgs → post to wall
Table 8-1: Messaging methods of the social service
Methods | Description |
---|---|
social→create message( message : String) : Message |
Creates a new message with the text body provided. |
social→search(network : String, terms : String) : Message Collection | Searches twitter or Facebook for recent messages matching the search terms provided. |
A Message value will usually have a text component, because that is the simplest form of message. However additional information is usually associated with that message. The TouchDevelop API supports many methods for accessing or setting extra content attached to a message. These are all methods of the Message datatype. The methods for accessing, or getting, content are listed in the first table of section C.25 in Appendix C, those for setting content in the second table, and some additional methods in the third table.
It should be remembered that the extra content of a message is not always present. After retrieving one of these optional values, such as media link, the script should perform the test is invalid to verify that the value was actually available.
The share method of a Message instance allows the message to be transmitted in one of a variety of ways. Whichever choice is provided for the where parameter, a dialog box is displayed. The message is not sent until a selection has been picked and/or a button to send the message has been tapped.
The Message Collection type is a mutable collection of messages. An empty instance may be created with the following call:
var msgs := collections → create message collection
This empty collection may then be populated using the standard methods for adding new elements to a collection.
Collections of messages may also be created by the social→search and web→feed methods. The web→feed method accesses an RSS stream or Atom feed on the internet and parses that stream into a sequence of messages. An example script which uses the method is rmc reader (/fiol).
The Message Collection type provides several methods which are common to all mutable collection types. However there are two additional methods which are particularly useful for managing a message collection. These are listed in Table 8-2.
Table 8-2: Extra methods of the Message Collection datatype
Message Collection Method | Description |
---|---|
reverse: Nothing | Reverses the order of the messages in the collection |
sort by date : Nothing | Sorts the messages by their associated date and time values, from newest to oldest |
Many messages, pictures and media resources have location information associated with them. A location is implemented as a pair of geographical coordinates. However, web services exist for finding a place name near to the location, for pinpointing the location on a map, and for obtaining directions from one location to another.
A location can be created or described by using the methods of the locations resource. These methods are listed in Table 8-3.
Table 8-3: Methods of the locations service
Method | Description |
---|---|
locations → create location(latitude : Number, longitude : Number) : Location | Creates a new location from its coordinates |
locations → create location list : Location Collection | Creates an empty list of locations |
locations → describe location(location : Location) : String | Finds a name or an address for a location using Bing |
locations → search location(address : String, postal code : String, city : String, country : String) : Location | Looks up the coordinates of an address using Bing |
In addition to the methods provided by the locations service, location values can be obtained from several other sources. Here is a list of the possibilities.
Locations are closely associated with maps. The TouchDevelop API provides both a maps service and a Map datatype. Maps are provided through use of Bing. The methods of the maps service are listed in Table 8-4 and the methods of the Map datatype in Table 8-5.
Table 8-4: Methods of the maps service
Method | Description |
---|---|
maps→ create full map : Map | Creates a full screen Bing map |
maps → create map : Map | Creates a Bing map |
maps → directions(from : Location, to : Location, walking : Boolean) : Location Collection | Provides a point by point itinerary to get from the one location to another. If walking is true, the route is suitable for walking; otherwise a vehicle route is assumed |
maps → open directions(start search : String, start loc : Location, end search : String, end loc : Location) : Nothing | Opens the Bing map application to show the route from one point to another. The two end points can be specified by either a search term or a location. The search term should be “” if the location is to be used. |
maps → open map(center : Location, search : String, zoom : Number) : Nothing | Opens the Bing map application around a central point specified by either a search term or a location; zoom is 0 (close) to 1 (far) |
Table 8-5: Methods of the Map datatype
Map Method | Description |
---|---|
add line(locations : Location Collection, color : Color, thickness : Number) : Nothing | Fits a line through the list of locations, drawing the line with the given thickness and color |
add link(link : Link, background : Color, foreground : Color) : Nothing | Adds a link pushpin to the map at the location associated with the link value |
add message(msg : Message, background : Color, foreground : Color) : Nothing | Adds a message pushpin to the map at the location associated with the message value |
add picture(location : Location, picture : Picture, background : Color) : Nothing | Adds a picture pushpin to the map at the location associated with the picture value |
add place(place : Place, background : Color, foreground : Color) : Nothing | Adds a place pushpin to the map at the location associated with the place value |
add text(location : Location, text : String, background : Color, foreground : Color) : Nothing | Adds a text pushpin to the map at the specified location |
center : Location | Gets the map center location |
clear : Nothing | Removes all lines, pushpins and regions |
fill region(locations : Location Collection, fill : Color, stroke : Color, thickness : Number) : Nothing | Draws the edges around a region whose vertices are specified by the list of locations, and fills the region with a given color. |
set center(center : Location) : Nothing | Sets the map’s center |
set zoom(level : Number) : Nothing | Sets the map’s zoom level, ranging from 1 (whole earth displayed) to 21 (street level) |
view pushpins : Nothing | Changes the zoom and center so that all pushpins are visible; the map must be posted on the wall |
zoom : Number | Gets the current zoom level |
A small example of using locations and the Bing map service is provided by the script go to picture (/gpona). The entire script is reproduced below.
action main( )
// Picks a picture in the library and displays
// directions to the location where it was taken.
var pic := media → choose picture
var loc := pic → location
if loc → is invalid then
wall → prompt("This picture does not have location information.")
else
maps → open directions("", senses → current location, "", loc)
The Place datatype provides a wrapper for a location so that additional information can be attached to the location. There are both getter and setter methods for the different kinds of additional information. They are listed in the tables of Section C.37 in Appendix C. In addition to these methods, there the usual is invalid and post to wall methods and two more. They are check in, which is provided for Facebook interactions, and to string which creates a string representation of a place.
A TouchDevelop script can prepare an email message ready for transmission, but it does not actually send it. The following short script prepares a message:
var msg := social → create message(“The dinner party is tonight!”)
msg → set from(“your friendly host”)
msg → set to(“[email protected]”)
msg → set title(“Invitation reminder”)
msg → share(“email”)
When these commands are executed, the last one (the share method call) asks which mail account should be used (if more than one has been set up on the phone) and then invokes the phone’s email application. The message is not sent until a send button in that application is tapped.
Although the email application can be invoked to send a message, there is no API support for directly reading email with a TouchDevelop script.
A script can prepare for a phone call by setting up the number and transferring control to the phone’s software for making the call. This facility is provided by the phone resource in the API. The relevant method calls in the API are listed in Table 8-6.
Table 8-6: Methods for handling phone calls
Method | Description |
---|---|
phone → choose phone number: Link | Opens the phone’s contact list so that a phone number can be selected |
phone → dial phone number(number : String) : Nothing | Sets up a phone call with the provided number, but does not dial the number |
phone → save phone number(phone number : String) : Nothing | Opens the phone’s contact list to allow the number to added to an existing entry or to a new entry |
Some sample code to set up a phone call, ready for initiating the connection, is as follows:
var link := phone → choose phone number
phone → dial phone number( link → address)
It is not possible to write a script which answers an incoming phone call or which records an audio clip from a phone call.
TouchDevelop provides access to the Microsoft Tag service which generates two-dimensional barcodes for text messages and for URLs. These barcodes are square images which can be printed onto documents or publicity material. Most smart phones, whether a Windows phone or not, possess scanning software which enables a user to focus on the barcode with the phone’s camera and automatically display the text or visit the webpage.
The barcode generation methods are provided by the tags resource. Its two methods are listed in Table 8-7.
Table 8-7: Barcode generation methods
Method | Description |
---|---|
tags → tag text(text : String, size : Number, bw : Boolean) : Picture | Generates a barcode for the text (up to 1000 characters); size is the width and height of the picture in inches and must be in the range 0.75 to 5.0; if bw is true, the image is generated in black and white, otherwise color. |
tags → tag url(url : String, size : Number, bw : Boolean) : Picture | Generates a barcode which points at the supplied URL; size and bw have the same meanings as above. |
This sample code generates and displays a barcode:
var pic := tags → tag text(“TouchDevelop is cool!”, 1.0, false)
pic → post to wall
The result of running these two statements is shown in Figure 8-1 on the left. The result when the third argument is changed to true appears on the right. Both versions of the barcode work with scanning software.
Figure 8-1: Examples of 2D barcodes
SMS is an abbreviation for Short Message Service. It is a text messaging service provided by the phone company. It is normally used for sending a message from one cellphone to another cellphone, though some phone companies may provide additional methods for sending or receiving the messages. The original standard for SMS limited message bodies to be a maximum of 140 bytes. (The twitter social networking service has the same limit.) Longer messages are automatically broken up into a sequence of short messages.
The TouchDevelop API allows a script to generate an SMS message ready for transmission but it will not actually send it. The user has to perform one additional action.
A few lines of script to generate an SMS message and prepare it for transmission are as follows:
var msg := “Come right now, the pizza has arrived”
var recipient := “202 555 1234”
social → send sms( recipient, msg )
If that script is executed, the phone’s messaging software is activated and the phone displays the standard dialog for sending a SMS message, as shown in Figure 8-2.
Figure 8-2: Sending an SMS message
The Windows phone provides a calendar where each day’s schedule, comprised of various meetings or appointments, is recorded.
The phone’s calendar may be synchronized with one or more calendars held externally, such as a Windows Outlook calendar or a calendar of events on a social network site.
A TouchDevelop script has read-only access to the phone’s calendar and can retrieve all the appointments for a specific range of times. As a small example, the following statements will retrieve and display tomorrow’s appointments.
var start time := time → tomorrow
var end time := start time → add hours(24)
var appts := social → search appointments (start time, end time)
appts → post to wall
Note that social→search appointments is the only mechanism provided for accessing the calendar. Each appointment obtained from the calendar has several associated attributes. They may be accessed by using the methods listed in Table 8-8. (The two methods, invalid and post to wall, are omitted from the table.)
Table 8-8: Methods of the Appointment datatype
Appointment Method | Description |
---|---|
attendees : Contact Collection | Gets the list of attendees for the appointment |
details : String | Gets the details (body) of the appointment |
end time : DateTime | Gets the end time, if available |
is all day event : Boolean | Returns true if the appointment is flagged as being all day |
is private : Boolean | Returns true if the calendar entry is flagged as being private |
location : String | Returns location associated with the appointment |
organizer : Contact | Returns the organizer of the appointment, if available |
source : String | Returns the appointment’s source, i.e. which calendar or social network site it came from |
start time : DateTime | Gets the end time, if available |
status : String | Returns the user’s status for this appointment (free, tentative, busy or outofoffice) |
subject : String | Returns the appointment’s subject, if available |
Each contact contains several fields. All fields except for the name are optional. The values of these fields may be retrieved by using the access methods listed in first table given in Section C.7 of Appendix C. The values of nearly all these fields may be changed by using the methods listed in second table of that section.
When some part of the contact’s information has been changed, the updated contact may be saved back to the phone’s contact list by using the social→save contact method.
Table 8-9: Methods for accessing and creating contacts
Method | Description |
---|---|
social→choose contact : Contact | Allows user to select a contact from the phone’s contact list |
social→choose email : Link | Allows user to select a contact’s email from the phone’s contact list |
social→create contact( nickname : String) : Contact | Creates a new contact with only the nickname field specified |
social→save contact( contact : Contact): Nothing | Saves a new contact in the phone’s contact list |
social→search contacts( prefix : String) : Contact Collection | Searches for contacts whose names begin with the supplied prefix |
3.133.134.17