Events of graphics objects

Graphics object events are actions which can trigger the execution of scripts when performed.

The following events are available as standard:

Events Action
Activated When the user presses the Return or Enter key or double-clicks a date in the calendar widget.
Acknowledge When acknowledged
AreaClosed

AreaClosed(int area);

The event is triggered when closing an area inside of the trend. Please note that the passed area parameter is the current index of the area inside of the trend and not an actual ID. The index may change according to the numbers of available areas inside of the trend.
Clicked

Left-click. For primitive shapes the event can also be triggered by other available buttons. The exception is the right click, which has its own event. The button being used is specified in the mapping "event", which is passed to the script.

Note: If the MousePressed event is also defined, this is triggered first.
Note: To use the middle mouse button to activate scripts, panning must be deactivated with [ui] middleMousePanning.

This event is only triggered if the mouse button is released on the object on which the click event has been started.
Change Change of slider position.
Changed When an item of a selection list is selected.
Command A text field event. It is executed when you press the enter key.
CurrentPageChanged When the currently shown month or year is changed in the calender widget. The new year and month are passed as parameters.
CursorPositionChanged Is started when the cursor position in a textEdit document changes.
CurveDataError This script is triggered from each DPE, when receiving an error, while using dpGetPeriod, from the Data-Manager using (Available for: Trend).
CurvesScaled

CurvesScaled(dyn_string curves);

This Event will be activated after a timeout of 500ms and supplies in a dyn_string all curve names of a trend, which have been modified (Removing, Zoom etc.).
DoubleClicked

Left-double-click.

Note that if the MousePressed/MouseReleased event is also defined, this is triggered first.

If no DoubleClick script has been added a double click will trigger two separate simple clicks. This only applies to simple graphical objects as well as the push button.
DragDrop This event will be started when the user drops the information onto it and the shape notified the system before to accept the dropped media with dropAccept(). For more information, see chapter Drag & Drop at runtime.
DragEnter This event will only be started when the shape accepts drops (the acceptDrops attribute in the attribute editor has been set) and has not been disabled. The shape must decide if it is prepared to accept the dropped information. For more information, see chapter Drag & Drop at runtime.
DragStart

This event will only be started when the "Draggable" attribute of the attribute editor has been set to "TRUE". For more information, see chapter Drag & Drop at runtime.

Drop at runtime.

CAUTION: Note that you can drag the cells of a table to an object (for example, a textWidget) by default. If you, however, modify the dragStart event and add a code and then delete the code but not the entire script including main{}, you cannot drag the cells anymore. Bear in mind that you have to delete the entire script.
GestureTriggered The event is triggered when you swipe an embedded module (refer to Properties and events of the panel for a detailed description on this event)..
HeaderClicked Executes an event if a header of a table is clicked with the left mouse button.
Initialize When opened
Note: The order cannot be determined
KeyboardFocusOut When focus is lost
KeyboardFocusIn When focus is set
LangChanged When the language is changed.
ModificationChanged

ModificationChanged(bool mod)

This event will be started when the modification status of a textEdit document has changed. If mod is TRUE, the document was modified, otherwise the modification state has been reset to unmodified.
MousePressed

Left mouse button pressed. For primitive shapes the event can also be triggered by other available buttons. The exception is the right click, which has its own event. The button being used is specified in the mapping "event", which is passed to the script.

Note: To use the middle mouse button to activate scripts, panning must be deactivated with [ui] middleMousePanning.

This means that the script is started whenever the mouse button is pressed. Whether it will be released afterwards is irrelevant.

If the mouse cursor with pressed mouse button is moved outside of the button border (or a simple graphics object), the event is triggered each time the mouse cursor moves to the object.
MouseReleased

Left mouse button released. For primitive shapes the event can also be triggered by other available buttons. The exception is the right click, which has it's own event. The button being used is specified in the mapping "event", which is passed to the script.

Note: To use the middle mouse button to activate scripts, panning must be deactivated with [ui] middleMousePanning.

The script is started whenever the mouse button moves up. This can be either when the mouse button is released or when the mouse cursor is moved away from the button (or simple graphics object).

The event is triggered again after re-entering and again leaving the area of an object.
MouseOver

The mouse is moved over an object.

Note: Note that the MouseOver event contains the boolean parameter "enter" which is TRUE == when the mouse is moved over the object and FALSE == when the mouse leaves the object. This allows you to, for example, set different background colors depending on the position of the mouse.
OnButtonDblClk Left-double-click on a DPTree.
OnLButtonClk Left-click on a DPTree.

OnDpTypeChanging

OnDpTypeChanged

 OnDpTypeChanging will be executed when using the DPTree and the createDpType() function has been called. This means that if a data point type has been created. OnDpTypeChanged again will be executed when the dpTypeEditor() has been called and the data point type was created (the OK button was pressed).
Resized Is executed when the objects size has been changed
ReturnPressed Is executed when the return key is pressed in a textEdit document.
RightMousePressed Right-click
Scrolled To be able to only query and display data you can currently see and to avoid extensive queries that could take a long time, a scrolled event has been implemented. Thus, data will be requested for an area of a table widget when you scroll to that area and not before. The scrolled event is executed 0.3 seconds after you stop scrolling the table. Note that the table must be filled with rows.
SelectionChanged

When changing the tab or whenever the "selected" state of a primitive shape changes, either interactively by the user selecting the shape or by the CTRL programmer setting the "selected" attribute programmatically. See Multiselection at run time.

Or whenever the selected lines of a table are changed, for example, via keyboard MultiSelections. Note that you have to use the following functions when using the event SelectionChanged:

TABLE1.tableMode

(TABLE_SELECT_MULTIPLE);

TABLE1.selectByClick(3);
Slide When you slide the slider.
TextChanged

This event type only exists for the graphic objects textEdit and text field. The event is called whenever the user types something or text is changed via Control code.

To access the new text inside the event the event parameter newText must be used.
TabCloseRequested Only available for the tab widget. The event will be activated when a tab will be closed.
Wheel

Wheel(mapping event)

The "Wheel" event can be used to react to inputs made with the mouse wheel. It is only available for the panel. An example can be found here.

The "event" mapping contains following information:

Key Values
type "Wheel"
buttons

MOUSE_LEFT

MOUSE_RIGHT

MOUSE_MIDDLE

Represents the button states when the event was triggered. The "buttons" state is an OR combination of the MOUSE_* elements above.
buttonsAsString

“LeftButton”

“RightButton”

“MiddleButton”

The Names of the buttons that are pressed while triggering the event as strings. If multiple buttons are pressed they are returned as one string divided by the "|" character.
modifiers

KEY_SHIFT

KEY_CONTROL

KEY_ALT

KEY_META

Represents the keyboard modifier states when the event was triggered. The "modifiers" state is an OR combination of the KEY_* elements above.
modifiersAsString

”ShiftModifier”

”ControlModifier”

”AltModifier”

“MetaModifier”

The Names of the keyboard keys that are pressed while triggering the event as strings. If multiple keys are pressed they are returned as one string divided by the "|" character.
localPos X,Y mapping of the relative position on the panel.
globalPos X,Y mapping of the position on the global screen.
angleDelta

X,Y mapping of the mouse wheel rotation.

Returns the distance that the wheel is rotated, in eighths of a degree. A positive value indicates that the wheel was rotated forwards away from the user; a negative value indicates that the wheel was rotated backwards toward the user. Most mouse types work in steps of 15 degrees, in which case the delta value is a multiple of 120; i.e.:

120 units * 1/8 = 15 degrees.
isSynthesized Returns TRUE if the event is triggered by a "touch" event.

  • Events that are triggered when the panel is opened during initialization (Initialize). If the script has been defined for panel properties and not for graphic objects, then Initialize will not be executed.

  • Click events that are triggered by user actions (clicking with the mouse).

  • Events that are triggered when the slider position is changed (Change).

  • Events that are triggered by the focus position (KeyboardFocusIn, KeyboardFocusOut).

  • Alarm events that are triggered by an alert status.

  • Events that are triggered when the tab is changed (SelectionChanged)

  • Events that are triggered when panels are closed (Terminate)

  • Events that are triggered when the language is changed (LangChanged).

  • Events that are triggered when the mouse is moved over an object.

The event DoubleClicked exists for a button but it is executed through a click, meaning there is no difference between a single and a double click. For tables, radio and check boxes, we also recommend to use either the event "Clicked" or "DoubleClicked".

Do not use the setInputFocus() function in scripts for KeyboardFocusIn.

Figure 1. Events for an object of type rectangle

NOTE

It is only possible to assign a script to an event of the type "Acknowledge" through the wizards. Since this script is used for alarms, it has to have a specific format and cannot be edited with the script editor.

If there are 2 scripts running parallel when using KeyboardFocusOut (KeyboardFocusOut of the shape that looses the focus and Clicked of the shape that gets the focus), then WinCC OA ensures that the KeyboardFocusOut script will be started first.

It is not allowed to call a function, that changes the visibility, enabled property or the focus of the object, in KeyboardFocusOut and KeyboardFocusIn scripts.

The graphics objects combo box and list do not contain the event "Clicked" but "Changed".

Wheel Event Example

Following example demonstrates how the Wheel event could be used to zoom your panel.

main(mapping event)
{
 float factor = (event.angleDelta.y / 120.0) * 1.1;
 if ( factor > 0.0 )
   panelZoomIn(myModuleName(), factor, event.localPos);
 else



   panelZoomOut(myModuleName(), -factor, event.localPos);
}