TextEditorDialog Function

Introduction

Opens a dialog with a title, a text editor and, OK and Cancel buttons.

Syntax

Informal Syntax:

TextEditorDialog( Title, Prompt, Rows, Columns, StringValue )

Formal Syntax:

TextEditorDialog( Title:=Expression, Prompt:=Expression, Rows:=Expression, Columns:=Expression, StringValue:=Variable Reference )

Parameters

Parameter	Type	Description
Title	ANY_STRING	The title that appears at the top of the dialog.
Prompt	ANY_STRING	The prompt string associated with the text entry field.
Rows	ANY_INT	The number of rows to display in the text entry field. If the value provided is less than 1, the value is rounded up to 1. If the value provided is greater than 12, the value is rounded down to 12.
Columns	ANY_INT	The approximate number of columns to display in the text entry field. If the value provided is less than 32, the value is rounded up to 32. If the value provided is greater than 240, the value is rounded down to 240.
Target	REF_TO ANY_STRING	A reference to a string program variable: The field is initialized with the value of the program variable when the dialog is opened. The value of the field is written to the program variable when the OK button is pressed.

The TextEditorDialog() function is logically equivalent to:

FUNCTION TextEditorDialog : INT
VAR_INPUT
    Title : WSTRING;
    Prompt : WSTRING;
    Rows, Columns : INT;
END_VAR
VAR_IN_OUT
    TextValue : WSTRING;
END_VAR

    DialogNew();
    DialogAddTextEditor( Prompt, Rows, Columns, TextValue );
    TextEditorDialog := DialogOpen( Title, 1 );
END_FUNCTION

Return Value

An INT value indicating which button was pressed:

Value	Button
0	Cancel
1	OK

Example

In the following example shows how to use the TextEditorDialog() function:

VAR 
    Result : INT; 
    TankContents : WSTRING;
END_VAR

TankContents := %"Message Tag";

Result := TextEditorDialog(
        "Tank Contents", 
        "Enter the description of the tank contents:",
        3, 80,
        TankContents );

IF Result = 1  THEN
    (* Update the tank contents tag *)
    TagWriteValue( "Message Tag", TankContents );
END_IF

Code Notes:

The value of a string tag called "Message Tag" is assigned to the variable TankContents.
A Text Editor Dialog 3 rows by 80 columns is displayed.
If the user presses the OK button, the Result value will be 1 and the code goes on to update the string tag.

The following image shows the dialog displayed by the preceding code example:

Further Information

DialogNew

To learn about the DialogNew() function.

DialogAddTextEditor

To learn about the DialogAddTextEditor() function.

DialogOpen

To learn about the DialogOpen() function.

Operator Actions

To learn where you can use this function.

Glossary

For the meaning of terms used in Fernhill SCADA.