Scientific Graphic Library Product Overview (Version 0.2) This graphics package is a high level Application Programming Interface(API) library which can be used to create two-dimensional, scientific graphs. Graph Relationship to an Application Window The graphics package creates a window that can be sized and positioned by the developer. It can therefore be used as a standard control in any window or dialog box. Creating a Graph To create a graph, the developer can use on of two methods. The first method uses the function GraphCreate. This function is used to place a graph object within a client window. You can position the graph window using GraphSetDimensions and paint the graph using GraphPaint. The graph window can be positioned using GraphSetWindowPos. The second method involves creating a graph as a User defined control. In this case the graph must first be registered by using GraphRegister. This function registers a user defined control. This control name can then be used by any user defined control and placed in resource files. The handle of the graph can be obtained using the function GraphQueryHandle. A graph control can be positioned (as usual) using WinSetWindowPos. Graph Types The graphics package initially supports five types of graphs. These graph types are Scatter, Line, XY-Line, Spectral, and Area graphs. In the future, support for Polar, Bar, Pie, Tabular, Radar, HILO, Stacked Bar, Step and thier 3D compliments will be included. Graph Regions The graph is currently sub-divided into ten areas. These areas are as follows: o Graph Window o Heading o X-Axis Text o X-Axis Labels and Tick Marks o Y-Axis Text o Y-Axis Labels and Tick Marks o 2Y-Axis Text o Plot o Legend o Company Classification (Upper Left, Lower Right) Other areas to be defined in an enhanced version are: o X-Axis Units o Y-Axis Units o 2Y-Axis Labels and Tick Marks o 2Y-Axis Units o User defined Notation Text o User defined arrows The graph window contains all other regions. The Plot is positioned within the graph window using the function GraphPositionPlot. The plot is positioned by specifing the plots Heading, Left Margin, Right Margin, and Footing with respect to the graph window. The parameters for this function are in percentages of the total graph window, not pixels or inches. The automatic default for these regions are heading=10%, footing=15%, left margin = 15%, right margin = 20%. The area bounded by the vertical and horizontal borders is call the Plot. The vertical size of the plot is controlled by the Heading and Footing percentage. The horizontal size of the plot is controlled by the Left and Right margins. The default parameters provide a plot area of approximately 70% in height and 75% in width. Graph Text, Alignment, Fonts, Colors The developer can specify the text for the Title, X-Axis, Y-Axis, and 2Y-Axis. Any available vector font can be assigned to each text region. Fonts resize automatically when necessary as the graph size changes. Text can be aligned in thier areas either horizontally or vertically. Besides using the standard sixteen color indexes, you can specify any RGB color. Graph Fonts Only vector fonts are supported and a font is described by name (e.g. "Times Roman Bold"). In addition to a font name, a point size may also be provided. The graphics package will use the point size specified as long as the text will fit into the text boundary. If the text does not fit, the font is automatically scaled so that it fits the text boundary. Each data group and its associated data points can be provided a name that will be used in the graph legend. The fonts for the legend are can be set by the developer as described above. Data Groups Before any data can be added to the graph, the number of groups must be specified using the function GraphSetGroupCount. Groups are numbered starting with group 1. Once a group has been specified, the develpoer can modifiy group parameters such as group legend text, color, marker type, line type, and pattern using the GraphSetGroup... function calls. Specifying Graph Data After a groups creation, the developer provides the graph with the data points to display. The data points are given as a set of points, hereafter called a group. A group can contain any number of points. The graphics package can support any number of groups within memory and performance constraints. Each data group and its associated data points are initially defined with the function GraphSetupData which specifies the data types and pre-allocates storage. The function GraphSetData can then be used to add X and Y data pairs upto the maximum number of points specified in GraphSetupData. To initialize any array of data points, you can use the functions GraphSetXData and GraphSetYData. These function assume an array of points as long as specified in graph setup data. Data can be appended to a group using the function GraphAppendData. If more memory is required, this function will re-allocate memory as necessary. The number of data points can be reduced by calling GraphSetupData with the required number of data points. All data points are Zero based indexed. Graph Axis Support The X-Axis and Y-axis support manual or automatic scaling for positive and negative data. Automatic axis support for linear and logarithmic numbers is included. In the future support for calendar (days, weeks, months, years), time (seconds, minutes, hours), and military/international hours will be included. Graph Axis Scaling The Axis scaling algorithm will automatically compute the maximum and minimum values for the axis from the data groups. To insure readibility, the scaling algorithm provides axis major tick increments. These increments are from the base set or a multiple of 10 from the base set. The base set is 1, 2, 5, 10, 15. 20, 25. Minor tick increments are either 2, 3, 5, 10, the increment must make sense given a major increment. The automatic scaling algorithm will roundup the maximum data point or round down the minimum data point to fit the major tick increment as required. The font for the text labels can be set by the developer. This font size is used by the automatic scaling algorithm in determinig the labeling increment. The automatic labeling algorithm can be disabled (using GraphSet(X,Y)Options) by setting the GRAPH_AUTO_LABEL and GRAPH_AUTO_RANGE flags off (e.g. GraphSetXOptions(hGraph, GRAPH_AUTO_RANGE, FALSE)). Once the automatic labeling and ranging are disabled, a manual range or label increment can be set using the functions GraphSet(X,Y)DataRange and GraphSet(X,Y)Labeling. Graph Tactile Feedback Two functions are provided to allow an application to interact with the graph. The first is GraphQueryPointer. This API allows the developer to pass x and y coordinates to the graph and determine what data region , data group, and, if in the graphic region, the corresponding x,y data coordinates. This function is useful in-conjunction with the mouse pointing device. The second function is GraphQueryLocation. The developer can ask for the coordinates of a specific item display in a graph. The application can the provide a note, information, or position the mouse pointing device in this location. Graph Metafiles, Bitmaps, and Printing The graph can be saved to disk as a bitmap or metafile using the functions GraphOutputBitmap and GraphOutputMetafile. These can be replayed using a utility such as the OS/2 Picture Viewer found in the productivity folder. Bitmaps and metafiles used the current screen size for the basis of thier output. The GraphPrint API supports printing. The graph can be sent to a designated printer or the default printer can be used by specifying a NULL for the printer queue name. The printer job name is also optional. In addition, the function GraphSetPrintQData can be used to locally define the printer Queue information directly. The function GraphSetPrintMargin can be used to set the print margins and GraphPreview can be used to get a look at the printed graph. When creating a metafile, bitmap, or printed page, color printing can be enabled or disabled (default) using the function GraphEnableColorPrint. By disabling color output, a good quality Black & White copy can be created. Graph Menus Built in menus are provided to allow the user to manipulate the style of the graph. These menus are not complete but can be activated by using the function GraphPopupMenu (note: that the menus are designed to be used as popup menus and are region specific). The function GraphSelectObject is used to set the menu reference to a particular region and group within the graph. The function GraphSelectMenuItem is then used to process the menu items. The predefined menu items can be found in gmenu.h. I have not yet decided how to proceed with menus, using SOM would help. Future Direction This was done initially for an internal need and because I had so much fun I decided to expand it. Besides implementing all functionality such as graph types and 3D (including possibly 3D grahics and wireframe capability) I'm not sure how I want to proceed. I've done this in plain C, but it really needs to be an object implementation. C++ seems to limited to me and as I have done other projects in SOM, I think thats where I will head. I would like to use DSOM actually as soon as I can get my hands on the kit (cost is always a problem). Any inputs to this line of anquish would be appreciated. Problems Do not set the graph axis type to PERCENT as this will cause the program to generate a divide by zero (function is not yet implemented). Metafile generation contains a clip region. This region does not always correlate to the plot area causing pre-mature clipping to occur in some instances. Selection of printer font does not work correctly. Fixes Version 0.2 (1) Fixed problem with graph crashing on minimize (2) Fixed problem with selecting a graph area pattern Enhancements Version 0.2 (1) Added encode file formats for PM version 1.x Bitmaps, Windows Version 3.x Bitmaps, and GIF. (2) Enable clipboard copy of the graphic image (3) Added printer font selection (does not work correctly) Notes Use the right mouse button to view the menu selections available for the test cases. This will demonstrate most of the graph features. If you can do it with the menus, you can programm it. Since this is so porly documented, the best advise I can give is look at the sample code provided and the header files. Any comments or suggestions can be forwarded to: Steven Murray 100 Stoney Hollow Road Tiverton, RI 02878 COMPUSERVE 71053,1346 ========================================================================== TERMS ========================================================================== This API is Freeware. You are free to use it and give it to others, as long as you don't sell it. It is NOT public domain; I retain copyright.