Top Up Prev Next Bottom Contents Index Search

3.3 I/O Classes

Star programmers often need to communicate with the user. The most flexible way to do this is to build a customized, window-based interface, as described in "Using Tcl/Tk" on page 5-1. Often, however, it is sufficient to plot some data or to just construct strings and output them to files or to the standard output1. To do the latter, use the classes pt_ifstream and pt_ofstream, which are derived from the standard C++ stream classes ifstream and ofstream, respectively. More sophisticated output can be obtained with the XGraph class, the histogram classes, and classes that interface to Tk for generating animated, interactive displays. All of these classes are summarized in this section.

3.3.1 Extended input and output stream classes

The pt_ofstream class is used in the Printer star on page 2-28. Include the header file pt_fstream.h. The pt_ofstream constructor is invoked in the setup method with the call to new. It would not do to invoke it in the constructor for the star, since the fileName state would not have been initialized. Notice that the setup method reclaims the memory allocated in previous runs (or previous invocations of the setup method) before creating a new pt_ofstream object. Notice that we are not using a wrapup method to reclaim the memory, since this method is not invoked if an error occurs during a run.

The classes pt_ifstream and pt_ofstream are only a slight extension of the classes ifstream and ofstream. They add the following features:

3.3.2 Generating graphs using the XGraph class

The XGraph class provides an interface to the pxgraph program, used for plotting data on an X window system display. The pxgraph program and all its options are documented in the User's Manual. An example of the output from pxgraph is shown in figure 3-1
.The most useful methods of the class are summarized in table 3-2.

Using the XGraph class involves an invocation of the initialize method, some number of invocations of the addPoint method, followed by an invocation of the terminate method. Multiple data sets (currently up to 64) may be plotted together. They will each be given a distinctive color and/or line pattern. Within each data set, it is possible to break the connecting lines between points by calling the newTrace method.

3.3.3 Classes for displaying animated bar graphs

The BarGraph class creates a Tk window that displays a bar graph that can be modified dynamically, while a simulation runs. An example with 12 data sets and 8 bars per data set is shown in figure
3-2. The most useful methods of the class are summarized in table 3-3. This class is directly usable only by stars linked into a pigi process, not to stars linked into the interpreter, ptcl. The reason for this is that ptcl does not have the Tk code linked into it. Correspondingly, the class definition source code is in $PTOLEMY/src/pigilib, rather than the more usual $PTOLEMY/src/kernel.

3.3.4 Collecting statistics using the histogram classes

The Histogram class constructs a histogram of data supplied. The XHistogram class also constructs a histogram, but then plots it using the pxgraph program. An example of such a plot is shown in figure 3-3.
The most useful methods of both classes are summarized in tables 3-4 and 3-5.

The Histogram class counts the number of occurrences of data values that fall within each of a number of bins. Each bin represents a range of numbers. All bins have the same width, and the center of each bin will be an integer multiple of this width. Bin number 0 is always that with the smallest center. Bins are added if new data arrives that does not fit within any of the existing bins. The getData method is used to read out the contents of a bin. If you start with bin number 0, and proceed until getData returns FALSE, you will have read all the bins.

Top Up Prev Next Bottom Contents Index Search

1 Note that when users run pigi, the standard output may appear on a window that is buried. The
-console option to pigi helps, in that it creates a specific window for the standard output and other interactions with the user. The standard output is much more useful with ptcl, the textual interpreter.

Copyright © 1990-1997, University of California. All rights reserved.