The VisualizationApp class

The data structure and algorithm visualizations are implemented as instances of the VisualizationApp class. This class provides the common framework of the applications: the canvas at the top, an operations area at the bottom, and a code visualization area at the lower right of the window.

The VisualizationApp class is complex. Keeping a long description of all its features and quirks in this wiki page would be difficult to do. Instead, people who wish to understand its functions are better off running some of the existing instances of the app and reviewing the source code. Here, we'll keep some notes on the overall strategy and hard-to-find features.

Class Hierarchy

Here's an example class hierarchy for the Array app:

      object
        |
   Visualization    (Visualization.py)
        |
  VisualizationApp  (VisualizationApp.py)
        |
   SortingBase      (SortingBase.py)
        |
      Array         (Array.py)

The Visualization class implements the overall window with a canvas for drawing. It has many methods for drawing things, moving them around on the canvas, and manipulating their attributes. It implements an Animation (enumerated) class for the different modes of animation: running, paused, stepping, and stopped. While it defines these animation states, and provides the basic methods testing and changing the animation mode, most of the operational controls that enable users to change the animation are in VisualizationApp and its subclasses. The other things you'll find in Visualization.py are utilities for managing Tk widgets.

The VisualizationApp class implements the buttons, sliders, text entry, message widgets, and code display that appears at the bottom of the application window. It's basically the "control panel" for the visualization. All the visualization apps have one or more operations that get launched with a button. Each operation can take 0-3 user provided arguments. The subclasses of VisualizationApp add their operations to "empty" VisualizationApp when constructed, declaring how many arguments they require and providing hint strings about what the arguments do.

Most VisualizationApps include a 3-button animation control to play/pause, step, or stop the animation. These are implemented as image buttons.

The SortingBase and Array classes are where the code specific to that data structure and its algorithms lives. The structure of those classes is defined according to what needs to be shown among related data structures.

Special features of VisualizationApp applications

• Typically users launch operations by clicking or tapping one of the buttons. The operations that require arguments are grouped together next to some text entry widgets. The operations that require arguments are only enabled when some argument text is present and the animations are stopped. Operations that don't require arguments, including the 3-button animation control, are grouped to the right.
• Users can move the keyboard focus between the text entry areas and the (enabled) buttons using the Tab and Shift-Tab keys. Pressing the Space-bar when the keyboard focus is on a button will press the button. The 3-button animation controls also can be invoked this way allowing the Space-bar to pause/play, or advance individual steps in the program
• Pressing the Enter or Return key when the keyboard focus is in an argument text entry area will run the most recently run operation that used that argument. There is no most-recently-run operation when the program starts, but after filling in an entry and clicking, say, the Insert button, users can edit what is in the entry area and press Enter to re-run the Insert operation on a new value.
• The animation "steps" of an operation are determined by the code that is highlighted in the code text area. Each time the highlighted code changes, the animation will pause until the user presses the step advance button. This includes when highlighting is removed (as a function call exits).
• Normally, operations are launched with the animation mode RUNNING. You may also launch them in STEP mode by holding the Shift key down when clicking the operation button (or pressing the Space-bar with focus on the operation button). Launching in step mode means you don't need to quickly navigate to the step button and press it after launching the operation, if you want to pause at the first step.
• Developers may wish to launch the Python debugger at some point while the program is running. Instead of restarting the whole program and using the -m pdb command line option, you can launch the Python debugger by holding the Control and Shift keys when clicking an operation button. In addition to the modifier keys, a file named .debug.pyc must exist in the directory where the program was launched (the current working directory of the process). The check for this special file's presence ensures that users won't accidentally launch the debugger. If the file is not there, the debugger is not started. Note the debugger is launched the next time the system "waits" as part of an animation (so choose a button that causes some animation to occur). This is kind of clunky, since keyboard input needs to be switched between the Tk application window and the window where the program was launched from the command line, but at least it allows starting the debugger without a complete relaunch. If you've already hit an error that caused a stack trace, however, there may not be a way to get into the debugger and see what's going on.