Introduction

( 1 )
Next (Table Of Contents)

cGraph

by John Kopplin

Copyright © 2002-05

Welcome to cGraph, a top-level window that offers a Cartesian (i.e., x/y) plot. I use this same window for a number of my programs such as GRAPHIT.EXE and RPNCALC.EXE . The GRAPHIT.EXE program is a general purpose plotting program that demonstrates the full capabilities of the cGraph window.

The help page that you are now viewing is merely the first of a set of help pages that together document the operation of this software. There is a hyperlink at the top and bottom of each page labeled "Next" which will take you to the next help page.

You have probably seen a Help system like this one already. It is built upon Microsoft's standard HTML Help technology. In the left-hand pane you can observe 4 tabs labeled Contents, Index, Search, and Favorites. The Contents tab simulates a book's table of contents while the Index tab simulates a book's index. The Search tab offers the feature that books would kill for. The Favorites tab is where you can record bookmarks on your favorite pages. These bookmarks make it easy to return to these spots later.

The home page for all of my software is www.computersciencelab.com For questions, you can reach me at support@computersciencelab.com. Enjoy!

Next (Table Of Contents)


( 2 )
Previous Table Of Contents Next

Table Of Contents

Introduction

Table of Contents (this page)

Basic Operations

File Operations

Advanced Operations

About cGraph

Previous Table Of Contents Next


( 3 )

Basic Operations

When you first initiate the GRAPHIT.EXE program you will be greeted with the following window:

This is the canvas for a Cartesian plot (i.e., an x/y plot) but at the moment it has no data points. The various ways that you can create data points for the canvas all reside in the File menu on the menu bar. This File menu is shown below:

Select the File menu entry labeled "Manually enter y data..." which will cause the following dialog box to display. On this Enter New Data Set dialog I have already entered 4 data points. Because I selected the "Manually enter y data..." menu item I am only required to enter the y axis values for each data point. The x axis values will be automatically assigned to the sequence of integers starting from 0. That is, via the Enter New Data Set dialog seen below I am defining the four data points (0,2), (1,3), (2,4), and (3,5).

When you click on "OK" to close the Enter New Data Set dialog the cGraph window is redrawn as shown below:

We have defined a single data set which is also known as a data line or a data curve.

You will also notice that the ranges of the x and y axes changed to match the data that we entered. This is because, by default, the cGraph window is in its Auto Range mode.

Now let's define a second data set so that our graph will have two data lines. This time, select the File menu entry labeled "Manually enter x,y data..." which will cause the following dialog box to display. On this dialog box I have already typed in 3 data points. Because I selected the "Manually enter x,y data..." menu item I am now required to enter (x,y) number pairs for each data point. The x and y values can be separated (delimited) by either a comma or a space character.

When you click on OK to close the Enter New Data Set dialog the cGraph window is redrawn as shown below:

The plot axes adjust to the new data because we are still in Auto Range mode. One way to tell whether the cGraph window is in its Auto Range mode is to right-click anywhere on the plot to get the context menu seen below. Incidentally, all the entries in this right-click context menu duplicate entries found on the main menu under the File or Edit menu items.

The check-mark next to the "Auto Range" entry on the context menu assures us that the cGraph window is in its Auto Range mode.

After right-clicking to open the context menu, left click on the "Reformat Plot..." entry on the context menu. The following Reformat Plot dialog box will then display:

Before the Reformat Plot dialog is presented it is first initialized with the current settings. It is via this dialog that you can change the title of the plot, which is currently the word "title". Via this dialog you can also change the horizontal axis label which is currently the phrase "x axis" (the title serves as the vertical axis label). And you can specify a particular plot range and number of tick marks for either the x or y axis. And there are checkboxes that allow you to add horizontal and/or vertical grid lines and to hide or show the legend.

The legend is the very bottom portion of the cGraph window. At the moment the legend is not doing us very much good since each of the data sets has the same label of "manually added", is assigned the same line color of black, the same line style of solid, and the same line width of 1 pixel. We will shortly see how to change these items.

Also on the Reformat Plot dialog are pushbuttons that allow you to change the font and color used for the annotations, the color used for the axes and tick marks, and the background color.

If you cancel out of the Reformat Plot dialog by clicking on the CANCEL pushbutton then you will stay in Auto Range mode (or more accurately, you will stay in whatever mode you were in previously). But if you close the Reformat Plot dialog by clicking on the OK pushbutton then you will definitely shut off cGraph's Auto Range feature. Go ahead and click on the OK pushbutton without making any changes to the min and max values offered for the x and y axes and the cGraph plot will look just like it did before. But we will demonstrate that the Auto Range feature is now inactive.

Again select the "Manually enter y data..." menu choice and type in the three data points seen below:

When you then click on OK to close the Enter New Data Set dialog the cGraph window will appear as shown below. Note that the legend claims there is now a third data set but we can't see it. This is because we requested -- via the Reformat Plot dialog -- a fixed x axis range of 0 to 5 and a fixed y axis range from 2 to 7. The new data set does not fall within this range and hence cannot be seen in the graph.

To further prove that the Auto Range mode has been disabled let's take a look at the Edit menu from the main menu bar. Note the absence of a checkmark next to the "Auto Range" entry.

Select the "Auto Range" entry from either the Edit menu or the right-click context menu and the cGraph window will change as seen below thus allowing us to observe all three data sets.

To summarize the Auto Range mode: the Auto Range mode remains active from the time you select the Auto Range option from the menu until you next click on OK to close the Reformat Plot dialog (that you get via the "Reformat Plot..." menu choice). The Auto Range mode remains inactive from the time you OK out of the Reformat Plot dialog until you next select the Auto Range menu item.

Let's now do something about the legend. Select the "Reformat Line..." entry from either the Edit menu or the right-click context menu and the following Reformat Line dialog will display:

The Reformat Line dialog can only show the particulars for a single data set at a time. You control which data set you are reformatting via the control labeled "Info for Data Line #" located at the very top of the Reformat Line dialog. This dialog offers a pushbutton that allow you to change the color used for the data line. There are other controls that allow you to specify the width of the data line and the line style (solid, dashed, etc.). And there is an EDIT box where you can enter an arbitrary label for this particular data set. It is this label that appears in the legend.

The Graph Type control allows you to connect the data points with straight lines, or with stair steps, or to not connect them at all. Digitally sampled data is traditionally plotted using stair steps. When the data points are not connected the graph is called a scattergram. The "Stoop" option is the traditional way to plot histogram data.

At the very bottom of the Reformat Line dialog you will find two controls labeled Multiplier and Offset. The data that is actually plotted on the cGraph window is given by the following equation:

Yplotted = Multiplier * Yactual + Offset

Hence as long as Multiplier = 1 and Offset = 0 these controls do not influence the data curve. But they provide a handy way to offset or scale the raw data. For example, if you end up with one data set showing grams and another data set showing kilograms then you could align the two data sets by setting the Multiplier control for the first data set to .001 (thus causing both curves to represent kilograms) or by setting the Multiplier control for the second data set to 1000 (thus causing both curves to represent grams).


( 4 )

File Operations

Now that we have manually entered a few data sets we would probably like to save this data into a plain-text (i.e. ASCII) data file. Such data files employ the .TXT filename suffix and are the only type of file which you can view using the Notepad word processor that Microsoft includes with every version of their operating system.

To save your data to a data file select either "Save" or "Save As" from the File menu on the main menu bar. If you have never assigned a filename to this data then you will next be greeted with the standard Windows Save As filename dialog which asks you to specify a filename. You can also use this dialog to navigate to wherever in the Windows file system you wish to place the file. Assuming the particular case of the three data sets that we constructed in the prior help page, when you click on "Save" to close the standard Save (or Save As) dialog you will be greeted with the following message:

This dialog is telling us that we were only able to save the first data set in the data file (for which we chose the filename "junk.txt"). The problem is that the three data sets do not have compatible x axis values, which is a requirement for multiple data sets to share a single cGraph data file. The reason for this will become clear shortly. If the three data sets had shared the same x axis values then they would have all been saved to the data file we just created.

Let's take a look at the contents of a cGraph data file. Just as there are two menu options labeled "Manually enter y data..." and "Manually enter x,y data..." there are two flavors of cGraph data file called an implicit x and an explicit x data file. The File/Save (and File/Save As) menu choice creates the type of file that corresponds to the first data set. For the particular case of the three data sets that we constructed in the prior help page, the first data set was an implicit x data set since it originated with the "Manually enter y data..." menu choice. Hence the File/Save As operation created the implicit x data file which is shown below. Remember that you can use Notepad to show you the contents of these data files.

ImplicitX Title "title" HorzAxisLabel "x axis" SetLabels "manually added" 2.000000 3.000000 4.000000 5.000000

The first line of the data file states that it is an implicit X data file. This means that every data point is specified only by its y axis value and the x axis value is understood. You can see the four y axis data points at the bottom of the data file. The next three lines hold the title, horizontal axis label, and the set label seen in the legend for this data set.

You are free to create implicit x and explicit x data files using Notepad (or any other word processor as long as you specify a "plain text" file). The ImplicitX, ExplicitX, Title, HorzAxisLabel, and SetLabels statements are all optional. When a file lacks either the ImplicitX or ExplicitX declaration statement it is treated by cGraph as an implicit x data file. An example of an explicit X data file is shown below. This example also shows that data files can contain blank lines and comment lines.

// file junk2.txt // This is a comment ExplicitX Title "The Title" HorzAxisLabel "The Horz Axis Label" SetLabels "Set #1 Label", "Set #2 Label" 0 2 4 1 3 5 2 4 6 3 5 7

In an explicit x data file, every data point must be described by an (x,y) pair. But this example explicit x data file has 3 columns of numbers. What gives? If you ask cGraph to read this last data file (via the File/Open menu choice) you will get the following plot.

As you can see, the 3 columns of numbers have been interpreted by cGraph as shown below:

x1, y1_1, y2_1 x2, y1_2, y2_2 ...

Hence this file holds two data sets. The first data set consists of the points (x1, y1_1), (x2, y1_2), ... The second data set consists of the points (x1, y2_1), (x2, y2_2), ... An explicit x data file can contain any number of columns as long as that number is at least 2. An implicit x data file can contain any number of columns as long as that number is at least 1. In either case, all the data sets share the same x axis values.

Even though a cGraph data file cannot hold incompatible data sets, the cGraph window does not mind overlaying data sets with incompatible x axis values. Incidentally, if you really need to save an incompatible second data set to a cGraph data file you can accomplish this -- after saving the first data set -- by deleting the first data set via the "Edit/Delete Line..." menu choice. This action promotes the second data set to the first data set which is the one that gets to call the shots as far as who else gets to share its data file. Then perform the File/Save As operation (if you choose File/Save you will overwrite the prior first data set).

On the File menu you will notice the two choices File/Open and File/Append. The difference between these is that the former clears any prior graph and the latter simply adds to it.


( 5 )

Advanced Operations

Regardless of whether you read a plain-text data file or manually entered your data points, you can modify them using the "Edit Data Set..." menu choice found on the Edit menu. This menu choice brings up the Edit Line dialog shown below:

This is how the dialog looks for an explicit x data set. For an implicit x data set only a single column of numbers is shown. Via this same dialog you can edit any of the data sets in your cGraph window by entering the desired data line number in the control seen at the very top of the Edit Line dialog. You are free to modify x or y axis values or to delete or add data points. The only thing you can't do is to change an implicit x data set into an explicit x data set, or vice versa.

You can ask the cGraph window to display the exact x and y values for any point on any of the data sets. You do this by positioning the mouse cursor near the intended data line and then depressing and holding the left mouse button. While the left mouse button is kept depressed the title area of the window is replaced by a text message that displays the exact (x,y) coordinates for the data point currently being digitized. You can move the mouse while holding the left button depressed and thereby digitize the entire curve. A screen capture of the cGraph window during this digitization procedure is shown below. While digitizing the curve the mouse cursor changes from the usual arrow to a crosshair. Although this crosshair looks fine in this picture, when digitizing a perfectly horizontal or vertical section of a data curve the crosshair will take on strange colors but this is normal.

The legend portion of the cGraph window has a hidden feature. As you keep adding data curves to a plot the portion of the window used for the legend will initially grow but then eventually will reach a maximum allowed size. Whenever the maximum allowed size is insufficient to display all the legend entries, a scroll bar will appear on the legend thus allowing you to scroll to the invisible legend entries. The hidden feature is that you can (within limits) control this maximum legend size by dragging the top edge of the legend. The following screen capture shows how the mouse cursor changes when you have it positioned at the spot where -- if you depress and drag the mouse -- you will be able to increase or decrease the amount of screen real estate dedicated to the legend.

The most common reason that you would want to drag the legend is to eliminate the scroll bars before you create a .BMP or .GIF file of the current contents of the cGraph window. You want to fully expand the legend because the .BMP or .GIF file will show exactly what is visible in the window and hence will not include any invisible legend entries. The menu entries that create a .BMP or .GIF file are found on both the File menu on the main menu bar and on the right-click context menu. Via the ensuing Create .BMP File or Create .GIF File dialogs, you can specify the exact pixel dimensions that you wish. This is a very handy feature for creating images that you can then import into word processor documents.

You are not required to have a title or a horizontal axis label. If you don't request these items then no screen real estate will be reserved for them.

Finally, the cGraph window will print itself to a printer. Any hard copy always shows the entire legend. The default margins are 1" on all four sides. If you want to specify different margins then employ the File/Print Setup menu selection prior to requesting the print.


( 6 )
Previous Table Of Contents

About cGraph

cGraph consists of 8,500 C++ statements that employ Microsoft's WIN32 API. It (and these help pages) was written over a period of a few months in 2001 by yours truly, John Kopplin, in Boise, Idaho. I have seen it run under Windows 95, Windows 98, Windows Me, Windows NT 4, Windows 2000, and Windows XP. It should run acceptably on any PC no matter its age as long as it contains one of these operating systems.

The name cGraph is actually the name of the C++ class that encapsulates the code. Thanks to this encapsulation, it is easy for me to attach the code to other Windows programs such as my RPN calculator simulator, which is the first component of my computer programming curriculum.

Acknowledgements

I would like to thank Andy Key for providing the source code that I use to construct .GIF files. You can read about Andy's "Generalized Bitmap Module" on his home page at: http://www.nyangau.fsnet.co.uk