GraphZ 1.2 Application Programming Interface

Copyright © 1995, ZSoft. All rights reserved.

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

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. User's help can be found in the User's Guide help file. It is recommended that you read it before you start with programming matters.

Main features

Programming Principle

Functions, Structures and Constants

Product Information.


GraphZ is a Dynamic Link Library (DLL).

It is not a Visual Basic Control (VBX), a static library (LIB), an object library (OBJ) or even a Pascal Unit (TPU).

For your convenience, GrphZ is shipped with an import library (LIB) generated by Borland C++.

GraphZ implements a global window class called "GraphZ". This class remains valid as long as the library is loaded and as soon as you have called the GZRegister  function.


In Microsoft Windows, each window has a given class. The class is identified by a name (ie. a string).

The class is declared by the API RegisterClass function, and the class name is used for example as the first parameter of the API CreateWindow function.

A class can be either private (to an application) or global. In that case it is available to all the applications running at that time.

GraphZ implements one global class named "GraphZ".


Main Features

•	Plot of xy-values with different line styles, colors and symbols.

•	Internal FIFO-buffering of the data. Virtually unlimited buffer size, per curve.

•	Scrolling window, with scroll bar.

•	Optimized space occupation and layout. On/off display of the legend. Movable legend.

•	Automatic sizing.

•	Save and load all the graph settings to/from settigns files. Standard ascii file format.

•	Full date & time support.

•	On-the-fly alarm checking and display.

•	Highly configurable at run-time with complete user-interface.

•	Possibility for your application to validate or reject some user actions/changes at run-time.

•	Speed-optimized for "real-time like" applications.

•	WYSIWYG Printing.

•	Each curve is independant.

•	Automatic or manual scaling, even with dynamic data.

•	Linear or logarithmic scaling (with definable log base). The scale does not have to start or stop at a decade.

•	The x-values do not need have a fixed increment, so you can plot an asynchronous data stream, even with missing values. You can therefore also use GraphZ as any other graphics package.

•	GraphZ is a library that you easily can link to your program. Your program keeps the control on it.

•	Possibility to include your own logo in the graph, so you don't have to "misuse" the title for that purpose.

•	Source code available.

•	Unlimited cascaded zooming / unzooming.

The next version will include:

•	Multiple (possibly two) y-axis, possibly merging linear and logarithmic axisses.


Real-time applications

GraphZ has been designed with real-time applications in mind.

Therefore it offers features like:

•	It is a library so you can easily integrate it in your application. It is not a complete environment for off-line data analysis.

•	It has been strongly optimized for speed matters.

•	It displays incomming data provided by your application. Your application has the complete control on the data flow.

•	It displays data in a continuous way, with a sliding window.

•	It has full support for data & time scaling.

•	It is small and implements only what you need with no overkill.

Still, there is no real-time guarantee. That is, GraphZ does not guarantees that a given transaction will be performed within a given time. Hence I advise the following if you have real-time requirements:

•	Try to get a fast computer. In particular a math-coprocessor is very strongly recommended.

•	Try not to be too short in memory. I believe 4M is a little bit short. But this depends a lot on the rest of your application. It also depends on how much concurrent graphs and curves you have and what is the curves buffer length.

•	Another rather important speed factor seems to be the display card and/or driver. In that respect, making graph windows smaller may help significantly.

•	To a smaller extent, the number of curves also has some influence.

•	Make some tests about the execution speed with your application and your computer. For instance, if you have data comming in only every 30 seconds, then you probably won't have to worry about real-time aspects.

•	In order to be able to guarantee the response time of your application's data handling routine, I recommend that you implement a first-in-first-out (FIFO) buffer mechanism between your data handling routine and the calls to GraphZ.

Note:	This is only if you:

1	do have real-time requirements and have to guarantee the response time of your data handling routine; and

2	have a high data flow rate which makes you work at the limit of your computer's capability so from time to time (not in average) GraphZ takes more time than is allowed by your requirements.


Buffer Length

Each curve has its own buffer for storing historical data. The buffer length is a general setting of a graph. The default buffer length is 500 data elements. In the current version, the buffer length is limited to maximum 60000 data elements (which is already more than 1Mb in memory, so be careful...). Still, if you need more, its only a compile-time #define so if you want to contact me...

See further details in the User's Guide help file.


Display card and/or driver.

I developped GraphZ on a 386, 25 Mhz, without coprocessor ! First I thought the bottleneck was the CPU-speed so I did a lot of work in optimizing the processings and in particular the floating point calculations. This of course helped a lot. Finally I observed that the bottleneck had become the speed of the low-level GDI graphics routines like ScrollWindow or FillRect.


Programming principle

In the following, I assume you are programming in C. If you actually program in C++, Pascal, VisualBasic or whatever, then you will have to adapt this a little bit. But there is no big effort involved.

The principle of using GraphZ in your application is quite simple. You have to proceed as follows:

•	Register GraphZ. You will then receive a name and password.

•	GraphZ needs the ControlZ run-time libraries (CZxxxxx.dll). They must be located either in the current directory, or in the Windows (or Windows\system) directory. GraphZ also needs the BWCC.DLL library (Borland Windows Custom Controls).

•	Possibly, you will have to tell GraphZ about the location of the User's Guide help file.

•	Either link with the GraphZ.LIB import library, or modify your project's DEF file.

•	Add the following line to your source files.:

#include "GraphZ.h"

•	At the beginning of your application (a good idea is to do this is the WinMain function), make the following call:

GZRegister (your name, your password);

and possibly also:

GZSetWMFLogo (filename);

•	Create one or more GraphZ child window(s).

•	One way for that is make a call to the API CreateWindow function with the string "GraphZ" as the first parameter (i.e. the window class name).

•	Another way is to do this in your resource definition file (*.rc). For instance, in a dialog box definition, you can add a line like this:

CONTROL "", ID_GRAPH, "GraphZ", WS_CHILD | WS_CLIPCHILDREN | WS_VISIBLE, 10, 10, 300, 200

Possibly, your resource editor will complain about the fact that "GraphZ" is not a defined control calss at that time, but that's okay.

Note that the window's name (first parameter of the CONTROL statement, and second parameter of the CreateWindow API function) has no effect.

The GraphZ window must at least have the WS_CHILD | WS_CLIPCHILDREN style.

It is important that you ensure that the DLL has been loaded before you attempt to create a window. Otherwise the "GraphZ" class will not be available and window creation will fail. Therefore I recommend you call GZRegister at the beginning of your program (even with dummy parameters) to force the DLL to load.

•	GraphZ initializes a graph with default values. Then you may:

1	Directly provide the settings:

GZSetSettings (hGraphWindow, GRAPH structure);

2	Load the settings from a given settings file:

GZSetIni (hGraphWindow, lpszSettingsFilename);

GZLoadIni (hGraphWindow);

Note that you can do this at any time and repeat it any number of times.

Note that there is a GRAPH structure associated with each GraphZ window. You will find this structure as parameter of a number of functions.

•	Pass your data to GraphZ each time new data comes in. You'll probably want to do this in an interupt handling routine (a simple example being the WM_TIMER message).

GZAddPoints (hGraphWindow, values, nNumValues);

•	Make a case-insensitive link (and imports) of your application. Compile with 1-byte structure alignement.

•	The user may also modify the settings at run-time. Before this modication actually takes place, GraphZ will notify its parent window with a notification message. You must handle this message and return TRUE if you validate the user action or FALSE if you reject it.

See also:

Functions, Structures and Constants.

A note about sizing.

The source code of the demo program included in the GraphZ.zip package.


Resizing the graph window

GraphZ provides no (re)sizing functionality (unless you create the window with the WS_OVERLAPPED style, but you probably won't want to do that). Three common cases are:

•	The graphs are on a dialog box and their size is fixed.

•	You have one GraphZ and handle the WM_SIZE message of your application's main window so the GraphZ window will always occupy the entire client area.

•	You make a MDI (Multiple Document Interface) application where each MDIClient window has one child: the GraphZ window. Your application takes care of always keeping the GraphZ window exactly the size of the MDIClient window client's area.

When resizing its window, GraphZ tries to make the best possible use of the available place. Still there are a couple considerations to do on that subject:

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

•	The logo, if any, will appear on the top-right corner and will be sized to fit the title's height.

•	The title will remain right aligned remain but will be truncated if needed.

•	The legend does not affect the sizing of the GraphZ window.


In order to be able to use the GraphZ library in your program, you have to tell the linker to import the GraphZ functions from the DLL. You do this by one of the following alternatives:

•	Link your program with the GraphZ.LIB import library, or

•	Include the following line in your project's DEF file:

IMPORTS

GZRegister=GraphZ.1

GZAddPoints=GraphZ.2

GZGetSettings=GraphZ.3

GZSetSettings=GraphZ.4

GZWriteIni=GraphZ.5

GZLoadIni=GraphZ.6

GZSetIni=GraphZ.7

GZMakeDate=GraphZ.8

GZExtractTime=GraphZ.9

GZExtractDate=GraphZ.10

GZMakeDuration=GraphZ.11

GZAddPointsSeries=GraphZ.12

 	GZShowSettingsDialog=GraphZ.13

 	GZPrint=GraphZ.14

GZShowAllObjects=GraphZ.15

 	GZClearBuffer=GraphZ.16

 	GZRefresh=GraphZ.17

GZSetWMFLogo=GraphZ.18

 	GZGetNow=GraphZ.19

 	GZClearCurveBuffer=GraphZ.20

 	GZAddCurveSegment=GraphZ.21

 	GZGetCurveSettings=GraphZ.22

GZSetCurveSettings=GraphZ.23

GZGetTitle=GraphZ.24

GZSetTitle=GraphZ.25

GZSetBufferLength=GraphZ.26

GZSetNumCurves=GraphZ.27

GZStartDisplayAt=GraphZ.28


In either of the following cases:

1	the GraphZ User's Guide help file ("GraphZ.hlp") is located neither in your application's directory, nor in the windows (or windows\system) directory; or

2	you have renamed this file; or

3	you want to provide another kind of help file to your users;

you will have to add the following lines to your WIN.INI file:

[GraphZ]

HelpFile=<the path and name of the GraphZ User's Guide help file>


Functions, structures and constants

The "GraphZ.h" header file defines the following:

Functions:

Initialization:

GZRegister

GZSetWMFLogo

Settings file:

GZSetIni

GZLoadIni

GZWriteIni

Settings:

GZGetSettings

GZSetSettings

GZGetcurveSettings

GZSetCurveSettings

GZGetTitle

GZSetTitle

GZSetNumCurves

GZSetBufferLength

Plotting:

GZAddPoints

GZAddPointsSeries

GZAddCurveSegment

Date and Time: (objects)

GZMakeDate

GZMakeDuration

GZExtractDate

GZExtractTime

GZGetNow

Interaction:

GZShowSettingsDialog

GZPrint

GZShowAllObjects

GZClearBuffers

GZClearCurveBuffer

GZRefresh

GZStartDisplayAt

GZZoom

GZUnzoom

Structtures:

GRAPH

CURVE

TITLE

GZNOTIFY

GZPOINT

Constants:

Symbols

Date & Time display formats

Colors

Notification message:

Any GraphZ's parent window will receive a notification message upon user action. That is:

hWnd = GraphZ's parent window.

iMessage = WM_COMMAND.

wParam = GraphZ's window id.

(LPGZNOTIFY)lParam = far pointer to a GZNOTIFY structure.

You will have to look at this structure and return either TRUE or FALSE to validate or reject the user action.

See also:

Settings file format.

Settings constraints.


GZRegister

BOOL FAR PASCAL GZRegister (LPSTR szName, LPSTR szCode)

szName is the name that you registered your copy of GraphZ with.

szCode is the password you received when you registered your copy of GraphZ.

return value:

Non-zero if the registration is okay, zero otherwise. In that case the graph title will be forced to be the string "GraphZ: Unregistered Copy".


GZLoadIni

void FAR PASCAL GZLoadIni (HWND hWnd)

hWnd is the window handle of the GraphZ window for which you want to load the settings from a settings file.

The name of the settings file is contained in the GRAPH structure associated with the window. This is the szIniFile item. You may set or modify this file name by making use of either the GZSetSettings or, preferably the GZSetIni function.

If the settings file cannot be read or does not provide certain settings, default values will be provided.

If hWnd is not a GraphZ window, this function has no effect.

See also:

GZSetIni

GZWriteIni

GZSetSettings


GZWriteIni

void FAR PASCAL GZWriteIni (HWND hWnd)

Dumps the current settings of a GraphZ window to its associated settings file. The settings file name must be set in the GRAPH structure.

hWnd is the GraphZ window for which to save the settings.

This function has no effect if:

•	hWnd is not a GraphZ window, or

•	the settings file name is empty or incorrect, or

•	the file cannot be written (write protection, etc.)


GZSetIni

BOOL FAR PASCAL GZSetIni (HWND hWnd, LPSTR lpszIniFile)

This function sets the given settings file name in the GRAPH structure associated with the given GraphZ window. It does not modify the other member of the structure (use GZSetSettings). It does not load the settings from the file (use GZLoadIni).

hWnd is the GraphZ window for wich you want to set the settings file name.

lpszIniFile is the name of the settings file.

return value:

Zero if hWnd is not a GraphZ window. Non-zero otherwise.


GZGetSettings

BOOL FAR PASCAL GZGetSettings (HWND hWnd, LPGRAPH lpGraph)

Gets the current settings for the given GraphZ window.

This includes the curve settings, title, etc.

hWnd is the GraphZ window for which to retrieve the settings.

lpGraph is a far pointer to the GRAPH structure that is to receive the settings.

return value:

Zero if hWnd is not a GraphZ window. Non-zero otherwise.

See also:

GZSetSettings

GZGetCurveSettings

GZGetTitle

GZLoadIni


GZSetSettings

BOOL FAR PASCAL GZSetSettings (HWND hWnd, LPGRAPH lpGraph)

This function replaces the current settings for the given GraphZ window, by the given settings. This is equivalent to user pressing the "Ok" button from the settings dialog box.

hWnd is the GraphZ window for which to replace the current settings.

lpGraph is a far pointer to a GRAPH structure specifying the new settings.

return value:

Zero if hWnd is not a GraphZ window. Non-zero otherwise.

Note:	If some of the provided settings do not comply to the constaints, they will be automatically corrected.

Note:	If you change the buffer length, the buffer will be cleaned up, which means you will loose all the historical data stored so far.

See also:

GZGetSettings

GZSetCurveSettings

GZSetTitle

GZWriteIni


GZGetCurveSettings

BOOL FAR PASCAL GZGetCurveSettings(HWND hWnd, LPCURVE lpCurve, WORD nCurve);

Gets the current settings for the given curve of a GraphZ window

hWnd is the GraphZ window for which to retrieve the settings.

lpCurve is a far pointer to the CURVE structure that is to receive the settings.

nCurve is the 0-based number of the curve from which to retreive the settings.

return value:

FALSE if hWnd is not a GraphZ window, if nCurve is invalid or if the curve was not allocated.

TRUE otherwise.

See also:

GZGetSettings

GZSetCurveSettings


GZSetCurveSettings

BOOL FAR PASCAL GZSetCurveSettings(HWND hWnd, LPCURVE lpCurve, WORD nCurve);

This function replaces the current settings for the given curve of the given GraphZ window, by the given settings.

hWnd is the GraphZ window for which to replace the current curve settings.

lpCurve is a far pointer to a CURVE structure specifying the new settings.

nCurve is the 0-based number of the curve for which to replace the settings.

return value:

FALSE if hWnd is not a GraphZ window, if nCurve is invalid or if the curve was not allocated.

TRUE otherwise.

Note:	If some of the provided settings do not comply to the constaints, they will be automatically corrected.


GZGetTitle

BOOL FAR PASCAL GZGetTitle(HWND hWnd, LPTITLE lpTitle);

Gets the current title settings (title strings, style, etc.) for the given GraphZ window.

hWnd is the GraphZ window for which to retrieve the title settings.

lpTitle is a far pointer to the TITLE structure that is to receive the title settings.

return value:

FALSE if hWnd is not a GraphZ window.

TRUE otherwise.

See also:

GZGetSettings

GZGetCurveSettings


GZSetTitle

BOOL FAR PASCAL GZSetTitle(HWND hWnd, LPTITLE lpTitle);

Replaces the current title settings for the given GraphZ window, by the given ones.

hWnd is the GraphZ window for which to set the title settings.

lpTitle is a far pointer to the TITLE structure containing the new title settings.

return value:

FALSE if hWnd is not a GraphZ window.

TRUE otherwise.

See also:

GZSetSettings

GZSetCurveSettings


GZSetBufferLength

BOOL FAR PASCAL GZSetBufferLength(HWND hWnd, LONG lBufferLength);

This function allows you to directly adjust the length of the already allocated buffer(s), without having to call the overal GZSetSettings function.

If the length you give differs from the previous length, then for all the already allocated curves, the buffer will be erased (thus cleared) and re-allocated again with the given length.

hWnd is the GraphZ window for which to change the length of the buffer(s).

lBufferLength is the desired new length for the buffer of each curve. This is expressed in number data elements (not in bytes). Please consider physical storage limitations...

return value:

FALSE if hWnd is not a GraphZ window, or if the buffer(s) for some curve(s) could not be allocated.

TRUE otherwise.

Note: If the buffer length is unchanged, the function returns TRUE but the buffers are not re-allocated and all the data is kept.

See also:

GZSetSettings

GZSetNumCurves

Changing the number of curves and the buffer length.


Changing the number of curves and the buffer length.

Very often you want to adjust the number of allocated curves and the length of the buffer at the same time. You do this by calling either the overall GZSetSettings function, or by calling successively GZSetNumCurves and GZSetBufferLength.

In order to avoid problems with physical storage limitations, you should take care of calling these last two functions in the best order. For example, supposing the settings were previously: 2 curves and 50000 buffer length:

bad:	prefered:

GZSetNumCurves(hWnd, 10);	GZSetBufferLength(hWnd, 500);

GZSetBufferLength(hWnd, 500);	GZSetNumCurves(hWnd, 10);


GZSetNumCurves

BOOL FAR PASCAL GZSetNumCurves(HWND hWnd, WORD nNumCurves);

This function allows you to directly adjust the number of allocated curves, without having to call the overal GZSetSettings function. Already allocated curves are left unchanged. The curves in exceed are first removed and then missing curves are allocated with the buffer length as defined in the GRAPH structure..

Curves are numbered with a 0-based number. This is the index in the .curves[] array of the GRAPH structure. Curves are allocated strating at number 0, and going up to the whished number.

hWnd is the GraphZ window for which to change the number of allocated curves.

nNumCurves is the desired number of allocated curves for this graph. It must not be greater than NUM_CURVES. Please consider physical storage limitations...

return value:

FALSE if hWnd is not a GraphZ window, or if the buffer(s) for some curve(s) could not be allocated.

TRUE otherwise.

See also:

GZSetSettings

GZSetBufferLength

Changing the number of curves and the buffer length.


GZAddPoints

BOOL FAR PASCAL GZAddPoints (HWND hWnd, LPGZPOINT lpPoints, WORD nNumCurves)

Adds nNumCurves new incomming points to a graph, ideally one point for each curve.

Then, performs an incremental scale calculation and display.

hWnd is the GraphZ window to add new data to.

lpValues is a long pointer on an array of GZPOINT's to add to the graph. The intension is that each point in this array is for a different curve. If some curves are not allocated, GraphZ will try to allocate them on the fly, based on default settings.

nNumCurves is the number of elements in the lpValues array.

return value:

Zero if hWnd is not a GraphZ window, or if GraphZ failed to allocate some curves on the fly. Non-zero otherwise.

Note:	In logarithmic scale mode, you should take care of providing strictly possitive values. However GraphZ actually does some error prevention on that subject.

See also:

GZAddCurveSegment

GZAddPointsSeries


GZAddPointsSeries

BOOL FAR PASCAL GZAddPointsSeries (HWND hWnd, GZPOINT FAR **lpPointsSeries, WORD nNumCurves, WORD nArrayLength)

Basically repeats GZAddPoints for each element of the lpPoints array. It is just much more efficient because the scaling and refresh is done only once at the end. Still, this is a complete rescaling and refresh (not incremental) so this function will be only efficient if the number of points is not too small, in which case you may consider using GZAddPoints.

In case you deal only with one curve at a time, then you may prefer the GZAddCurveSegment function.

hWnd is the GraphZ window to add new data to.

lpPointsSeries is a far pointer on a series of arrays of GZPOINT's to add to the graph. Folowwing the increasing order of indexes in the series, x-values of the GZPOINT structures must be sorted in the increasing order, for each curve.

nNumCurves is the number of points in each *lpPointsSeries array. (same as in GZAddPoints)

nArrayLength is the number of elements in the series.

Merely, lpPointsSeries should be allocated as:

double far lpPointsSeries[nArrayLength][nNunCurves];

return value:

Zero if hwnd is not a GraphZ window or if it failed to allocate some curves on the fly. Non-zero otherwise.

Note:	In logarithmic scale mode, you should take care of providing strictly possitive values. However GraphZ actually does some error prevention on that subject.

Note:	If you allocate lpPointsSeries as show above as static data, don't make it too big or your compiler may complain about the size of the data segment.

See also:

GZAddCurveSegment

GZAddPoints


GZAddCurveSegment

BOOL FAR PASCAL GZAddCurveSegment(HWND hWnd, double FAR *lpX, double FAR *lpY, LONG lNumPoints, WORD nCurve);

Adds lNumPoints points to one curve in the graph. Like for GZAddPointsSeries, the display and scaling is done only once, after all the points have been added. But this is a complete rescaling and refresh so in some cases, an incremental scaling and display (GZAddPoints) may be prefered.

Because this function deals with only one curve, there is no need for using a GZPOINT structure as parameter and thus can pass directly two arrays for the x and y value.

Another advantage of this function is that the number of elements in both arrays in virtually unlimited. In the limit of physical storage, you may thus allocated big arrays with GlobalAlloc and pass them directly.

hWnd is the GraphZ window to add new data to.

lpX is a far pointer on an array of x-values for the points to add.

lpY is a far pointer on an array of y-values for the points to add.

lNumPoints is the number of points to add, that is, the number of elements in the lpX and lpY arrays. lpX and lpY must contain the same number of elements.

nCurve is the 0-based number of the curve this data belongs to. It must be < NUM_CURVES. If the curve has not been allocated, then GraphZ allocates it on the fly, based on default settings.

return value:

Zero if hwnd is not a GraphZ window or if it failed to allocate the curve on the fly. Non-zero otherwise.

See also:

GZAppPoints

GZAddPointsSeries


GZMakeDate

void FAR PASCAL GZMakeDate(double FAR *lpDateTime, WORD nDay, WORD nMonth, WORD nYear, WORD nHour, WORD nMinute, WORD nSecond, WORD nHundredth)

Builds a date & time variable out of its components.

lpDateTime is a far pointer to a double that is to receive the date/time value.

nDay is the day component of the date & time variable to build.

nMonth is the month component of the date & time variable to build.

nYear is the year component of the date & time variable to build.

nHour is the hour component of the date & time variable to build.

nMinute is the minute component of the date & time variable to build.

nSecond is the second component of the date & time variable to build.

nHundredth is the hundredth-of-a-second component of the date & time variable to build.

See also:

Date & Time constraints.


GZMakeDuration

void FAR PASCAL GZMakeDuration(double FAR *lpDuration, WORD nDays, WORD nHour, WORD nMinute, WORD nSecond, WORD nHundredth);

Builds a date & time variable out of its components. Unlike the GZMakeDate function, GZMakeDuration is not intended for absolute date/time values but for relative durations. When you add a duration to an absolute date, you still get an absolute date. For example you may write the following:

CZMakeDate(&d0, ...);

CZMakeDuration(&d, ...);

d0 += d;

lpDateTime is a far pointer to a double that is to receive the date/time value.

nDays is the number of days component of the date & time variable to build.

nHour is the number of hours component of the date & time variable to build.

nMinute is the number of minutes component of the date & time variable to build.

nSecond is the number of seconds component of the date & time variable to build.

nHundredth is the number of hundredth-of-a-second component of the date & time variable to build.

See also:

Date & Time constraints.

Note: The reason why GZMakeDate and GZMakeDuration do not return directly a double, is to avoid linkage problems.


GZExtractDate

void FAR PASCAL GZExtractDate (double datetime, LPINT lpnDay, LPINT lpnMonth, LPINT lpnYear)

Extracts the date components out of a date & time variable.

datetime is the variable to extract the date components from.

lpnDay is a far pointer to an integer that is to receive the day component.

lpnMonth is a far pointer to an integer that is to receive the month component.

lpnYear is a far pointer to an integer that is to receive the year component.

See also:

Date & Time constraints


Date & Time variables

GraphZ uses the double C variable type to represent date & time values. This has the advantage that calculations such as adding time can be performed rapidly. Another advantage is that there is virtually no difference between normal numbered x-axis and a date & time x-axis.

The integral part of the floating point value represents the number of days since 1/1/1900.

The fractionnal part represents the fraction of a day. For instance 1h is 1/24, 1m is 1/1440, etc.

For your convenience GraphZ provides functions for dealing with date & time values:

•	GZMakeDate

•	GZMakeDuration

•	GZExtractDate

•	GZExtractTime

•	GZGetNow


Date & Time constraints

The date and time variables and components have the following boundaries:

variable	minimum value	maximum value

datetime	0.0 (1/1/1900)	73050.0 (1/1/2100)

day	1	28, 29, 30 or 31

month	1	12

year	0 (prefered) or 1990	200 (prefered) or 2100

hour	0	23

minute	0	59

second	0	59

hundredth	0	99


Date and Time

In addition to the date & time functions,  and the date & time support for the x-axis, GraphZ provides also user-interface objects for easily displaying and selecting a date, time, date & time, or duration. One example of those is in the x-axis settings dialog box.

Those date & time user-interface objects are actually part of the ControlZ library, which is already licenced inside GraphZ. Thus you may freely use them, like any other ControlZ object in fact.


GZExtractTime

void FAR PASCAL GZExtractTime (double datetime, LPINT lpnHour, LPINT lpnMinute, LPINT lpnSecond, LPINT lpnHundredth);

Extracts the time components out of a date & time variable.

datetime is the variable to extract the time components from.

lpnHour is a far pointer to an integer that is to receive the hour component.

lpnMinute is a far pointer to an integer that is to receive the minute component.

lpnSecond is a far pointer to an integer that is to receive the second component.

lpnHundredth is a far pointer to an integer that is to receive the hundredth-of-a-second component.

See also:

Date & Time constraints


GZGetNow

void FAR PASCAL GZGetNow (double FAR *lpNow);

Fills a date & time variable with the current system date and time.

lpNow is a far pointer to the date & time variable to receive the current date and time.

See also:

Date & Time constraints


GZShowSettingsDialog

BOOL FAR PASCAL GZShowSettingsDialog(HWND hWnd);

This function is equivalent to the user clicking the "Settings" button. It pops up the main settings dialog box.

Thsi function is provided in case the settings button is not available and if you want to embed this, for instance, as a menu function.

hWnd is the handle of the GraphZ window of which you want to pop up the settings dialog.

return value:

FALSE if hWnd is not a GraphZ window or if there is another problem. TRUE otherwise.


GZPrint

BOOL FAR PASCAL GZPrint(HWND hWnd, BOOL bUseDefaultPrinter);

Prints a GraphZ graph.

•	hWnd is the window handle of a GraphZ window that you want the graph to be printed.

•	bUseDefaultPrinter, if TRUE, directs GraphZ to use the default windows printer without showing the print dialog box. Watch out: when doing so, GraphZ will not force the Landscape paper orientation. If this parameter is FALSE, the print dialog box will be displayed just as if the user had clicked the "Print" button.

In any case the print job percentage message box will be displayed.

return value:

FALSE if hWnd is not a GraphZ window or if there is another problem. TRUE otherwise.


GZShowAllObjects

BOOL FAR PASCAL GZShowAllObjects(HWND hWnd, BOOL bShow);

Shows or hides the object balk on the bottom of a GraphZ window. This contains the slider, the "Print", "Settigns" and "Legend" buttons, and the mouse tracking window.

Hiding the objects balk can be useful to either prevent the user to do anything unexpected, or make some free space for the graph itself.

This function is equivalent to setting the bShowAllObjects attribute of the GRAPH structure to bShow.

hWnd is the window handle of a GraphZ window.

bShow directs GraphZ to either show or hide the objects balk.

return value:

FALSE if hWnd is not a GraphZ window or if there is another problem. TRUE otherwise.


GZClearBuffers

BOOL FAR PASCAL GZClearBuffers(HWND hWnd);

Clears all the buffers (for each curve) of a given GraphZ window. All the curves data will be lost and the curves will begin again the next time data will be passed. The curve settings ramain valid and the buffers remain allocated.

hWnd is the window handle of a GraphZ window.

return value:

FALSE if hWnd is not a GraphZ window. TRUE otherwise.


GZClearCurveBuffer

BOOL FAR PASCAL GZClearCurveBuffer(HWND hWnd, WORD nCurve);

Clears the buffer for one given each curve of a given GraphZ window. All the data for this curve will be lost and the curve will start again the next time data will be passed. The curve settings remain valid and the buffer remain allocated.

hWnd is the window handle of a GraphZ window.

return value:

FALSE if hWnd is not a GraphZ window or if the given curve is invalid or was not allocated yet. TRUE otherwise.


GZRefresh

BOOL FAR PASCAL GZRefresh(HWND hWnd);

Performs a refresh of the given GraphZ window. That includes a complete recalculation of the sizes and positions of the different items and a complete rescaling in autoscale mode.

hWnd is the window handle of a GraphZ window.

return value:

FALSE if hWnd is not a GraphZ window or if there is another problem.

TRUE otherwise.


GZStartDisplayAt

BOOL FAR PASCAL GZStartDisplayAt(HWND hWnd, double xDisplayStart);

This function allows you to set the slider position to where you want. It is equivalent to the user dragging the slider.

In addition, it has the advantage that you may tell the slider to position itself so as to display x-values that are normally not reachable. For example if the graph contains points of which the x values range from 10 to 100, then the user has only acess via the slider to the range 10 to max(100, 10+xRange). With this function, you still can access whatever x-value. For instance you can let the display start at 0, even though the first point would come at 10.

This may be usefull when you have several separate graph windows, and you want the displayed range in all the windows to be exactly the same.

Note that the effect of this function is not permanent. That is, as soon as there will be some scrolling, the available range will return to normal.

hWnd is the handle of a GraphZ window.

xDisplayStart is the x-value that you want the display to start at, that is, the leftmost x-value in the curves window.

return value:

FALSE if hWnd is not a GraphZ window or if there is another problem.

TRUE otherwise.

Note:	In case the x-axis is a date/time axis, you may want to make a user-interface to enter this xDisplayStart value. For this purpose is is advised that you use the provided date & time objects.


GZSetWMFLogo

BOOL FAR PASCAL GZSetWMFLogo(LPSTR szFileName);

Informs the GraphZ library about the logo to use for all the GraphZ windows.

Note that you will have to perform a refresh on your windows for the change to be visible.

szFileName is the name of a window metafile (WMF) to use for the logo. It is recommended to prefix this name by ".\\" to indicate the current directory.

return value:

FALSE if the file could not be found or read or if it has an unknown format. TRUE otherwise.

There is only one logo at a time supported by the GraphZ library. It basically represents your application. The logo is optional. GraphZ only supports windows metafiles (WMF) for the logo.

The logo, if any, will appear on the top-right corner, aside the title. It will be proportionally  resized to fit the title's height.

GraphZ skips any SelectPalette and RealizePalette record in the metafile, in order to prevent frequent palette realization, screen blinking, colors inacuracy and a lot of wasted time.

This basically means you should provide a metafile that does not use palette colors. Normal RGB colors are okay, but no PALETTERGB or PALETTEINDEX. If so, the colors will not be the original ones and will be mapped to the GraphZ palette and possibly animated at undesired times...

In summary, try to provide a simple, black and white logo. Avoid shading and time consuming features. Avoid using palette colors. Note that many drawing packages that produce WMF files use a palette by default, even if your drawing uses only two colors.


GZZoom

BOOL FAR PASCAL GZZoom(HWND hWnd, double xMin, double xMax, double yMin, double yMax);

Performs a "zoom in" of the curves display window. This is equivalent to the user selecting a zoom area by clicking and dragging the mouse.

Note that after this, if the action is successful, the y-axis isreset to manual scaling.

hWnd is the window handle of a GraphZ window.

xMin, xMax define the x-range of the zoom-in rectangle. xMin must not be equal to xMax.

yMin, ymax define the y-range of the zoom-in rectangle. yMin must not be equal to yMax.

return value:

FALSE if hWnd is not a GraphZ window or if the given zoom-in rectangle is empty. TRUE otherwise.


GZUnzoom

BOOL FAR PASCAL GZUnzoom(HWND hWnd);

Performs an unzoom of the curves display window. That is, brings the range settings back to what they where before the last zoom-in action. This is equivalent to the user pressing the "Unzoom" button.

Note that after this, if the action is successful, the y-axis isreset to manual scaling.

hWnd is the window handle of a GraphZ window.

return value:

FALSE if hWnd is not a GraphZ window. TRUE otherwise. Note that Unzooming is only performed if a zoom-in had been performed before. But this is not considered as an error and it does not cause the return value to be FALSE.


Curve

A GraphZ graph displays a number of curves simultaneously. This is fixed by the settings and is represented by the numCurves item of the GRAPH structure associated with the GraphZ window.

In order to define the settings for each curve, and array of CURVE srtuctures is present in the GRAPH structure. A curve is a series od points provided by your application (GZAddPoints). All the curves are plotted inside the curves box. The curves box is subject to a sliding window mechanism (that is, it is scrolled forth whenever your application adds new data, and the user may scroll it back and forth as desired). Depending on the curve settings, each curve is plotted with a given pen. Each point is linked to the previous and next one with a line, and a symbol is plotted to represent the point. A curve also has a name (legend).

A detailled description of all the settings can be found in the User's Guide.

The CURVE structure is defined as follows in the "GraphZ.h" header file:

typedef struct

{

char	szLegend[41];	/* name for this curve (ie. legend) */

LOGPEN	pen;	/* logical color pen */

BYTE	nSymbol;	/* symbol for use in the normal case */

BOOL	bNoLine;	/* plot no line, only symbols */

BOOL	bAlarms;	/* check for alrams ? */

ALARM	alarmLow, alarmHigh;	/* Alarm settigns... */

BYTE    reserved[10];	/* for internal and future use. Do not modify ! */

} CURVE, NEAR *PCURVE, FAR *LPCURVE;

See also:

Settings constraints.

ALARM structure.


More details can de found about alarms in the Curves Settings section of the User's Guide.


Alarm

When plotting curves, GraphZ gives you the possiblity to test for alarm conditions on the fly and to display such events and conditions.

The condition consists of a low (resp. high) threshold beyong which y-values will be considered to be in low (resp. high) alarm. Alarm thresholds can be represented visually by an horizontal line.

Points that meet an alarm condition can be plotted with a symbol different from the one used in normal conditions, so they get more attention.

The "GraphZ.h" header file defines the following structure for specifiy alarm settigns. There are two of thoses structures (for low and high) in each CURVE structure.

typedef struct

{

double	limit;	/* The threshold value */

BYTE	nSymbol;	/* Symbol to draw if a point goes beyond the limit */

BOOL	bHorizontalLineAtLimit;	/* Draw an horizontal line to show the limit */

LOGPEN	pen;	/* Pen to use for the horizontal line */

BYTE	reserved[2];	/* reserved for internal use. Do not modify ! */

} ALARM, NEAR *PALARM, FAR *LPALARM;


Graph

A GraphZ window stores all the settings related the its graph in a GRAPH structure. This structure is also used as parameter of a number of functions.

A detailled description of all the settings can be found in the User's Guide.

The GRAPH structure is defined as follows in the "GraphZ.h" header file:

#define NUM_CURVES	16

#define MAXFONTNAME	41

typedef struct

{

char	szIniFile[81];	/* the path and filename of the settings file */

TITLE	title;	/* the graph's title */

char	szXLabel[41];	/* label for the X axis (horizontal) */

char	szYLabel[41];	/* label for the Y axis (vertical) */

double	xRate;	/* real interval between two successive entries */

 	double	xStart;	/* real x-value of the first entry */

double	xRange;	/* real x-value range that has to be displayed */

double	yMin, yMax;	/* y-scale boundaries when not in autoscale mode */

 	double	logBase;	/* base for logarithm scaling (eg. 10 for decimal log) */

 	BOOL	bAutoscale;	/* autoscale the Y axis */

BOOL	bLogarithmic;	/* logarithmic Y-scale */

BOOL	bGrid;	/* display a grid ? */

BOOL	bTics;	/* display tics and tic labels */

BOOL	bMouseTrack;	/* display the real under mouse point coordinates */

WORD	wTimeFormat;	/* date/time display format code for the x axis */

LONG	bufferLen;	/* number of buffered values for each curve */

WORD	numCurves;	/* number of curves to be displayed */

char	szFontName[MAXFONTNAME];	/* font family name for all but the title */

int	nFontSize;	/* font size in pts */

COLORREF	background;	/* curves-box background color */

LOGPEN	penGrid;	/* the pen to use for the grid */

LOGPEN	penTics;	/* the pen to use for the tics */

CURVE	curves[NUM_CURVES];	/* the curves definition */

BYTE	reserved[530];	/* for indernal and future use. Do not modify ! */

} GRAPH, NEAR *PGRAPH, FAR *LPGRAPH;

See also:

Settings constraints.


See for further details the description of the horizontal scale in the User's Guide.


Number of displayed curves

The number of displayed curves in a given GraphZ graph is fixed by the numCurves item of the associated GRAPH structure. There is a maximum of NUM_CURVES (16) curves per graph.

Your application supplies data (GZAddPoints) for a certain number of curves. When this differs from numCurves, then GraphZ either:

•	tries to allocate the missing curves on the fly (which implies that the curve settings and buffer will be reset), or

•	generates data for the curves that your application does not feed. This feature is realated to alarm (see further details in the User's Guide).


Title

A GraphZ graph has a title which is displayed and printed above the graph itself. The title will always be centered on the curves box. Possibly it will have to be truncated. There the User's Guide for a more detailed description.

The title can have a number of formatting attributes that make the graph more attractive. Hence a TITLE structure has been defined to store those attributes.

The TITLE structure is defined as foollows in the "GraphZ.h" header file:

typedef struct

{

char	szTitle[81];	/* the graph's tile */ 	char	szFontName[MAXFONTNAME];	/* title font family name */

int	nFontSize;	/* title font size in pts */

BOOL	bBold;	/* bold or regular */

BOOL	bItalic;	/* italic or regular */

BOOL	bUnderline;	/* underline or not */

BOOL	bGraved;	/* graved or not (display only) */

BOOL	bEmbossed;	/* embossed or not (display only) */

BOOL	bBorder;	/* border or not (display only) */

COLORREF	color;	/* RGB text color (ignored for sculpted styles ) */

 	} TITLE, NEAR *PTITLE, FAR *LPTITLE;

Notes:

•	When your GraphZ copy is unregistered (call the GZRegister function), the text "GraphZ: Unregistered Copy" will appear instead.

•	The bGraved and bEmbossed attributes are mutually exclusive. When boths are set, bGraved has precedence.

•	When bBorder is non-zero, a graved border is drawn. The exception is when bGraved is also non-zero, in which case an embossed border is drawn.

•	When either bGraved or bEmbossed is non-zero, the color has no effect.

•	bBorder, bGraved and bEmbossed are ignored for printing. The color is used instead.

•	The title text is given by the szTitle attribute of the TITLE structure. The window name (ie, second parameter of the API CreateWindow function) has no effect.


GZNotify

Any GraphZ's parent window will receive a notification message upon user actions. That is:

hWnd = GraphZ's parent window.

iMessage = WM_COMMAND.

wParam = GraphZ's window id.

(LPGZNOTIFY)lParam = far pointer to a GZNOTIFY structure.

The GZNOTIFY structure is defined in the "GraphZ.h" header file as:

typedef struct

{

WORD	wNotify;	/* Notification code (see below) */

HWND	hWnd;	/* Handle of the GraphZ window that is notifying its parent */

LPGRAPH	lpGraph;	/* far pointer to a GRAPH structure */

LPSTR	lpszFileName;	/* settings file name */

} GZNOTIFY, NEAR *PGZNOTIFY, FAR *LPGZNOTIFY;

You will have to look at this structure and return either TRUE or FALSE to validate or reject the user action.

The "GraphZ.h" header file also defines the following possible values for the wNotify code:

#define GZUA_SETSETTINGS 1	/* The user clicked OK in the Settings dialog box. */

/* The settings are about to be changed. */

/* lpGraph = the new settings as wanted by the user. */

/* You may modify the values in lpGraph. */

/* lpszFileName = settings file name */

#define GZUA_LOADSETTINGS 2	/* The user clicked LOAD in the Settings dialog box. */

/* The settings are about to be loaded. */

/* lpGraph = NULL. */

/* lpszFileName = settings file name to load from. */

#define GZUA_SAVESETTINGS 3	/* The user clicked SAVE in the Settings dialog box. */

/* The currently active settings are about to be saved. */

/* lpGraph = NULL. */

/* lpszFileName = settings file name to save to. */

Note:	Those notification messages are sent only as a consequence of intereactiv euser actions, not after your clling a function (e.g. GZSetSettings).

Note:	You have to process these messages to authorize the user actions. If you don't process them windows will return 0 and all the user actions will be rejected. So as a minimum you should have something like:

.

.

.

case WM_COMMAND:

switch (wParam)

{

case ID_GRAPHWINDOW:

/* GraphZ asks for validation before user action. */

/* We don't check it in this demo. Always validate */

 	return TRUE;

case ...

}

break;

.

.

.


GZPoint

The GZPOINT structure is used in the GZAddPoints and GZAddPointsSeries function calls.

It is defined as follows:

typedef struct

{

double	x;	/* x-value for this point */

double	y;	/* y-value for this point */

int	curve;	/* 0-based curve number of the curve this point belongs to. */

} GZPOINT, NEAR *PGZPOINT, FAR *LPGZPOINT;

The reason for having the curve number in the structure is because very often when data comes in asynchronously, you will not GZAddPoints for all the curves at the same time.

When you want to add a number of points for one given curve, you'll probably find it more convenient to use the GZAddCurveSegment function.


Colors

GraphZ has extended color support. In a number of places you have to specify a color. Note that GraphZ puts some constraints on the colors you give.

For your convenience, a number of commonly used colors are defined in the "graphz.h" include file:

#define	value	#define	value

COLOR_BLUE	RGB(0,0,255)	COLOR_GREEN 	RGB(0,255,0)

COLOR_RED	RGB(255,0,0)	COLOR_YELLOW	RGB(255,255,0)

COLOR_PURPLE	RGB(255,0,255)	COLOR_CYAN	RGB(0,255,255)

COLOR_GRAY	RGB(128,128,128)	COLOR_NAVY	RGB(0,0,128)

COLOR_BOTTLE	RGB(0,128,0)	COLOR_CARMEN	RGB(128,0,0)

COLOR_BROWN	RGB(128,128,0)	COLOR_MAGENTA	RGB(128,0,128)

COLOR_TEMPEST	RGB(0,128,128)	COLOR_WHITE	RGB(255,255,255)

COLOR_STEAL	RGB(192,192,192)	COLOR_BLACK	RGB(0,0,0)


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

xRange	100	the length of x-range of displayed data

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

TimeFormat	0	a number indicating the display format for the date & time scale, 0 means normal numbered scale.

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

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

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

FontName	Arial	font family name

FontSize	8	font size (in points)

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	font family name

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	SymbolCode

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

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

CheckAlarm	0	check for alarms ? (0 / 1) = (true / false)

[CurveNAlarmLow]	Limit	0	the threshold value for low alarm

Symbol	0	SymbolCode

HLine	0	horiz.line at threshold ? (0 / 1) = (true / false)

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

[CurveNAlarmHigh]	Limit	1	the threshold value for high alarm

Symbol	0	SymbolCode

HLine	0	horiz.line at threshold ? (0 / 1) = (true / false)

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

See also:

Settings constraints.


Symbols

Each curve has 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.

For that purpose the GraphZ.h include file defines the following codes.

#define	value	meaning

SYM_NONE	0	No symbol. Just the line.

SYM_CIRCLE	1	A circle (o) filled with the curves box background brush

SYM_SQUARE	2	A square (ÿ) filled with the curves box background brush

SYM_PLUS	3	A plus sign (+)

SYM_CROSS	4	A cross (x)

SYM_DIAMOND	5	A diamond (◊) filled with the curves box background brush

SYM_DOT	6	A dot (.)

SYM_START	7	A start (*)

SYM_TRIANGLE	8	A triangle (∇) filled with the curves box background brush


Date & Time display formats

As described in the User's Guid, GraphZ extensively supports time scaling, on the horizontal scale (x-axis).

GraphZ can display dates and times in a number of formats. The wTimeFormat item of the GRAPH structure tells GraphZ which display format to use.

wTimeFormat is composed of two parts: the data and the time parts, which you must combine with the bitwise OR operator (|).

Date formats:

#define	value	meaning

DATE_NO	0x0000	no date is displayed

DATE_DMY	0x0001	"DD/MM/YY"

DATE_YMD	0x0002	"YY/MM/DD"

DATE_MDY	0x0003	"MM/DD/YY"

DATE_DmY	0x0004	"DD mon YY"

DATE_YmD	0x0005	"YY mon DD"

DATE_mDY	0x0006	"mon DD, YY"

Time Formats:

#define	value	meaning

TIME_NO	0x0000	no time is displayed

TIME_HM	0x0100	"HH:MM"

TIME_MS	0x0200	"MM:SS"

TIME_HMS	0x0300	"HH:MM:SS"

TIME_S99	0x0400	"SS.99"

TIME_MS99	0x0500	"MM:SS.99"

TIME_HMS99	0x0600	"HH:MM:SS.99"

Note:	When both date and time are specified, the date is displayed first and then the time on the following line.

Note:	When (DATE_NO | TIME_NO) is specified, then no date & time scale is used. A normal numbered scale is used instead.

Note:	In these tables,  DD, MM, YY, mon, HH, MM, SS and 99 stand respectively for the day, month, year, month name, hour, minute, second and hundredth of a second. They are all formatted on 2 charecters excet the month name which occupy three.

Note:	The slash (/) and colon (:) characters used in these tables are only (very common) examples. The actual charecters used by GraphZ are those configured in the WIN.INI file. One can set those by the Control Panel.


Settings constraints

There are some constraints related to the settings, that is, the elements of the GRAPH, CURVE and TITLE structures. In addition, there are also constraints for date & time variables.

Here are the restrictions:

structure	item	restriction

GRAPH	xRange	> 0.0.

Date & time constraints when relevant

yMin, yMax	yMax > yMin.

log error prevention in log scale.

if (yMin == yMax) then yMax += 1.0

logBase	log error prevention.

!= 1.0

 	wTimeFormat	Date & time display format

 	bufferLen	> 0

<= 60000

Look at your available memory.

numCurves	> 0

< NUM_CURVES (16)

szFontName	Specify an existing (on your system) scalable font.

nFontSize	> 0

In points. Making this > 10 quickly becomes ugly.

background	color constraints.

penGrid, penTics	pen constraints.

CURVE	szLegend	GraphZ will try to reserve enough place on the right of the graph to display the legend entirely. Thus, making this too long migh go at costs of the graph readability.

pen	pen constraints.

nSymbol	A valid symbol code. Otherwise SYM_NONE is substituted.

alarmLow, alarmHigh	alarmLow.limit < alarmHigh.limit

ALARM	pen	pen constraints.

nSymbol	A valid symbol code. Otherwise SYM_NONE is substituted.

TITLE	szTitle	If you have not registered your GraphZ copy, the text "GraphZ: Unregistered Copy" will be displayed and printed instead.

bGraved, bEmbossed	Mutually exclusive.

bBorder	Normally a graved border is displayed, except in combination with bGraved where an embossed border is substituted.

The bBorder, bEmbossed and bGraved attributes will have no effect for printing.

color	color constraints.

See also:

Default settings.


Pen Constraints

You specify pens by means of the LOGPEN structure. This structure is defined in "windows.h" as follows:

typedef struct tagLOGPEN {

    UINT     lopnStyle;

    POINT    lopnWidth;

    COLORREF lopnColor;

} LOGPEN;

with the following restrinctions:

•	a number of styles (like PS_SOLID, PS_DOT, etc.) are defined for lopnStyle.

•	lopnWidth.y is not used. lopnWidth.x must be > 0. Only with the PS_SOLID style, lopnWidth.x can be > 1.

GraphZ adds the following restrinctions:

•	lopnStyle may be only PS_DOT (2) or PS_SOLID (0). Any other style will be replaced by PS_SOLID.

•	lopnColor must comply to the colors constraints.


Colors constraints

When you must specify a COLORREF variable, GraphZ puts the restriction that it must be either an RGB or a PALETTERGB value, but not a PALETTEINDEX.


Log(.) error prevention

In logarithmic scale, any value for which the log(.) function has to be calculated undergoes the following tests:

•	value = abs(value)

•	if (value == 0.0) then value = 1.0


Settings file name

The settings file name is stored in the szIniFile item of the GRAPH structure associated with a GraphZ window. You may set or modify this name by the GZSetSettings or preferably the GZSetIni function.

Note:	The settings file name shoud either:

•	include a complete path.

•	be preceeded by ".\" in order to specify the current directory.

•	not include any path, in which case the window directory will be searched.

See also:

Settings file format

GZLoadIni

GZWriteIni


Product Information

This is GraphZ version 1.2.

GraphZ is copyright © 1995, ZSoft. All rights reserved.

All the fancy objects are from the ControlZ library.

ControlZ is also copyright © 1995, ZSoft. All rights reserved.

GraphZ has to be registered to your application. When you register you will get a name and password that you'll have to pass to the GZRegister function at the begining of your program. Please do not tell anybody about these strings. It is even recommended that you do some encryption of them inside your application.

Registering GraphZ will prevent you from having the text "GraphZ: Unregistered Copy" substituted to the graph title.

You need to register GraphZ on a per-copy basis.

Questions:

If you have any question, desire, remark or bug report, please e-mail me at:

czwy@eo.net

See also:

How to register.

Registration form.


How to register

The basic GraphZ registration fee is 17000 FLUX per copy.

You get an overall 50% discount after the 12th copy..

The pricing is as follow (the US$ prices are given only for information, please pay in FLUX):

FLUX	 US$ (info)

GraphZ copy:	17,000	570

GraphZ copy (as of 13th copy):	8,500	285

GraphZ source code:	180,000	6000

GraphZ source code (with 12 copies):	90,000	3000

ControlZ source code (special offer with 12 copies):	60,000	2000

To register, proceed as follows:

•	Fill in the registration form.

•	Send it to:

ZSoft.

6, Rue du Couvent.

L-1363 Howald.

Luxemburg.

or fax it to:

(+352) 40101-201

•	Transfer the registration fee to the following account:

Bank account number: 1203/6378-2

Bank: Banque et Caisse d'Epargne de l'Etat. Luxembourg.

Unfortunately we cannot accept credit cards.

Possibly e-mail us when you have done so, so that we can check it more quickly.

•	As soon as we have notice of your payment from the bank, we will send you back your name and password. You will get nothing more (argh!) since the distributed library is already fully featured and the complete documentation consists of this heelp file, together with the User's Guide help file.


ControlZ is another library copyright by ZSoft, which provides all the fancy controls that are used in GraphZ. You don't have to register it to use GraphZ but it is recommended since both libraries are intended to cooperate together.

The normal registration fee for ControlZ 1.4 is US$ 395 and the source code is available for US$ 4000. This is a special offer for GraphZ users with at least 12 users.


Luxemburgish Franc


GraphZ 1.2 Registration Form

To register GraphZ 1.2, please first deposit the correct amount

on the bank account number 1203/6378-2 of the BCEE bank in Luxembourg.

Then fax or mail us a printed copy of this page. As soon as

we have notification of your payment from the bank you will be

retruned a registration name and a password.

Terms/Conditions:

-----------------

I agree that GraphZ is distributed as shareware. No warranty

exists, either express or implied. No liability is assumed for

any damage or loss resulting from the use of this program. No

claims are made regarding the accuracy of this program. The

author reserves the right to change pricing in future versions.

Your signature below indicates your acceptance of these terms

and conditions.

Product               Nb. Copies      Total (FLUX)

GraphZ                ..........      ............

GraphZ source code    ..........      ............

ControlZ source code  ..........      ............

Total                                 ............

Registration Name: ____________________________________________

(Name you will supply to the GZRegister function.

This is recommended to be your application's name)

Your Complete Name: _______________________________________________________________

Postal Address: _______________________________________________________________

                _______________________________________________________________

                _______________________________________________________________

City: ________________________________ Country: _______________

Phone No: ______________________ Fax No: ______________________

Internet E-mail address: ______________________________________

How do you prefer to receive your user name and password ?

      O. E-Mail      O. Post      O. Fax

Signature: ______________________________ Date: _______________

***************************************************************

* Mail address:    ZSoft. 6, Rue du Couvent.                  *

*                  L-1363 Howald. Luxembourg                  *

* Fax number:      (+352) 40101-201                           *

***************************************************************