home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / graphics.zip / GRAPHICS.TXT < prev    next >
Text File  |  1993-10-28  |  12KB  |  256 lines
  1.                      Scientific Graphic Library
  2.  
  3. Product Overview (Version 0.2)
  4.  
  5.    This graphics package is a high level Application Programming
  6. Interface(API) library which can be used to create two-dimensional, 
  7. scientific graphs.
  8.  
  9. Graph Relationship to an Application Window
  10.  
  11.    The graphics package creates a window that can be sized and positioned 
  12. by the developer.  It can therefore be used as a standard control in any 
  13. window or dialog box.
  14.  
  15. Creating a Graph
  16.  
  17.    To create a graph, the developer can use on of two methods.  The
  18. first method uses the function GraphCreate. This function is used to
  19. place a graph object within a client window.  You can position
  20. the graph window using GraphSetDimensions and paint the graph using 
  21. GraphPaint.  The graph window can be positioned using GraphSetWindowPos.
  22.  
  23.    The second method involves creating a graph as a User defined control. 
  24. In this case the graph must first be registered by using GraphRegister. 
  25. This function registers a user defined control.  This control name can
  26. then be used by any user defined control and placed in resource files.
  27. The handle of the graph can be obtained using the function GraphQueryHandle.
  28. A graph control can be positioned (as usual) using WinSetWindowPos.
  29.  
  30. Graph Types
  31.  
  32.    The graphics package initially supports five types of graphs.
  33. These graph types are Scatter, Line, XY-Line, Spectral, and Area graphs.
  34. In the future, support for Polar, Bar, Pie, Tabular, Radar, HILO, Stacked
  35. Bar, Step and thier 3D compliments will be included.
  36.  
  37. Graph Regions
  38.  
  39.    The graph is currently sub-divided into ten areas.  These areas are as
  40. follows:
  41.  
  42.    o  Graph Window
  43.    o  Heading
  44.    o  X-Axis Text
  45.    o  X-Axis Labels and Tick Marks
  46.    o  Y-Axis Text
  47.    o  Y-Axis Labels and Tick Marks
  48.    o  2Y-Axis Text
  49.    o  Plot
  50.    o  Legend
  51.    o  Company Classification (Upper Left, Lower Right)
  52.  
  53. Other areas to be defined in an enhanced version are:
  54.    o  X-Axis Units
  55.    o  Y-Axis Units
  56.    o  2Y-Axis Labels and Tick Marks
  57.    o  2Y-Axis Units
  58.    o  User defined Notation Text
  59.    o  User defined arrows
  60.  
  61. The graph window contains all other regions.  The Plot is positioned within 
  62. the graph window using the function GraphPositionPlot.  The plot is 
  63. positioned by specifing the plots Heading, Left Margin, Right Margin, and 
  64. Footing with respect to the graph window.
  65.  
  66.    The parameters for this function are in percentages of the total graph
  67. window, not pixels or inches.  The automatic default for these regions
  68. are heading=10%, footing=15%, left margin = 15%, right margin = 20%.
  69. The area bounded by the vertical and horizontal borders is call the Plot.
  70. The vertical size of the plot is controlled by the Heading and Footing 
  71. percentage. The horizontal size of the plot is controlled by the Left and 
  72. Right margins. The default parameters provide a plot area of approximately 
  73. 70% in height and 75% in width.
  74.  
  75. Graph Text, Alignment, Fonts, Colors
  76.  
  77.    The developer can specify the text for the Title, X-Axis, Y-Axis,
  78. and 2Y-Axis.  Any available vector font can be assigned to each text
  79. region.  Fonts resize automatically when necessary as the graph size changes.
  80. Text can be aligned in thier areas either horizontally or vertically.
  81. Besides using the standard sixteen color indexes, you can specify
  82. any RGB color.
  83.  
  84. Graph Fonts
  85.  
  86. Only vector fonts are supported and a font is described by name 
  87. (e.g. "Times Roman Bold"). In addition to a font name, a point size may also 
  88. be provided.  The graphics package will use the point size specified as long 
  89. as the text will fit into the text boundary.  If the text does not fit, the 
  90. font is automatically scaled so that it fits the text boundary.
  91.  
  92. Each data group and its associated data points can be provided a name that
  93. will be used in the graph legend.  The fonts for the legend are can be set
  94. by the developer as described above.
  95.  
  96. Data Groups
  97.  
  98.    Before any data can be added to the graph, the number of groups must be
  99. specified using the function GraphSetGroupCount.  Groups are numbered starting
  100. with group 1.  Once a group has been specified, the develpoer can modifiy
  101. group parameters such as group legend text, color, marker type, line type, 
  102. and pattern using the GraphSetGroup... function calls.
  103.  
  104.  
  105. Specifying Graph Data
  106.  
  107.    After a groups creation, the developer provides the graph with the data
  108. points to display.  The data points are given as a set of points, hereafter
  109. called a group.  A group can contain any number of points.  The graphics
  110. package can support any number of groups within memory and performance
  111. constraints.  Each data group and its associated data points are initially
  112. defined with the function GraphSetupData which specifies the data types and
  113. pre-allocates storage.  The function GraphSetData can then be used to add
  114. X and Y data pairs upto the maximum number of points specified in
  115. GraphSetupData.  To initialize any array of data points, you can use the
  116. functions GraphSetXData and GraphSetYData.  These function assume an array
  117. of points as long as specified in graph setup data.
  118.  
  119. Data can be appended to a group using the function GraphAppendData.  If more
  120. memory is required, this function will re-allocate memory as necessary.  The
  121. number of data points can be reduced by calling GraphSetupData with the
  122. required number of data points.
  123.  
  124. All data points are Zero based indexed.
  125.  
  126. Graph Axis Support
  127.  
  128.    The X-Axis and Y-axis support manual or automatic scaling for positive
  129. and negative data.  Automatic axis support for linear and
  130. logarithmic numbers is included. In the future support for calendar
  131. (days, weeks, months, years), time (seconds, minutes, hours), and
  132. military/international hours will be included.
  133.  
  134. Graph Axis Scaling
  135.  
  136.    The Axis scaling algorithm will automatically compute the maximum and 
  137. minimum values for the axis from the data groups.  To insure readibility, 
  138. the scaling algorithm provides axis major tick increments.  These 
  139. increments are from the base set or a multiple of 10 from the base set. 
  140. The base set is 1, 2, 5, 10, 15. 20, 25.  Minor tick increments are either 
  141. 2, 3, 5, 10, the increment must make sense given a major increment.
  142.  
  143. The automatic scaling algorithm will roundup the maximum data point or round
  144. down the minimum data point to fit the major tick increment as required.
  145.  
  146. The font for the text labels can be set by the developer.  This font size is
  147. used by the automatic scaling algorithm in determinig the labeling increment.
  148.  
  149. The automatic labeling algorithm can be disabled (using GraphSet(X,Y)Options)
  150. by setting the GRAPH_AUTO_LABEL and GRAPH_AUTO_RANGE flags off (e.g.
  151. GraphSetXOptions(hGraph, GRAPH_AUTO_RANGE, FALSE)).  Once the automatic
  152. labeling and ranging are disabled, a manual range or label increment can
  153. be set using the functions GraphSet(X,Y)DataRange and GraphSet(X,Y)Labeling.
  154.  
  155. Graph Tactile Feedback
  156.  
  157.    Two functions are provided to allow an application to interact with the 
  158. graph.  The first is GraphQueryPointer.  This API allows the developer to
  159. pass x and y coordinates to the graph and determine what data region , data
  160. group, and, if in the graphic region, the corresponding x,y data coordinates.
  161. This function is useful in-conjunction with the mouse pointing device.
  162.  
  163.    The second function is GraphQueryLocation.  The developer can ask for 
  164. the coordinates of a specific item display in a graph.  The application can
  165. the provide a note, information, or position the mouse pointing device in 
  166. this location.
  167.  
  168. Graph Metafiles, Bitmaps, and Printing
  169.  
  170.    The graph can be saved to disk as a bitmap or metafile using the
  171. functions GraphOutputBitmap and GraphOutputMetafile.  These can be
  172. replayed using a utility such as the OS/2 Picture Viewer found in the
  173. productivity folder.  Bitmaps and metafiles used the current screen
  174. size for the basis of thier output.
  175.  
  176.    The GraphPrint API supports  printing.  The graph can be sent to a designated
  177. printer or the default printer can be used by specifying a NULL for the 
  178. printer queue name.  The printer job name is also optional.  In addition, 
  179. the function GraphSetPrintQData can be used to locally define the printer 
  180. Queue information directly.  The function GraphSetPrintMargin can be used
  181. to set the print margins and GraphPreview can be used to get a look at the
  182. printed graph.
  183.  
  184.    When creating a metafile, bitmap, or printed page, color printing can be
  185. enabled or disabled (default) using the function GraphEnableColorPrint.  
  186. By disabling color output, a good quality Black & White copy can be created.
  187.  
  188. Graph Menus
  189.  
  190.    Built in menus are provided to allow the user to manipulate the style of
  191. the graph.  These menus are not complete but can be activated by using the
  192. function GraphPopupMenu (note: that the menus are designed to be used as
  193. popup menus and are region specific).  The function GraphSelectObject is
  194. used to set the menu reference to a particular region and group within
  195. the graph.  The function GraphSelectMenuItem is then used to process the
  196. menu items.  The predefined menu items can be found in gmenu.h.
  197.  
  198. I have not yet decided how to proceed with menus, using SOM would help.
  199.  
  200. Future Direction
  201.  
  202.    This was done initially for an internal need and because I had so much
  203. fun I decided to expand it.  Besides implementing all functionality such as
  204. graph types and 3D (including possibly 3D grahics and wireframe capability)
  205. I'm not sure how I want to proceed.  I've done this in plain C, but it really
  206. needs to be an object implementation.  C++ seems to limited to me and as I
  207. have done other projects in SOM, I think thats where I will head. I would like
  208. to use DSOM actually as soon as I can get my hands on the kit (cost is
  209. always a problem).  Any inputs to this line of anquish would be appreciated.
  210.  
  211. Problems
  212.  
  213.    Do not set the graph axis type to PERCENT as this will cause the program
  214. to generate a divide by zero (function is not yet implemented).
  215.  
  216.    Metafile generation contains a clip region.  This region does not always
  217. correlate to the plot area causing pre-mature clipping to occur in some
  218. instances.
  219.  
  220.    Selection of printer font does not work correctly.
  221.  
  222. Fixes
  223.    Version 0.2
  224.    (1) Fixed problem with graph crashing on minimize
  225.    (2) Fixed problem with selecting a graph area pattern
  226.  
  227. Enhancements
  228.    Version 0.2
  229.    (1) Added encode file formats for PM version 1.x Bitmaps,
  230.        Windows Version 3.x Bitmaps, and GIF.
  231.    (2) Enable clipboard copy of the graphic image
  232.    (3) Added printer font selection (does not work correctly)
  233.  
  234. Notes
  235.  
  236.    Use the right mouse button to view the menu selections available
  237. for the test cases.  This will demonstrate most of the graph features.
  238. If you can do it with the menus, you can programm it.
  239.  
  240.    Since this is so porly documented, the best advise I can give is look
  241. at the sample code provided and the header files.
  242.  
  243.    Any comments or suggestions can be forwarded to:
  244.  
  245.       Steven Murray
  246.       100 Stoney Hollow Road
  247.       Tiverton, RI 02878
  248.       COMPUSERVE 71053,1346
  249.  
  250. ==========================================================================
  251.                               TERMS
  252. ==========================================================================
  253. This API is Freeware.  You are free to use it and give it to others,
  254. as long as you don't sell it.  It is NOT public domain; I retain copyright.
  255.  
  256.