KDGraf
Version 2.1 - August 1989
A Product of KD Ranch Enterprises (c)


GENERAL:

KDGraf is a pull-down, menu-driven graphics package for EGA/VGA users.
It will not display graphics on a CGA system. Bars, 3D Bars, Lines,
3D Lines and Pies are supported. Graphs can be saved and retrieved.
They can be printed on most Epson compatible printers (FX-80 and above)
and HP Laser Jets and compatibles (maybe). A maximum of 6 sets of values
can be displayed over 60 occurrences -- i.e., up to 360 values can be shown.

You will need appx. 256K available to run the program.
KDGraf was written in Turbo Pascal 5.0.


HISTORY:

Version 1.0 - Beta Only (April 1988).
Version 1.1 - Initial Release (June 1988).
Version 1.2 - Minor Bug Fixes (Sept.1988).
Version 1.3 - Added Scaling Enhancements (May 1989).
Version 1.4 - Added HP Laser Jet output.
Version 1.5 - Revised print process windows.
Version 2.0 - Increased occurrences from 15 to 60. [See note below!]
Version 2.1 - Implemented full-screen input mode and a few other things.



****************** IMPORTANT NOTE TO USERS OF VERSION(S) 1.x ****************

Due to the increase of the allowable occurences from 15 to 60, the
entire internal data structure of KDGraf had to be revised. As such,
saved grafs (.KDG's) from versions prior to 2.0 cannot be retrieved
properly by this version. I have not include a conversion program for
two reasons: 1). Data entered was usually not that extensive.
2). I have absolutely no idea how to write one.

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



COMMAND SYNTAX: KDGraf [grafname]

The only parameter supported by KDGraf is the name of an existing graph.
All graphs are saved with the extension .KDG. Do not use the extension
when calling a graph with the command parameter. The called graph will be
loaded at startup. The parameter is not required. Any existing graph in
the current directory can be called from within the program.

USAGE:

Upon execution, a pull-down menu system will be displayed.
The idea here is to use the menus to select the type of graph,
input the data, make whatever cosmetic adjustments you might be
interested in, and then display and/or print your graph.

Hopefully, to create a reasonably useful and attractive graph,
this should be pretty simple. If not, the author (me) has failed
in one of the primary goals. There are, however, some intricacies
that may take further explanation -- that's why we have a .DOC file.

I do not plan to describe everything possible in this .DOC file.
Most functions will be obvious. The following information will
concentrate on those that aren't.

Additionally, if the package you have received is intact, there should
be 14 example graphs to help you with most of the functions. All data
and settings used to create these graphs are always included in the
saved graph file and are available from the menu system.

FUNCTIONS:

The Pull-Down Menu System:
These menus operate like most other pull-down systems. Generally,
you hilite your selection with the arrow keys and then press ENTER,
or simply select the item you want by pressing the first character
(KeyLetter) of any item within the current selection menu.

A selection from a menu could do a lot of different things:
- just pull-down another selection menu.
- set an item as data that affects the graph.
- open a data input area asking for you to input some data.
- open a special sub-process for various reasons.
- actually execute something.

What each menu does will become evident rather quickly. The "Help"
function is designed to let you know what might happen to you before
it happens in addition to providing a hint or two about input data.

There are a few special keys that may be of use:
F1 - is usually a "HELP" key and will provide a little information
about where you currently are and what you will get next.
F2 - is the pull/pop key. If a menu is currently displayed, F2 will
pop you all the way back to ground zero (Data Display). If
you are at ground zero, it will pull back all the menus that
were last activated. Data Display can be scrolled for viewing.
F3 - Activates full-screen input mode -- allows input for data,
names and labels only. F3 is only active from ground zero.
This is simply an alternate method to enter chart data. It
can also be entered via the pull-down menus as explained later.
This is the easiest way to enter a lot of data -- try it!
/ - takes you to the Main (Top) Menu from almost everywhere. This is
a very valuable key. For example, the keys "/VG" will show
your graph as long as you are not currently in a process that
requires Esc to leave.
Esc - moves you back one level in the menu process or takes you out of
sub-processes. Sometimes, this is the only avenue of escape.


Message Line:

The last line of the screen, The Message Line, will always show which
keys are active and what they do. Once you play with the menus a
while, you should have little problem.


Menu Detail (based on Main Menu options):

*** Many of the options listed below have some common selection criteria.
Most of these are listed under APPENDIX I. ***

ChartType:
Allows you to select one of 13 types. I am not going to list them
here. When you change a choice here, you are automatically thrown to
the View Graph selection. It may seem a little strange at first, but
I believe you will find it useful.

Data:
Data comes in two varieties - Values and Names. You will find that a
graph is constructed by use of a matrix with the "names" of a set
of "values" listed down the side and "labels" listed along the top.
This is where you enter all that stuff. You will also be allowed to
give specific color and pattern information to each set of values and
names from here. Specific details about what impact the data values,
names, colors and patterns may have are covered as we go on.

Titles:
Three titles can be entered which will automatically be centered on
the top of the graph. From here you also enter the X and Y axis titles
which will be placed appropriately. You can vary the Font, Color, and
Size of any of these (See APPENDIX).

Notes:
Up to 9 notes can be entered and placed on the graph anywhere you
want. Again, Font, Color and Size can be selected along with the
position. The position is controlled by a set of X,Y coordinates.
You will probably have to play with the positioning a bit to get the
note exactly where you want it. For general information, the notes are
connected at the chosen X,Y coordinates at their left center. X
coordinates range from 0 to 639, Y from 0 to 349.

A free-form line drawing capability can be accessed via "Notes".
"Lines" require FromX, FromY, ToX and ToY coordinates. The note
color and size also affect the lines (size "3" gives a thick line).
"Lines"are independent of note text, except where they share color
and/or size.

Enhancements:
This is the most complicated, least necessary, most used and hardest
to explain section of the whole package.This is where most of the
cosmetic changes are made to the graphs. It is also the only menu
that varies with a ChartType selection (a Pie requires different stuff
than the other 12 types do). Here goes:

BackGround - Select a background color. 0 (black) is the default.
Any other color selected causes that color's number to
mean black. That way, you don't lose a color and all
that you had set up will still show when you switch.
Think about it -- it makes sense (I think).
Outline - Tell whether you want an outline around the whole graph
or not. You also have your basic Color, Thickness and
Style choices. The default is ON and color 15.


**** For Bars and Lines -- Pie information to follow ****

X axis line,
Y axis line,
Vert Grid,
Hor Grid - Tell whether you want them and select Color, etc. The
axis defaults are ON and 15. The grids default to OFF.
Annotation - Tell if you want the values and/or labels to be shown
and where (most of the time). The choices are "DO NOT
DISPLAY", "INTERNAL", "EXTERNAL" and "BOTH" (internal
and external). You will have to play with this some to
get it where you like it. It would take the rest of
this file to try to explain all the possibilities and
the effect that each has on the various graphs.
Chart Limits-Assign Low, High and Step Size values for the graph and
set "ROOM" variables for top,bottom,left and right.
Room means just what it implies - how much room should
be available on each of the perimeters. The defaults:
Top and Bottom - 45; Left and Right - 60. These will
handle a "normal" graph. If your numbers are unusually
large, or you make big titles, etc., adjust the room
to accommodate them. Room is also used to squeeze,
elongate and position graphs for different effects.

Also, in 3D mode, a platform depth can be assigned. The
limits are 1 to 349. This is used to help view the
data at slightly different angles -- nothing too
dramatic. All of these values, by default (indicated
by 0), will scale automatically.

**** For Pies [Ok - here's where it gets tough!] ****

Values Attribute,
Percent Attribute,
Labels Attribute - For each of these, select whether you want
them or not, Color, Size and Font. Their
placement is controlled by ANNOTATION (below).
A "bogus" color is allowed to force the color
of these items to match the color of their
respective pie slice. That color is 16 (15 is
normally the limit). The normal defaults are
color-15, Size-0, Font-0 (0 = default) and ON.
InBox Attribute - If you have chosen "INTERNAL" for any of the
above items, they can be surrounded by a box.
Select the attributes for that box here.
A SPECIAL NOTE: The normal style for the InBox
is 0 which means "hollow" and therefore just
lets the background color show through. To
change the color, a style other than 0 must be
selected. The default is ON and "hollow".
Annotation - Similar to annotation from BARS except there
are two more items - PERCENT and NAMES. If you
choose to have the NAMES external you will
also have to indicate side or bottom. Again,
this is best to play with instead of trying to
explain the possibilities.
Size - This is a relative pie size indicator.
Basically, it is expressed as a percentage of
the "normal" full screen pie. The default is
100, but if you don't want room for titles and
stuff, you can go larger. Size becomes very
important if you plan to display more than 1
pie. Again, play with it.
Relationship - This is a Yes/No question. It is primarily
designed to show multiple pies in sizes that
are relative to each other as opposed to
showing them all the same size even though
the total value of each pie is different. The
default is NO. EXTRA: If relationship is YES,
and the pie label is on, the total value of
each pie is shown as part of the label even
if there is only one pie.
Centers - Allows placement of any of the 6 possible pies
using X,Y coordinates. The X,Y coordinate is
where the center of the pie will be drawn.
Coordinates are the same as NOTES. Placing
pies becomes very important when using the
RELATIONSHIP option. You'll see.

View:
This is the place you go to show your graph.

Select the "Graph" option to display it. After you see the graph,
any key will return to the menu system.

Select "Print" to (you guessed it) print the graph. You will be
given the choice of a portrait or landscape output on either an
Epson or HP LaserJet (or compatibles maybe). Assuming you
have the correct printer and it is ready, you will then have the
option to set the graph's position on the output. The graph will be
displayed (that's how I get my hands on the data to print --
directly from the screen) and the printing will start after you hit
ENTER. Return is automatic as soon as all the necessary data is
in the print buffer.

The other option, "Data", is simply a listing of what your data
currently looks like from a save file standpoint. It was used as a
debug tool for me, but I kind of liked it, so I left it in. With some
thought, you may find some value in it too. WARNING: The data listed
is not being extracted from a saved file. It is a listing of the data
that is currently active in the menu system. If you want to keep it,
you must use the SAVE function. APPENDIX II list the line numbers
and what they mean.

Files:
To retrieve a saved graph, you have two options. If you select "Get",
a new window is displayed allowing you to enter the saved graf name.
You can also select "Directory" which will show you a list of all the
graphs saved in the current directory and allow you to hilite the one
that you want. Press ENTER and the hilited file will automatically
go through the "Get" routine. The "Directory" function also allows
you to sort or delete files.

"Save" is pretty straightforward. A new window will ask for a name
and go through a normal save type routine (check for duplicates,etc.).
If you want to save with the current file name (lower right corner of
Data Screen), leave the field blank and just press ENTER.
The save files are pure ascii. APPENDIX II lists the line numbers and
what they mean.

"Reset" does just that -- resets all the values and selections to
their original defaults. Be careful, if you haven't saved your
current work, it will be gone.

The initial screen starts in the "FILES" menu. From here, you can
access any of the saved files. It seemed like a better place to
start than the actual beginning. The actual beginning has no menu
items hilited or any menus pulled for your use (ground zero). You
can get to that point by simply pressing F2.

Quit:
You get two chances. The trailing menu requires another "Quit" to
actually exit. "Stay" does nothing but stay.


APPENDIX I:

Most of the values allowed below are indigenous to Turbo Pascal 5.0.

Colors: 0 - black Fonts: 0 - default (character)
1 - blue 1 - triplex
2 - green 2 - small
3 - cyan 3 - sans serif
4 - red 4 - gothic
5 - magenta 5 - script
6 - brown 6 - block
7 - gray (dull white) Patterns: 0 - empty (hollow)
8 - dark gray 1 - solid
9 - light blue 2 - lines
10 - light green 3 - light slashes
11 - light cyan 4 - slashes
12 - light red 5 - back slashes
13 - light magenta 6 - light back slashes
14 - light brown (orange ?) 7 - hatches
15 - white (bright) 8 - cross hatches
16 - match to slices/bars only 9 - interleave
10 - wide dots
Styles: 0 - solid 11 - close dots
1 - dotted
2 - center dotted Thickness: 1 - normal
3 - dashed 2 - thick
4 - dash/dot * 3 - thick [note lines only]
5 - dash/dash/dot * Sizes: 0 - 4 (0 is default)
6 - dash/dot/dot *
* used for line on line graph only.

APPENDIX II:

The following are the line numbers used in the save files:

1.. 60 Name Font
61..120 Name Size
121..123 Title Font
124..125 X,Y Axis Font
126..134 Note 1-9 Font
135..138 Annotation (Values,Names,PerCent,Labels)
139..140 Relativeness*,Side or Bottom*
141..143 Title Size
144..145 X,Y Axis Size
146..154 Note 1-9 Size
155..157 Outline (Exist,Font/Thk,Size/Stl)
158..160 X Axis (Exist,Font/Thk,Size/Stl) [Value*]
161..163 Y Axis (Exist,Font/Thk,Size/Stl) [PerCent*]
164..166 H Grid (Exist,Font/Thk,Size/Stl) [Label*]
167..169 V Grid (Exist,Font/Thk,Size/Stl) [InBox*]
170 ChartType
171..230 Fill Color
231..290 Fill Pattern
291..350 Name Color
351..353 Title Color
354..355 X,Y Axis Color
356..364 Note 1-9 Color
365..369 Color (out,x,y,h,v) or if pie*: (val,%,lab,inbox)
370 Background Color
371..388 Notes(X,Y);
389..400 Pie Centers(X,Y)*;
401..404 Room (top,bottom,left,right)
405 Platform Depth
406 Reducer*
407..442 Lines[notes] (fromX,fromY,toX,toY)
443..502 Values - Set #1
503..562 Values - Set #2
563..622 Values - Set #3
623..682 Values - Set #4
683..742 Values - Set #5
743..802 Values - Set #6
803..862 Names
863..868 Labels
869..871 Chart Limits (step,low,high)
872..874 Title Text
875..876 X,Y Axis Text
877..885 Note 1-9 Text

* if Pie


REQUISITE DISCLAIMER and OTHER STUFF:

I am not a programmer by profession and not a very good one by
avocation. As such, KDGraf is an extremely ambitious venture into
programming for me. It is very large and terribly complicated.
You have your hands on version 2.1 (the second release). I would
suspect that there are still some bugs and many things that could be
done differently and/or improved.

It was written to try to learn a little something about how two
things work -- pull-down menus and graphics. Both of these are
tough nuts to crack. The pull-down menus were designed as a
composite of many of the systems that I have worked with or seen --
primarily Turbo Pascal itself, Windows and a program that credited the
included menu system to something called "PULL11". The graphics part
is pure Turbo.

So, the following is extra true about KDGraf:

Every reasonable attempt has been made to offer a fun product that
may be of some use and be "bug" free. I (the author) can, however,
offer no guarantees as to the suitability or use of this program.
Therefore (here we go)...

THIS PRODUCT IS PROVIDED "AS IS" AND
WITHOUT WARRANTIES EXPRESS OR IMPLIED.
THE USER ASSUMES ALL RISK ASSOCIATED
WITH THE USE OF THIS PROGRAM.

You may copy and distribute this program freely. Please don't
charge for it and please provide this .DOC file and the example
grafs with it.

Anyone who is interested, can send the author (me) $5.00 or so.
(Mainly, I'm curious to see if anyone is interested!)

David A. Befort
KD Ranch Enterprises (c)
Rt.3, Box 8080
Bartlesville, Ok. 74003