CHAPTER 7 BASIC GRAPHICS, EVENTS AND GLOBAL DATA

VERSION 1 BASIC GRAPHICS, EVENTS AND GLOBAL DATA CHAPTER 7 BASIC GRAPHICS, EVENTS, AND GLOBAL DATA In this chapter, the graphics features of TouchDevelop are introduced and then combined with scripts when an action, such as turning the phone around, is performed. That topic leads very naturally to scripts which access the sensors built into a Windows phone. Providing code to be executed whenever an event is triggered then leads naturally into scripts which use global data items. 7.1 GRAPHICS FACILITIES 7.2 EVENTS AND SENSORS 7.3 GLOBAL DATA 7.1 GRAPHICS FACILITIES The phone s screen is composed of many dots which can be illuminated in different colors. All characters, all lines, all pictures seen on the screen are displayed as patterns of these dots where the phone s software has selected the color and intensity for each dot. Graphics programming is, in effect, a matter of writing code to set the color and intensity of each dot in an area of the screen. Anyone who has had some previous experience with graphics programming can skip the following brief introduction to the subject. After that introduction, we will move on to the facilities for graphics programming provided in TouchDevelop. COMPUTER GRAPHICS TERMINOLOGY Each dot on the screen is known as a PICTURE ELEMENT and that term is usually abbreviated to PIXEL or to PEL. We will use the term pixel. The TouchDevelop API for setting the pixel s color and intensity uses a triple of three numbers. In most graphics software, these three numbers are one-byte integers in the range 0 to 255, and they specify the intensity of the red, green and blue components of the color separately. However TouchDevelop scales these numbers to be in the range 0.0 to 1.0. The triple of three numbers is commonly called an RGB VALUE. An integer value of 0 means that the color component has zero intensity and a value of 1.0 means maximum intensity. Some typical combinations of integers as RGB values in TouchDevelop are: 73

BASIC GRAPHICS, EVENTS AND GLOBAL DATA VERSION 1 (0.0, 0.0, 0.0) black (0.0, 1.0, 0.0) green (1.0, 1.0, 1.0) white (0.0, 0.0, 1.0) blue (0.5, 0.5, 0.5) gray (1.0, 1.0, 0.0) yellow (1.0, 0,0, 0.0) red (1.0, 0.0, 1.0) purple The pixels on the screen are arranged in a rectangular grid. Each pixel has a coordinate position in this grid given by an x value and a y value. The x values start at 0 and increase from left-to-right across the screen; the y values start at 0 and increase from top to bottom down the screen. (Note that y-axis values grow in the opposite direction to how you would normally draw a graph.) The size of the displayable area on the screen is exactly 480 pixels wide by 800 pixels high for a Windows 7 phone. This means that the x and y coordinates can range from (0,0) in the top-left corner to (479,799) in the bottom right corner, as shown on the right. A TRIVIAL GRAPHICS PROGRAM Figure 7.1: Trivial graphics script A short graphics program was used as an example in Chapter 2. It begins by creating a new Picture value and assigning it to variable pic. It is an array of pixel values 480 wide and 300 wide. The width is the maximum which can be displayed on a Windows phone. The height of 300 is much less than the maximum 800 allowed for the phone. The pixels are initialized to be white. The second statement draws a solid rectangle in the Picture array. The top left corner of the rectangle is at (10,10) i.e. 10 pixels in from the left and 10 pixels down from the top. The width of the rectangle is 200 pixels and its height is 100 pixels. The fifth argument of 0 means that we do not want to rotate the rectangle before drawing it onto the picture object. (To be more precise, it is rotated by 0 degrees.) The last parameter specified the color to use for the rectangle. The colors red value is equivalent to using (1.0,0.0,0.0) as the RGB value for the pixels, and is much more readable. 74

VERSION 1 BASIC GRAPHICS, EVENTS AND GLOBAL DATA The third statement draws a solid ellipse inside the Picture array. One has to imagine that the ellipse fits inside a rectangle whose top left corner is at the coordinates (270,190). The width and height of that ellipse are set to be 200 and 100 respectively. Again, we rotate that containing rectangle by 0 degrees. The color for the ellipse is chosen to be blue. The fourth statement draws the four sides of a rectangle at approximately the extreme edges of the Picture array. The thickness of the lines used for the four sides has been set at 3 pixels. The color of the lines is whatever has been chosen in the phone s settings as the accent color; for the screen shot shown below, that accent color is magenta. The fifth statement draws a line from the bottom left corner up towards the top right corner, and the thickness of the line is chosen to be 3 pixels wide. Finally the last statement sends the picture to be displayed on the wall. A screen shot of our program s output appears in Figure 7.2. Figure 7.2: Output from trivial graphics script MORE DETAILS ABOUT PICTURES Any photograph held on the phone or downloadable from the web is held as a Picture value too. This means that you can write scripts which transform the photograph or overwrite them in some way. Anything is possible given enough effort spent developing a script. Just to introduce you to the possibilities, Figure 7.3 shows a script which first prompts the user to enter a string (to use as the value of the parameter msg), then asks the user to select a photograph from amongst those on the phone, overprints a text message diagonally across the picture from the bottom left to the top right and finally displays the picture. 75

BASIC GRAPHICS, EVENTS AND GLOBAL DATA VERSION 1 Figure 7.3: Script to Overprint a Photograph The script has to make some calculations to determine a suitable size for the characters in the message being displayed and what angle to draw the text at, if we want that text to be along the diagonal. The character size calculation is very approximate (as not all characters are the same width) and the formula used here was found by trial and error. The angle of the diagonal is found by computing the arctangent of height/width for the image. The math function atan2 provided in the TouchDevelop API performs that calculation but returns the result in radians. The angle argument to the draw text method requires the angle in degrees however, so a call to the rad to deg conversion function is needed too. Finally a minus sign is needed in front because we are drawing the text in a direction which ascends from left to right which corresponds to an anticlockwise rotation, whereas the draw text method normally performs a clockwise rotation on the text. A sample output from this script is shown in Figure 7.4. Note that the photograph selected for display in Figure 7.4 is too large to fit on the screen. Its width is 800 pixels yet the screen itself is only 480 pixels wide. The post to wall method scaled the image by a factor of 480/800 in both dimensions so that it would fit without having to scroll the image from side to side. 76

VERSION 1 BASIC GRAPHICS, EVENTS AND GLOBAL DATA Figure 7.4: Output from the Overprint Photograph Script Table 7.1 provides a description of most of the methods available for the Picture datatype. Table 7.1: Useful Picture Methods Method Description Operations on the Image as a Whole height: Number Returns the picture height in pixels width: Number Returns the picture width in pixels invert: Picture Inverts the R,G,B color components of every pixel clear(col:color): Nothing Sets all pixels to color col clone: Picture Returns a duplicate of the picture post to wall: Nothing Displays the picture on the screen, resizing it if necessary to fit within the maximum width of 480 pixels and a maximum height of 800 pixels. crop(x:number, y:number, w:number, Crops the picture to have width w and height h, selecting h:number): Nothing a subimage whose top left corner is at position x,y blend(other:picture, x:number, Overwrites this picture with picture, other, putting its top y:number, angle:number, left corner at position x,y and rotating about that corner alpha:number): Nothing by angle degrees in a clockwise direction; alpha is used as the transparency of all pixels in the other picture. resize(w:number, h:number): Nothing Scales the picture to have width w and height h 77

BASIC GRAPHICS, EVENTS AND GLOBAL DATA VERSION 1 Shape Drawing Methods draw ellipse(x:number, y:number, Draws the largest ellipse which fits inside a rectangle w:number, h:number, angle:number, with width w and height h; the top left corner of the rectangle is at position x,y; the rectangle is rotated about the c:color, th:number): Nothing top left corner by angle degrees in a clockwise direction; the line has a thickness of th pixels and is drawn in color c. draw line(x1:number, y1:number, Draws a line from position x1,y1 to position x2,y2; the x2:number, y2:number, c:color, line has thickness of th pixels and is drawn in color c. th:number): Nothing draw rect(x:number, y:number, w:number, h:number, angle:number, c:color, th:number): Nothing draw text(x:number, y:number, txt:string, fs:number, angle:number, c:color): Nothing fill ellipse(x:number, y:number, w:number, h:number, angle:number, c:color): Number fill rect(x:number, y:number, w:number, h:number, angle:number, c:color): Nothing pixel(x:number, y:number): Color set pixel(x:number, y:number, c:color): Nothing Draws a rectangle whose top left corner is at position x,y; it has width w and height h; the rectangle is rotated about the top left corner by angle degrees in a clockwise direction; the line has a thickness of th pixels and is drawn in color c. Draws text as pixels in color c on the picture; the top left of the first character is at position x,y; the size used for the characters is fs; the text is rotated by angle degrees about the x,y position. Like draw ellipse except that the ellipse is drawn as a solid object (not as a line surrounding an elliptically shaped area) Like draw rect except that the rectangle is drawn as a solid object (not as four lines surrounding a rectangular area) Access to Pixels Returns the color of the pixel at position x,y Sets the pixel at position x,y to have color c WORKING WITH PIXELS As explained earlier, each pixel has a color and an intensity determined by a triple of three numbers, the RGB values. There is an additional number attached to each pixel which comes into play if we want to superimpose one picture on top of another. This additional integer is known as the AL- PHA value and controls the degree of transparency of the pixel. Suppose that we want to overlay part of picture A with picture B. Should the pixels from Picture B replace the pixels of A? This is usually known as knockout overprinting. It means that you cannot see through the pixels from picture B and see any remnants of picture A in the overlaid area. However, perhaps the colors of the B picture pixels should be blended with the pixels of the A picture so 78

VERSION 1 BASIC GRAPHICS, EVENTS AND GLOBAL DATA that you can see both the A and B images combined? The alpha values associated with the B pixels determine their degrees of transparency. If alpha is 1.0, the pixel is fully opaque and the B pixel will knockout (replace) the A pixel. If alpha is 0.0, the pixel is fully transparent and no trace of picture B will be seen when overlaid on picture A. Intermediate values for alpha result in partial transparency for the B picture. Given a picture referenced by variable pic, the pixel at coordinates x,y can be retrieved by a statement like the following. var col := pic pixel(x,y) The value so obtained has the datatype Color. That value can be decomposed into its A (alpha), R, G and B components with statements like these: var red component := col R var green component := col G var blue component := col B var alpha component := col A We can change these color components in any way we like, as long as the values stay in the 0.0 to 1.0 range, and then recombine them to create a new color which can be stored back into the picture as a changed pixel value. For example, the following code inverts the color intensities, giving an effect similar to creating a color negative image: red component := 1.0 - red component green component := 1.0 - green component blue component := 1.0 - blue component col := colors from argb(alpha component, red component, green component, blue component) pic set pixel(x, y, col) However that particular sequence of statements would rarely be needed because the Picture datatype has an invert method which performs exactly that operation to every pixel in the image. Many of the methods used for working with colors and individual pixels are listed below in Table 7.2. They are accessed from the service named colors. For example, var y := colors yellow declares variable y to have the type Color and initializes it to the yellow color. 79

BASIC GRAPHICS, EVENTS AND GLOBAL DATA VERSION 1 Table 7.2: Methods provided by the colors Service Method Description Composing and Decomposing Color Values from argb(alpha:number, r:number, Constructs a color from the alpha and RGB values, which g:number, b:number): Color must all be in the range 0.0 to 1.0 from rgb(r:number, g:number, Constructs a color from the RGB values provided; the alpha component is set to 1.0 (totally opaque) b:number): Color Access to the Phone s Theme Colors accent: Color background: Color foreground: Color chrome: Color subtle: Color Returns the accent, background, foreground, chrome and subtle (light gray) colors selected for the phone s theme in its Settings menu Standard Colors black: Color blue: Color brown: Color cyan: Color dark gray: Color gray: Color green: Color light gray: Color magenta: Color orange: Color purple: Color red: Color white: Color yellow: Color Obtain standard colors by their usual names. Obtaining Special Colors random: Color linear gradient(c1:color, c2:color, alpha:number): Color Returns a random (opaque) color Computes a color in between c1 and c2 where c2 overlays c1 with the specified alpha factor for transparency. 7.2 EVENTS AND SENSORS The Windows phone contains a number of sensors, such as an accelerometer, which can trigger events that get passed on to the TouchDevelop script. In addition, a script which implements an interactive game needs to respond when the user taps certain items on the screen, and those taps can also trigger events. 80

VERSION 1 BASIC GRAPHICS, EVENTS AND GLOBAL DATA The various kinds of events recognized by TouchDevelop are listed in Table 7.3. Sensors are covered in some more detail in Chapter 8 as well as more examples which use events. The events grouped in the Game Playing category will be covered only in Chapter 9. Table 7.3: Events in TouchDevelop Scripts Event shake phone face up phone face down phone portrait phone landscape left phone landscape right active song changed camera button pressed camera button half pressed camera button released tap wall XX(item: XX) gameloop player state changed tap board: b(x,y) swipe: board: b(x, y, dx, dy) tap sprite in s(sprite, index, x, y) swipe sprite in s(sprite, index, x, y, delta x, delta y) drag sprite in s(sprite, index, x, y, delta x, delta y) Description Phone Movement Events Triggered when the phone is shaken Triggered when the phone is turned so that it is face up Triggered when the phone is turned so that it is face down Triggered when the phone is turned so the screen in portrait mode (such as when the phone is vertical) Triggered when the phone is turned so that its left side is facing down Triggered when the phone is turned so that its right side is facing down Media Events The names of these events describe the events Tap Wall Events XX represents any of the TouchDevelop datatypes, such as String or Location or Number Map, etc. The event is triggered when a user taps a display of a value of type XX on the wall (i.e. the screen). The value is passed as a parameter to the event. Game Playing Events An event which is triggered by a timer approximately every 50ms Triggered when a global data item named b with type Board is tapped; x and y are the coordinates of the tap. Similar to tap board, except that it is triggered by a swiping action starting at position x,y and with a distance vector dx,dy Sprites will be covered in Chapter 9. (They are graphics objects which can move around on the screen.) 81

BASIC GRAPHICS, EVENTS AND GLOBAL DATA VERSION 1 EXAMPLE EVENT HANDLING SCRIPT: PHONE ORIENTATION A script can optionally include code which is executed whenever a particular kind of event happens. As a simple example, let us construct a script which displays the words Portrait and Landscape in large letters on the screen according to the phone s current orientation. To reuse some of the graphics code covered earlier in this chapter, we will create Picture values and write text with suitable orientations for display into the pictures and display the pictures in the event code. The code for the main action and all three events is shown in Figure 7.5. As you can see, the main action has got absolutely nothing to do. Even though control returns from the main action, the script stays active waiting for events. The only way to stop this script is to tap the phone back button (or to tap the Windows button to exit from TouchDevelop completely). Figure 7.5: Code for the Orientation Event Script Two of the screen displays produced by this script as the phone is rotated are shown below in Figure 7.6. 82

VERSION 1 BASIC GRAPHICS, EVENTS AND GLOBAL DATA Figure 7.6: Some Output Displayed by the Orientation Script 7.3 GLOBAL DATA Sometimes an event in a script needs to save information which is used later by an action or by another invocation of an event (perhaps the same event, perhaps a different event). Where can such information be saved? The only reasonable answer is to use a GLOBAL DATA VARIABLE. We have already seen some example programs which use global data items. Let us look at one more. EXAMPLE SCRIPT: A PEDOMETER If you carry your Windows phone with you when jogging or walking briskly, the phone s sensors should trigger a SHAKE event each time you take one step. We can therefore write a simple script which records how many steps you take, incrementing a counter each time the shake event occurs. With a little more coding, we can compute the number of steps per minute. By using access to the phone s GPS location, we can also compute your average speed. However that programming feature does not need to use any event code, so we will omit that feature in this version of the program. When we begin creating the Pedometer script, TouchDevelop provides a default action named main and that is all. No events and no global data items exist for the script. We could tap the plus button to the right of the data icon to create a global data item for the number of steps taken, but let s do it another way. We can use the promote to global data item form of refactoring explained in Chapter 6. The first thing we do in creating the script is to edit the code for the main action. We add the statement var steps := 0 83

BASIC GRAPHICS, EVENTS AND GLOBAL DATA VERSION 1 where we have declared and initialized steps as a local variable. Now, by selecting this declaration line for editing and selecting the left-hand side variable, we can promote it to a global data item named steps. Similarly, we should declare var start time := time now and then promote the start time local variable to be the global data item start time. We need to remember the time at which the script was started so that we can determine the elapsed time, needed for computing the number of steps per minute. The code for the Pedometer program is shown in Figure 7.6. The local variable elapsed is the time since the script was started, measured in seconds. It is probably unnecessary to check that elapsed has a non-zero value, but it is good programming practice to avoid division by zero. To compute the walking or jogging rate as the number of steps per minute, we need to multiply the steps per second by 60. Otherwise, the script should be easy to follow. Figure 7.6: The Pedometer Script Output from the script while it is running looks similar to that shown below. This does not look very professional! Accuracy to 15 decimal places is just a bit excessive. Fortunately it takes only one extra line of code to reduce the number of digits after to the decimal point to a more reasonable number. Let s pick one digit. If we insert either this line of code: 84

VERSION 1 BASIC GRAPHICS, EVENTS AND GLOBAL DATA rate := math round(10*rate)/10 or this line of code rate := math round with precision(rate,1) after the line declaring and initializing the local variable rate, we will get just one digit to the right of the decimal point. The output produced by the program now looks like this: Now, why did we have to initialize steps to zero in the main action? Why did it not just start with the value 0 when we begin running the script? This is explained in the next subsection. PERSISTENCE OF GLOBAL DATA VALUES The very first time you use a script after it has been installed, the global data items will have initial values which are 0 for Number values, false for Boolean values, an empty string for String values, and date / time combination from long ago for DateTime values. For all other datatypes, the global data item has the special INVALID value. It may be necessary for the script to check and initialize global data variables to take account of first time use of a script. The is invalid method is useful for checking the data items which start off with an invalid value. When the script is run a second time or a third time or, the global data items still have the same values as they had at the end of the previous run. In the terminology of programming languages, we say that the values of the global data items PERSIST from one run to the next on your phone. Persistence is a highly useful feature because it allows your scripts to accumulate information over many runs. (In a misuse of the English language, programmers often say that a variable is persisted if it retains its value from one run to the next.) If you do not want to reuse a value from the previous run of the script, as is the case with the Pedometer example, the script should re-initialize the global data items in whichever of its actions will be invoked when the script is started. (This is likely to be every action which is not flagged as private.) 85

BASIC GRAPHICS, EVENTS AND GLOBAL DATA VERSION 1 86