OnReturn Functions in Modals

This page details the functions in WinCC OA that handle child panels with return values, similar to promises or async/await in JavaScript. These functions allow for the execution of a child panel and returning values back to the parent upon completion.

PanelOffReturn()

Closes a child panel and returns values to the parent panel. This function should be used in lieu of a simple close when data needs to be passed back.


    main() {
       dyn_float f;
       dyn_string s;
       PanelOffReturn(f, s);
       // Additional script logic
    }
    

ChildPanelOnCentralModalReturn()

Opens a modal child panel, centered within the parent panel, and returns values after the child panel is closed.


    main() {
        dyn_float dreturnf;
        dyn_string dreturns;
        string strvar = "example";
        ChildPanelOnCentralModalReturn("ChildPanels.pnl", "Testpanel", makeDynString("$p1:first", "$p2:"+strvar), dreturnf, dreturns);
        DebugN("Return values from the child panel", dreturnf);
        DebugN(dreturns);
    }
    

Using Dialog Functions with Return Values

These dialog functions are particularly useful when a panel needs to perform operations and then pass results back to the calling panel. Instead of navigating away or storing interim results in data points, these functions streamline the process by managing the flow directly through return values.

Best Practices

When using these functions:

  • Ensure the child panel is properly initialized with necessary parameters.
  • Use modal functions to focus user interaction on the child panel until completion.
  • Manage return values effectively to handle user decisions and input from the child panel.

To call a child panel and receive return values, you can use functions such as ChildPanelOnReturn(). This function opens a child panel and waits for it to close before continuing execution, at which point it retrieves the return values set in the child panel.


    // This is an example of calling a child panel and processing its return values.
    main() {
        DebugN("Preparing to open child panel");
        dyn_float returnFloats;
        dyn_string returnStrings;
        int posX = 800;
        int posY = 100;
        ChildPanelOnReturn("path/to/child/panel.xml", "Child Panel Title", makeDynString("$param1:value1"), posX, posY, returnFloats, returnStrings);

        // Processing the returned values
        ProcessReturnValues(returnStrings);
    }

    // Function to process the returned string values from the child panel
    void ProcessReturnValues(dyn_string returnStrings) {
        for (int i = 1; i <= len(returnStrings); ++i) {
            DebugN("Returned String: " + returnStrings.at(i));
        }
    }
    

Setting Return Values in a Child Panel

In the child panel, you can set the return values using the dpSet function to assign values to the reserved data points. Or just have it in the memory of the panel itslef its okay either way as long as it can handle those parameters back.


    // This function is called within the child panel to set return values before closing.
    void SetAndCloseChildPanel(dyn_string dataToReturn) {
        dpSet("_Ui_" + myManNum() + ".ReturnValue.Text", dataToReturn);
        PanelOff();
    }
    

Important Considerations

  • Always validate the return values from the child panel before using them.
  • Ensure the child panel is properly handling user input and setting the return values before it is closed.
  • Use appropriate naming conventions and avoid exposing sensitive information in your script variables and function names.