Fields and Placeholders
A field consists of an FPScript expression that supplies a value or string to be displayed and a formatter that determines how the data is to be formatted for output.
You can insert fields in any text, for instance, in axis labels, text objects, document labels, etc. Values to be displayed can be calculation results, header information such as a data set name and physical unit, or the current date and time.
The following field shows, for instance, the first value in the X component of a signal with three fractional digits:
%.3f{Signal.x[0]}
In this example, Signal.x[0] is the FPScript expression that supplies the value, and %.3f{...} is the formatter that determines that the number is to be formatted with three fractional digits instead of an exponent. Formatting information is optional here; the simple formatter %{...} outputs any data types in a standard format. Floating point values are output using a number of valid places that can be set on the General tab in the Properties dialog box of the FlexPro project database.
Fields always start with a % sign. Therefore, if you want to insert a single percent sign into a text, you need to type in the percent sign twice to prevent it from being interpreted by the formatter. For instance:
The probability of error is %{Probability}%%.
Accessing Object Attributes in Fields
Since FPScript has full access to FlexPro's Automation object model, you can display any object attributes, also known as properties. The pre-defined fields for axis labeling in diagrams is used frequently here, for instance, to determine the names, comments and units of the data sets to be plotted over an axis. The FPScript fields used for this can be somewhat long, which is why FlexPro uses placeholders. Placeholders also have a formatter, which is followed by a name instead of FPScript code. The standard text for labeling the Y axis of a 2D curve, for instance, looks like this:
%<NameOrQuantityOrComments> %<[Unit]>
FlexPro replaces both placeholders when text is created using the following FPScript fields:
%{.Data.YValueObject(%<ListElement>).NameOrQuantityOrComments(.Data.YComponent)}
%{ThisFPObject.YAxes(.YAxis).Scaling.CurrentUnitInBrackets(%<YAxisElement>)}
FPScript defines a standard object, which can be activated using the optional keyword ThisObject. The expression .Data is thus equivalent to the expression ThisObject.Data. When evaluating the axis label of a curve, ThisObject is a reference to the curve. With ThisFPObject you have access to the FlexPro object, such as the diagram or table containing the field.
If the curve is assigned a list with several data sets, the data sets are evaluated for each element in the list. %<ListElement> is a placeholder that is replaced before the evaluation by the index of the list element.
The following table specifies which objects ThisObject and ThisFPObject reference:
Field contained in |
ThisObject points to |
ThisFPObject points to |
|---|---|---|
Axis labeling of an axis |
Axis |
Diagram |
Axis labeling, curve labeling or legend entry of a curve |
Curve |
Diagram |
Legend title |
Legend |
Diagram |
Color legend label |
Color Legend |
3D diagram |
Column table title |
Column table |
Column table |
Column title in a column table |
Table column |
Column table |
Cell table title |
Cell table |
Cell table |
Cell in a cell table |
Cell |
Cell table |
Text object |
Text object |
Text object |
Label in a document/diagram |
Label |
Document/diagram |
Placeholders for FPScript Fields
The following list contains die placeholders that you can embed in labels using the drop-down menu.
Most placeholders access object attributes. The way some placeholders work depends on the type of label in which the placeholder is used. The %<Comments> placeholder, for example in the title of a table column, references the comments of a data set displayed in the column. If on the other hand it is used in a diagram title, it references the diagram comments.
Description |
Placeholder |
Purpose |
|---|---|---|
FPScript Expression |
%{ ... } |
Adds a field in which you can embed any FPScript code. |
Parameters |
%{ ... .Parameters("Name")} |
The value of the Name parameter of the object that contains the placeholder, or the value of the Name parameter of the data object to which the placeholder refers. |
Project database name |
%<DatabaseName> |
The name of the project database. |
Project database path |
%<DatabasePath> |
The name of the project database, including its path on the hard disk. |
Path |
%<Path> |
The name of the object that contains the placeholder, including its path in the project database. |
Name |
%<Name> |
The name of the object that contains the placeholder, or the name of the data object to which the placeholder refers. |
Element name |
%<ElementName> |
The name of the list element or of the component of the data object to which the placeholder refers. |
Name or comments |
%<NameOrComments> |
For the Y component, this is the name, and for the remaining components, this is the comments of the component of the data object to which the placeholder refers. |
Name or quantity or comments |
%<NameOrQuantityOrComments> |
For the Y component, this is the name, and for the remaining components, if present, this is the physical quantity; otherwise, this is the comments of the component of the data object to which the placeholder refers. |
Comments |
%<Comments> |
The comments of the object that contains the placeholder, or the Y comments of the data object to which the placeholder refers. |
Comments or name |
%<CommentsOrName> |
Depending on the availability, this is the comments or name of the object containing the placeholder, or the comments or name of the component of the data object to which the placeholder refers. |
Quantity, comments or name |
%<QuantityOrCommentsOrName> |
Depending on the availability, this is the physical quantity, the comments or name of the component of the data object to which the placeholder refers. |
Unit |
%<Unit> |
The physical unit of the component of the data object to which the placeholder refers. |
[Unit] |
%<[Unit]> |
The physical unit, in square brackets, of the component of the data object to which the placeholder refers. If the unit is empty, no brackets are output. |
(Unit) |
%<(Unit)> |
The physical unit, in parentheses, of the component of the data object to which the placeholder refers. If the unit is empty, no parentheses are output. |
Quantity |
%<Quantity> |
The physical quantity of the component of the data object to which the placeholder refers. |
Author |
%<Author> |
The author of the data object to which the placeholder refers. |
Creation date |
%<CreationDate> |
The creation date of the object that contains the placeholder, or the creation date of the data object to which the placeholder refers. |
Creation time |
%<CreationTime> |
The creation time of the object that contains the placeholder, or the creation time of the data object to which the placeholder refers. |
Modification date |
%<ModificationDate> |
The last modification date of the object containing the placeholder, or the last modification date of the data object to which the placeholder refers. |
Modification time |
%<ModificationTime> |
The last modification time of the object containing the placeholder, or the last modification time of the data object to which the placeholder refers. |
Origin |
%<Origin> |
The origin of the data object to which the placeholder refers. |
Z value |
%<ZValue> |
When displaying a signal series, this is the Z value assigned to the signal of the signal series displayed as a curve. |
Z comments |
%<ZComments> |
When displaying a signal series, this is the comments of the Z component of the data object to which the placeholder refers. |
Z unit |
%<ZUnit> |
When displaying a signal series, this is the physical unit of the Z component of the data object to which the placeholder refers. |
Z unit |
%<(ZUnit)> |
When displaying a signal series, this is the physical unit, in square brackets, of the Z component of the data object to which the placeholder refers. If the unit is empty, no brackets are output. |
(Z unit) |
%<(ZUnit)> |
When displaying a signal series, this is the physical unit, in parentheses, of the Z component of the data object to which the placeholder refers. If the unit is empty, no parentheses are output. |
Date |
%<Date> |
The date on which the placeholder was last updated. |
Time |
%<Time> |
The time at which the placeholder was last updated. |
Folder name |
%<FolderName> |
The name of the folder in the project database with the object that contains the placeholder. |
Folder comments |
%<FolderComments> |
The comments of the folder in the project database with the object that contains the placeholder. |
Active subfolder name |
%<ActiveFolderName> |
The name of the active subfolder within the folder in the project database with the object that contains the placeholder. |
Active subfolder comments |
%<ActiveFolderComments> |
The comments of the active subfolder within the folder in the project database with the object that contains the placeholder. |
User |
%<User> |
The name of the user who is currently logged in on Windows. |
Document path |
%<DocumentPath> |
The path in the project database of the container object in which the object containing the placeholder is found. In the case of a diagram embedded in a document or worksheet, this is the path of the document or worksheet; otherwise, it is the path of the folder that contains the diagram. |
Document name |
%<DocumentName> |
The name of the container object in which the object containing the placeholder is found. In the case of a diagram embedded in a document or worksheet, this is the name of the document or worksheet; otherwise, it is the name of the folder that contains the diagram. |
Integrated placeholders
FlexPro also uses some placeholders that do not store FPScript code:
Placeholder |
Description |
Used in |
Purpose |
|---|---|---|---|
%<DataSet> |
Data set index |
Axis label, curve label and legend entry for 3D curve |
Represents the number of the respective data series in the curve for which an axis label, curve label or legend entry is created and is used in FPScript code as an index for the Curve3DDataSets collection of the Curve3D object. |
%<Index> |
Data series index |
Axis label, curve label and legend entry for 2D or 3D curve. Marker on 2D or 3D curve and coordinates at cursor. |
Represents the number of respective data series in a 3D data set for which a label is created. Used in the text to display the data series index or in the FPScript code as an index variable. |
%<[Index]> |
Data series index, in brackets |
" |
Like %<Index>, but the output result is in brackets. This placeholder cannot be used in the FPScript code. |
%<ListElement> |
List element index |
Axis label, curve label and legend entry for 2D or 3D curve and column title of a column table. |
Represents the number of respective list elements in the curve for which an axis label, curve label or legend entry is created. Used in the FPScript code as an argument for the ValueObject property. |
%<YAxisElement> |
%<YAxisElement> |
Axis label, curve label and legend entry for 2D curve |
Represents the number of the scale of the Y axis over which the curve is displayed for which an axis label, curve label or legend entry is created. Used in the FPScript code as an argument for the CurrentUnit property. |
%<XAxisElement> |
%<XAxisElement> |
" |
Represents the number of the scale of the X axis over which the curve is displayed for which an axis label, curve label or legend entry is created. Used in the FPScript code as an argument for the CurrentUnit property. |
%<YName> |
Y name Z name |
Data label and marker on 2D or 3D curve and coordinates at cursor. |
The names of the individual components of the data point to be labeled. %<ZName> can only be used in 3D curves. The names correspond to the data set name (Y) or the relevant comments (Y, Z). |
%<YValue> |
Y value Z value |
" |
The values of the individual components of the data point to be labeled. %<ZValue> can only be used in 3D curves. |
%<Y2Value> |
Y2 value Z2 value |
Range marker on a 2D or 3D curve |
The values of the individual components of the second data point of the range marker. %<Z2Value> can only be used in 3D curves. |
%<YUnit> |
Y unit Z unit |
" |
The physical units of the individual components of the data point to be labeled. %<ZUnit> can only be used in 3D curves. |
%<DeltaY> |
Delta Y |
Range marker on a 2D or 3D curve and coordinates at cursor |
The difference values of the two cursors or the two positions of the range marker. %<DeltaZ> can only be used in 3D curves. |
%<DeltaYPerc> |
Delta Y % |
Range marker on a 2D or 3D curve and coordinates at cursor |
The difference values of the two cursors or the two positions of the range marker as a percentage, related to the first value. %<DeltaZPerc> can only be used in 3D curves. |
%<OrderTrackingName> |
Order tracking name |
Marker with order line or frequency hyperbola and coordinates at cursor in speed-frequency spectrum or order spectrum. |
Outputs either "order" (speed-frequency spectrum) or "frequency" (order spectrum). |
%<OrderTrackingValue> |
Order tracking value |
" |
The order is the ratio of speed and frequency at the marked position. |
%<OrderTrackingUnit> |
Order tracking unit |
" |
The unit of the order tracking value. |
%<AreaName> |
Area name |
Range marker with area under curve as marker cursor |
Outputs "area". |
%<AreaValue> |
Area value |
" |
Outputs the content of the area under the marked curve range. |
%<AreaUnit> |
Unit of area |
" |
The unit of the area content. |
%<SlopeName> |
Slope name |
Range marker with tangent as marker cursor |
Outputs "slope". |
%<SlopeValue> |
Slope value |
" |
Outputs the slope at the marked point of the curve. |
%<SlopeUnit> |
Slope unit |
" |
The unit of the slope. |
%<Length> |
Length |
Range marker with dimension line |
The length of the dimension line in the unit of the curve. |
%<DataSetName> |
Data set name |
Data label in a 2D or 3D curve |
The name of the additional data set for data labeling. |
%<DataSetValue> |
Data set value |
" |
The value of the additional data set for data labeling. The value is assigned to the data point to be labeled. |
%<DataSetUnit> |
Data set unit |
" |
The unit of the additional data set for data labeling. |
%<XIndex> |
X index |
Data label or marker |
The row index of the data point to be labeled/marked. |
%<ZIndex> |
Z index |
Data label or marker in a 3D curve |
The column index of the data point to be labeled/marked in a 3D data set. |
%<PlotOrder> |
Plot order |
Marker in a diagram |
The markers are numbered in ascending order over the plot order. Markers with a larger plot order appear in the foreground. When reading the markers without sorting, they are returned according to their plot order. |
%<PageNumber> |
Page number |
"Label" shape in document |
The page number in the document where the label shape is found. |
%<NumberOfPages> |
Number of pages |
"Label" shape in document |
The number of pages in the document in which the label shape is found. |
%<H1> ... %<H9> |
Outline level counter 1 - 9 |
"Label" shape in document |
The current counter value for the corresponding outline level of the document. |
%<N> |
Label counter |
"Label" shape in document |
The current counter value for the outline level assigned to the label. |
Fields for Outputting Complex Numbers
If the data set with the contents you want to display contains complex numbers, you can use the following functions in the field:
Function |
Description |
|---|---|
RealPart(DataSet) |
Displays the real part of the complex number in the data set. |
ImaginaryPart(DataSet) |
Displays the imaginary part of the complex number in the data set. |
Absolute(DataSet) |
Displays the absolute value of the complex number in the data set. |
Phase(DataSet) |
Displays the phase of the complex number in the data set. |
Indexing Scalar Values for Display
If the data set with the value that is to be displayed does not contain a scalar value, but instead contains a data series or data matrix, you can use an Index to display a particular value. If you do not use an index, the first value is taken. If you enter the number -1 as the index, the last value is always taken.
If the data set contains a signal, signal series or space curve, you can select the desired component and append .X, .Y or .Z to the name of the desired Component. If you do not specify a component, the Y component is used.
Examples
%{Signal.Y[10]} |
Displays the 11th value of the Y component of the signal. |
%{Signal.X[-1]} |
Displays the last value of the X component of the signal. |
%{DataMatrix[0][10]} |
Displays the 11th value of the first column in the data matrix. |
%{SignalSeries.Z[%<Index>]} |
Displays the Z value of the series of a signal series displayed as a curve. |
Fields with a User Prompt
You can use special fields to embed user prompts into the text. Use this option to prompt input from the user, for instance, when documents are updated for subsequent display in the document.
There are two options for embedding a user prompt into a text. You can either build a user prompt into the FPScript expression of a field, such as %{TextInput("Please enter your name")}, or you can use a special formatter that requests input, such as %"Recorder:\DM2000\MX2000". The second option has various advantages. First, you can specify default values for input, such as "DM2000" or "MX2000". These are then displayed in a drop list box. Second, FlexPro combines several user prompts embedded in the same text, and third, FlexPro remembers past entries so that you only have to enter changes when making revisions.