Copyright: Copyright ® 1995, C. van Zwynsvoorde


GraphZ

GraphZ 1.1 - User's Guide

Copyright © 1995, C. van Zwynsvoorde. All rights reserved.

Author's E-Mail: cvzwynsv@estec.esa.nl

GraphZ is a dynamic link library (DLL) that curently implements one type of dynamically updated graph. This is a 2d-plot graph.

GraphZ is particularly suitable for displaying continuously incomming technical data in a simple way and at nearly real-time.

GraphZ is highly configurable, either from the program to which it is linked, or at run time, by the user. The latter is the purpose of this help. Programmer's help can be found in a separate help file.

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 specific settings

Resizing the graph window

Seeing historical data

Playing with alarms

Product information


Playing with alarms

One of the nicest GraphZ's feature is alarms.

You can specify low and high alarms for each curve. In-alarm points are indicated by using a (different) symbol.

You can also add horizontal lines to a graph, in order to visually in dicate alarm limits for certain curves. Horizontal lines are actually additional constan-value curves.

See further the Curves settings.


Resizing the graph window

The resizing functionality 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. Still there are a couple considerations to do:

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

•	The title will remain centered but will be truncated if needed.

•	GraphZ will try to reserve horizontal place to display the legend completely, so don't make it (ie. the curves names) too long.

•	The legend may be vertically trunctated if needed.


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.


Printing

You can access the printing facility by clicking on the print button. It is situated on the right edge of the graph.

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:	Most probably you will want to set the printer in landscape mode prior to printing the graph. For that purpose, you will have to go to the printer setup.

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. Note: In order to do so, lines have to be more that one point width. Therefore, lines of width 1 will always appear black on a non-color printer.

•	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 1.5 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 and print buttons will not appear on the printed output.

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. It is located on the bottom right edge 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 mouse tracking presence or absence. If you choose to tack the mouse, the real coordinates of the graph point under the mouse cursor will be displayed continuousely while the mouse is located inside the curves box. Many poeple find this a very convenient feature, but you must be aware that (a) it takes some place to display, and (b) it consumes some CPU-time.

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

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.

The "Sample" button allows you to get a preview of how the title would look like with the currently selected attributes. Note that this preview is not automatically updated and you do have to click on the "Sample" button.


Background color, tics and grid

You acces this dislog 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. Still, if needed, this can be set in the "Ini" file.

•	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 the grid. That it its color, size and solid/dotted atrribute. Many people find it nice to use a dotted pen for the grid.

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.

Colors are specified by means of their red, green and blue components. Each component accepts values ranging from 0 to 255.

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 turn out to become quickly ugly.

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

•	The unit is the default unit of the device, that is 1 pixel for display and 1 point for printing.


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.

The "Sample" button allows you to preview the selected font. The preview is not updated automatically and you do have to click on the "Sample" button.


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 at any time by checking of not the "Use date / time scale" attribute. Depending on that attribute, one of the following two dialog boxes will be poped up:

1- Normal numbered scale.

This dialog box allows you to set or modify the:

"First":	X-value associated of the first data that will or has come in.

"Rate":	Increment added to the current x-value to be associated with new incomming data.

"Range":	length of the interval of x-values that will continuously be displayed.

Example:	Suppose First = 50, Rate=2 and Range = 100. Suppose there have been 230 data elements coming in so far. Suppose the window is not scrolled back.

•	The (historical) data will start at 50.

•	The current x-value will become First + 230 * Rate = 510.

•	The next incomming data will get an x-value of 510+Rate=512.

•	The displayed range of values will be 510-Range=410 to 510. Next time this will become 412 to 512, etc.

The dislog 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:

•	The "Rate" must be positive and not zero.

•	The "Range" must be positive and not zero.

2- Date & Time scale.

The dialog box allows you to set or change the same attributes as above, except that it makes use of special drop-down objects for entering date & time values.

The "First" attribute is an absolute date & time value, whereas the "Rate" and "Range" attributes are actually durations.

The drop-down objects are intuitive for use. You start at the years (or days) level and finish at the hundredth-of-a-second level. It is recomended that you complete all the levels, though if you don't, zero values are assumed for all the lower levels.

In addition to that, the dialog box allows you to specify the text format for displaying the values.

The format is splitted in two part: the date and the time part.

You may choose to display one the date, only the time, or both.

You you choose to display neither the date nor the time part, then GraphZ assumes this is actually no date & time scale and you come back to the normal (numbered) scale. See above.

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

If the 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 precede the filename with ".\"

(see also the settings file format).


Settings file format

The settings file has a Windows "*.ini" file compatible format. It is devided in sections, each of them having a number of items and values. Below is a list of those sections, items and default value.

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

Section	Item	Default Value	Description

[GraphZ]	xLabel	(none)	the horizontal scale name

yLabel	(none)	the vertical scale name

Logarithmic	0 10.0	(0 / 1) = (true / false), base

yScale	0 1	min max

xRate	1	the "Rate" attribute

xStart	0	the "First" attribute

xRange	100	the "Range" attribute

MouseTrack	1	(0 / 1) = (true / false)

TimeFormat	0	a number indicating the display format for the date & time scale, (see the programmer's help). 0 means normal numbered scale.

Autoscale	1	(0 / 1) = (true / false)

Grid	1	(0 / 1) = (true / false)

Tics	1	(0 / 1) = (true / false)

Font	Arial,8	general font name, point size

Curves	0	number of curves (0 to 16).

BufferLen	500	length of the history buffer

Background	0 0 0	curves box background color (red green blue)

GridPen	255 255 255 2 1	red green blue dotted=2/solid=0 size

TicsPen	0 0 0 0 1	red green blue dotted=2/solid=0 size

[Title]	Title	(none)

FontName	Times New Roman

FontSize	16	title font size in points

Bold	0	(0 / 1) = (true / false)

Italic	0	(0 / 1) = (true / false)

Underline	0	(0 / 1) = (true / false)

Graved	0	(0 / 1) = (true / false)

Embossed	1	(0 / 1) = (true / false)

Border	0	(0 / 1) = (true / false)

Color	0 0 0	red green blue

[CurveN]	Legend	"Curve N"	the legend for this curve

Symbol	0 0	SymbolCode DrawLine=0/DrawOnlySymbol=1

Color	r g b 0 1	red green blue dotted=2/solid=0 size. (r,g,b default values depend on the curve number N).

AlarmEffects	0	(0 / 1) = (true / false)

AlarmLow	0 0	LowAlarmLimit LowAlarmSymbol

AlarmHigh	100 0	HighAlarmLimit HighAlarmSymbol


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.

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.

You have to proceed in several steps:

1- Setting the number of curves.

The dial-like object on the top left of the dialog box, lets you adjust the number of curves that will be displayed. You change this at any time but it's a good idea to set it first.

Up to 16 curves are allowed on one graph.

Normally the number of curves will have to be set by your application. Still you can modify it, and take a lot of advantage out of it, by knowing that:

Your application is the one that generates the incomming data. It will most probably always generate data for a given number of curves (say N).

If you, as user, change this number to M, two cases are possible:

• M < N	You set the number of displayed curves to less than what your application generates. GraphZ will first destroy the curves M+1 up to N. Nevertheless, next time your application will try to display its N curves, GraphZ will see that some are mssing and will try to allocate the missing curves (that is M+1 up to N) on the fly. Therefore, the only thing you'll perform there, is to clean up the buffer and reset to default settings for the curves M+1 up to N.

• N < M	You set the number of displayed curves to more than what your application generates. GraphZ will then automatically generate constant data for the curves N+1 up to M. For this data the low alarm limit value of the concerned curves will be used. So those curves will appear as an horizontal line at y=LowAlarmLimit.

This feature can be very useful in case you indeed want to display an horizontal line, in addition to what's already present. One very common application is to set horizontal lines at another curve's low and/or high alarm limits.

2- Selecting a curve.

One thing to have to do before setting the attributes is selecting the curve of which you will edit the attributes.

You do this by selecting a curve in the curves 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.

3- Changing the attributes of a curve.

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 use in the normal case.

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

•	Whether to use alarm effetcs or not. If so:

•	The low alarm limit.

•	The symbol to use in case a value comes beneath the low alarm limit.

•	The high alarm limit.

•	The symbol to use in case a value comes above the high alarm limit.

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

Note:	In case your application generates no data for this curve, GraphZ will automatically generate constant data equal to the low alarm limit (see above).


Product information

This is GraphZ version 1.1.

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.