TScGraph
=============================================================


About TScGraph
--------------

TScGraph is a Delphi32 component for scientific/technical
graphing of x/y-data.

The basis for this component was a graphing component

    txyGraph (version 1.0)

which was made available by

  Grahame Grieve, Biochemistry, St Vincent's Hospital
  Victoria Parade, Fitzroy, 3065, Australia,
  (g.grieve@pgrad.unimelb.edu.au),

which is gratefully acknowledged. Graham Grieve has done further 
work; he has made version 2 of txyGraph available but TScGraph in its 
basics has still many features of txyGraph (v. 1). 

This program is distributed as Freeware. You use it completely at 
your own risk.  You may distribute this program in any manner, 
as long as the following conditions are met:

1) This file (ScGraph.txt) accompanies it, and is not modified.
2) No modifications are made to the units and code.
3) No fees are charged for the program.
4) If you wish to include this file in a collection of Freeware/Shareware
   utilities, I would like a copy of that collection.


Installation
------------

After copying to a suitable directory install as customary in Delphi32.
From main menu drop down Component + Install and click the Add button.
Find path and file name of where the TScGraph module (ScGraph.dcu) is 
located. Click on OK. The component should now appear in a 'Graph' 
folder within Delphi. Test it using the demo application.


DISCLAIMER
----------

No warranty is given that the software or documentation is "error free"
or meets any user's particular standards, requirements, or needs.
Therefore, the author can not be made liable for any error or claims
that arises directly or indirectly from the use of this software.
The author is not responsible for any damage caused by using this
component.


Bugs
----

No fatal bugs are known to me for the time being in my environment
(which is somewhat limited with respect to possible variations in
hardware). 

Certainly the component still lacks some features or shows some 
deficiencies (as any graphing component obviously always does).
These are in particular:

- slow routines for drawing patterned lines, in particular
  printing such graphs could result in long printing times.
  Also dithering of colors in patterned lines could give poor
  results in printing.
- rather simple formatting of tick labels, no exponents
- flashing of graph when refreshing
- wasting memory with fixed data arrays
- no error bars
- yet no windows help file
- etc.

Printing ScGraph with the method provided yields a practicable
output with my printer (600dpi) but I am aware that in particular
handling of font sizes for various printer resolutions is
deficient and could result in inadequate font sizes.

If you find any bugs or have comments please mail to

  R.Nowotny@bmtp.akh-wien.ac.at


Using this component
--------------------

The appearance of the graph can be manipulated and viewed
at design time. Data and plotting modes can only be added
and viewed at run time. If a legend box is used only a
placeholding box is displayed at design time.

Sizing of the plot box is adjusted automatically and depends
on sizes of titles, legends, ticks and legends.

In 'Autometrics' mode, distances are not being given in pixels but 
rather in units 1/1000 of the corresponding dimension of GraphPlot 
(width or height) either on the screen or the printer canvas. 
This results in proportional scaling of the graph when window sizes 
(i.e. size of ScGraph) are changed or when printing.

For scaling the size of symbols and fonts the diagonal dimension is
chosen as the reference length instead. The same applies to line
width and line pattern length except for a line width equal to 0
which gives always the thinnest possible line width (hair line)
on screen or printer.

If 'Autometrics is set to false common Windows sizing is used.

The 'plotting' property turns plotting and refreshing of the
graph on and off. In case lots of data are loaded into the
data series or if many graph properties are changed it is
a good idea to turn 'plotting' off.

It is the users duty to care for the range and size of data 
added to the data series. The component does not raise 
exceptions for negative values when log scales are used or 
if data are out of range.


Properties
----------

  Graphing Panel:
    TScGraph: TCustomPanel;
      Align,            BevelInner,          BevelOuter,
      BevelWidth,       BorderStyle,         BorderWidth,
      ctl3d,            cursor,              Color,
      Height,           HelpContext,         Hint,
      Left,             Name,                ParentColor,
      ParentCtl3d,      ParentFont,          Tag,
      Top,              visible,             Width
        these are all inherited properties; seek Help in Delphi.

    MarginLeft,       MarginRight,
    MarginTop,        MarginBottom
      margins between the graphic panel border and and any graphical
      component drawn on the ScGraph panel.

    Plotting
      if true, the graph will be updated every time data and/or
      properties are changed, if false, the name only will be shown.

    PlotColor
      gives the color inside the plot box

    Autometrics
      if true, margins and distances are automatically adjusted in 
      relation to the resp. dimensions on screen or in print size,
      for symbol sizes, font sizes and line widths the average of
      horizontal and vertical size is taken for scaling.
      if false, all units are used as defined in Windows/Delphi.


  Graph title:
    GraphTitle
      Title    : if true, a Graph Title will be drawn
      Caption  : title text string for GraphTitle
      Distance : distance from title to the next graphical component below
      Position : the horizontal position of the title is scaled from 0
                 to 1000
                      0: left border of text box coincides with the left
                         border of the plot box
                    500: centered horizontally
                   1000: right border of text box coincides with the right
                         border of the plot box

    GraphTitleFont: TFont;
      Font for GraphTitle (see TFont object in Delphi)


  Axes:
    XAxis : TAxis;
      properties for the (horizontal) x-axis

    YAxis : TAxis;
      properties for the (vertical) y-axis

    TAxis object properties:
      MajorTicks   : if true, major ticks are drawn
      MajorTickLen : length of the major tickmarks
      MajorTickWid : line width of the major tickmarks
      MinorTicks   : if true, minor ticks are drawn
      MinorTickLen : length of the minor tickmarks
      MinorTickWid : line width of the minor tickmarks
      TickPosition : position of the tickmarks
                       tpOut   : tickmarks are drawn outside plot box
                       tpCenter: tickmarks are centered on axis
                       tpIn    : tickmarks are drawn inside plot box
      TickLabels   : if true, labels are drawn next to each major tick
      LabelDistance: gives the distance of the label text box from the
                     tickmark
      LabelAngle   : three directions for tick lables are available
                       lr0  : horizontal
                       lr90 : vertical (90 deg rotation)
                       lr270: vertical (270 deg rotation)
      LabelFormat  : format string for the label value. A Format String as
                     explained in Delphi Help should be used.
      Title        : if true, an axis title will be displayed
      TitleText    : title text string
      TitleDist    : distance of the title text box from tick labels or
                     major ticks or axis, whatever is nearest
      TitlePos     : the position of the axis title is scaled from 0 to
                     1000 along the axis
                       0   : leftmost/lowest position
                       500 : centered
                       1000: rightmost/top position
      TitleAngle   : three directions for axis titles are available
                       lr0  : horizontal
                       lr90 : vertical (90 deg rotation)
                       lr270: vertical (270 deg rotation)

    AxisPen: TPen;
      Pen object properties for drawing of all axes

    AxisTitleFont: TFont;
      Font for all axis titles

    Frame
      if set true a frame is drawn around the plot box

    FramePen: TPen;
      pen object properties for the plot box frame

    TickLabelFont: TFont;
      font for all tick labels


  Scales:
    XScale: TScale;
      properties for the scale on the x axis

    YScale: TScale;
      properties for the scale on the y axis

    TScale object properties:
      ScaleType      : sets the scale type
                         stLin: linear scale
                         stLog: logarithmic scale
      Min            : minimum value on scale
      Max            : maximum value on scale
      MinRange       : minimum range on scale starting with Min
      Intersection   : value on axis where the other axis intersects this
                       axis, Min <= Intersction <= Max
      LinStep        : LinStep gives the interval for major tick marks
                       and major gridlines for a linear scale
      MinorTickNumber: number of minor ticks per LinStep for a linear scale
      MajorLogPattern: major ticks and grid lines are drawn for powers of
                       ten. Additional major ticks and/or grid lines are
                       drawn after setting an appropriate element ltxx out
                       of (lt20, lt30, lt40, lt50, lt60, lt70, lt80, lt90)
                       to true. Any combination is feasible.
      MinorLogPattern: minor ticks and/or grid lines are drawn if appropriate
                       elements stxx out of (st15, st20, st25, st30, st35,
                       st40, st45, st50, st55, st60, st65, st70, st75, st80,
                       st85, st90, st95) are set to true. Any combination is
                       feasible.
      AutoSizing     : if true, the values for Min/Max are recalculated
                       when the graph is redrawn.
      AutoStepping   : if true, the values for LinStep are recalculated
                       when the min/max values change.


  Grids:
    GridHorizontal: TGrid;
      provides properties for the horizontal major and minor grid

    GridVertical: TGrid;
      provides properties for the vertical major and minor grid

    TGrid object properties:
      MajorGrid     : if true a grid line will be drawn for each major
                      tick on the appropriate axis
      MajorGridColor: color of the major grid lines
      MajorGridStyle: TPenStyle type
      MinorGrid     : if true a grid line will be drawn for each minor
                      tick on the appropriate axis
      MinorGridColor: color of the minor grid lines
      MinorGridStyle: TPenStyle type


  Legends:
    LegendBox
      ShowLegends: if true, a legend box will be drawn
      BoxColor   : color of the legend box background
      BoxStyle   : brush for the legend box background
      Framed     : if true, a frame will be drawn around the legend box
      FrameColor : color of the legend box frame
      FrameWidth : width of the legend box frame
      Placement  : position of the legend box in the graph
                     lbxTop      : outside the top border of the plot box
                                   centered horizontally
                     lbxRight    : outside the right border of the plot box
                                   centered vertically
                     lbxBottom   : outside the bottom border of the plot box
                                   below axis and/or axis label centered
                                   horizontally
                     lbxNorthEast: top right within plot box
                     lbxNorthWest: top left within plot box
                     lbxSouthEast: bottom right within plot box
                     lbxSouthWest: bottom left within plot box
      Distance   : gives the distance(s) of the legend box border to the
                   plot box border

    LegendFont   : TFont;
      Font object for the legends


Controlling the data series
---------------------------

In this version the number of data series is limited to 6 and
number of data per series to 600.

Setting up a data series:

  procedure SetSeries(sN: integer; makeActive, Initialize: boolean;
                      Color: TColor; Legend: shortstring);

    sN        : series number;  1 <= sN <= 6
    makeActive: true/false turns display of series on/off
    Initialize: true clears all data of series
    Color     : defines color of lines, symbols and sticks
                associated with this series
    Legend    : text string for the legend box


Checking status of a series:

  function GetSeries(sN: integer; var Color: TColor;
           var Legend: shortstring): boolean;

    returns false if not active

    sN        : determines the series
    Color     : series color on return
    Legend    : series legend on return

    see SetSeries for details


Adding Data to the series:

  function AddPoint(sN: integer; x, y: double): boolean;

    returns true if the data were successfully added

    sN        : number of series to which data are to be added
    x, y      : data point to add. Only one single data point is
                accepted for each value of x.


Delete a single data point:

  function DeletePoint(sN: integer; x: double): boolean;

    returns true if data point was succesfully deleted.

    sN        : number of series from which a data point is to be
                deleted.
                If sN = 0, all active series are checked for x
                values.
    x         : x value of the data point to delete.


Find a data point for a given x-value:

  function GetPoint(sN: integer; var x, y: double): boolean;

    returns true if a data point was found

    sN        : number of series for point search
    x, y      : x-value of point


Deleting all data of a series:

  procedure ClearSeries(sN: integer);

    sN        : number of series to be cleared, the status of the
                series remains unchanged. Data can also be cleared
                by SetSeries setting both makeActive and Initialize
                to true.
                If sN = 0, all series are cleared.


Plotting lines:

  procedure SetSeriesLine(sN: integer; Status: boolean;
              Mode: pmPlotMode; LWidth: integer; LStyle: TPenStyle);

    sN        : determines the series
    Status    : a line will be drawn if true
    Mode      : plot mode of type
                  pmLine   : straight line connecting the points
                  pmHisto  : histogram line
                  pmSticks : draws sticks from the X-axis to the point
    LWidth    : line width given in 1/1000 of graph diameter.
                For LWidth = 0 a hair line will always be drawn.
    LStyle    : line style
                  psSolid  : solid line
                  psDash   : dashed line
                  psDot    : dotted line
                  psDashDot: alternating dashes and dots
                  psDashDotDot: series of dash-dot-dot combinations


Retrieving line settings:

  function GetSeriesLine(sN: integer; var Mode: pmPlotMode;
             var LWidth: integer; var LStyle: TPenStyle): boolean;

    result is equal to status of line drawing

    sN        : determines the series
    Mode      : returns plot mode, see SetSeriesLine
    LWidth    : returns line width
    LStyle    : returns line style

    see SetSeriesLine for details


Plotting symbols:

  procedure SetSeriesPoints(sN: integer; Status: boolean;
                  Shape: etPointShape; Size: integer);

    sN        : determines the series
    Status    : symbols for data points will be drawn if true
    Shape     : symbol shape of type
                  psCross        : Diagonal cross
                  psHCross       : Hatched cross
                  psSquare       : hollow square
                  psSquareFilled : filled square
                  psDiamond      : hollow diamond
                  psDiamondFilled: filled diamond
                  psCircle       : hollow circle
                  psCircleFilled : filled circle
                  psTriangleUp   : hollow triangle pointing upwards
                  psTriangleUpFilled: filled triangle pointing upwards
                  psTriangleDown : hollow triangle pointing downwards
                  psTriangleDownFilled: filled triangle pointing downwards
    Size      : size of the symbol given by the size of the
                circumscribing square in 1/1000 units of graph diameter.


Retrieving point settings:

  function GetSeriesPoints(sN: integer; var Size: integer;
                var Shape: etPointShape): boolean;

    result is equal to status of symbol drawing

    sN        : determines the series
    Size      : symbol size
    Shape     : symbol shape

    see SetSeriesPoints for details


Run time mouse routines
-----------------------

  function GetMouseX(x: integer): double;

    returns the scaled value given by the X-scale for a given mouse
    position x given in pixels

  function GetMouseY(y: integer): double;

    returns the scaled value given by the Y-scale for a given mouse
    position y given in pixels

  function GetMouseVals(sN, x: integer; var xVal, yVal: double): boolean;

    Retrieves the value of the data point matching the mouse point
    given by its x position best.
    Function returns true if successful, or false if the mouse is
    outside the plot area.

    sN       : series number
    x        : mouse x position in pixels
    xVal     : scaled x value of data point
    yVal     : scaled y value of data point

  function GetMouseXY(Sn, x, y: integer; var xbyscale, ybyscale,
                xbyPoint, ybyPoint: double): boolean;

    Calculates scaled values for mouse position x/y and retrieves
    the value of the data point matching the mouse point best
    with regard to its x position.
    Function returns true if successful, or false if the mouse is
    outside the plot area.

    sN       : series number
    x, y     : mouse x and y position in pixels
    xbyscale : scaled x value of data point
    ybyscale : scaled y value of data point
    xbyPoint : scaled x value of nearest data point in series
    ybyPoint : scaled y value of nearest data point in series


Printing of the graph
---------------------

  procedure PrintGraph(LeftMM, TopMM, WidthMM, HeightMM: longint);

    prints the graph on the current windows printer.

    LeftMM   : distance of the left topmost corner of the graph from
               left edge of the paper in mm, if < 0 the graph is
               centered horizontally
    TopMM    : distance of the left topmost corner of the graph from
               the top edge of the paper in mm, if < 0 the graph is
               centered vertically
    WidthMM  : width of the graph in mm, if < 0 the full printing
               width of the paper is used
    HeightMM : height of the graph in mm, if < 0 the full printing
               height of the paper is used

  'Autometrics' should be set to true as this gives adequate scaling 
   of sizes and better results.


Copying to the clipboard
------------------------

  procedure CopyGraphToClipboard;

    copies the graph as a bitmap to the windows clipboard so that
    the graph could be used in other windows applications.


Enjoy,

Robert Nowotny
R.Nowotny@bmtp.akh-wien.ac.at
