Parameterization of a Visualization with an Interface

You can declare an interface for parameters for a visualization that is to be referenced. The actual parameters are passed to the interface (similar as in the case of a function block) when the visualization is called at runtime.

This kind of visualization is used as a visualization template which is referenced by a superordinate visualization via a frame or tab element. The interface variables are declared in the interface editor of the template visualization. In the superordinate visualization which calls the template visualization, the transfer parameters are assigned to the reference element (frame or tab).

First of all, declare the interface variables in the interface editor of the template visualization. Then configure the parameters by assigning a data-type-compliant application variable to each interface variable. You assign the parameters to the frame element (or tab element) in the element properties (Properties view).

Depending on the display variant, the parameter transfer of local variables (with the VAR scope) is limited.

Note

If you execute the visualization as an integrated visualization, you can only transfer local variables having a basic data type as parameters. If the visualization is called as CODESYS TargetVisu or CODESYS WebVisu, then you can also transfer parameters with a user-defined data type.

Assistance when updating frame parameters

If you change interface variables in a visualization template, then you are assisted in updating the occurrence locations.

During compilation, locations with a parameter transfer which is no longer valid are detected and displayed in the message view. The following error message is displayed for each detected location: The interface of the referenced visualization <name of visualization> does not match the current configuration. Please do an update of the frame references of the current visualization.

If you double-click on the message, then you will be assisted in correcting the error and the Update the Frame Parameters dialog will open. There you can edit the parameter transfer at the relevant location. However, you can also edit the parameter transfer of all affected locations in the entire project.

For more information, see: Updating the Frame Parameters, Options: Visualization

Calling visualization with interface (VAR_IN_OUT)

Requirement: The project contains a visualization and a main visualization. The main visualization contains an element that the visualization references.

Open the visualization.
Click Visualization → Interface Editor.
Declare a variable in the interface editor.
The visualization has an interface and the Updating the Frame Parameters dialog appears.
Assign a type-compliant transfer parameter to the interface variables in all calls by entering an application variable in Value. Exit the dialog.
A transfer parameter is assigned at the points where the visualization is to be referenced. These now appear in the main visualization in the References property.

Example 17. Example

The visPie visualization contains an animated, colored pie. The visMain main visualization calls the visPie visualization multiple times in Tabs. Color information, angle information, and label are transferred via the pieToDisplay interface variable. The pies vary at runtime.

Visualization visPie:

Table 3. Properties of the Pie element:

Variable for begin	`pieToDisplay.iStart`
Variable for end	`pieToDisplay.iEnd`
Texts → Text	%s
Text variables → Text variable	`pieToDisplay.sLabel`
Color variable → Normal state	`pieToDisplay.dwColor`

Interface of the visualization visPie:

                            VAR_IN_OUT
                            pieToDisplay : DATAPIE;
                            END_VAR

Main visualization visMain:

Table 4. Properties of the "Tabs" element:

References
visPie
Heading	`A`
`pieToDisplay`	`PLC_PRG.pieA`
visPie
Heading	`B`
`pieToDisplay`	`PLC_PRG.pieB`
visPie
Heading	`C`
`pieToDisplay`	`PLC_PRG.pieC`

DATAPIE (STRUCT)

TYPE DATAPIE : // Parameter type used in visPie
STRUCT
    dwColor : DWORD; // Color data
    iStart : INT; // Angle data
    iEnd : INT;
    sLabel : STRING;
END_STRUCT
END_TYPE

GVL

{attribute 'qualified_only'}
VAR_GLOBAL CONSTANT
    c_dwBLUE : DWORD := 16#FF0000FF; // Highly opaque
    c_dwGREEN : DWORD := 16#FF00FF00; // Highly opaque
    c_dwYELLOW : DWORD := 16#FFFFFF00; // Highly opaque
    c_dwGREY : DWORD :=16#88888888; // Semitransparent
    c_dwBLACK : DWORD := 16#88000000; // Semitransparent
    c_dwRED: DWORD := 16#FFFF0000;  // Highly opaque
END_VAR

PLC_PRG

PROGRAM PLC_PRG
VAR
    iInit: BOOL := TRUE;
    pieA : DATAPIE; // Used as argument when visPie is called
    pieB : DATAPIE;
    pieC : DATAPIE;
    iDegree : INT; // Variable center angle for the pie element used for animation
END_VAR

IF iInit = TRUE THEN
    pieA.dwColor := GVL.c_dwBLUE;
    pieA.iStart := 0;
    pieA.sLabel := 'Blue';

    pieB.dwColor := GVL.c_dwGREEN;
    pieB.iStart := 22;
    pieB.sLabel := 'Green';

    pieC.dwColor := GVL.c_dwYELLOW;
    pieC.iStart := 45;
    pieC.sLabel := 'Yellow';

    iInit := FALSE;
END_IF
iDegree := (iDegree + 1) MOD 360;
pieA.iEnd := iDegree;
pieB.iEnd := iDegree;
pieC.iEnd := iDegree;

Main visualization visMain at runtime:

Printing the instance name of a transfer parameter

In order to obtain and output the instance name of a transfer parameter, you can implement an interface variable (data type STRING) with the pragma {attribute 'parameterstringof'} in the VAR_INPUT scope.

The project contains a visualization and a main visualization. The main visualization contains elements that the visualization references.

Open the visualization.
Click Visualization → Interface Editor.
Declare an interface variable (VAR_IN_OUT).
pieToDisplay : DATAPIE;
In the interface editor, declare a variable (VAR_INPUT) with attribute {attribute 'parameterstringof'}.
{attribute 'parameterstringof' := 'pieToDisplay'}
sNameToDisplay : STRING;
Save the changes.
The Updating the Frame Parameters dialog does not open.
Insert a Text Field element.
In the Texts, Text property, assign an output text to the text field.
Visualization of %s
In the Text variablesText variable property, assign the interface variable to the text field.
sNameToDisplay
visPie has a heading.

Example 18. Example

The visPie visualization consists of one pie until now. The visMain main visualization calls visPie in Tabs three times with different transfer parameters.

visPie is extended with a text field which outputs the name of the actual parameters passed to the visualization. In addition, the interface of visPie is extended with a string variable which contains the instance name of the specified transfer parameter. At runtime, each pie is overwritten.

Table 5. Properties of the "Text Field" element:

Texts, Text	`Visualization of %s`
Text variables, Text variable	`sNameToDisplay`

Interface of the visPie visualization

VAR_INPUT
    {attribute 'parameterstringof' := 'pieToDisplay'}
    sNameToDisplay : STRING;
END_VAR
VAR_IN_OUT
    pieToDisplay : DATAPIE;
END_VAR

Main visualization visMain at runtime: