EWO Basics and Development

What is an Ewo?

An EWO (External Widget Object) is a graphical object (a Widget) and can be embedded into any WinCC OA panel.

It is implemented in C++ by the use of the platform neutral Qt graphical toolkit, see http://www.qt.io/developers/. An EWO can generally display and contain everything Qt allows in a QWidget object. An EWO is dynamically loaded into the WinCC OA user interface (it is compiled as a plugin into a shared library/dll). An EWO contains attributes that can be changed in the Property editor of GEDI.

You can access an EWO by using CTRL scripts. It triggers CTRL scripts (Events) through corresponding signals.

In addition to the non-dynamic data types, the following data types can be exchanged between EWO and WinCC OA scripts:

  • all WinCC OA dyn_* data types
  • all data types from QList<QVariant>

QVariant::Size -> dyn_int with width and height

QVariant::Polygon -> dyn_dyn_int with each dyn_int as x, y coordinates

QVariant::BitArray -> up to 32 bit -> bit32; 33 up to 64 bit -> bit64

QVariant::Pen -> string

QVariant::Brush -> string

QVariant::Map -> mapping

When a QBrush contains a pixmap, this cannot be converted to a string. That means that reading pixmaps from an EWO is only possible to a limited extent. However, writing from a WinCC OA script to EWO is possible.

Existing EWOs that are used with a new WinCC OA version must be recompiled.

Due to changes in WinCC OA it is necessary to change the class forwarding declaration schema for the Qt libs from "class QString;" to "QT_FORWARD_DECLARE_CLASS(QString)" when linking an EWO with the Qt libs (only when using Linux). Following shell script can be used:

The parameter value is the starting directory of the EWO source code.

The notation "QT_FORWARD_DECLARE_CLASS(xxx)" can be used on every operating system but it is mandatory when using Linux.

#!/bin/sh
find $1 -type f -name \*hxx -o -name \*.h | xargs sed -i -e 's/^\(class *\)\(Q.*\);/QT_FORWARD_DECLARE_CLASS\(\2\)/'

How to implement an Ewo?

You have to derive from the BaseExternWidget class and implement at least the method providing the 
QWidget virtual QWidget *widget() const = 0
and then compile and use it.

For details, see the BaseExternWidget.hxx headerfile (located in wincc_oa_path/api/include) that describes all methods.

You can find an example under api/newEWO (cmd for Windows, sh for Linux). This example generates an EWO that can be compiled and that contains example code.

It must be considered that the environment variable API_ROOT is set to the path of the /api folder contained within the installation directory. Extend the missing code sections that are marked with //TODO with your valid custom code and compile the EWO. The EWO can be compiled even if no changes are made and will result in a runnable EWO that provides to buttons with various signals/methods.

Please consider the requirements for API development when creating custom components.

How to set up my QT library

Since you need to have a Qt development license to be able to implement an EWO, you also need to ensure that the setup of this installation matches the Qt library WinCC OA delivers, otherwise the compiled EWO cannot be loaded.

The Qt version actually used in WinCC OA can be seen inside of the GEDI (see About Qt).

How to install an EWO?

An EWO is a shared library/dll (located in <wincc_oa_path>/bin) that has to be copied to the <proj_path>/bin/widgets directory and must have a name ending with .ewo (not .so or .dll but, for example, MyWidget.ewo). Alternatively, the .ewo file can be put into one of the following subdirectories that hold the EWO compiled for the specific platform:

<proj_path>/bin/widgets/windows

<proj_path>/bin/widgets/windows-64

<proj_path>/bin/widgets/linux

<proj_path>/bin/widgets/linux-64

How to add an EWO to a panel

Simply activate the EWO Icon , the appropriate button in the EWO toolbar (or via the Object Menu) , select the .ewo file you want to use, and create the rectangular area in the panel which shall be used by the EWO. Use it then as you use the standard widgets (the special Events and properties are shown on the Extended Tab in the property editor).

A double-click on the EWO in the panel during engineering opens the Initialize script.

How can I get a special editor for the settings of my EWO ?

Some complex widgets in WinCC OA have separate editor panels (dialogs) for their settings, for example, the Trend Widget or the Cascade Button. You can do the same for your EWOs: Place a script in <proj_path>/scripts/gedi/<ewo-name>_ewo.ctl (for example, MyWidget_ewo.ctl) that then can open a panel and act on the EWO (see for example, gedi/sp.ctl - openDialog(), getConstructShape()).

Ewo Development

paintEvent()

If an EWO itself scales the font in the paintEvent(), create a property in the EWO widget as follows in order to avoid a font change by the UI while zooming. This leads to double scaling.

Q_PROPERTY(bool avoidFontTransform READ getAvoidFontTransform DESIGNABLE false SCRIPTABLE false)
bool getAvoidFontTransform() const { return true; }

inGedi()

Allows to define a different display behavior for EWOs inside the GEDI, e.g. to increase the visibility of the AttentionEffect.ewo inside the editor.

Q_PROPERTY(bool inGedi READ isInGedi WRITE setInGedi DESIGNABLE false SCRIPTABLE false)
bool isInGedi() const { return inGedi; }

Drop Event

To use drag and drop for your EWO the drop event handling can be added to your EWO implementation. To add the event handling to your EWO the EWO itself (not the QWidget used inside of the EWO) must be extended with following command inside of the EWO constructor:

setProperty("-droppedEvent", QLatin1String("main(string information, int dragType)"));

The arguments of the main function depend on the arguments that are passed as values inside of the signal. This means, that depending on the signal custom arguments can be implemented.

This interface is used for the drop script inside of the GEDI (as part of the property editor).