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 output¹. 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:

First, certain special file names are recognized as arguments to the constructor or to the open method. These file names are < cin>, < cout>, < cerr>, or < clog> (the angle brackets must be part of the string), then the corresponding standard stream of the same name is used for input (pt_ifstream) or output (pt_ofstream). In addition, C standard I/O fans can specify < stdin>, < stdout>, or < stderr>.
Second, the Ptolemy expandPathName (see table 3-7 on page 3-8) is applied to the filename before it is opened, permitting it to start with ~user or $VAR.
Finally, if a failure occurs when the file is opened, Error::abortRun is called with an appropriate error message, including the Unix error condition. These classes can be used for binary character data as well as ASCII.

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.

¹ 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.