Copyright: Copyright ® 1995, C. van Zwynsvoorde


GraphZ

GraphZ 1.2 - User's Guide

Copyright © 1995, ZSoft. All rights reserved.

Author's E-Mail: czwy@eo.net

When you reach this help point, you probably are running an application which, in turns uses the GraphZ library to display its graphics. This help file documents (only) the functionalities implemented by the GraphZ library. In the rest of this help file the term "the application" refers to the overall program that you are currently running.

Printing

General settings

Loading the settings from a file

Saving the settings to a file

Setting the title attributes

Setting the general colors

Setting the general font

Setting the horizontal scale

Setting the vertical scale

Curve settings

Alarm settings

Zooming

Resizing the graph window

Seeing the legend

Seeing historical data

Product information

Note: Programmer's help can be found in a separate help file.


Zooming

It is possible to zoom in and out the contents of a GraphZ window.

Zooming in can be performed by pointing the mouse inside the curves box, pressing the left mouse button, draggin the mouse to select a zoom area, and releasing the mouse.

There is the restriction that data coming in or the slider being moved, disables the zooming process.

With other words, only a static display can be zoomed in.

Zooming out is performed by hitting the Unzoom button. This button is only enabled when the window is already in a zoomed-in state.

Zooming in and out follows a stack principle, that is, you can zoom in an unlimited number of times and then zoom out again the same number of times.

Zooming in or out always resets the y-axis to manual scaling.


Seeing historical data

GraphZ keeps historical data in a memory buffer. This is a first-in-first-out type of buffer.

Though your application should do that, you can set the length of the buffer. Suppose this length is 500 (the default), then GraphZ will always keep the last 500 data enties in the buffer. Suppose the display range is set to display 100 values, then you still can see the remaining 400 values by using the scroll bar on the bottom of the graph to scroll the window back to the desired values.

Normally, GraphZ automatically scrolls the window forth to display new incomming data.

As soon as you scroll back to historical data, GraphZ stops to automatically scroll the window so that you get a stable view on your data. To have GraphZ start scrolling automatically again, you must move the scroll bar slider completely to the right.

Note that when you have scrolled the window back, the view becomes stable but there is probably data still comming in and the buffer continues to fill itself. That's why the scroll bar slider automatically moves to the left. A time will come when the buffer is unable to continue storing incomming data while keeping the view stable. At that time, GraphZ will start again to automatically scroll the window.


Resizing the graph window

The resizing of the overall GraphZ window is actually provided by your application, not by GraphZ.

GraphZ just resizes its window to the size your application tells it to. When doing so it tries to make the best possible use of the place. The following considerations may then be done:

•	Nothing is guaranteed when the size is really too small to contain all the items.

•	The logo, if present, will be on the top-right corber, resized so its height mtaches the title's height.

•	The title will remain right aligned, near the logo  but will be truncated if needed.

•	The additional items (slider, buttons, etc.), if displayed, will be placed at the bottom and have fixed sizes.

•	The legend size is calculated according to its contents. The legend does not affect the GraphZ window's resizing. when you press the legend button, the legend will popup on the top-left corner. After that you can move it around freely (drag and drop with the mouse).


Product Information

This is GraphZ version 1.2.

GraphZ is copyright © 1995, C. van Zwynsvoorde. All rights reserved.

All the fancy objects are from the ControlZ library.

ControlZ is also copyright © 1995, C. van Zwynsvoorde. All rights reserved.

GraphZ has to be registered for your application. You can see if your copy of GraphZ is registered because if it is not, the text "GraphZ: Unregistered Copy" will be substituted to the graph title. Information about how to register GraphZ can be found in the programmer's help.

ControlZ is already registered for GraphZ.


Seeing the Legend

The legend can be poped-up or down by pressing the "Legend" button located below the graph. By default and each time you click on this button, the legend will appear on the top-left corner of the window, since there is probably some available place ther, because of the title. The legend will but just big enough so as to list all the curves allocated in the graph. Since the legend may need more place that is actually available, it may grow as to overlap a part of the graph.

In most cases this overlap will be relatively small and not too disturbing since it should be old data displayed on the left. Still, if you find that there would be a better place somewhere for the legend, you can move it just by dragging it with the mouse button pressed.

When printing a graph, the legend will appear approximately at the same place it was on the display.


Printing

You can access the printing facility by clicking on the print button. If displayed, it is located on the bottom of the GraphZ window.

Before any attempt to print a graph, you must have installed one or more printers by the normal windows installation procedure.

After you click the print button (this might take some time on a slow computer, when you are displaying data at a rather high rate), a dialog box will appear that propose you a default printer, with default settings. This is the printer you usually print on.

At this point you have to choice to:

•	accept the selected printer and settings, and start to print, or

•	cancel the print action, or

•	go to the printer setup facility.

Note:	By default GraphZ attempts to select the Landscape paper orientation.

Note:	While this dialog box is displayed, you will be unable to change the graph settings.

See also:

What will be printed ?

When to print ?

Printing speed.


Printer Setup

You acces this section from the print dialog box, by clicking on the setup button.

This allows you to choose a printer among the printers installed on your system. Once you have selected a printer, you can set the options for this particular printer. Very popular options that are important for printing a GraphZ graph, are the page size and orientation.

Since the printer setup is a system-wide feature, you will find all the needed documentation in you Windows user's guid and possibly in your printer's guide.


Print Job

While GraphZ is busy to print a graph, a dialog box will appear on the screen, showing you:

•	The name of the print job GraphZ is busy with. This name is either the graph's title, or the text "GraphZ". This name is not very important. It is used to identify the job for the Windows Print Manager, and possibly for some network printers.

•	An indication about the percentage of the job that has been accomplished so far.

•	A "Cancel" button so that you can interrupt the print job.

This print job monitoring dialog box is existing on its own. It does not prevent you from interecting with the graph. Still, the "Settings" button remains disabled.


What will be printed ?

GraphZ will print the graph exactly in the state it was by the time you clicked the "Print" button. That is, at the same scrolling position, with the same scaling, colors, etc.

Still, there are some differences between the printed and displayed graphs:

•	If you have a black and white printer, the printer driver will probably dither the colors to gray tints.

•	Dotted lines will have a width of 1 printer unit, and will therefore appear as black on black and white printers.

•	Pure white colors will be replaced by pure black.

•	The curves box background will be left white.

•	There will be no 3D relief effect.

•	The title's border, graved and embossed styles will have no effect.

•	The fonts sizes will be 4/3 times the display fonts sizes. This is because, fonts that appear nice on the display would give the impression to be too small when printed exactly at the same size.

•	The scroll bar, mouse-track window, the settings, print and legend buttons will not appear on the printed output.

•	The legend will appear approximately at the same place as on the display and, possibly, on top of it.

The printed graph will occupy the whole page, with a margin on the four edges of 0.75 inch.


When to print ?

There are three considerations to do on that subject:

1-	GraphZ will print the graph exactly in the state it was at the time you clicked the "Print" button. Hence you should be careful to click this button when the graph is in the state you would like to see on the printed page.

In particular, when you want to print a given horizontal range (eg. units 10 to 20) of the graph, it is advised that you first wait till this range has been passed (eg. 12 to 22), then scroll back to the desired range (ie. 10 to 20) and then clcik "Print". This is because when you scroll back, GraphZ will stop shifting the window everytime data comes in, so you can better adjust the desired range.

2-	GraphZ can print only one graph at a time. That means if you are currently printing a graph, you cannot print it again (even if it has changed, because new data has come in or whatever). If your application manages several GraphZ windows, you also cannot print another GraphZ window.

3-	While printing is busy, the "Settings" button for this particular graph (not for possible other graphs that your application may manage) will be disabled.


Printing speed

Printing a GraphZ graph on itself should in principle take in the order of one second.

Still, because printing has not a high priority, it may take quite a long time in case you have a slow computer which is already heavily loaded with displaying the incomming data. That probably means your computer is not adapted to the data flow rate that you are trying to display.


General Settings

You access the GraphZ settings by clicking on the "Settings" button. If present, it is located on the bottom of the graph.

This pops up a dialog box which allows you to set or modify:

•	The graph title. This title will appear on the top of the graph. If your copy of GraphZ is unregistered, the text "GraphZ: Unregistered Copy" will appear instead.

•	The title attributes

•	The horizontal scale name (X-axis label). This name will appear at the bottom of the graph. Many people find it convenient to put the unit of the horizontal scale there.

•	The vertical scale name (Y-axis label). This name will appear vertically on the left of the graph. Many people find it convenient to put the unit of the displayed data there.

•	The presence or absence of the extra objects on the bottom of the graph. Those are: the slider, the print, settings and legend button, and the mouse tracking window. The mouse tracking window continuously displays the real coordinates of the graph point under the mouse cursor as long as the mouse is located inside the curves box.

•	The curves settings...

•	The background color, tics and grid attributes.

•	The font used for evrything but the title.

•	The horizontal scale attributes.

•	The vertical scale attibutes.

•	The length of the history buffer. Note: when you change this, the history buffer will be cleaned up, so this is something you should try not to change very often. A good idea is to set it at the beginning of your session and then do not modify it. Even better would be that the application would set it.

This dialog box also allows you to:

•	Load all the settings from a previously saved file, or

•	Save the current settings to a file.

Note: When you click "Ok", all the current settings are replaced by those you have specified. But before doing so, GraphZ asks the application for authorization to perform this action. The application may even modify some settigns at this time.

A button is also available to display the product information.


Title attributes

You access the Title dialog box from the general settings one.

It allows you to set or modify the style used for displaying the title. The title text itself can be specified directly from the general settings dialog box.

Note:	There are some restrictions regarding the title styles and printing.

You may choose:

•	The font and font size. Note: only scalable fonts are allowed.

•	Some font attributes like bold, itablic and underline.

•	Whether or not to display a border around the title.

•	Whether to display the title with a graved or embossed effect. Note: those two style are mutually exclusive.

•	The color for the title text (not the background). This has no effect if either the graved or embossed style is selected. Still, it will be used for printing.


Background color, tics and grid

You acces this dialog box by clicking on the "Color" button from the general settings dialog box.

You may there set or modify:

•	The color used for the curves box background.

•	The tics presence or absence (including the tics labels). Tics labels are the numbers appearing aside each tic.

•	The pen used for the tics. That is its color, and size. Note that the same color will be used for the tics labels. Also note that the solid/dotted attribute is not available for the tics pen.

•	The grid presence or absence. Note: although this has been strongly optimized, having a grid takes a little bit more of CPU-time.

•	The pen used to draw the grid. That it its color, size and solid/dotted atrribute. Many people find it nice to use a dotted pen for the grid, but it still appears to be faster and safer (?) to use a solid pen.

Note:	There is no way to modify the color of the horizontal and vertical scale names, the legend texts and the mouse tracking coordinates. They will all appear in black.


Colors

GraphZ uses a true colors palette. Therefore it is strongly recomended that you have at least a 256 colors display.

There are two ways to specify a color:

1	Whenever possible and by default, you can just pick up the color in a palette (note the scroll bar on the bottom of the palette to display more colors).

2	Otherwise and to have a more precise control, you can use the RGB mode. This stands for red-green-blue. You will then get three sliders graduated from 0 to 255 and you will have to specify the red, green and blue components of the desired color.

Here are some examples:

Pure blue is: red=0, green=0, blue=0.

Pure black is: red=0, green=0, blue=0.

Pure white is: red=255, green=255, blue=255.

Mid gray is: red=128, green=128, blue=128.

Deafult colors are proposed for the curves when you allocate them. Also anytime a color can be changed, GraphZ gives you a preview facility so you don't have to worry too much about the values and just have to test them.

Pure white will be replace by pure black for printing.


Pen size

Whenever you have to specify a size for a pen, you should be aware of the following:

•	The pen size must be a strictly positive integer.

•	Big sizes quickly turn out ugly.

•	A dotted pen can only have a size of 1.

•	The unit is the one pixel. When printing, the curves pens will be scaled accordingly, accept dotted pens.


General font

You acces this dialog box from the general settings one, by clicking on the "Font" button.

It allows you to select a font name, style and size. Only scalable fonts are available. This font will be used for everything but for the title.


Horizontal scale

You can access the horizontal scale settings from the gereral settings dialog box, by clicking on the "X-Scale" button.

The horizontal scale settings deeply depend on whether you want to have a normal (numbered) scale or a date & time scale. You may choose this by the two radio button on top of the dialog box.

Basically, what you set here is the length of the range of displayed data. That is the difference between the rightmost and leftmost values in the display.

To specify the range duration, a drop-down objects is used. It is rather intuitive. You start with the number of days years (you possibly have to scroll up to the top, first). Then you go down with ever more precision until you have the desired duration.

In addition, when date & time scale is selected, you may specify a display format for the date & time labels. Note that selecting both "no date" and "no time" will have the same effect as selecting the normal numbered scale.

For the date part, the following formats are available:

•	DD/MM/YY

•	MM/DD/YY

•	YY/MM/DD

•	DD month YY

•	YY month DD

•	month DD, YY

For the time part, the following formats are available: (99 stands for the hundredth of a second)

•	HH:MM

•	MM:SS

•	HH:MM:SS

•	SS.99

•	MM:SS.99

•	HH:MM:SS.99

Note:	The slash (/) and colon (:) characters used here are very common ones but only an example. The actual characters used can be configured by the general Windows settings (Control Pannel).


Vertical scale

You can access the vertical scale settings from the gereral settings dialog box, by clicking on the "Y-Scale" button.

This pops up a dialog box which allows you to set or modify the following:

•	Whether or not to use the automatic scaling feature of GraphZ. This will actually prevent you from bothering about the scale boundaries. Note that if automatic scaling is selected, the "Min" and "Max" attributes will be ignored.

•	The "Min" and "Max" boundaries of the vertical scale, in case the automatic scaling is not selected.

•	Whether or not to use a logarithmic scale.

•	The base for the logarithmic scale. You may enter any positive number here, except zero and one. The most commonly used value is 10. You may also enter the character 'e', which is interpreted as the base of the Neperian logarithm.

In logarithmic scale mode, GraphZ will display a vertical scale with tics on entire powers of the base. In addition, if the base is a multiple of 10, GraphZ will add 10 non-labelled sub-tics (and grid lines) between each main tic (and grid line).

Constraints:

The dialog box makes use of tuner-like objects. They have the advantage that the range of allowed values is unlimited. Still, GraphZ puts the following obvious restrictions on them:

•	Trying to make "Min" greater than "Max" will automatically increase "Max".

•	"Max" has a lower limit of "Min".

•	In logarithmic scaling, "Min" (and thus also "Max") must be grater than, and not equal to zero.

Besides, when you will press the "Ok" button in the general settings dialog box, the following checks will be performed:

•	General logarithmic error prevention.

•	If "Min" equals to "Max" then "Max" will be increased by 1.

•	On any error in the log-base, the default value (10) will be substituted.


Logarithm error prevention.

In logarithmic scaling mode, any value for which the log() will have to be calculated, will be checked as follows:

•	value = abs(value)

•	if (value == 0) then value = 1


Loading the settings from a file

Once you have specified a filename, you can load the settings from this file. This will overwrite all the current settings.

You do this by clicking on the "Load" button from the general settings dialog box.

Prior to loading the settigns, GraphZ asks the application for authorization to load the settings from the given file.

If a file with the specified filename cannot be found, or if it has an incorrect format, default values will be substituted for all the settings. This is also how GraphZ initializes the settings at the graph creation time.


Settings file name

The settings file name is displayed in the "Ini file name" edit-box in the general settings dialog box. Normally this name should be initialized by your application. Still you can modify it, possibly by making use of the disk "Browse" button. The prefered filename extension is "*.GRZ".

Note:

The file name should contain a complete path. Otherwise the Windows directory is assumed. To refer to the current directory, you should prefix the filename with ".\"


Default values

When one or more setting cannot be loaded from a settings file, default values are provided as follows. This also happens when a graph or a curve is created (ie. initialized).

Settings	Default Value

Logarithmic y-scale	NO

Logarithm base	10.0  (ie. decimal log)

y- scale min	0

y-scale max	1

length of x-range	100

ShowAllObjects	YES

TimeFormat	By default, a numbered scale is used.

y-Autoscale	YES

Grid	YES

Tics	YES

Font name	"Arial"

Font size	8 pt.

Buffer Length	500

Curves background color	black

Grid pen	white, dotted

Tics pen	black, solid

Title font name	"Times New Roman"

Title font size	16 pt

Title bold	NO

Title italic	NO

Title underline	NO

Title graved	NO

Title embossed	YES

Title border	NO

Title color	black

Curve legend	"Curve N"

Curve symbol	none

Curve pen	Default color depends on curve number.

Curve. No line	NO

Curve. Check alarms	NO

Alarm. Plot horizontal line	NO

Alarm symbol	none

High Alarm horiz. line pen	red

High alarm threshold	100

Low alarm horiz. line pen	blue

Low alarm threshold	1


Symbols

Each curve have symbols atributes. There are three symbols for each curve: One for the normal case, one in case the value is beneath the low alarm limit, and one in case the value is above the high alarm limit.

In the settings file, the following symbol codes are used:

0 = none

1 = circle	2 = square

3 = plus sign	4 = cross

5 = diamond	6 = dot

7 = star	8 = triangle.

Actually, those codes are more relevant to programmers and a normal user should not even have to see the settings file.


Saving the settings to a file

Once you have specified a filename, you can save the current settings to this file. This will overwrite all the settings possibly already saved in this file.

You do this by clicking on the "Save" button from the general settings dialog box.

Prior to saving the settings, GraphZ applies possible changes that you have made, that is, a virtual click on the "Ok" button is performed.

Prior to saving the settings, GraphZ asks teh application for authorization to save those settings.

If, for any reason (empty field, wrong syntax, write protected disk, etc.), the file with the specified filename cannot be written, then nothing is saved.


Curves settings

The curves settings can be accessed from the general settings dialog box, by clicking on the "Curves" button. This will pop up a dialog box which allows you to specify all the curve-related settings.

All the allocated curves for a graph are listed in the "Allocated curves" list box.

The number of allocated curves is fixed by your application and you cannot change it.

Before you change the settings for a given curve, you must select it in the list-box. In this list box, the curves' names (ie. legend) appear. When you select one, all the attributes are listed as text in the list box and also become available in the rest of the dialog box for editing.

Note that having them listed in the list-box can be useful when you have changed some attributes and don't remember what they previously were, but don't want to press "Cancel" because "Cancel" applies to all the curves.

Once you have selected a curve, you can change its attribute. They are:

•	The curve's name. This is the name that appears in the curves lst-box above, and that will appear in the graph's legend.

•	The pen used for this curve: color, size and dotted/solid style.

•	The symbol to plot at each point in the normal case (that is, not in alarm).

•	Whether to plot a line for this curve or only the point symbols.

•	Whether to check for and display alarm conditions.

If so, then you may specifiy the low (resp. high) alarm settings.

Note:	GraphZ will always keep the high alarm limit above the low limit.


Alarm settings

You reach those settings via the curve settings, by clicking on the "Low" (resp. "High") button in the curves dialog box. This will pop-up a new dialog box which allows you to specify the low (resp. high) alarm settings.

The name of the curve and type of alarm that you are setting is displayed in this dialog box.

For each curve, you may or may not let GraphZ check for alarm conditions. An alarm condition consists of a limit value (threshold) that may not be exceeded. There are two limits: a low and a high. If a value comes above the high limit, the the value is said to be in high-alarm. If it comes below the low limit, then it is in low-alarm.

Points that come in-alarm are visualized by using a different symbol for them.

You may also make alarm settings more obvious by letting GraphZ plot an horizontal line at each alarm threshold.

The settings available in the alarms dialog box are:

•	The threshold value for this alarm.

•	The symbol to plot for points that meet this alarm conition.

•	Whether or not to plot an horizontal line at the threshold value.

In that case you can also specify the pen for this horizontal line. This consists of a color, size and style (dotted/solid). there is a preview facility to help you select those attributes.