9. Overview Field Functions

  Field Functions
@f{3dlegend} Creates a legend for 3D datasets.
@f{_a} Displays the text of an alias.
@f{ansi} Displays an ANSI- or UNICODE character.
@f{area} Calculates the area for datasets.
@f{channelname} The field function returns the channelname of the first dataset in the diagram. The field function can be used in a text or table object or in diagram axis title. The text or table object must be assigned to a diagram with datasets.
@f{copytextcolortocurve} Copy the textcolor of the y-Title text to all 1D and 2D curves. The field function must be located in the y-Title-Text
@f{createdate} Displays the date when the document was created.
@f{cursor_value} Displays the x- or y-value of a 2D dataset at the cursor position.
@f{datafilenames} Writes a list of all used data file names used in the page.
@f{datasetfilter} Displayes the record filter for the given dataset.
@f{date} Writes the current date.
@f{documentname} Writes the document file name.
@f{excel_data} Displays the specified range of an Excel file in a UniPlot table. The Excel file is linked to the table by the file name. Press F9 to update the UniPlot table in the page.
@f{file} Writes the contents of a text file (maxium 100 lines).
@f{labeldatapoint} Labels the data points of the original data with its y value.
@f{labeldataset} The field functions labels a curve with its legend text, set with XYSetLegendText or the y-channelname.
@f{labelsinglepoint} Labels a single data point.
@f{lastprintdate} Displays the date when the document was last printed.
@f{lastsavedate} Displays the date when the document was last saved.
@f{latex} Displays a LaTeX Formula in a Text object, axis title of table cell.
@f{legend_table} Creates a legend table for the data files used in the page or document.
@f{legendchannel} Creates a legend with the y-channel names of all curves in the diagram.
@f{legendfile} Creates a legend for all datasets in the parent layer of the text object.
@f{legendstyle} Creates a legend for a dataset without the legend text.
@f{legendtext} Displays the legend text of the specified dataset.
@f{legend} Creates a legend for 1D and 2D datasets.
@f{linkaxisscale} The function calculates the formula scale * x + offset and displays the result as the new axis scale based on a axis given by the diagram name and axis type (x,y,z).
@f{marker} This function can be added to the axis title. It displays the used marker of the first dataset.
@f{ncattfromdata} Displays the specified attribute from a netCDF file (nc file). The function finds the file name via a specified dataset name.
@f{ncattribute} Displays a netCDF file attribute (nc file).
@f{ncvaluefromdata} Displays the value of a data point of a netCDF data file channel. The file name of the netCDF data file will be received via the connected dataset.
@f{pagename} Displays the page name.
@f{pagenumber} Displays the page number.
@f{revnum} Displays the document version number.
@f{runtimevalue} Writes the value of the given Sequencer Runtime Value.
@f{scaleaxis} Creates an axisscale depending on another diagram axis.
@f{summaryinfo} Displays an item from the summary info dialog File=>Summary Info.
@f{symbol} Displays a character from the symbol character set.
@f{time} Writes the current time.
@f{update3dcolorlegendtable} Color legend of a x/y/z dataset. The field function must be inserted into the name of a table object.
@f{update3dcolorlegend} Color legend of a x/y/z dataset.
@f{xyinterpol} Displays the interpolated y-coordinate for a given x-coordinate or the x-coordinate for a given y-coordinate of a 1D or 2D dataset.
@f{xyminmax} Displays the minimum/maximum coordinates of a dataset.
@f{xystatistic} Displays the following values of a 2D dataset: Minimum, maximum, arith. mean value, mean deviation, variance and standard deviation.
@f{xystatvalue} Display statistical values for the specified 1D or 2D dataset.
@f{xyvalue} Displays the x- and y-coordinate of a given 1D or 2D dataset.
@f{xyzstatistic} Displays statistical information about a 3D map (see example).
@f{xyzstatvalue} Display statistical values for the specified 3D datasets created from data triples.
@f{xyzvolume} Calculates the volume, area or the quotient volume/area for a given 3D dataset.

9.1. Writing user-defined Field Functions

You can write your own field functions. The following example shows the definition of the field function @f{pagename}. The name of a field function starts with the prefix __ff_ (2 underscores followed by ff followed by one underscore) (The prefix will be added by UniScript to the field function call). The function name must be specified in small letters. Every field function has 6 parameters. The call parameters which are used in the text element are passed to the field function in the parameter svParameter. The function must return the field result as a scalar string. In case of an error, an empty string ("") should be returned.

User defined field functions should be saved in a file with the extension .ic in the autoload directory. (uniplot/autoload). All ic files in this directory are loaded at startup.

The parameter hText is the handle of the text object which contains the field function. The parameters hLayer, hPage and hDoc are the handles of the parent diagram, parent page and parent document of the text object.


def __ff_pagename(hDoc, hPage, hLayer, hText, nAction, svParameter)
    if (hPage != 0) {
        return PageGetTitle(hPage);
    return "";

You can find more field function examples in directory uniplot\script\field.