Funplot - 2D data plotting environment, version 1.0
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.
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.
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.
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.
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.
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
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 [-]
);
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 [-]
);
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 [-]
);
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
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]
);
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) [-]
);
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]
);
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 [-]
);
Sets the size of the window at the size of the screen. But note, that the window is not "maximized".
void SetFullScreen(void);
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 [-]
);
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 [-]
);
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 [-]
);
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);
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);
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 [-]
);
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]
);
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 [-]
);
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 [-]
);
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 [-]
);
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 [-]
);
Sets the showing of the grid, with the following options:
void ShowGrid(
short showGrid // I,D: show value [-]
);
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 [-]
);
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);
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 [-]
);
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 [-]
);
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)
[-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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) [-]
);
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 [-]
);
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
[-]
);
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
[-]
);
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 [-]
);
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
[-]
);
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
[-]
);
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
[-]
);
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 [-]
);
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 [-]
);
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 [-]
);
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 [-]
);
Returns the number of graphs that have already been allocated.
short GetNumGraphs(void); // O: number of allocated graphs [-]
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
[-]
);
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
[-]
);
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
[-]
);
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 [-]
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 [-]
);
Removes all the points of all graphs and sets the number of graphs to 0.
void DeleteAllGraphs(void);
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);
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);
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]
);
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]
);
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 [-]
);
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 [-]
);
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:
bool FileOpen( // O: flags if file opened
successfully [-]
short openInfo // I,D: predefined option for file opening [-]
);
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:
void FileAutoOpen(
char* fileName, // I,P: (full) file name of file to be
opened [-]
short openInfo // I,D: predefined option for file
opening [-]
);
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 [-]
);
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 [-]
);
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 [-]
);
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
[-]
);
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 ".") [-]
);
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) [-]
This function clears the complete window and redraws the plot, including coordinate frame, grid, all graphs and points if selected.
void Update(void);
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 [-]
);
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 [-]
);
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 [-]
);
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);
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 [-]
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) [-]
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);
Minimises (iconises) all Funplot windows belonging to the application.
static void MinimizeAllWindows(void);
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);
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);
Shows the Funplot window if it previously was hided using HideWindow.
void ShowWindow(void);
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);
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.