Viz Mode Tutorial

The layout of the Viz mode user interface

To get started with CodeSkulptor Viz mode, visit the default demo page. This version of CodeSkulptor, shown top screenshot, includes the standard CodeSkulptor controls as well as one extra button that is circled in red. These standard controls allow you to run Python programs in CodeSkulptor as usual. To activate Viz mode, you simply click the circled button with the wrench icon. This action updates the layout of CodeSkulptor's controls as shown in the bottom screenshot.

Activating Viz mode spawns four new buttons circled in red in the bottom screenshot. To use these buttons, first click the "Run" button on the left to run your Python program. In Viz mode, CodeSkulptor will record the sequence of Python statements that were evaluated during execution of your program to form a traceof the execution of the program. These four buttons now allow the user to navigate through this trace. Once the user has selected a particular statement in the trace, Viz mode displays information about the state of the program immediately prior to the execution of the selected statement.

This state information is displayed on the right hand side of the window, which has been split into two smaller panes. The top pane corresponds to the original console and now includes not only the output of print statements, but also a log of the events created during execution of the program. The bottom pane contains the state diagram. This diagram displays the values of the variables of your Python program (its state) prior to execution of the selected statement.

With this overview under our belt, let's explore Viz mode.

Navigating the trace of a simple program

As our first example, let's run this program, consisting of a sequence of print statements, in Viz mode. Click the "Wrench" button to active Viz mode and then click "Run" to execute the program. The top screenshot below shows the output of running the program in Viz mode. Observe that the console now includes the output of the five print statements as well as two extra lines labelled "Begin" and "End".

The primary output of running a program in Viz mode is a statement-by-statement trace of the execution of the program. The four navigation buttons to the left of the wrench allow the user to navigate this trace and visualize the state of the program at any point during its execution. After the initial execution of the program, the "End" label is highlighted in the console to indicate that Viz mode is currently displaying the state of the program at the end of its execution.

To visualize the state of the program at another point during its execution, click the "Prev Statement" button to move backwards in the program trace. Note the various statements in the Python code are now highlighted in blue. The lower screenshot below shows that output of the program prior to the execution of the highlighted print "Step 3" statement in line 9. Observe that the console displays only the output from lines 7 and 8. Clicking "Next Statement" selects the next statement in the execution trace, line 10, and adds the output from line 9 to the console.

Navigation using breakpoints

To navigate to the beginning or end of your trace, you may click on the blue "Begin" or "End" lines in the console. To navigate to a particular line in your trace (say line 9 in the example), click on the line number in the left hand margin (marked by the red rectangle in the example) to set a breakpoint. The breakpoint will then be highlighted by a red rectangle. Clicking the "Prev Breakpoint/ Prev Event" or "Next Breakpoint/ Next Event" buttons navigate in the appropriate direction to the next breakpoint in the trace.

Next, let's proceed to a slightly more interesting program that uses global variables and conditionals.

Visualizing the state of a simple program

The previous example only printed output to the console. More interesting programs create variables and use the values of these variables to control the behavior of the program. Viz mode provides the ability to visualize the values of these variables as you navigate through the execution trace for your program.

As a simple example, load this program. Running this program produces the output shown in the top screenshot below. The lower right pane of the screenshot contains a state diagram that displays the values of the four global variables associated with the program. The console shows the output produced by the program.

The statement navigation buttons allow us to navigate the execution trace of the program and visualize the value of these global variables at any location in the trace. The state diagram in the bottom screenshot shows the values of these variables prior to the execution of the highlighted assignment statement in line 17. Note that the state diagram displays only the three variables that have been defined at that point in the trace.

Experiment with uncommenting the alternate values for name and age in lines 11 and 12. You will need to rerun the program to generate a new trace. Observe that values of name and age are updated in the state diagram when the assignment statements in lines 11 and 12 are executed.

As the next part of our tutorial, let's examine the trace of a program that includes a function definition and call.

Visualizing function evaluation via frames

The previous example considered programs consisting of assignments and conditionals. Viz mode also supports visualizing the evaluation of function calls. As a simple example, load this program. The top screenshot below shows the final state of this program that uses a function name_tag() to automate the construction of a name tag string. Observe that the state diagram includes two global variables joe_tag and scott_tag as well as a global variable name_tag that refers to a function that takes two parameters.

In Viz mode, these three variable are grouped together to form a single frame that corresponds to the set of all global variables. This frame is visualized via the blue box labelled "Global variables". (Note that these frames displayed in the state diagram and the frame created by simplegui.create_frame() are different constructs.)

During the execution of the program, Python evaluates two calls to the function name_tag() in lines 12 and 13. As you navigate through the execution trace created in Viz mode, Python generates a separate set of local variables during each evaluation of name_tag() that include first_name, last_name and tag. The bottom screenshot shows the state of the program during the evaluation of the second call to name_tag prior to returning the value of tag. Viz mode has created a second frame, labelled "name_tag", that displays the current values of these local variables.

In cases where one function may itself call another function in its definition, the frames may stack more deeply. To follow the execution trace of such a program, use the "Next Statement" and "Prev Statement" buttons to examine the structure of the trace in detail. Remember that the function names attached to the top of the frames provide a convenient way to keep track of which function calls are being evaluated.

As the next part of our tutorial, we consider an example of visualizing a reference diagram

Visualizing lists via reference diagrams

One of the main capabilities of Viz mode is visualizing the structure of lists using reference diagrams. To try out this capability, load this program. The screenshot below shows the final state of a short program that creates the three lists a, b and c. Experiment with running this program in Viz mode and then step through the resulting trace. Note how the state diagram includes the lists (visualized as yellow boxes containing sequences of values) and references to these lists (visualized as arrows).

The variable a is initialized to be a list that contains the values [2, 9, 0]. The variable b is then assigned the value of a which is itself a reference to the list [2, 9, 0]. Statement 13 then updates the last entry in the list referenced by a to have the value 10. Note that this assignment mutates both a and b as reflected by the output from the print statement in line 11. Next, line 16 creates a copy of the mutated list [2, 9, 10] using the list operation and then assigns a reference to this new list to c. Observe that the assignment in line 17 only mutates the new copied list referred to by c. This behavior is reflected in the output of line 18.

Viz mode is capable of visualizing more complicated list structures. As the size of the state diagram increases, scroll bars are added to the state diagram to allow the user to examine the relevant part of the diagram. As the next part of our tutorial, we consider an example of a simple program with classes.

Visualizing classes and objects

Viz mode also supports the visualization of class definitions and class instances. To experiment with this capability, load this program. The screenshot below shows the final state of a short program that creates several instances of the class Instructors. Note that the state diagram includes a visualization of the structure of the Instructor class including all of its associated methods.

In this example, the Instructor class has been used to create two instances of the class prior to the execution of line 20. The variable instructor1 contains a reference to one Instructor object while the variable instructor2contains a reference to a second Instructor object. In line 20, the program creates a second reference to the first Instructor object via simple assignment. In line 21, the program mutates the second Instructor object so its name field is now "John".

For the next part of our tutorial, we consider event-driven programs. We begin with a simple example involving buttons and input fields.

Firing button/input events and the event log

The previous examples in this tutorial all consisted of standard Python programs that did not incorporate events. Viz mode also supports visualization of interactive Python programs. As a first example of visualizing the behavior of an event-driven program, load this program that prints a user-entered message when a button is clicked. The top screenshot below shows the state of this program after the "Run" button has been clicked, but prior to the firing of any events. Note that the initial value for the variable message is the string "This message is boring!".

The second screenshot shows the final state of the execution trace after the user has fired three events by clicking the "Print message" button, entering the string "Bad message" into the input field and clicking the "Print message" button again. Note the value of the global variable message is now the string "Bad message".

You can use the scroll bar in the console to examine the entire event log. Note that it is interspersed with the text output associated with each event. You may navigate the trace of this program using the "Prev Event" and "Next Event" buttons as well as clicking directly on the entries in the event log. Firing a new event appends the trace for that event to the end of the current trace and resets the current location in the trace to its end. As a result, there is no need to rerun the program when you wish to add new events to the event log. Simply fire the event by clicking the button or entering input in the input field.

As the next part of our tutorial, we consider an example of an event-driven program that draws on the canvas.

Firing draw/timer events

In event-driven programs, some events such as buttons clicks, mouse clicks and keyboard presses are always fired manually by the user. However, two kinds of events are fired automatically by the browser: draw events and timer events. During standard execution of an event-driven program, these events are often fired at a rate that makes debugging a program by inserting print statements into the handlers for these events difficult. Having the draw handler fire at 60 times per second generates a blizzard of output in the console.

In Viz mode, both draw events and timer events can only be fired by the user manually. This approach allows the user fine-grained control over the order in which events associated with the program are fired. To illustrate this approach, load and run this example program that increments a global variable using a timer and draws the resulting number on the canvas.

The top screenshot shows the final state of the execution trace before any events are fired. Note that the canvas is blank since no draw events have been fired. Also, the global variable counter has its initial value zero. The second screenshot shows the final state of the program after three events have been manually fired by the user: a draw event, a timer event, and a draw event. Note the global variable counter now has value one while the canvas displays the result of calling draw_text with this value of the counter.

The user can fire more events by clicking the draw and timer buttons and can then navigate the resulting trace using the statement and event navigation buttons. Note the timer button activates a pop-up menu to accommodate multiple timers. For draw events involving multiple statements in the draw function, the user can visualize the painting of the canvas by stepping through the trace of the draw function, statement by statement. The canvas is cleared at the start of each draw event and the result of each statement in the draw function is added to the canvas incrementally as the user navigates through the draw function.

One particularly useful approach to understanding the behavior of an event-driven program is to fire a sequence of events and then examine the global state of the program via the state diagram after each event using the "Next Event" and "Prev Event" buttons. Our final example illustrates firing keyboard events.

Firing mouse/keyboard events

In Viz mode, both mouse events and keyboard events are fired manually by the user. Firing a mouse event in Viz mode simply entails clicking on the canvas. When firing keyboard events in Viz mode, slightly more care is involved. For a keyboard event to be recorded in the event log, the CodeSkulptor frame must be currently selected. This example program echoes a sequence of key presses on the canvas.

In the screenshot below, the user has fired six events: press the "a" key, click "draw" button, press the "b" key, click "draw" button", press the "c" key and then clicked the "draw" button. Note that the canvas at the end of the execution trace displays "ABC".