Abstract
A TouchDevelop script usually needs to interact with the user. While input via a microphone and output via speakers built into, or connected to, the device are certainly possibilities, a touchscreen or a screen plus a mouse is almost always used for input and output. In TouchDevelop, the screen is known as the wall. The API provides many ways in which a script can access the wall.
You have full access to this open access chapter, Download chapter PDF
Keywords
These keywords were added by machine and not by the authors. This process is experimental and the keywords may be updated as the learning algorithm improves.
A TouchDevelop script usually needs to interact with the user. While input via a microphone and output via speakers built into, or connected to, the device are certainly possibilities, a touchscreen or a screen plus a mouse is almost always used for input and output. In TouchDevelop, the screen is known as the wall. The API provides many ways in which a script can access the wall.
3.1 Output – the writing on the wall
3.1.1 Output of simple values
Every datatype in TouchDevelop provides a method named post to wall. If that method is called, some representation of the value is displayed. Here are some simple examples.
action main()
(1/3) → post to wall
123 → post to wall
("hello" || " there") → post to wall
(11>11) → post to wall
The code produces a result like that shown in Figure 3-1 on the left side. Note that the output is apparently displayed in reverse order. That is because the default is for each new output item to be inserted at the top of the screen, pushing previously generated output further down. The default is a good one if it is desired that the user can see the most recent item without having to scroll down.
To display a value in a manner which stands out prominently on the screen, a TextBox value can be used. The text can be displayed in any color, with any size font, against any background color. A simple example of using a TextBox to display a string is shown in Figure 3-2. The script is shown on the left and the result of running it is shown on the right.
3.1.2 Direction of Output
The default direction of output on the screen can be changed so that items are displayed from top-to-bottom. To do so, make the method call:
wall →set reversed(true)
The following sample script should make the effect clear.
action main()
(1/3)→post to wall
123→post to wall
wall →set reversed(true)
("hello" || " there") →post to wall
(11>11) →post to wall
The result of running the script is shown in Figure 3-1 on the right side. Comparison of the two snapshots shows that the call affected all output on the screen – not just the output generated after the call was made.
In summary, the effect of making the call with an argument of true is to cause existing output on the screen to be reordered if necessary, so that the oldest output is at the top and the newest output is at the bottom. Future calls to
post to wall
cause the new output to be added at the bottom. Making the call
wall →set reversed(false)
reorders the output again so that the oldest output is at the bottom and the newest is at the top, then subsequent calls to post to wall will again cause output to be inserted at the top of the screen.
3.1.3 Output of composite values
Displaying a composite value such as one with the DateTime or Vector3 type produces an appropriately formatted result. Displaying a collection of values produces a list of items on the screen, each element formatted in the appropriate manner for the element’s datatype.
Figure 3-3 gives a few examples of composite values being displayed.
3.1.4 Output of media values
Each media value is displayed on the screen in a manner appropriate for the datatype. In the case of a Song or a Song Album value, there is also a play button displayed. Tapping that play button causes the song or the song album to be played.
A summary of what is displayed for each datatype is given in Table 3-1.
3.1.5 Output of social values
Each value managed by the social API is displayed in a manner appropriate for the datatype. The Contact and Link values include buttons which can be tapped to initiate a phone call or send a message.
A summary of what is displayed for each datatype is given in Table 3-2.
3.1.6 Output of web values
There are several datatypes specifically associated with web access. Values of five of these types are displayed on the wall according to Table 3-3.
3.3 Updating the wall’s content
Each call of post to wall adds a new item on the screen. However it is frequently the case that we wish to leave the number of items unchanged and simply alter the value of one of them. The simplest, least sophisticated and least efficient way to achieve that effect would be to invoke
wall → clear
and then re-display all the items with their new values.
However, TouchDevelop provides some alternatives which should be preferred.
3.3.1 Updatable textbox
For the display of text which needs to be changed while the script is executing, a textbox provides an easy-to-use mechanism. Figure 3-5 shows a simple script which displays a line of text on the screen and then changes the text when the page button at the bottom is tapped.
The call to the set text method of the textbox causes the string displayed on the screen to be updated immediately. It is also possible to change the size of the text and the colors used in the textbox on the fly. Note that if the same textbox value has been posted to the wall more than once, then the set text method will cause all of those occurrences on the wall to be updated.
3.3.2 Updating a board display
For updating more sophisticated displays of information on the screen, an instance of the Board datatype is normally used. Pictures, text messages and shapes can all be drawn on the board as sprites. Each sprite can have its position, orientation or content changed individually. Then a call to the update on wall method of the board causes a rendering of the board on the screen to be immediately updated. Although the main usage of the Board datatype was intended to be for implementing games, it is useful in any situation where information displayed on the screen needs to be changed.
A re-implementation of the previous example where a board is used instead is shown in Figure 3-6. The use of a board and sprites provides much greater flexibility because the positions and orientations of the items on the screen can also be updated.
3.4 Events on the touchscreen
3.4.1 Tap wall events
A script can receive input via tap events on the screen. There is one event type for nearly every kind of value which can be displayed on the screen. A full list is provided in Table 3-5.
If one of these values is displayed on the screen, then tapping the value will cause the corresponding event to be executed. The tapped item is passed as a parameter to the event. The normal parameter passing rules are used, implying that a copy of the value is passed if the item is a value type and a reference to the value is passed if the item is a reference type. A trivial script which shows the use of tap events to select a string is shown in Figure 3-7.
3.4.2 Tap board events
Although it is easy to display values on the screen and associate ‘tap wall’ events with them, there is very little control over where the values are positioned. To achieve full control over placement, it is necessary to display the values as sprites on an instance of the Board datatype. If the script displays the board with its sprites on the screen, then tapping or swiping or dragging one of the sprites will trigger an event that can be captured by the script.
A trivial script which brightens or darkens the color of a solid rectangle when buttons are tapped is shown in Figure 3-8.
Simply defining a variable with a datatype of Board or Sprite or Sprite Set in the data section of the script causes new event types to be made available. In the case of the script shown in Figure 3-7, the data section contains three sprites named rectangle, Lighter and Darker, it contains controls which has type Sprite Set, and board which has type Board.
The existence of these globally visible data variables creates 14 events with these names:
-
tap sprite: rectangle, swipe sprite: rectangle, drag sprite: rectangle
-
tap sprite: Lighter, swipe sprite: Lighter, drag sprite: Lighter
-
tap sprite: Darker, swipe sprite: Darker, drag sprite: Darker
-
tap sprite in controls, swipe sprite in controls, drag sprite in controls
-
tap board: board, swipe board: board
For sprites, the event names have the pattern tap/swipe/drag sprite: xxx where xxx is the name of the sprite. For sprite sets, the names have the pattern tap/swipe/drag sprite in YYY where YYY is the name of the set. For boards, the names have the pattern tap/swipe board: ZZZ where ZZZ is the name of the board. Parameters passed to each event identify which sprite was touched (when it is a sprite set event), the coordinates of the sprite on the board, and the extent of a swiping or a dragging action.
Note that there are yet more events associated with the Board datatype which have not been listed here, including the possibility of tapping anywhere on the board (not just on a sprite) and obtaining the coordinates of where the screen was tapped.
3.5 Pushing and popping pages
Some scripts may need to display information temporarily and then have it disappear. Or, perhaps, there is a need to input some extra information from the user but it is undesirable to disrupt what has already been displayed on the screen. The solution, for situations like these, is to create a brand new wall on which information is displayed and input is requested, then have that wall disappear and have the original wall re-displayed.
The general facility takes the form of a stack of pages. Each page corresponds to an instance of the wall.
The following command creates a new empty wall.
wall → push new page
The script can then proceed to display information or prompt for input on this new wall. Afterwards, the following command
wall → pop page
will delete that new wall and revert to displaying the previous version.
Some additional methods associated with the wall API are wall→pages which returns the stack of pages as a collection, and wall→current page which gets the current page.
3.6 Titles and subtitles
The output from a script can be beautified by displaying a title at the top of the screen. If appropriate, a subtitle may be displayed too. A few lines of code which illustrate the features are as follows.
wall → set title(“The wall’s title”)
wall → set subtitle(“The subtitle”)
“First line of output” → post to wall
“Second line of output” → post to wall
The result of running this code appears in Figure 3-9. Note that the capitalization of the title and subtitle has been changed; they have both been converted to lowercase.
3.7 Wall buttons
Buttons in the form of simple icons may be displayed at the bottom of the screen. These are page buttons. Tapping a button triggers an event which can be captured in the script. The icons are predefined and have names. The names are as follows.
"add", "back", "cancel", "check", "close", "delete", "download",
"edit", "favs.addto", "favs", "feature.camera", "feature.email",
"feature.search", "feature.settings", "feature.video", "folder",
"minus", "new", "next", "questionmark", "refresh", "save",
"share", "stop", "sync", "transport.ff", "transport.pause",
"transport.play", "transport.rew", "upload"
This list of names can be generated by executing the following statement.
wall → button icon names → post to wall
A possible statement to generate a button is the following.
wall → add button( “questionmark”, “help?” )
Executing that statement causes the bar at the bottom of the screen to contain a ‘question mark’ icon with the label “help?” as shown in Figure 3-10.
There is space for several page buttons at the bottom of the screen. Therefore the event triggered when a page button is tapped has a parameter which enables the button to be identified, that parameter being the string used as the label. The following code shows how an event can distinguish between different possibilities for the button.
event tap wall Page Button(item: Page Button)
if (item → icon → equals(“help?”) then
▷show help info
else
if (item → icon → equals(“cancel”) then
time → stop
else
// do nothing
The methods provided for the Page Button datatype are listed in Table 3-6.
3.8 On-demand creation of output
Some scripts may need to generate a lot of output which the user will need to scroll through. It may be a waste of processing time (and perhaps battery charge) if all that output is generated at once. A better approach would be to create chunks of output only as the user scrolls to view the part of the screen where the output would be displayed.
An event empty space on wall is triggered whenever there is space on the wall for displaying new output. There will be space when the user scrolls to the end of the displayed output.
Author information
Authors and Affiliations
Rights and permissions
Open Access This chapter is licensed under the terms of the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (http://creativecommons.org/licenses/by-nc-nd/4.0/), which permits any noncommercial use, sharing, distribution and reproduction in any medium or format, as long as you give appropriate credit to the original author(s) and the source, provide a link to the Creative Commons licence and indicate if you modified the licensed material. You do not have permission under this licence to share adapted material derived from this chapter or parts of it.
The images or other third party material in this chapter are included in the chapter’s Creative Commons licence, unless indicated otherwise in a credit line to the material. If material is not included in the chapter’s Creative Commons licence and your intended use is not permitted by statutory regulation or exceeds the permitted use, you will need to obtain permission directly from the copyright holder.
Copyright information
© 2013 R. Nigel Horspool
About this chapter
Cite this chapter
Horspool, R.N., Tillmann, N. (2013). The Wall – using the screen. In: TouchDevelop: Programming on the Go. Apress, Berkeley, CA. https://doi.org/10.1007/978-1-4302-6137-7_3
Download citation
DOI: https://doi.org/10.1007/978-1-4302-6137-7_3
Published:
Publisher Name: Apress, Berkeley, CA
Print ISBN: 978-1-4302-6136-0
Online ISBN: 978-1-4302-6137-7
eBook Packages: Professional and Applied ComputingApress Access BooksProfessional and Applied Computing (R0)