Calling a Dialog with an Interface

You can define an interface for a visualization that is called as a dialog.

Create a visualization for this with visualization type Dialog and declare an interface for the dialog. The reference the visualization in a primary visualization by means of a user input and transfer the parameters to the interface.

If you call the visualization as an integrated visualization, then the parameter that are transferred must be variables of a basic data type. If the visualization is called as CODESYS TargetVisu or CODESYS WebVisu, then the parameters can have user-defined data types as well.

Main procedure

Set the visualization types of the visualization to dialog.
Declare variables in the interface editor of the dialog.

⇒ The dialog has an interface. You can transfer parameters when calling the dialog.
Configure the elements of the dialog and use the interface variables.
Select an element in another visualization (usually the main visualization) for configuring how the dialog opens.
Click Configure in the property Input configuration ‣ OnMouseDown .

⇒ The Input Configuration dialog box opens.
Select Open dialog in the list of selected input actions.
Select one from the Dialog drop-down list.

⇒ If the selected dialog has an interface, then the interface variables are listed below.
Assign a transfer parameter to the interface variables in the Value column.
Select the result for which the parameters were updated in the list Update and Parameter in case of results.
Activate the option Open dialog modal. Click OK to close the dialog box.

⇒ The dialog opening is configured.

Note

Executing a dialog several times at the same time requires multiple instances of the dialog. These must have already been downloaded to the visualization device when downloading the application. For this purpose, set the number of instances to download in the visualization manager (Visualizations tab).

Example

the following application calls the Change User Level dialog and prompts the user to select a level and specify a password. If the password agrees, then the OK button is enabled. Then the user can close the dialog. The input of the level is also applied.

Dialog visChangeUserLevel:

Declaration of the interface of dialog visChangeUserLevel:

VAR_INPUT
    sTitle: STRING; // titel of the dialog box
    sItfLevel0: STRING; //password level 0
    sItfLevel1: STRING; //password level 1
    sItfLevel2: STRING; //password level 2
    sItfLevel3: STRING; //password level 3
    sItfLevel4: STRING; //password level 4
    sItfLevel5: STRING; //password level 5
    sItfLevel6: STRING; //password level 6
    sItfLevel7: STRING; //password level 7
END_VAR
VAR_IN_OUT
    iItfLevel: INT; // user input: level
    sItfPwd: STRING; //user input: password
END_VAR

Element list of the `visChangeUserLevel` dialog box:
Type	Name	Element properties	Description
`#0 Image`	`Background`	Static ID: `VisuDialogs.ImagePoolDialogs.Login`	The property assigns the image of a blank dialog with a gray background and a blank blue caption bar to the element. The image is included in the VisuDialogs library.
`#1 Box`	`Title`	Texts ‣ Text : `%s`	Output with placeholder for text variable
		Text variables ‣ Text variable : `sItfTitle`	Assignment of interface variable `sItfTitle` for which a parameter is transferred at call time.
`#2 Radio Buttons`	`Input level`	Variable: `iItfLevel`	Assignment of interface variable `iItfLevel` for which a parameter is transferred at call time. Includes the user input at runtime.
		Number of columns: `4`
		Radio button order: Left to right	Display
		Radio button settings ‣ Radio button ‣ Areas : [0] bis [7] [<n>] ‣ Text : <n>	Label of eight radio buttons with numbers from 0 to 7
`#3 Text Field`	`Input password`	Texts ‣ Text : `%s`	Output with placeholder for text variable
		Text variables ‣ Text variable : `sItfPwd`	Assignment of interface variable `sItfPwd` for which a parameter is transferred at call time. Includes the user input at runtime.
		Input configuration ‣ OnMouseDown ‣ Write variable : `Variable:,InputType:Edit,Use text output variable : TRUE`	In the Input configuration dialog, Text input is selected for the Input type drop-down list and the option Use text output variable is activated.
`#4 Text Field`	`Label for level`	Texts ‣ Text : `Level:`	Label
`#5 Text Field`	`Label for password`	Texts ‣ Text : `Password`	Label
`#6 Button`	`OK`	Texts ‣ Text : `OK`	Label
		Colors ‣ Color : `Element base color` Colors ‣ Alarm color : `Alarm fill color`	Configuration of the display in state-dependent colors. You can switch between colors.
		Color variables ‣ Toggle color : `sItfPwd <> MUX(iItfLevel, sItfLevel0, sItfLevel1, sItfLevel2, sItfLevel3, sItfLevel4, sItfLevel5, sItfLevel6, sItfLevel7);`	If the password and the user input do not agree, then the expression is `TRUE`. Then the button is displayed in the alarm color.
		State variables ‣ Deactivate inputs : `sItfPwd <> MUX(iItfLevel, sItfLevel0, sItfLevel1, sItfLevel2, sItfLevel3, sItfLevel4, sItfLevel5, sItfLevel6, sItfLevel7);`	If the password and the user input do not agree, then the expression is `TRUE`. The button is deactivated. If the password agrees, then the button is enabled.
		Input configuration ‣ OnMouseDown ‣ Close dialog : `Close Dialog: visChangeUserLevel, Result : OK`	If a user clicks the OK button, then the `visChangeUserLevel` dialog is closed and the parameters are updated.
`#7 Button`	`Cancel`	Texts ‣ Text : `Cancel`	Label
		Colors ‣ Color : `Element base color`	Display
		Input configuration ‣ OnMouseDown ‣ Close dialog : `Close Dialog: visChangeUserLevel, Result : Cancel`	If a user clicks the Cancel button, then the `visChangeUserLevel` dialog is closed.

Main visualization visMain:

Element list of the `visMain` visualization:
Type	Name	Element properties	Description
`#5 Text Field`	`Button for change user level`	Texts ‣ Text : `%s`	Output with placeholder
		Text variables ‣ Text variable : `PLC_PRG.iLevel`	Assignment of the `PLC_PRG.iLevel` variables to the placeholder. Includes the level number.
`#6 Button`	`Title`	Texts ‣ Text : `Change user level`
		Input configuration ‣ OnMouseDown ‣ Open dialog : `Open Dialog: visChangeUserLevel`	If a user clicks the `Change user level` button, then the `visChangeUserLevel` dialog opens with the parameter list stored here. Tip: Click Configure to view the stored configuration in the Input Configuration dialog (input action Open dialog).

Configuration of the call of dialog `visChangeUserLevel`:
Parameter	Type	Value	Description
The parameter list is stored in the Input Configuration dialog (input action Open dialog).
`sItfTitle`	`STRING`	`'ChangeUse user level'`	Transfer of a string for the title.
`sItfLevel0`	`STRING`	`'pwd0'`	Transfer of a string as password for Level0.
`sItfLevel1`	`STRING`	`'pwd1'`	Transfer of a string as password for Level1.
`sItfLevel2`	`STRING`	`'pwd2'`	Transfer of a string as password for Level2.
`sItfLevel3`	`STRING`	`'pwd3'`	Transfer of a string as password for Level3.
`sItfLevel4`	`STRING`	`'pwd4'`	Transfer of a string as password for Level4.
`sItfLevel5`	`STRING`	`'pwd5'`	Transfer of a string as password for Level5.
`sItfLevel6`	`STRING`	`'pwd6'`	Transfer of a string as password for Level6.
`sItfLevel7`	`STRING`	`'pwd7'`	Transfer of a string as password for Level7.
`iItfLevel`	`INT`	`PLC_PRG.iLevel`	Transfer of a variable for the level specified by the user.
`sItfPwd`	`STRING`	`PLC_PRG.sPwd`	Transfer of a variable for the password specified by the user.

List Update and Parameter in case of result
Value	Description
OK	activated

Open in dialog mode

activated Input outside of the dialog is not possible.

Application code PLC_PRG:

PROGRAM PLC_PRG
VAR
        iLevel: INT;
        sPwd : STRING;
END_VAR

Visualization at runtime

After clicking the button, the dialog opens and permits input. If the specified text agrees with the stored text, then OK is enabled:

After clicking OK, the selection is applied.

Note

The example shows the procedure for multiple return values. However, the password can be returned more easily with a local variable in the dialog.

Accessing parameters programmatically

The variables declared in the interface of a visualization are available automatically as structure variables. They are identified by <Name of visualization>_VISU_STRUCT. Therefore, you can access the interface variables of visualizations that appear as a dialog. Normally you use the structure in the application code of a function that is called by a user input.

Passing pointers as parameters

To pass a complex data structure, you can flag an interface variable of type VAR_IN_OUT with the pragma attribute VAR_IN_OUT_AS_POINTER and pass a pointer or reference to it as a parameter.

Procedure for using references

Declare the user data object (DUT).
In the interface editor of a dialog, declare an interface variable (VAR_IN_OUT) as a reference to the data object by assigning the attribute 'VAR_IN_OUT_AS_POINTER' to the variable.
Program the user interface: use the dialog in a visualization or assign the dialog in the input configuration of a visualization element. Then access to the referenced data is possible.

Example: Using an interface with the pragma 'VAR_IN_OUT_AS_POINTER'

FUNCTION_BLOCK ControlFB
VAR
        bOk : BOOL := TRUE;
        nCounter : INT;
        nValue : INT;
END_VAR
nCounter := nCounter + 1;

Declaration of an interface variable with VAR_IN_OUT_AS_POINTER

User interface: dialog opens: