Funplot Programmers Interface

Funplot - 2D data plotting environment, version 1.0


Contents



Introduction

This document describes the programmers interface to the 'Funplot' C++ graphics library.

Funplot's aim is to visualise 2 dimensional data in a Plot and give the user the possibility to analyse, store, print and copy the Plot during and after the data generation.

A first and important impression of the 'Funplot' library gives the 'Funplot' program itself together with the Users Manual. So read that manual and 'play' with Funplot before you go trough the following text.

The library was designed to be programmers-friendly, therefore advanced programmers should be able to use it by simply having a look at the delivered example program and the header file 'Funplot.h'. Yet I recommend that even they go through this text to get a deeper understanding of the single functions.

I guide you through this library by giving you information for compiler settings, helping you to compile your first program, explaining examplarily one program and describing all programmers functions as they appear in the header file. This includes set functions, output functions and print, copy and save functions.

Note, that every function of the Funplot menu item and users interaction is also accessible from the 'Programmers Interface' described here. In this description I distinguish the persons programmer and user. The programmer is the person who uses this library to build an application program (also called Session), the user is the user of the application program.

This library was designed to be used with the MS Visual C++ Developer Studio with almost all Windows operating systems. As only API-functions are used for the development of Funplot, it should run directly with other Windows C++ Compilers (as e.g. Borland or Watcom), but the functionality isn't guaranteed.

The funplot library itself uses the object oriented programming techniques and was developed in C++. Even if you are not familiar with C++ or object-oriented techniques, the use of Funplot is very simple and you can program your part of your application in simple C. Think of Funplot as a struct variable type, with the difference that members you can access are only functions. So for every Funplot window, you just have to define a variable (further called instance) of type Funplot, then to call your desired functions. A normal function is called by using a dot between the instance name and the function. A static function is common to all instances and is called by using two colons (::) between the classname Funplot and the static function.


Compiler Settings

For using the Funplot library you have to add the directory of the Funplot header file (Funplot.h) to the include path of your compiler. Using Microsoft Developer Studio you have two possibilities.

  1. Specify the include path for all your projects:
    Choose the menu item 'Tools | Options | Directories', and add the path in the 'Directories' field. (Of course the path can be removed in the same way.)
  2. Specify the include path only for your actual project:
    Choose the menu item 'Project | Settings | C++ | Preprocessor' and add the path in the 'Additional include directories' filed.

Building and Executing Projects

Using the Microsoft Developer Studio the following steps have to be made to build and execute a Funplot based Windows application.

Tip: try this first with the code of the delivered example programs, so you're sure that you are using the Funplot library correctly. If you want more detailed information about building projects with you compiler or you just want to use Funplot with another compiler please refer to your compiler's user manual.


Example Program

The following example demonstrates how a simple (but effective) program is set-up. Follow the links to the called member functions to know more about the function itself.

/*****************************************************************************

  Harmony

  Displays a musical Consonance and a Dissonance in two separate Plots.

  $Name: Funplot_v10 $
  $Revision: 1.1 $
  $Date: 2006/06/08 19:45:02 $

  Copyright © 1998-2006 Domenico Reggio, Software-Engineering.

*****************************************************************************/


#include "Funplot.h"
#include <math.h>


int PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
                   LPSTR lpszCmdLine, int nCmdShow)
{
  // Register the Funplot window class
  Funplot::ClassRegister(hInstance, hPrevInstance, nCmdShow);

  // Program variables
  double f,ome1,ome2a,ome2b,ome3a,ome3b,musiCon,pi,t,amp;

  // Instantiation of the first Funplot window
  Funplot Consonance("Consonance");
  Consonance.SetLables("time [s]","amplitude [-]","Visualisation of a Consonance");
  Consonance.SetNumGraphs(1);
  Consonance.SetRange(-0.05,1.05,-4.1,4.1);
  Consonance.SetAutoWindow(2,1,1);    // Place the Plot at the upper window part
  Consonance.ShowGraphPoints(HIDE);   // Draw only the lines, not the points
  Consonance.SetGraphLineWidth(3);    // Set the line width to 3 pixel wide
  Consonance.SetGraphColorNum(2);     // Select color number 2, which is green
  Consonance.Rise();

  // Instantiation of the second Funplot window
  Funplot Dissonance("Dissonance");
  Dissonance.SetLables("time [s]","amplitude [-]","Visualisation of a Dissonance");
  Dissonance.SetNumGraphs(1);
  Dissonance.SetRange(-0.05,1.05,-4.1,4.1);
  Dissonance.SetAutoWindow(2,1,2);
  Dissonance.ShowGraphPoints(HIDE);
  Dissonance.SetGraphLineWidth(3);
  Dissonance.SetGraphColorNum(3);
  Dissonance.Rise();

  // Definition of Pi
  pi= 3.1415926;

  // Definition of the "Musical Constant"
  musiCon= pow(2,1/12.);

  // Frequencies of a Consonance and a Dissonance
  f= 880;                          // Base frequency [Hz]
  ome1= 2*pi*f*pow(musiCon,2.);

  ome2a= 2*pi*f*pow(musiCon,3.);
  ome3a= 2*pi*f*pow(musiCon,5.);   // Consonance

  ome2b= 2*pi*f*pow(musiCon,2.9);
  ome3b= 2*pi*f*pow(musiCon,4.8);  // Dissonance


  // Superimposition of these frequencies as function of time
  for (t=0; t<=1; t+=0.00001) {

    // ... for a Consonance
    amp= sin(ome1*t) + sin(ome2a*t) + sin(ome3a*t);
    Consonance.LineTo(t,amp);

    // ... for a Dissonance
    amp= sin(ome1*t) + sin(ome2b*t) + sin(ome3b*t);
    Dissonance.LineTo(t,amp);

    // Allow user interaction
    Funplot::MessageCheck();

  }

  // Enter the 'endless' message loop until the user exits
  Funplot::MessageLoop();

  return 0;
}

And this comes out when executing the program. One Plot shows the consonance, the other Plot the dissonance. Which one is the consonance, do you see the difference?


When executing this example just keep in mind that the Plots contain 100000 points each. This is done to slow down the computation, thus to allow user interaction during the data is generated.

You can find the source code and the executable of this and other examples in the 'examples' directory.


Access Functions

The following interface functions are part of the class Funplot and are taken from the header-file 'Funplot.h'. Meaning and parameter type are always explained in the comment region. The unit of the parameter is enclosed in square brackets. The following legend is used for the parameter type:

I: Input
O: Output
D: Predefined value, see respective function or 'FunplotDef.h'
P: Pointer
X: Optional parameter

Constructor

This function is implicitly called at the moment you define your Funplot instance. Default values for the instance are set and the specified title for the Funplot window is copied.

Funplot(                    // Constructors never have a return value
  char *funTitle="Funplot"  // I: title of the Funplot window [-]
);

Copy Constructor

This function is implicitly called when the Funplot instance has to be copied, e.g. in a function call where the Funplot instance is passed by value and not by reference. Dynamic memory is allocated and you got a complete independent copy of the specified instance.

Funplot(    // Constructors never have a return value
  Funplot&  // I: Funplot instance that has to be copied [-]
);

Assignment Operator

This function is implicitly called when you assign a Funplot instance to another Funplot instance when using the assignment operator. Dynamic memory is allocated and you got a complete independent copy of the specified instance. This function is similar to the Copy Constructor. As the assignment function returns a reference of the left hand side instance you can nest assignment operators (like this:  a = b = c)

Funplot& operator=(  // O: reference of the left hand side instance [-]
  Funplot&           // I: Funplot instance that has to be assigned [-]
);

Destructor

This function is implicitly called when the Funplot instance leaves its definition scope. Here mainly the allocated memory is freed.

~Funplot(void);  // Destructors never have a return value

SetWindowPos

Sets the position of the Funplot window on screen. The specified position refers to the upper left corner of the Funplot window. Note, that the call of this function is optional. The default position of the first window and the increment values for succeeding windows can be set using the static function SetDefValue.

void SetWindowPos(
  short xWinPos,  // I: position in x-direction [pixel]
  short yWinPos   // I: position in y-direction [pixel]
);

SetAutoWindow

Sets the position of the window on screen automatically, considering your specified positioning information. First you specify your virtual subdivision of your screen in rows (y) and columns (x)  then you specify the positioning of your instance relative to this subdivision. The position of the window is automatically calculated and set. Consider you want to divide your screen in 2 rows with 3 columns and you want to place the instance in the middle of the lower row (5th window counted row-wise), then the function call SetAutoWindow(2,3,5) has to be performed. Note, that you can call this function for another instance with a different virtual subdivision.

void SetAutoWindow(
  short numRows,  // I: number of rows                     [-]
  short numCols,  // I: number of columns                  [-]
  short element   // I: element number (counting row-wise) [-]
);

SetWindowSize

Sets the size of the window on screen. Note, that the call of this function is optional. The default size of the window can be set using the static function SetDefValue.

void SetWindowSize(
  short xWinSize,  // I: size in x-direction [pixel]
  short yWinSize   // I: size in y-direction [pixel]
);

SetWindowTitle

Sets or changes the title of the window on screen. The specified title is copied and if the window is already raised (shown), the new title appears on the window preceded by the instance ID.

void SetWindowTitle(
  char *windowTitle  // I: title of the Funplot window [-]
);

SetFullScreen

Sets the size of the window at the size of the screen. But note, that the window is not "maximized".

void SetFullScreen(void);

SetZoomMode

When using this function a "zoom mode" is preset when using your application. The following zoom modes are available:

void SetZoomMode(
  short zoomMode  // I,D: Zoom mode value [-]
);

SetColorScheme

Sets the color scheme of the Plot. A color scheme consists of a predefined set of colors for the border, the axes system, the axes background and the color of the grid. Use one of the following color schemes: LIGHT, DARK, PAPER, SCOPE, FANCY.

void SetColorScheme(
  short colorScheme  // I,D: color scheme to be selected [-]
);

SetUserFile

Usually data is read from a "data file" and is saved to file using the Funplot format described in File Types. The same applies for Plot files and Session files. Using this function here, allows the programmer to handle his own files. In this case when the user selects the respective Funplot file menu item a message will be generated (instead of saving or opening the file) which can be checked using the function CheckUserFileRequest. The function calling arguments can be a selection of one or more of the following predefined values:

Use the | operator to set multiple options e.g. SetUserFile(OPEN | ADD | DATA_FILE | PLOT_FILE), meaning you want to handle opening and adding data files and Plot files, while saving of these and handling of Session files are done in the conventional way. It is obvious that NO_USER_FILE is used alone and OPEN, ADD, SAVE are always paired with DATA_FILE, PLOT_FILE, SESSION_FILE.

void SetUserFile(
  short userFile  // I,D: User file flag [-]
);

SetFocus

Normally, the last defined Funplot instance has the focus. Focus means the window is active and receives all user messages. With this function you can set explicitly the focus to the particular Funplot window.

void SetFocus(void);

Rise

After you have defined a Funplot instance and you have called some setting functions you can let the Plot window appear on screen using this function. The window is created together with the menu and the status bar, the Plot is drawn.

void Rise(void);

SetRange

Sets the viewing range of the Plot by specifying the minimum and maximum world coordinates. Note, that the call of this function is optional. The last parameter of the function is also optional - it specifies if the last view has to be stored for been called with the View Last menu item - and by default is set to true.

void SetRange(
  double xMin,         // I: minimum x-value [world unit]
  double xMax,         // I: maximum x-value [world unit]
  double yMin,         // I: minimum y-value [world unit]
  double yMax,         // I: maximum y-value [world unit]
  bool storeLast=true  // I,X: storage of last view [-]
);

SetTicks,SetXTicks, SetYTicks

These function set the tickmark distances for the main ticks and the sub-tickmarks. If no value is specified for the sub ticks, the value will be calculated automatically dividing the main ticks distances by the number of sub ticks defined. The tickmark distances can also be set for a single axis only. An automatic calculation of tickmark distances is supported using the AutoTicks functions, which will be called in the case you do not want to use the SetTicks functions.

void SetTicks(
  double xTick,     // I: main tick distance in x  [world unit]
  double yTick,     // I: main tick distance in y  [world unit]
  double xSubTick,  // I,X: sub tick distance in x [world unit]
  double ySubTick   // I,X: sub tick distance in y [world unit]
);

void SetXTicks(
  double xTick,    // I: main tick distance in x  [world unit]
  double xSubTick  // I,X: sub tick distance in x [world unit]
);

void SetYTicks(
  double yTick,    // I: main tick distance in y  [world unit]
  double ySubTick  // I,X: sub tick distance in y [world unit]
);

SetLables

Sets the lables of the Plot. The x- and y-lables are the description of the respective axes. The x-lable is placed horizontally below, the y-lable is placed rotated by 90 degree at the left, the axis title is placed above the axes system. All lables are centered between the axes system borders. Note, that the lable texts are copied to private variables such that you can reuse or "free" your passed variables.

void SetLables(
  char* xLable,       // I,P:   lable of the x-axis      [-]
  char* yLable,       // I,P:   lable of the y-axis      [-]
  char* axesTitle=""  // I,P,X: lable of the axes system [-]
);

SetUserInterface

Use this function, if you do not want the user to interact with the window. In this case no menu and no status bar is displayed, zooming and keyboard inputs are ignored. Possible is only sizing and moving the Funplot window. Of course as default the user interface is switched on. Allowed are the following defined values: HIDE or SHOW.

void SetUserInterface(
  short userInterface  // I,D: show value [-]
);

ShowCoorSystem

There are three possibilities for showing the coordinate system. In this contents this means the borders, the tickmarks and grid. The following values are defined:

void ShowCoorSystem(
  short showCoorSystem  // I,D: show value [-]
);

ShowLegend

Displays a legend at the specified location. There it uses the already specified graphs line settings (width, color, style), the graph marker and the specified graph lable. You can choose among the following defined values:

void ShowLegend(
  short showLegend  // I,D: show value [-]
);

ShowGrid

Sets the showing of the grid, with the following options:

void ShowGrid(
  short showGrid  // I,D: show value [-]
);

SetAspectRatio

This feature is specially designed for purposes where you want equal sized x- and y-axes. This means the aspect ratio is set so that equal tick mark increments on the x- and y-axis are equal in size. Mostly used, when the two axes have the same unit as e.g. architectural drawings. Use

void SetAspectRatio(
  short aspectRatio  // I,D: aspect ratio [-]
);

SetOriginalRange

The range which is used for the first display of the Plot is taken as the original range, which can be selected by the user with the respective menu item. However you can overwrite the original range with the actual range using this function.

void SetOriginalRange(void);

SetColorSet

A color number is assigned to each graph. The color itself is determined by this number and the respective entry in the color set. Following sets are available:

The 'number of colors' specified is used for subdividing the color set. So if you choose e.g. SetGraphColorSet(RED_SCALE,20) you will have the red palette divided in 20 colors starting with black and finishing with white using 18 red color shades in between. The color sets MIXED_COLORS_I and MIXED_COLORS_II ignore the number of colors. For these color sets the assignment of a color to a color number is cyclic, thus restarting with the color palette when the color number exceeds the number of colors of this set. Note, that for the other color sets when exceeding the number of colors specified the "last" color is chosen.

void SetColorSet(
  short colorPalette,  // I,D: predefined color set [-]
  short numColors=16   // I,X: number of colors     [-]
);

SetGraphsReadMode

This function is used to set the default value for reading data files, which do not have a Plot file (*.plt). Data in data files can be interpreted in different ways from your Plot window. According to the data file description in the user manual, the read mode value can be set to XYY, XYXY, XYAYA, XYAXYA, YY.

void SetGraphsReadMode(
  short readMode  // I,D: Read mode value [-]
);

SetGraphLinesDrawRate

As default every line and pixel of a graph is drawn. You can reduce the data output on the drawing region of your coordinate frame, e.g. to have a faster response (even if Funplot handles 100000 points very fast :-) or to have a Plot decreased in size for later copy&paste, by using this function. Setting this value to 'n' results in every 'n'-th value to be drawn. Resetting it to 1 draws every line. Note, that the set value takes effect when the Plot is redrawn (use Update).

void SetGraphLinesDrawRate(
  short linesDrawRate,  // I:   draw rate frequency of lines and pixel [-]
  short graphNum=0      // I,X: graph number (0: all graphs)           [-]
);

SetGraphPointsDrawRate

This features changes the drawing rate of points (if or when activated), maintaining the actual line draw rate (and so maintaining the actual line curvature). Increase the function value from 1 to n to have drawn any n-th point. Note, that the set value takes effect when the Plot is redrawn (use Update).

void SetGraphPointsDrawRate(
  short pointsDrawRate,  // I:   draw rate frequency of points [-]
  short graphNum=0       // I,X: graph number (0: all graphs)  [-]
);

SetGraphMarkerDrawRate

This features changes the drawing rate of marker (if or when activated), maintaining the actual line draw rate (and so maintaining the actual line curvature). Increase the function value from 1 to n to have drawn any n-th marker. Note, that the set value takes effect when the Plot is redrawn (use Update).

void SetGraphMarkerDrawRate(
  short markerDrawRate,  // I:   draw rate frequency of marker [-]
  short graphNum=0       // I,X: graph number (0: all graphs)  [-]
);

SetGraphFixDrawRate

This functions fixes the actual draw rate of a single or all graphs and does not display the points for this graph. Even if the user changes the draw rates or the points view settings this graph remains unchanged. It is a feature for the programmer when he wants a constant line in the background, e.g. a map or a reference function, which shall not be influenced by the user.

void SetGraphFixDrawRate(
  bool fixDrawRate,  // I:   fix draw rate flag           [-]
  short graphNum=0   // I,X: graph number (0: all graphs) [-]
);

SetGraphLineWidth

Sets the line width of a single or all graphs to the specified value in pixel. The default line width is 1.

void SetGraphLineWidth(
  short lineWidth,  // I:   line width                   [pixel]
  short graphNum=0  // I,X: graph number (0: all graphs) [-]
);

SetGraphColorNum

Sets the color number of a single or all graphs, which then refers to the color set. See function SetColorSet for more detailed information.

void SetGraphColorNum(
  short colorNum,   // I:   color number                 [-]
  short graphNum=0  // I,X: graph number (0: all graphs) [-]
);

SetGraphMarkerType

Sets the type of marker of a single or all graphs, which can be switched to one of the following:

Note, that all marker with exception of POINT are outlined.

void SetGraphMarkerType(
  short markerType,  // I,D: marker type                  [-]
  short graphNum=0   // I,X: graph number (0: all graphs) [-]
);

SetGraphType

Sets the graph type of a single or all graphs, with one of the following values:

void SetGraphType(
  short type,       // I,D: type of the graph            [-]
  short graphNum=0  // I,X: graph number (0: all graphs) [-]
);

SetGraphLable

Sets the lable of a single or all graphs. The default lable is "Graph x", with x being the graph number. The graph lable is used in the legend and for identification of the graph in dialog boxes.

void SetGraphLable(
  char* lable,      // I,P: graph lable                  [-]
  short graphNum=0  // I,X: graph number (0: all graphs) [-]
);

SetGraphPointsSize

Set the size of points of a single or all graphs. The points size is used when the respective point has to be shown.

void SetGraphPointsSize(
  short pointsSize,  // I:   points size (radius)         [pixel]
  short graphNum=0   // I,X: graph number (0: all graphs) [-]
);

SetGraphMarkerSize

Set the marker size of a single or all graphs. The marker size is used when the respective point has to be shown.

void SetGraphMarkerSize(
  short markerSize,  // I:   points size  (radius)        [pixel]
  short graphNum=0   // I,X: graph number (0: all graphs) [-]
);

ShowGraphLines

Sets the showing of the lines of a single or all graphs.

void ShowGraphLines(
  short showLines,   // I,D: show lines value             [-]
  short graphNum=0   // I,X: graph number (0: all graphs) [-]
);

ShowGraphPoints

Sets the showing of the points of a single or all graphs in form of small spheres (3D-Effect).

void ShowGraphPoints(
  short showPoints,  // I,D: show points value            [-]
  short graphNum=0   // I,X: graph number (0: all graphs) [-]
);

ShowGraphMarker

Sets the showing of the marker of a single or all graphs which are assigned to the graph (see SetGraphMarkerType).

void ShowGraphMarker(
  short showMarker,  // I,D: show marker value            [-]
  short graphNum=0   // I,X: graph number (0: all graphs) [-]
);

LineTo

Draws a line from the cursor ("last point") of the specified graph to the specified point. When you use the function for the first time for the specified graph no line is drawn. After the operation the graph cursor ("last point") is located at the specified point. The line style (color, width, marker, ...) is taken from the actual graph settings.

void LineTo(
  double x,         // I:   x co-ordinate of point [world unit]
  double y,         // I:   y co-ordinate of point [world unit]
  short graphNum=1  // I,X: graph number           [-]
);

LineOut

Draws a line between the two specified points for the specified graph. After the operation the graph cursor ("last point") is located at the second point. The line style (color, width, marker, ...) is taken from the actual graph settings.

void LineOut(
  double x1,        // I:   x co-ordinate of 1st point [world unit]
  double y1,        // I:   y co-ordinate of 1st point [world unit]
  double x2,        // I:   x co-ordinate of 2nd point [world unit]
  double y2,        // I:   y co-ordinate of 2nd point [world unit]
  short graphNum=1  // I,X: graph number               [-]
);

PixelOut

Sets a pixel at the specified point with the respective color of the specified graph. After the operation the graph cursor ("last point") is located at the specified point.

void PixelOut(
  double x,         // I:   x co-ordinate of point [world unit]
  double y,         // I:   y co-ordinate of point [world unit]
  short graphNum=1  // I,X: graph number           [-]
);

CircleOut

Draws a circle with radius 'r' using the given midpoint co-ordinates and the number of specified circle segments. The line style (color, width, marker, ...) is taken from the actual graph settings. After the operation the cursor ("last point") of the specified graph is located at position "3:00".

void CircleOut(
  double x,         // I:   x co-ordinate of midpoint [world unit]
  double y,         // I:   y co-ordinate of midpoint [world unit]
  double r,         // I:   radius of circle          [world unit]
  short numPoints,  // I:   number of segments        [-]
  short graphNum=1  // I,X: graph number              [-]
);

RectangleOut

Draws a rectangle 'dx' wide and 'dy' high symmetrically around the given midpoint. The line style (color, width, marker, ...) is taken from the actual graph settings. After the operation the cursor ("last point") of the specified graph is located at the lower left corner of the rectangle.

void RectangleOut(
  double x,         // I:   x co-ordinate of midpoint [world unit]
  double y,         // I:   y co-ordinate of midpoint [world unit]
  double dx,        // I:   width of rectangle        [world unit]
  double dy,        // I:   height of rectangle       [world unit]
  short graphNum=1  // I,X: graph number              [-]
);

PolylineOut

Given an array of 'x'-values and an array of 'y'-values a polyline is drawn. Multiplication factors for the x- and y-values give you the possibility to scale the values before they are drawn, always useful when you change the physical units. Before drawing the polyline, the cursor ("last point") of the specified graph is moved to the first specified point of the data values. Use ClosedPolylineOut for a closed polyline. The line style (color, width, marker, ...) is taken from the actual graph settings. After the operation the cursor ("last point") of the specified graph is located at the last point of the data values.

void PolylineOut(
  double *x,        // I:   pointer to an array of x-values    [world unit]
  double *y,        // I:   pointer to an array of y-values    [world unit]
  long numPoints,   // I:   number of data value pairs         [-]
  double factorX,   // I:   multiplication factor for x-values [-]
  double factorY,   // I:   multiplication factor for y-values [-]
  short graphNum=1  // I,X: graph number                       [-]
);

ClosedPolylineOut

Given an array of x-values and an array of y-values a polyline is drawn. The line is closed by connecting the last data values of the x- and y-values with the first values. Multiplication factors for the x- and y-values give you the possibility to scale the values before they are drawn, always useful when you change the physical units. Before drawing the polyline, the cursor ("last point") of the specified graph is moved to the first specified point of the data values. Use PolylineOut for a regular (not closed) polyline. The line style (color, width, marker, ...) is taken from the actual graph settings. After the operation the cursor ("last point") of the specified graph is located at the first point of the data values.

void ClosedPolylineOut(
  double *x,        // I:   pointer to an array of x-values    [world unit]
  double *y,        // I:   pointer to an array of y-values    [world unit]
  long numPoints,   // I:   number of data value pairs         [-]
  double factorX,   // I:   multiplication factor for x-values [-]
  double factorY,   // I:   multiplication factor for y-values [-]
  short graphNum=1  // I,X: graph number                       [-]
);

AddLineTo

Similar to the LineTo function this function adds a line to the specified point of the specified graph but does not draw it immediately, only when the Plot is redrawn (use Update). After the operation the cursor ("last point") of the specified graph is located at the specified point.

void AddLineTo(
  double x,         // I:   x co-ordinate of point [world unit]
  double y,         // I:   y co-ordinate of point [world unit]
  short graphNum=1  // I,X: graph number           [-]
);

AddPixel

Similar to the PixelOut function this function adds a pixel at the specified point of the specified graph but does not draw it immediately, only when the Plot is redrawn (use Update). After the operation the cursor ("last point") of the specified graph is located at the specified point.

void AddPixel(
  double x,         // I:   x co-ordinate of point [world unit]
  double y,         // I:   y co-ordinate of point [world unit]
  short graphNum=1  // I,X: graph number           [-]
);

NewLine

Useful when you want a new segment of lines for that graph (a graph does not necessarily need to be an uninterrupted polyline). You don't need this function when you start a graph.

void NewLine(
  short graphNum=1  // I,X: graph number [-]
);

SetNumGraphs

Sets the number of graphs you need in your Plot. If the number specified is bigger than the actual number of graphs (use GetNumGraphs to get the number) new graphs are allocated to reach the specified number. In the case the specified number is smaller than the actual number of graphs nothing is done. New graphs are implicitly allocated using the function NewGraph. Note, that the actual used graphs are not modified.

void SetNumGraphs(
  short numGraphs  // I: number of required graphs [-]
);

GetNumGraphs

Returns the number of graphs that have already been allocated.

short GetNumGraphs(void);  // O: number of allocated graphs [-]

GetGraphNumPoints

Returns the actual number of points of the specified graph.

long GetGraphNumPoints(   // O: number of points of the graph [-]
  short graphNum=1        // I,X: graph number                [-]
);

GetGraphData

Returns the x- and y-coordinate of the specified point of the graph.

void GetGraphData(
  double* x,        // O:   x co-ordinate of point [world unit]
  double* y,        // O:   y co-ordinate of point [world unit]
  long pointNum,    // I:   point number           [-]
  short graphNum=1  // I,X: graph number           [-]
);

GetGraphDataAtt

Returns the attribute value of the specified point of the graph. If the attribute value is 1 a new line begins here (a graph can consist of multiple lines), the value 0 means connection to the value pair before.

void GetGraphDataAtt(
  short* att,       // O:   attribute value of point [world unit]
  long pointNum,    // I:   point number             [-]
  short graphNum=1  // I,X: graph number             [-]
);

NewGraph

Adds an additional graph. The graph number of the new graph is returned. The graph is empty. If you need more than one additional graph you can also use SetNumGraphs.

short NewGraph(void);  // O: graph number of new graph [-]

DeleteGraph

Removes the specified graph and so all the respective points of it (freeing the allocated memory). Note, that subsequent function calls of the graphs must consider, that the graph number of all the graphs with a bigger graph number than the specified one, are reduced by 1.

void DeleteGraph(
  short graphNum  // I: graph number [-]
);

DeleteAllGraphs

Removes all the points of all graphs and sets the number of graphs to 0.

void DeleteAllGraphs(void);

AutoRange, AutoRangeX, AutoRangeY

When choosing the AutoRange feature the actual range of the Plot is selected such that all points are inside. It goes through all points of all graphs and calculates the boundary box. When choosing AutoRangeX it holds the actual y-range and displays all points in that range. The vice versa is valid for AutoRangeY.

void AutoRange(void);

void AutoRangeX(void);

void AutoRangeY(void);

AutoTicks, AutoXTicks, AutoYTicks

An automatic calculation of tickmark distances is supported using these functions. The distance for the main ticks is calculated dividing the range for the respective axis by the number of main ticks, the distance for the sub ticks is calculated dividing the main ticks distance by the number of sub ticks. The tickmark distances can also be set for a single axis only using the respective functions.

void AutoTicks(void);

void AutoXTicks(void);

void AutoYTicks(void);

CopyToClipboard

Copies the actual Plot, black and white or coloured, as Enhanced Metafile to the Windows clipboard, using the specified resolution. The specified resolution is taken as the width (x) of the Plot, while the height (y) is calculated implicitly by considering the actual Width-to-Height ratio. Setting the resolution to 0, or when the resolution is not specified at all, leads to the use of the Plot resolution. You can paste the clipboard metafile to any Windows application that handles wmf as e.g. Word, Visio or CorelDraw. When choosing black and white, every graph, the grid and the coordinate frame are copied black. Thus the following values can be used for colorMode:

void CopyToClipboard(
  short colorMode     // I,D: predefined color mode   [-]
  short resolution=0  // I,X: resolution for the Plot [pixel]
);

SaveFigure

Saves the actual Plot, black and white or coloured, as Enhanced Metafile to File, using the specified resolution. The specified resolution is taken as the width (x) of the Plot, while the height (y) is calculated implicitly by considering the actual Width-to-Height ratio. Setting the resolution to 0, or when the resolution is not specified at all, leads to the use of the Plot resolution. When choosing black and white, every graph, the grid and the coordinate frame are copied black. Thus the following values can be used for colorMode:

void SaveFigure(
  short colorMode     // I,D: predefined color mode   [-]
  short resolution=0  // I,X: resolution for the Plot [pixel]
);

Print

This feature directly prints your Plot view black and white or coloured. 'Funplot' uses the full horizontal resolution of the printer. Note, that 'Funplot' takes care of the Plot window's actual Width-to-Height ratio. The default printer with it's actual orientation (normally 'Portrait') is used. Change the printer's orientation to 'Landscape' to obtain a full paper Plot. When choosing black and white, every graph, the grid and the coordinate frame are printed black. The specified print factor is a multiplicator for the line width of the graphs and the coordinate frame and for the text size of titles and values. The default value 1 for printFactor is suited for most purposes. The following values can be used for colorMode:

void Print(
  short colorMode,      // I,D: predefined color mode           [-]
  double printFactor=1  // I,X: multiplication factor for style [-]
);

PrintSession

Prints all plots of the Session. It uses implicitly the Print function for every single Plot. See there for definition of parameters printFactor and colorMode.

void PrintSession(
  short colorMode,      // I,D: predefined color mode           [-]
  double printFactor=1  // I,X: multiplication factor for style [-]
);

FileOpen

Calling this function let a dialog box appear, which lets the user choose/specify a file. This file is further (implicitly) processed with the FileOpenDirect function. The following values can be used for openInfo:

in combination with: Thus FileOpen(ADD|PLOT_FILE) opens a dialog box letting the user choose (with default extension filter) or specify a Plot file which is added to the current Session. Note, when using DATA_FILE the configured read mode will be taken, which can be set with SetDefValue.

bool FileOpen(    // O: flags if file opened successfully    [-]
  short openInfo  // I,D: predefined option for file opening [-]
);

FileAutoOpen

This function checks the specified 'fileName' for its extension and decides there from if it is a DATA_FILE , a PLOT_FILE or a SESSION_FILE. This file is further (implicitly) processed with the FileOpenDirect function. One of the two following values can be used for openInfo:

Note, when DATA_FILE is automatically chosen, the configured read mode will be taken, which can be set with SetDefValue.

void FileAutoOpen(
  char* fileName,  // I,P: (full) file name of file to be opened [-]
  short openInfo   // I,D: predefined option for file opening    [-]
);

FileOpenDirect

The FileOpenDirect function generally serves to replace or add graphs to existing ones in your Plot, to add or replace the Plot or to add or replace the Session. In normal case the chosen file is expected to be 'Funplot' compliant, see handled files in the User Manual. Instead, if you have set the user file (SetUserFile) with appropriate options, the FileOpenDirect function just generates a user file request, which value can be checked using the function CheckUserFileRequest. The following values can be used for setting openInfo:

in combination with:

Thus FileOpenDirect(ADD|PLOT_FILE) opens the specified file as a Plot file (there is no extension check and no check if it is really a Plot file) which is then added to the current Session. Note, when using DATA_FILE the configured read mode will be taken, which can be set with SetDefValue.

bool FileOpenDirect(  // O: flags if file opened successfully       [-]
  char* fileName,     // I,P: (full) file name of file to be opened [-]
  short openInfo      // I,D: predefined option for file opening    [-]
);

FileSave

Calling this function let a dialog box appear, which lets the user choose/specify a file. This file is further (implicitly) processed with the FileSaveDirect function. The following values can be used for saveInfo:

in combination with:

Thus FileSave(SAVE|DATA_FILE) opens a dialog box letting the user choose (with default extension filter) or specify a data file and saves the data of the current Plot to that file.

bool FileSave(    // O: flags if file saved successfully    [-]
  short saveInfo  // I,D: predefined option for file saving [-]
);

FileSaveDirect

The FileSaveDirect function generally serves to save the data in a plot, to save the plot itself or to save the Session. See the File | Open menu entries in the User Manual. If you have set the user file (SetUserFile) with appropriate options instead, the FileSave function just generates a user file request, which value can be checked using the function CheckUserFileRequest. The following values can be used for saveInfo:

in combination with:

Thus FileSaveDirect(SAVE|DATA_FILE) saves the data of the current plot to the specified file.

bool FileSaveDirect(  // O: flags if file saved successfully      [-]
  char* fileName,     // I,P: (full) file name of file for saving [-]
  short saveInfo      // I,D: predefined option for file saving   [-]
);

FileOpenDialogBox

This function is used only when the user file (SetUserFile) with appropriate options is set, then normally after a CheckUserFileRequest has resulted in OPEN or ADD. The appearing file open dialog box let the user choose/specify a file. The chosen filename is returned. You can use an extension filter for selecting files. Normally this goes together with a string which has to be displayed. The return value tells you if the user has selected or specified a valid and existing file. In this case the file path and name is returned in a string, for which no memory allocation is required. A title text for the box has to be provided.

bool FileOpenDialogBox(     // O: flag if file selected successfully  [-]
  char*& filePathAndName,   // O: file name with path                 [-]
  char* boxTitle="Open",    // I,P: dialog box title                  [-]
  char* filterDisplay="",   // I,P: string for filter to be displayed [-]
  char* filterPattern=""    // I,P: extension filter                  [-]
);

FileSaveDialogBox

This function is used only when the user file (SetUserFile) with appropriate options is set, then normally after a CheckUserFileRequest has resulted in SAVE. The appearing file save dialog box let the user choose/specify a file. The chosen filename is returned. You can use an extension filter for selecting files. Normally this goes together with a string which has to be displayed. The return value tells you if the user has selected or specified a valid file. In this case the file path and name is returned in a string, for which no memory allocation is required. A title text for the box has to be provided.

bool FileSaveDialogBox(     // O: flag if file selected successfully  [-]
  char*& filePathAndName,   // O: file name with path                 [-]
  char* boxTitle="Save",    // I,P: dialog box title                  [-]
  char* filterDisplay="",   // I,P: string for filter to be displayed [-]
  char* filterPattern=""    // I,P: extension filter (without ".")    [-]
);

CheckUserFileRequest

This function is used only when the user file (SetUserFile) with appropriate options is set. A user file request is then generated when the FileOpen or FileSave function is called by the user or the programmer. This is especially the case, when the user clicks the respective menu item. Use this function for checking if and kind of the request. After interpretation of the request you usually call FileOpenDialogBox or FileSaveDialogBox to let the user select a file, then open and process the file your own way. When you have used this function, the request is implicitly reset with the value NO_REQUEST. Thus the return value will have one of the following predefined values:

in combination with:

Or if no request exists just simply

short CheckUserFileRequest(void);    // O,D: user request (predefined) [-]

Update

This function clears the complete window and redraws the plot, including coordinate frame, grid, all graphs and points if selected.

void Update(void);

MessageBoxExclamation

This message box informs the user with a specified text message. He must accept the box clicking the OK button. An exclamation icon is added to the box, so that you normally use this function to display an important notification, like an error message.

void MessageBoxExclamation(
  char *messageText   // I,P: text to be displayed [-]
);

MessageBoxInformation

This message box informs the user with a specified text message. He must accept the box clicking the OK button. An information icon is added to the box, so that you normally use this function to display a user information.

void MessageBoxInformation(
  char *messageText   // I,P: text to be displayed [-]
);

ClassRegister

In Windows before using a window class it has to be registered. This static function registers the Funplot class, so that you can start working with it. It has to be called once, at the beginning of your code. The function parameters are directly passed from the WinMain function parameters. Note, that a Windows program requires a WinMain function with specified function parameters, instead of the typical main function. It is called by the system as the initial entry point for a Win32-based application. See the added examples for the concrete implementation.

static void ClassRegister(
  HINSTANCE hInstance,       // I: handle to current instance  [-]
  HINSTANCE hPrevInstance,   // I: handle to previous instance [-]
  int nCmdShow               // I: show state of window        [-]
);

MessageCheck

If you write an application with a big amount of calculation time and you just want to give the user the possibility to interact with your application during calculation time, e.g. zooming in and out, you must use this static function in regular intervals. It's up to you to decide how often this should happen. Normally it is sufficient to put it at an outer 'for loop', but this depends on your kind of calculation. After this function is called, perform a CheckUserBreak to check if the user wants to break or terminate or CheckUserFileRequest if you have set the user file. See also MessageLoop.

static void MessageCheck(void);

MessageLoop

The static function MessageLoop is used at the end of your application, when all calculations are done, allowing the user to analyze your generated data, add his own data, copy, print or save the actual Plot. The loop is left when the user exits the application. The return value is suited as return value for your application to the system.  See also MessageCheck.

static int MessageLoop(void);   // O: exit value of message loop [-]

CheckUserBreak

Checks if the user wants to BREAK or EXIT by clicking the respective menu items. BREAK is a feature that the programmer can use as additional information in communication with the user. Generally you use the BREAK item to leave your calculation loop, going then to the end of your application and use the MessageLoop to let the user analyse your data generated so far. EXIT is generated if the user wants to terminate the application. Please free your allocated memory and exit the application. In case there is no user request NO_BREAK is returned. Note, after having have used this function the BREAK request is removed while the EXIT request remains. Thus the return value can be one of the following predefined values:

static short CheckUserBreak(void);   // O,D: user request (predefined) [-]

CloseAllWindows

Closes all Funplot windows belonging to this application and generates an EXIT request. If there is more than one Funplot window the user is asked for confirmation. When closing the windows the generated data in the plots are freed. This static function is called implicitly when the user terminates the application. Note, that the EXIT request can be checked using the function CheckUserBreak.

static void CloseAllWindows(void);

MinimizeAllWindows

Minimises (iconises) all Funplot windows belonging to the application.

static void MinimizeAllWindows(void);

MaximizeAllWindows

Maximises (full screen) all Funplot windows belonging to the application. Note, that the not maximised windows appear in the order they have been generated.

static void MaximizeAllWindows(void);

ShowNormalAllWindows

Shows all Funplot windows belonging to the application in normal size. Note, that the iconised or maximised windows are shown in the order they have been generated.

static void ShowNormalAllWindows(void);

ShowWindow

Shows the Funplot window if it previously was hided using HideWindow.

void ShowWindow(void);

HideWindow

Hides the Funplot window if it previously was shown. Hiding the window makes it completely invisible for the user, but it is still there. Use ShowWindow to make it visible again.

void HideWindow(void);

SetDefValue

Sets the default value of a specified parameter. The names of the parameter are identical to those used in the Funplot.ini file. See also the Options chapter in the 'User Manual' for the parameter names, their meaning and the units.

static void SetDefValue(
  char* paramStr,  // I,P: name of parameter to be set with default [-]
  double value     // I: value of parameter                         [-]
);


Funplot is not free software! Please read carefully the License Agreement!

e-mail:   support@VanillaWare.de
www:   http://www.VanillaWare.de

Copyright © 1998-2006 Domenico Reggio, Software-Engineering.