Visualizing Structures

If you print a pointer or a structure (or a structure-valued expression) in a window, a structure visualizer appears.

Figure 5-17 shows an example of a structure visualizer.

Figure 5-17 Structure Visualizer

The structure you specified appears inside a box; this is referred to as a node. The node shows the fields in the structure and their values. If the structure contains pointers, small boxes appear next to them; they are referred to as buttons. Left-click on a node to select it. Use the up and down arrow keys to move between buttons of a selected node.

You can perform various actions within a structure visualizer, as described below.

Expanding Pointers

You can expand scalar pointers in a structure to generate new nodes. (You cannot expand a pointer to a parallel variable.)

To expand a single pointer:

• With a mouse - Left-click on a button to expand the pointer. For example, clicking on the button next to the nav field in Figure 5-17 changes the visualizer as shown in Figure 5-18.

• From the keyboard - Use the right arrow key to expand and visit the node pointed to by the current button. If the node is already expanded, pressing the right arrow key simply visits the node. Use the left arrow key to visit the parent of a selected node.

Figure 5-18 Structure Visualizer, With One Pointer Expanded

To expand all pointers in a node:

• With the mouse - Double-click or Shift-left-click on the node.

• From the keyboard - Press the Shift key along with the right arrow key.

• From the Options menu - Click on Expand. The cursor turns into a target; move the cursor to the node you are interested in and left-click.

To recursively expand all pointers from the selected node on down:

• With the mouse - Triple-click or Control-left-click on the node.

• From the keyboard - Press the Control key and the right arrow key.

• From the Options menu - Click on Expand All. The cursor turns into a target; move the cursor to the node you are interested in and left-click.

Panning and Zooming

You can left-click and drag through the data navigator or the display window to pan through the data, just as you can with visualizers; see " Using the Data Navigator in a Visualizer" and " Using the Display Window in a Visualizer".

You can also "zoom" in and out on the data by left-clicking on the Zoom arrows. Click on the down arrow to zoom out and see a bird's-eye view of the structure; click on the up arrow to get a closeup. Figure 5-19 shows part of a complicated structure visualizer after zooming out.

Left-click on a node in a zoomed-out structure visualizer to pop up a window showing the full contents of the node.

Figure 5-19 Zooming Out in a Structure Visualizer

The selected node is centered in the display window whenever you zoom in or out.

Deleting Nodes

To delete a node (except the root node):

• With the mouse - Middle-click on a node (except the root node).

• From the Options menu - Click on Delete. The cursor turns into a target; move the cursor to the node you want to delete and left-click.

Deleting a node also deletes its children (if any).

More About Pointers in Structures

Note the following about pointers in structure visualizers:

• Null pointers--have "ground" symbols next to them.

• If you have previously expanded a pointer, it has an arrow next to its button; you cannot expand the pointer again. (This prevents infinite loops on circular data structures.)

• A pointer containing a bad address has an X drawn over its button.

Augmenting the Displayed Information

You may provide a special function for each of your data types that makes additional information available to Prism. This enables Prism to more accurately display the contents of structures with that data type.

For C or C++ union types, you may identify which member of the union is valid. For a pointer within a structure, you may specify that the pointer's target is an array of elements, rather than a single element, and you may further specify the length of the array.

You must embed these specifications within a special function that is compiled and linked with your program being debugged. The function has the following form:

void prism_define_typename (typename *ptr);

where typename is the tag name of one of your structure data types. Thus, you can define one such function for each of your data types. When Prism displays a variable of this type, it checks whether an augmentation function is defined in the program. If so, Prism calls the function, passing a pointer to the instance of the structure being displayed. Your function may then look at the instance to choose valid union members and to size dynamic arrays.

You communicate this information back to Prism by calling the following, defined in prism.h:

void prism_add_array(char *member_name, int len);

This call specifies that the pointer named member_name points to an array of length len. The pointer's name, member_name, is the name of one of the members of the structure, as found in the structure's C (or C++) declaration. The results are undefined if member_name is not a pointer.

void prism_add_union(char *name, char
*valid_member);

This call specifies that the member named name is of type union, and of all the members of this union, only valid_member is to be displayed. Both name and valid_member are names as found in the C or C++ declarations of structs or unions.

Assume that data in the declaration below is a dynamic array:

 struct Vector {
      int len;
      int *data;
   };

The function you write looks like this:

#include "prism.h"
     void prism_define_Vector(struct
Vector *v)
   {
     prism_add_array("data",
v->len);
   }

Assume that the member type discriminates the union value in this example:

 enum Type {INT, DOUBLE};
     struct Value {
      enum Type type;
       union
{
        int
i;
        double
d;
      } value;
    };

The function you write would look like this:

#include "prism.h"
    void prism_define_Value(struct Value
*val)
     {
        if
(val->type == INT)
            prism_add_union("value",
"i");
        else
        prism_add_union("value",
"d");
     }

There are no restrictions on the number or order of calls to prism_add_union and prism_add_array.

Updating and Closing a Structure Visualizer

Left-click on Update in the File menu to update a structure visualizer. When you do this, the root node is re-read; Prism attempts to expand the same nodes that are currently expanded. (The same thing happens if you re-print an existing structure visualizer.)

Left-click on Close in the File menu to close the structure visualizer.