turtlestitch/help/manual/en/snap-manual.tex

\documentclass{report}

\input{../common/defs.tex}

\begin{document}

\title{\Snap{} Reference Manual}
\author{Brian Harvey \and Jens M\"{o}nig}
\date{}

\maketitle

\tableofcontents

\chapter*{}
\section*{Acknowledgements}

We have been extremely lucky in our mentors. Jens cut his teeth in the company of the Smalltalk pioneers: Alan Kay, Dan Ingalls, and the rest of the gang who invented personal computing and object oriented programming in the great days of Xerox PARC. He worked with John Maloney, of the MIT Scratch Team, who developed the Morphic graphics framework that's still at the heart of \Snap{}. The brilliant design of Scratch, from the Lifelong Kindergarten Group at the MIT Media Lab, is crucial to \Snap{}.

\textbf{\emph{Our earlier version, BYOB, was a direct modification of the Scratch source code. \Snap{} is a complete rewrite, but its code structure and its user interface remain deeply indebted to Scratch. And the Scratch Team, who could have seen us as rivals, have been entirely supportive and welcoming to us.}}

Brian grew up at the MIT and Stanford Artificial Intelligence Labs, learning from Lisp inventor John McCarthy, Scheme inventors Gerald~J. Sussman and Guy Steele, and the authors of the world's best computer science book, \textit{Structure and Interpretation of Computer Programs}, Hal Abelson and Gerald~J. Sussman with Julie Sussman, among many other heroes of computer science.

\textbf{\emph{In the glory days of the MIT Logo Lab, we used to say, ``Logo is Lisp disguised as BASIC.'' Now, with its first class procedures, lexical scope, and first class continuations, \Snap{} is Scheme disguised as Scratch.}}

We have been fortunate to get to know an amazing group of brilliant middle school (!\@) and high school students through the Scratch Advanced Topics forum, several of whom have contributed code to \Snap{}: Kartik Chandra, Nathan Dinsmore, Connor Hudson, and Ian Reynolds. Many more have contributed ideas and alpha-testing bug reports. UC Berkeley students who've contributed code include Michael Ball, Achal Dave, Kyle Hotchkiss, Ivan Motyashov, and Yuan Yuan. Contributors of translations are too numerous to list here, but they're in the ``About\ldots'' box in \Snap{} itself. This work was supported in part by the National Science Foundation grant 1143566, and in part by MioSoft.

\clearpage

\begin{center}
\bf \Huge \Snap{} Reference Manual \\
\huge Version 4.0
\vspace{40pt}
\end{center}

\Snap{} (formerly BYOB) is an extended reimplementation of Scratch (\url{http://scratch.mit.edu}) that allows you to Build Your Own Blocks. It also features first class lists, first class procedures, and continuations. These added capabilities make it suitable for a serious introduction to computer science for high school or college students.  To run \Snap{}, open a browser window and connect to either \url{http://snap.berkeley.edu/run} to start with a minimal set of blocks or \url{http://snap.berkeley.edu/init} to load a small set of additional blocks (a little slower startup, but recommended for convenience and assumed in this manual).

\clearpage

\chapter{Blocks, Scripts, and Sprites}

This chapter describes the \Snap{} features inherited from Scratch; experienced Scratch users can skip to section~\ref{sec:nesting-sprites}.

\Snap{} is a programming language---a notation in which you can tell a computer what you want it to do. Unlike most programming languages, though, \Snap{} is a visual language; instead of writing a program using the keyboard, the \Snap{} programmer uses the same drag-and-drop interface familiar to computer users.

Start \Snap{}. You should see the following arrangement of regions in the window:

\begin{center}
\includegraphics[width=\textwidth]{window-regions}
\end{center}

(The proportions of these areas may be different, depending on the size and shape of your browser window.)

A \Snap{} program consists of one or more \emph{scripts}, each of which is made of \emph{blocks}. Here's a typical script:

\label{fig:typical-script}
\bigpic{typical-script}

The five blocks that make up this script have three different colors, corresponding to three of the eight \emph{palettes} in which blocks can be found. The palette area at the left edge of the window shows one palette at a time, chosen with the eight buttons just above the palette area. In this script, the gold blocks are from the Control palette; the green block is from the Pen palette; and the blue blocks are from the Motion palette. A script is assembled by dragging blocks from a palette into the \emph{scripting area} in the middle part of the window. Blocks snap together (hence the name \Snap{} for the language) when you drag a block so that its indentation is near the tab of the one above it:

\bigpic{snapping-blocks}

The white horizontal line is a signal that if you let go of the green block it will snap into the tab of the gold one.

\subsection{Hat Blocks and Command Blocks}

At the top of the script is a \emph{hat} block, which indicates when the script should be carried out. Hat block names typically start with the word ``\code{when}''; in this example, the script should be run when the green flag near the right end of the \Snap{} tool bar is clicked. (The \Snap{} tool bar is part of the \Snap{} window, not the same as the browser's or operating system's menu bar.) A script isn't required to have a hat block, but if not, then the script will be run only if the user clicks on the script itself. A script can't have more than one hat block, and the hat block can be used only at the top of the script; its distinctive shape is meant to remind you of that.

The other blocks in this script are \emph{command} blocks. Each command block corresponds to an action that \Snap{} already knows how to carry out. For example, the block \inlinepic{move-10-steps} tells the sprite (the arrowhead shape on the \emph{stage} at the right end of the window) to move ten steps (a step is a very small unit of distance) in the direction in which the arrowhead is pointing. We'll see shortly that there can be more than one sprite, and that each sprite has its own scripts. Also, a sprite doesn't have to look like an arrowhead, but can have any picture as a costume. The shape of the \code{move} block is meant to remind you of a Lego\texttrademark{} brick; a script is a stack of blocks. (The word ``block'' denotes both the graphical shape on the screen and the procedure, the action, that the block carries out.)

The number~$10$ in the \code{move} block above is called an \emph{input} to the block. By clicking on the white oval, you can type any number in place of the $10$. The sample script on page~\pageref{fig:typical-script} uses $100$ as the input value. We'll see later that inputs can have non-oval shapes that accept values other than numbers. We'll also see that you can compute input values, instead of typing a particular value into the oval. A block can have more than one input slot. For example, the \code{glide} block located about halfway down the Motion palette has three inputs.

Most command blocks have that brick shape, but some, like the \code{repeat} block in the sample script, are \emph{C-shaped}. Most C-shaped blocks are found in the Control palette. The slot inside the C shape is a special kind of input slot that accepts a \emph{script} as the input. In the sample script, the \code{repeat} block has two inputs: the number $4$ and the script

\bigpic{typical-script-inner}

\section{Sprites and Parallelism}

Just below the stage is the ``new sprite'' button \inlinepic{../common/btn-new-sprite}. Click the button to add a new sprite to the stage. The new sprite will appear in a random position on the stage, facing in a random direction, with a random color.

Each sprite has its own scripts. To see the scripts for a particular sprite in the scripting area, click on the picture of that sprite in the \emph{sprite corral} in the bottom right corner of the window. Try putting one of the following scripts in each sprite's scripting area:

\begin{figure}[H]
\begin{minipage}{0.5\textwidth}
\centering
\includegraphics[scale=\defaultGraphicsScale]{sprites-and-parallelism-1}
\end{minipage}%
\begin{minipage}{0.5\textwidth}
\centering
\includegraphics[scale=\defaultGraphicsScale]{sprites-and-parallelism-2}
\end{minipage}
\end{figure}

When you click the green flag \inlinepic{../common/btn-start}, you should see one sprite rotate while the other moves back and forth. This experiment illustrates the way different scripts can run in parallel. The turning and the moving happen together. Parallelism can be seen with multiple scripts of a single sprite also. Try this example:

\begin{figure}[H]
\begin{minipage}{0.5\textwidth}
\centering
\includegraphics[scale=\defaultGraphicsScale]{sprites-and-parallelism-3}
\end{minipage}%
\begin{minipage}{0.5\textwidth}
\centering
\includegraphics[scale=\defaultGraphicsScale]{sprites-and-parallelism-4}
\end{minipage}
\end{figure}

When you press the space key, the sprite should turn forever in a circle, because the \code{move} and \code{turn} blocks are run in parallel. (To stop the program, click the red stop sign \inlinepic{../common/btn-stop} at the right end of the tool bar.)

\subsection{Costumes and Sounds}

To change the appearance of a sprite, import a new \emph{costume} for it. There are three ways to do this. First, select the desired sprite in the sprite corral. Then, one way is to click on the file icon \inlinepic{../common/btn-file} in the tool bar, then choose the ``\code{Costumes\ldots}'' menu item. You will see a list of costumes from the public media library, and can choose one. The second way, for a costume stored on your own computer, is too click on the file icon and choose the ``\code{Import\ldots}'' menu item. You can then select a file in any picture format (PNG, JPEG, etc.) supported by your browser. The third way is quicker if the file you want is visible on the desktop: Just drag the file onto the \Snap{} window. In any of these cases, the scripting area will be replaced by something like this:

\bigpic{scripting-area-with-additional-costume}

Just above this part of the window is a set of three tabs: Scripts, Costumes, and Sounds. You'll see that the Costumes tab is now selected. In this view, the sprite's \emph{wardrobe}, you can choose whether the sprite should wear its Turtle costume or its Alonzo costume. (Alonzo, the \Snap{} mascot, is named after Alonzo Church, a mathematician who invented the idea of procedures as data, the most important way in which \Snap{} is different from Scratch.) You can give a sprite as many costumes as you like, and then choose which it will wear either by clicking in its wardrobe or by using the \inlinepic{switch-to-costume-turtle} or \inlinepic{next-costume} block in a script. (Every costume has a number as well as a name. The \code{next costume} block selects the next costume by number; after the highest-numbered costume it switches to costume~1. The Turtle, costume~0, is never chosen by \code{next costume}.) The Turtle costume is the only one that changes color to match a change in the sprite's pen color.

In addition to its costumes, a sprite can have \emph{sounds}; the equivalent for sounds of the sprite's wardrobe is called its \emph{jukebox}. Sound files can be imported in any format (WAV, OGG, MP3, etc.) supported by your browser. Two blocks accomplish the task of playing sounds. If you would like a script to continue running while the sound is playing, use the block \inlinepic{play-sound-help}. In contrast, you can use the \inlinepic{play-sound-help-until-done} block to wait for the sound's completion before continuing the rest of the script.

\subsection{Inter-Sprite Communication with Broadcast}

Earlier we saw an example of two sprites moving at the same time. In a more interesting program, though, the sprites on stage will interact to tell a story, play a game, etc. Often one sprite will have to tell another sprite to run a script. Here's a simple example:

\begin{figure}[H]
\begin{minipage}{0.5\textwidth}
\centering
\includegraphics[scale=0.4]{../common/boy1-walking}
\end{minipage}%
\begin{minipage}{0.5\textwidth}
\centering
\reflectbox{\includegraphics[scale=0.3]{../common/dog2-c}}
\end{minipage}

\vspace{3ex}
\begin{minipage}[t]{0.5\textwidth}
\centering
\vspace{0pt} % REALLY align to top
\includegraphics[scale=\defaultGraphicsScale]{inter-sprite-communication-1}
\end{minipage}%
\begin{minipage}[t]{0.5\textwidth}
\centering
\vspace{0pt} % REALLY align to top
\includegraphics[scale=\defaultGraphicsScale]{inter-sprite-communication-2}
\end{minipage}
\end{figure}

In the \inlinepic{broadcast-bark-and-wait} block, the word ``bark'' is just an arbitrary name I made up. When you click on the downward arrowhead in that input slot, one of the choices (the only choice, the first time) is ``\code{new},'' which then prompts you to enter a name for the new broadcast. When this block is run, the chosen message is sent to \emph{every} sprite, which is why the block is called ``broadcast.'' In this program, though, only one sprite has a script to run when that broadcast is sent, namely the dog. Because the boy's script uses \code{broadcast and wait} rather than just \code{broadcast}, the boy doesn't go on to his next \code{say} block until the dog's script finishes. That's why the two sprites take turns talking, instead of both talking at once.

Notice, by the way, that the \code{say} block's first input slot is rectangular rather than oval. This means the input can be any text string, not only a number. In the text input slots, a space character is shown as a brown dot, so that you can count the number of spaces between words, and in particular you can tell the difference between an empty slot and one containing spaces. The brown dots are \emph{not} shown on the stage when the block is run.

The stage has its own scripting area. It can be selected by clicking on the Stage icon at the left of the sprite corral. Unlike a sprite, though, the stage can't move. Instead of costumes, it has \emph{backgrounds}: pictures that fill the entire stage area. The sprites appear in front of the current background. In a complicated project, it's often convenient to use a script in the stage's scripting area as the overall director of the action.

\section{Nesting Sprites: Anchors and Parts}
\label{nesting-sprites}

Sometimes it's desirable to make a sort of ``super-sprite'' composed of pieces that can move together but can also be separately articulated. The classic example is a person's body made up of a torso, limbs, and a head. \Snap{} allows one sprite to be designated as the \emph{anchor} of the combined shape, with other sprites as its \emph{parts}. To set up sprite nesting, drag the sprite corral icon of a \emph{part} sprite onto the stage display (not the sprite corral icon!) of the desired \emph{anchor} sprite.

Sprite nesting is shown in the sprite corral icons of both anchors and parts:

\bigpic{nested-sprites-in-corral}

In this illustration, it is desired to animate Alonzo's arm. (The arm has been colored green in this picture to make the relationship of the two sprites clearer, but in a real project they'd be the same color, probably.) Sprite1, representing Alonzo's body, is the anchor; Sprite2 is the arm. The icon for the anchor shows small images of up to three attached parts at the bottom. The icon for each part shows a small image of the anchor in its top left corner, and a \emph{synchronous rotation flag} in the top right corner. In its initial setting, as shown above, it means that the when the anchor sprite rotates, the part sprite also rotates as well as revolving around the anchor. When clicked, it changes from a circular arrow to a straight arrow, and indicates that when the anchor sprite rotates, the part sprite revolves around it, but does not rotate, keeping its original orientation. (The part can also be rotated separately, using its \code{turn} blocks.) Any change in the position or size of the anchor is always extended to its parts.

\begin{figure}[H]
\centering
\includegraphics[scale=\defaultGraphicsScale]{hand-waving-command}%
\hspace{2em}%
\includegraphics[scale=0.4]{../common/alonzo-waving}
\end{figure}

\section{Reporter Blocks and Expressions}

So far, we've used two kinds of blocks: hat blocks and command blocks. Another kind is the \emph{reporter} block, which has an oval shape: \inlinereporterpic{x-position}. It's called a ``reporter'' because when it's run, instead of carrying out an action, it reports a value that can be used as an input to another block. If you drag a reporter into the scripting area by itself and click on it, the value it reports will appear in a speech balloon next to the block:

\bigpic{x-position-returns-a-number}

When you drag a reporter block over another block's input slot, a white ``halo'' appears around that input slot, analogous to the white line that appears when snapping command blocks together. Here's a simple script that uses a reporter block:

\begin{figure}[H]
\centering
\includegraphics[scale=\defaultGraphicsScale]{example-script-that-uses-a-reporter}%
\hspace{2em}%
\includegraphics{../common/turtle-says-its-position}
\end{figure}

Here the \code{x position} reporter provides the first input to the \code{say} block. (The sprite's X position is its horizontal position, how far left (negative values) or right (positive values) it is compared to the center of the stage. Similarly, the Y position is measured vertically, in steps above (positive) or below (negative) the center.)

You can do arithmetic using reporters in the Operators palette: 

\begin{figure}[H]
\centering
\includegraphics[scale=\defaultGraphicsScale]{using-reporters-for-arithmetic}%
\hspace{2em}%
\includegraphics{../common/turtle-says-its-rounded-position}
\end{figure}

The \code{round} block rounds $35.3905\ldots$ to $35$, and the \code{+}~block adds $100$ to that. (By the way, the \code{round} block is in the Operators palette, just like~\code{+}, but in this script it's a lighter color with black lettering because \Snap{} alternates light and dark versions of the palette colors when a block is nested inside another block from the same palette:

\bigpic{zebra-coloring}

This aid to readability is called \emph{zebra coloring}.) A reporter block with its inputs, maybe including other reporter blocks, such as \inlinepic{round-x-position-plus-100}, is called an \emph{expression}.

\section{Predicates and Conditional Evaluation}

Most reporters report either a number, like \inlinereporterpic{plus}, or a text string, like \inlinereporterpic{join-hello-world}. A \emph{predicate} is a special kind of reporter that always reports \code{true} or \code{false}. Predicates have a hexagonal shape:

\bigpic{mouse-down}

The special shape is a reminder that predicates don't generally make sense in an input slot of blocks that are expecting a number or text. You wouldn't say \inlinepic{move-mouse-down-steps}, although (as you can see from the picture) \Snap{} lets you do it if you really want. Instead, you normally use predicates in special hexagonal input slots like this one:

\bigpic{if}

The C-shaped \code{if} block runs its input script if (and only if) the expression in its hexagonal input reports \code{true}.

\bigpic{predicates-and-conditional-evaluation-1}

A really useful block in animations runs its input script \emph{repeatedly} until a predicate is satisfied:

\bigpic{predicates-and-conditional-evaluation-2}

If, while working on a project, you want to omit temporarily some commands in a script, but you don't want to forget where they belong, you can say

\bigpic{predicates-and-conditional-evaluation-3}

Sometimes you want to take the same action whether some condition is true or false, but with a different input value. For this purpose you can use the \emph{reporter} \code{if} block:\footnote{\onehalfspacing If you don't see it in the Control palette, click on the File button \inlinepic{../common/btn-file} in the Tool Bar and choose ``Import tools.''}

\bigpic{predicates-and-conditional-evaluation-4}

\section{Variables}

Try this script:\footnote{The \code{for} block is also in the tools library; choose ``\code{Import tools}'' from the file menu if you don't have it in the Control palette.}

\bigpic{squiral-script}

The input to the \code{move} block is an orange oval. To get it there, drag the orange oval that's part of the \code{for} block:

\bigpic{variable-dragging}

The orange oval is a \emph{variable}: a symbol that represents a value. (I took this screenshot before changing the second number input to the \code{for} block from the default $10$ to $200$, and before dragging in a \code{turn} block.) \code{For} runs its script input repeatedly, just like \code{repeat}, but before each repetition it sets the variable \code{i} to a number starting with its first numeric input, adding $1$ for each repetition, until it reaches the second numeric input. In this case, there will be $200$ repetitions, first with $\code{i}=1$, then with $\code{i}=2$, then $3$, and so on until $\code{i}=200$ for the final repetition. The result is that each \code{move} draws a longer and longer line segment, and that's why the picture you see is a kind of spiral. (If you try again with a turn of $90$ degrees instead of $92$, you'll see why this picture is called a ``squiral.'')

The variable \code{i} is created by the \code{for} block, and it can only be used in the script inside the block's C-slot. (By the way, if you don't like the name \code{i}, you can change it by clicking on the orange oval without dragging it, which will pop up a dialog window in which you can enter a different name:

\subsection{Global Variables}
\subsection{Script Variables}
\section{Etcetera}
\chapter{Saving and Loading Projects and Media}
\section{Local Storage}
\subsection{Localstore}
\subsection{XML Export}
\section{Cloud Storage}
\section{Loading Saved Projects}
\chapter{Building a Block}
\section{Simple Blocks}
\subsection{Custom Blocks with Inputs}
\section{Recursion}
\section{Block Libraries}
\chapter{First Class Lists}
\section{The list Block}
\section{Lists of Lists}
\section{Functional and Imperative List Programming}
\section{Higher Order List Operations and Rings}
\chapter{Typed Inputs}
\section{Scratch's Type Notation}
\section{The \Snap{} Input Type Dialog}
\subsection{Procedure Types}
\subsection{Pulldown inputs}
\subsection{Input variants}
\subsection{Prototype Hints}
\subsection{Title Text and Symbols}
\chapter{Procedures as Data}
\section{Call and Run}
\subsection{Call/Run with inputs}
\subsection{Variables in Ring Slots}
\section{Writing Higher Order Procedures}
\subsection{Recursive Calls to Multiple-Input Blocks}
\section{Formal Parameters}
\section{Procedures as Data}
\section{Special Forms}
\subsection{Special Forms in Scratch}
\chapter{Object Oriented Programming}
\section{Local State with Script Variables}
\section{Messages and Dispatch Procedures}
\section{Inheritance via Delegation}
\section{An Implementation of Prototyping OOP}
\chapter{The Outside World}
\section{The World Wide Web}
\section{Hardware Devices}
\section{Date and Time}
\chapter{Continuations}
\section{Continuation Passing Style}
\section{Call/Run w/Continuation}
\subsection{Nonlocal exit}
\chapter{User Interface Elements}
\section{Tool Bar Features}
\subsection{The \Snap{} Logo Menu}
\subsection{The File Menu}
\subsection{The Cloud Menu}
\subsection{The Settings Menu}
\subsection{Stage Resizing Buttons}
\subsection{Project Control Buttons}
\section{The Palette Area}
\subsection{Context Menus for Palette Blocks}
\subsection{Context Menu for the Palette Background}
\section{The Scripting Area}
\subsection{Sprite Appearance and Behavior Controls}
\subsection{Scripting Area Tabs}
\subsection{Scripts and Blocks Within Scripts}
\subsection{Scripting Area Background Context Menu}
\subsection{Controls in the Costumes Tab}
\subsection{The Paint Editor}
\subsection{Controls in the Sounds Tab}
\section{Controls on the Stage}
\section{The Sprite Corral and Sprite Creation Buttons}

\end{document}