cdoc (ElVis C API)

ElVis API Documentation for C and C++

  cdoc

The GraphWindow encapsulates the object interface to ElVis. Application programs can send data to ElVis using the GraphWindow object.

The GraphWindow object defines the routines and data for defining a grid of graphs. Each cell of the grid contains one graph. A graph contains one or more datasets that are drawn in the plot area.

When a GraphWindow is displayed in ElVis it is drawn in a frame within the desktop window.

The geometric coordinates of a graph are specified between 0. - 1. horizontally and vertically. The origin, 0., 0., is at the lower left corner of the graph. The upper right corner of the graph is 1., 1. The layout of a graph is shown on the ElVis Programming Interface page.

In the C language API to ElVis the subroutine names start with e_ . The API allocates memory to store the GraphWindow before sending it to be displayed. Memory is allocated when the create routines are called (e_GraphWindowCreate, e_GraphCreate, e_DatasetCreate). The memory can be freed when it is no longer needed.

An application uses the API to build up the complete description of a GraphWindow and then send it to the ElVis display program. A typical sequence of calls is:

    #include "graphwindow.h"

    status = e_Initialize();
    status = e_Register("rplot", username, hostname, "NSTX-02");

    status = e_GraphWindowCreate("NSTX", 3, 2);
    status = e_GraphCreate("Temperature", E_NO_INDEX);
    status = e_GraphWindowAddGraph("NSTX", "Temperature", 0, 0);

    status = e_FxDatasetCreate("Exp 1", nPoints, x, fx);
    status = e_GraphAddFxDataset("Temperature", "Exp 1");

    status = e_GraphSetXLabel("Temperature", "X Axis Label");
    status = e_GraphSetYLabel("Temperature", "Y Axis Label");
    status = e_GraphSetTitle("Temperature", "Title of Graph");

    status = e_GraphWindowDisplay("NSTX");

    status = e_End();

This creates a GraphWindow with 3 rows and 2 columns. Then a graph is created and put in the leftmost column of the top row. A dataset is created and added to the graph. Then the parameters for the axes are set and a title is specified. Now that the GraphWindow is fully defined the last call is made to send the GraphWindow from the application to ElVis where it will be displayed. The upper left cell will contain the graph. The other 5 cells will be empty, but graphs can be added to them later.

The ElVis subroutines are in the library elvis.a. Application programs should be linked with elvis.a.

Constants
`int`	`E_DATASET_NOT_FOUND` The Dataset could not be found.
`int`	`E_DRAW_FAIL` The GraphWindow could not be drawn by ElVis display program.
`int`	`E_DRAW_SUCCESS` The GraphWindow was drawn in ElVis display program.
`int`	`E_FAIL` Parameters could not be set.
`int`	`E_FALSE`
`int`	`E_GRAPH_NOT_FOUND` The Graph could not be found.
`int`	`E_GRAPH_WINDOW_NOT_FOUND` The GraphWindow could not be found.
`int`	`E_LINEAR` The axis increments linearly.
`int`	`E_LOGARITHMIC` The axis increments logarithmically.
`int`	`E_NO_INDEX` The datasets in the graph are not indexed.
`int`	`E_PRINT_FAIL` The graph could not be printed by ElVis display program.
`int`	`E_PRINT_SUCCESS` The graph was printed by the ElVis display program.
`int`	`E_SEND_FAIL` The GraphWindow could not be sent to ElVis display program.
`int`	`E_SUCCESS` Parameters were set successfully.
`int`	`E_TIME_INDEX` The datasets in the graph are indexed in time.
`int`	`E_TRUE`
`int`	`E_VALUE_INDEX` The datasets in the graph are indexed by a value.

C Subroutine Summary
`int`	`e_CloseWindows(int port)` Close all the GraphWindows.
`int`	`e_End()` Terminate the API to ElVis.
`int`	`e_FxCreate(char *datasetName, int points, double x, double fx)` Create an f(x) dataset.
`int`	`e_FxtDatasetCreate(char *datasetName, int points, double x, double fx, double time)` Create an f(x) dataset that is indexed.
`int`	`e_FxtDatasetDisplay(char windowName, char graphName, char *datasetName)` Display an additional f(x) dataset that is indexed in time.
`int`	`e_GraphAddFxDataset(char graphName, char datasetName)` Add a dataset to the graph (by name).
`int`	`e_GraphAddFxDatasetID(char *graphName, int ID)` Add an indexed dataset to the graph (by ID).
`int`	`e_GraphAddLabel(char graphName, char label, float[] location, char font, char style, float size, float[] color)` Add a label to the graph.
`int`	`e_GraphCreate(char *graphName, int type)` Create a graph.
`int`	`e_GraphSetIndexLabel(char graphName, char label)` Specify the text of the Index label.
`int`	`e_GraphSetLegend(char *graphName, float[] location)` Position the legend.
`int`	`e_GraphSetPlotArea(char *graphName, float[] location, float width, float height)` Specify the plot area for the graph.
`int`	`e_GraphSetTitle(char graphName, char title)` Specify the title of the graph.
`int`	`e_GraphSetXAxis(char *graphName, int loglin)` Specify log/linear for the X axis.
`int`	`e_GraphSetXLabel(char graphName, char label)` Specify the label for the X axis.
`int`	`e_GraphSetYAxis(char *graphName, int loglin)` Specify log/linear for the Y axis.
`int`	`e_GraphSetYLabel(char graphName, char label)` Specify the label for the Y axis.
`int`	`e_GraphShowLegend(char *graphName, int show)` Draw or hide the legend.
`int`	`e_GraphWindowAddGraph(char windowName, char graphName, int row, int column)` Add a graph to a GraphWindow.
`int`	`e_GraphWindowAddSurface(char windowName, char surfaceName, int row, int column)` Add a surface to a GraphWindow.
`int`	`e_GraphWindowAppendGraph(char windowName, char graphName, int growth)` Append a graph to a GraphWindow.
`int`	`e_GraphWindowCreate(char *windowName, int rows, int columns)` Create a GraphWindow.
`int`	`e_GraphWindowDisplay(char *windowName, int port)` Send the GraphWindow data to ElVis and display it.
`int`	`e_GraphWindowFree(char *windowName)` Free memory allocated for a GraphWindow.
`int`	`e_GraphWindowPrint(char windowName, int row, int column, char fileName, int port)` Print a graph that is displayed in ElVis.
`int`	`e_Initialize()` Initialize the API to ElVis.
`int`	`e_Register(char source, char user, char host, char identifier)` Register the application with the ElVis server.
`int`	`e_ShowLines(char *datasetName, int show)` Control the display of lines between data points.
`int`	`e_ShowMarkers(char *datasetName, int showInterval)` Control the display of data point markers.
`int`	`e_SurfaceCreate(char surfaceName, char graphName)` Create a surface from a graph containing an indexed dataset.
`int`	`e_SurfaceSetTitle(char surfaceName, char title)` Specify the title of the surface.

Constants Detail

E_DATASET_NOT_FOUND

The Dataset could not be found.

Returned by: FxCreate, FxShowLines, FxShowMarkers, GraphAddFxDataset

E_DRAW_FAIL

The GraphWindow could not be drawn by ElVis display program. Data was received by the display program but could not be drawn.

Returned by: e_GraphWindowDisplay.

E_DRAW_SUCCESS

The GraphWindow was drawn in ElVis display program.

Returned by: e_GraphWindowDisplay.

E_PRINT_FAIL

The graph could not be printed by ElVis display program. The print command was received but the graph could not be printed to a file.

Returned by: e_GraphWindowPrint.

E_PRINT_SUCCESS

The graph was printed by the ElVis display program.

Returned by: e_GraphWindowPrint.

E_FAIL

Parameters could not be set.

Returned by: many.

E_FALSE

E_GRAPH_NOT_FOUND

The Graph could not be found.

Returned by: e_GraphAddFxDataset, e_GraphAddLabel, e_GraphSetIndexLabel, e_GraphSetPlotArea, e_GraphSetTitle, e_GraphSetXAxis, e_GraphSetYAxis.

E_GRAPH_WINDOW_NOT_FOUND

The GraphWindow could not be found.

Returned by: e_GraphWindowAddGraph, e_GraphWindowAppendGraph, e_GraphWindowDisplay.

E_LINEAR

The axis increments linearly.

E_LOGARITHMIC

The axis increments logarithmically.

E_NO_INDEX

The datasets in the graph are not indexed. All datasets are displayed simultaneously.

E_SEND_FAIL

The GraphWindow could not be sent to ElVis display program. The API tried to send data to the display program but there was no response. Make sure the ElVis display program is running. The ELVISHOST environment variable must be set to the name of the computer running the display program.

Returned by: e_GraphWindowDisplay.

E_SUCCESS

Parameters were set successfully.

Returned by: many.

E_TIME_INDEX

The datasets in the graph are indexed in time. Datasets indexed in time can be displayed as an animated sequence.

E_TRUE

E_VALUE_INDEX

The datasets in the graph are indexed by a value.

C Subroutine Detail

e_Initialize

int  e_Initialize()

Initialize the API to ElVis. The first subroutine call must be to initialize the data interface between the application program and ElVis.

The environment variable ELVISHOST must be set to specify the computer running the ElVis display program.

Returns:: E_SUCCESS or E_FAIL.

e_Register

int  e_Register(char *source,
                      char *user,
                      char *host,
                      char *identifier)

Register the application with the ElVis server. An application must register with the ElVis server before sending its data to the ElVis server.

Parameters:: source - - The name of the application.; user - - The user running the application.; host - - The hostname of the computer running the application.; identifier - - An aspect of the run for identifying it to potential display clients.
Returns:: E_SUCCESS or E_FAIL.

e_End

int  e_End()

Terminate the API to ElVis. Call this routine when the application has finished with ElVis. It will free any memory that ElVis still has allocated.

Returns:: E_SUCCESS or E_FAIL.

e_CloseWindows

int  e_CloseWindows(int port)

Close all the GraphWindows.

Parameters:: port - - The port number of the display client after it connects to the server.
Returns:: E_SUCCESS or E_FAIL.

e_GraphWindowCreate

int  e_GraphWindowCreate(char *windowName,
                               int rows,
                               int columns)

Create a GraphWindow. The name of the GraphWindow is shown in the title bar of the frame. Specify the number of row and columns in the GraphWindow.

Parameters:: windowName - - The name of the GraphWindow.; rows - - The number of rows in the GraphWindow.; columns - - The number of columns in the GraphWindow.
Returns:: E_SUCCESS or E_FAIL.

e_GraphWindowDisplay

int  e_GraphWindowDisplay(char *windowName,
                                int port)

Send the GraphWindow data to ElVis and display it.

Parameters:: windowName - - The name of the GraphWindow.; port - - The port number of the display client after it connects to the server.
Returns:: E_GRAPH_WINDOW_NOT_FOUND, E_DRAW_FAIL, E_DRAW_SUCCESS, or E_SEND_FAIL.

e_GraphWindowPrint

int  e_GraphWindowPrint(char *windowName,
                              int row,
                              int column,
                              char *fileName,
                              int port)

Print a graph that is displayed in ElVis. A graph that is currently displayed will be printed to a PostScript file. The graph is specified by its location in a GraphWindow.

The graph is scaled to fit an 8.5" x 11" sheet of paper. If the graph's width is greater than its height then the graph is printed in landscape format. Otherwise the graph is printed in portrait layout.

Parameters:: windowName - - The name of the GraphWindow.; row - - The row containing the graph to be printed. The top row is row 0.; column - - The column containing the graph to be printed. The leftmost column is column 0.; port - - The port number of the display client after it connects to the server.
Returns:: E_GRAPH_WINDOW_NOT_FOUND, E_PRINT_FAIL, E_PRINT_SUCCESS, or E_SEND_FAIL.

e_GraphWindowAddGraph

int  e_GraphWindowAddGraph(char *windowName,
                                 char *graphName,
                                 int row,
                                 int column)

Add a graph to a GraphWindow. If the GraphWindow is currently displayed then the graph is sent to ElVis and displayed in its cell.

Parameters:: windowName - - The name of the GraphWindow.; graphName - - The name of the graph.; row - - The graph is inserted in this row.; column - - The graph is inserted in this column.
Returns:: E_GRAPH_WINDOW_NOT_FOUND, E_GRAPH_NOT_FOUND, E_FAIL, or E_SUCCESS.

e_GraphWindowAddSurface

int  e_GraphWindowAddSurface(char *windowName,
                                   char *surfaceName,
                                   int row,
                                   int column)

Add a surface to a GraphWindow. If the GraphWindow is currently displayed then the surface is sent to ElVis and displayed in its cell.

Parameters:: windowName - - The name of the GraphWindow.; surfaceName - - The name of the surface.; row - - The graph is inserted in this row.; column - - The graph is inserted in this column.
Returns:: E_GRAPH_WINDOW_NOT_FOUND, E_SURFACE_NOT_FOUND, E_FAIL, or E_SUCCESS.

e_GraphWindowAppendGraph

int  e_GraphWindowAppendGraph(char *windowName,
                                    char *graphName,
                                    int growth)

Append a graph to a GraphWindow. If the GraphWindow is currently displayed then the graph is sent to ElVis and displayed.

Parameters:: windowName - - The name of the GraphWindow.; graphName - - The name of the graph.; growth - - If all cells contain a graph then: if E_TRUE then add a new row to the GraphWindow for this graph; if E_FALSE then delete the first graph, shift all graphs back by 1 cell, and insert this graph in the last cell.
Returns:: E_GRAPH_WINDOW_NOT_FOUND, E_GRAPH_NOT_FOUND, E_FAIL, or E_SUCCESS.

e_GraphWindowFree

int  e_GraphWindowFree(char *windowName)

Free memory allocated for a GraphWindow. All the memory in the interface that has been allocated for the GraphWindow is freed. The memory for its subcomponents, such as graphs and datasets, is also freed.

Parameters:: windowName - - The name of the GraphWindow.
Returns:: E_GRAPH_WINDOW_NOT_FOUND, E_FAIL, or E_SUCCESS.

e_GraphCreate

int  e_GraphCreate(char *graphName,
                         int type)

Create a graph.

Parameters:: graphName - - The name of the graph.; type - - The type of datasets that will be added to the graph: E_NO_INDEX, E_TIME_INDEX, or E_VALUE_INDEX.
Returns:: E_GRAPH_NOT_FOUND, E_FAIL or E_SUCCESS.

e_GraphSetTitle

int  e_GraphSetTitle(char *graphName,
                           char *title)

Specify the title of the graph. The title is drawn below the graph. Calling this routine is optional. If it is not called then no title is drawn.

Parameters:: graphName - - The name of the graph.; title - - The title of the graph.
Returns:: E_GRAPH_NOT_FOUND or E_SUCCESS.

e_GraphSetXLabel

int  e_GraphSetXLabel(char *graphName,
                            char *label)

Specify the label for the X axis.

Parameters:: graphName - - The name of the graph.; label - - The text for the axis label.
Returns:: E_GRAPH_NOT_FOUND or E_SUCCESS.
See:: e_GraphSetXAxis

e_GraphSetYLabel

int  e_GraphSetYLabel(char *graphName,
                            char *label)

Specify the label for the Y axis.

Parameters:: graphName - - The name of the graph.; label - - The text for the axis label.
Returns:: E_GRAPH_NOT_FOUND or E_SUCCESS.
See:: e_GraphSetYAxis

e_GraphSetXAxis

int  e_GraphSetXAxis(char *graphName,
                           int loglin)

Specify log/linear for the X axis. Calling this routine is optional. If it is not called then the axis will increment linearly.

Parameters:: graphName - - The name of the graph.; loglin - - E_LINEAR (default) or E_LOGARITHMIC.
Returns:: E_GRAPH_NOT_FOUND or E_SUCCESS.
See:: e_GraphSetXLabel

e_GraphSetYAxis

int  e_GraphSetYAxis(char *graphName,
                           int loglin)

Specify log/linear for the Y axis. Calling this routine is optional. If it is not called then the axis will increment linearly.

Parameters:: graphName - - The name of the graph.; loglin - - E_LINEAR (default) or E_LOGARITHMIC.
Returns:: E_GRAPH_NOT_FOUND or E_SUCCESS.
See:: e_GraphSetYLabel

e_GraphSetIndexLabel

int  e_GraphSetIndexLabel(char *graphName,
                                char *label)

Specify the text of the Index label. The index label is drawn above the upper left corner of the graph.

Parameters:: graphName - - The name of the graph.; label - - The text for the index label.
Returns:: E_GRAPH_NOT_FOUND or E_SUCCESS.

e_GraphAddLabel

int  e_GraphAddLabel(char *graphName,
                           char *label,
                           float[] location,
                           char *font,
                           char *style,
                           float size,
                           float[] color)

Add a label to the graph.

Parameters:: graphName - - The name of the graph.; label - - The text of the label.; location - - A 2 element array containing the x and y coordinates of the lower left corner of the label.; font - - Specify the name of the font as a character string: Serif, SansSerif, Monospaced, Symbol, Dialog, or DialogInput.; style - - Specify the style of the font as a character string: Plain, Bold, Italic, or Bold_Italic.; size - - The size of the font is specified in 0. - 1. coordinates.; color - - The color for drawing the label. A 3 element array containing the red, green, and blue intensity values. The intensity value range is 0. - 1 where 0 is no color and 1 is the brightest..
Returns:: E_GRAPH_NOT_FOUND, E_FAIL, or E_SUCCESS.

e_GraphSetPlotArea

int  e_GraphSetPlotArea(char *graphName,
                              float[] location,
                              float width,
                              float height)

Specify the plot area for the graph. The datasets are drawn in the plot area. The default plot area is set when a graph is created. The default lower left corner is: (.08, .08). The default width is .7 and the default height is .78. These values are used if this routine is not called.

Parameters:: graphName - - The name of the graph.; location - - The coordinate location of the lower left corner of the plot area.; width - - The width, 0. - 1., of the plot area.; height - - The height, 0. - 1., of the plot area.
Returns:: status - E_GRAPH_NOT_FOUND or E_SUCCESS.

e_GraphSetLegend

int  e_GraphSetLegend(char *graphName,
                            float[] location)

Position the legend. A legend is automatically created and drawn for a graph. The legend shows the line color and name for each dataset. The height of the legend increases with each dataset. The width depends on the length of the longest name. The legend is clipped if it extends beyond the edges of the graph.

Parameters:: graphName - - The name of the graph.; location - - The coordinate location of the upper left corner of the legend.
Returns:: status - E_GRAPH_NOT_FOUND or E_SUCCESS.

e_GraphShowLegend

int  e_GraphShowLegend(char *graphName,
                             int show)

Draw or hide the legend. A legend is automatically drawn for a graph.

Parameters:: graphName - - The name of the graph.; show - - E_TRUE (default if this routine is not called) or E_FALSE.
Returns:: status - E_GRAPH_NOT_FOUND or E_SUCCESS.

e_GraphAddFxDataset

int  e_GraphAddFxDataset(char *graphName,
                               char *datasetName)

Add a dataset to the graph (by name). The dataset can be f(x) or indexed. The name of the dataset is used to add it to the graph. If the graph contains indexed datasets then the datasets will be displayed in order of the index value. Indexed datasets with the same name are stored as a profile. Each profile is color-coded and the name of the dataset is listed in the legend. A new profile is created when an indexed dataset with a new name is added. For datasets with the same name, add each dataset before creating another dataset with the same name. Otherwise the new dataset will replace the previous dataset of the same name. The indexed datasets can be added to the graph in any order because they will be sorted by index value in ElVis.

Parameters:: graphName - - The name of the graph.; datasetName - - The name of the dataset.
Returns:: E_GRAPH_NOT_FOUND, E_DATASET_NOT_FOUND, E_FAIL, or E_SUCCESS. If the type of dataset is different from the first dataset added to the graph then E_FAIL is returned and the dataset is not added to the graph.

e_GraphAddFxDatasetID

int  e_GraphAddFxDatasetID(char *graphName,
                                 int ID)

Add an indexed dataset to the graph (by ID). The ID number of the dataset is used to add it to the graph. The datasets will be displayed in order of the index value. Indexed datasets with the same name are stored as a profile. Each profile is color-coded and the name of the dataset is listed in the legend. A new profile is created when an indexed dataset with a new name is added. For datasets in the same profile, add each dataset to the grph before creating another dataset with the same name. Otherwise the new dataset will replace the previous dataset of the same name. The indexed datasets can be added to the graph in any order because they will be sorted by index value in ElVis.

Parameters:: graphName - - The name of the graph.; ID - - The name of the dataset.
Returns:: E_GRAPH_NOT_FOUND, E_DATASET_NOT_FOUND, E_FAIL, or E_SUCCESS. If the type of dataset is different from the first dataset added to the graph then E_FAIL is returned and the dataset is not added to the graph.

e_FxCreate

int  e_FxCreate(char *datasetName,
                      int points,
                      double x,
                      double fx)

Create an f(x) dataset.

Parameters:: datasetName - - The name of the dataset.; points - - The number of points in the dataset.; x - - The x values of the points.; fx - - The f(x) values of the points.
Returns:: E_FAIL or E_SUCCESS.

e_ShowMarkers

int  e_ShowMarkers(char *datasetName,
                         int showInterval)

Control the display of data point markers.

Parameters:: datasetName - - The name of the dataset.; showInterval - - 0 = do not draw markers (default). 1 = draw marker at every point. Values greater than 1 = number of points to skip before drawing next marker.
Returns:: E_DATASET_NOT_FOUND or E_SUCCESS.

e_ShowLines

int  e_ShowLines(char *datasetName,
                       int show)

Control the display of lines between data points. A scatter plot can be drawn by turning off the lines and drawing a marker at each data point.

Parameters:: datasetName - - The name of the dataset.; show - - E_TRUE: draw a line between data point (default). E_FALSE: do not draw a line between data points.
Returns:: E_DATASET_NOT_FOUND or E_SUCCESS.

e_FxtDatasetCreate

int  e_FxtDatasetCreate(char *datasetName,
                              int points,
                              double x,
                              double fx,
                              double time)

Create an f(x) dataset that is indexed. Each dataset with the same name is put in a profile. The profiles are color-coded and can be animated. A new profile is created when a dataset is added with a new name. The name of the dataset is drawn in the legend. For datasets in the same profile, add each dataset to the graph before creating another dataset with the same name. Otherwise the new dataset will replace the previous dataset of the same name. The datasets can be added to the graph in any order because they will be sorted by index value in ElVis.

Parameters:: datasetName - - The name of the dataset.; points - - The number of points in the dataset.; x - - The x values of the points.; fx - - The f(x) values of the points.; time - - The index of the dataset.
Returns:: E_FAIL or ID number of dataset. The ID number is used in e_GraphAddFxDatasetID.

e_FxtDatasetDisplay

int  e_FxtDatasetDisplay(char *windowName,
                               char *graphName,
                               char *datasetName)

Display an additional f(x) dataset that is indexed in time.

Parameters:: windowName - - The name of the GraphWindow containing the graph.; graphName - - The name of the graph containing the Fxt datasets.; datasetName - - The name of the new dataset to display.
Returns:: E_FAIL or E_SUCCESS.

e_SurfaceCreate

int  e_SurfaceCreate(char *surfaceName,
                           char *graphName)

Create a surface from a graph containing an indexed dataset.

Parameters:: surfaceName - - The name of the surface being created.; graphName - - The name of the graph containing an indexed dataset or time indexed dataset.
Returns:: E_FAIL or E_SUCCESS.

e_SurfaceSetTitle

int  e_SurfaceSetTitle(char *surfaceName,
                             char *title)

Specify the title of the surface. The title is drawn below the surface. Calling this routine is optional. If it is not called then no title is drawn.

Parameters:: surfaceName - - The name of the surface.; title - - The title of the graph.
Returns:: E_SURFACE_NOT_FOUND or E_SUCCESS.