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

Acknowledge When acknowledged

Activated When the user presses the Return or Enter key or double-clicks a date in the calendar widget.

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.

Change Change of slider position.

Changed When an item of a selection list is selected.

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.

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 calendar 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 widget).

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:

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.

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, 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 in which objects are initialized within the context cannot be determined!

KeyboardFocusIn When focus is set on an object

KeyboardFocusOut When focus of an object is lost

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.

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.

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 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.

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.

OnButtonDblClk Left-double-click on a DPTree.

OnDpTypeChanging
OnDpTypeChanged

OnDpTypeChanging will be executed when using the DpTreeView and the createDpType() function has been called, meaning when a data point type has been created.

In contrast, OnDpTypeChanged will be executed when the dpTypeEditor() has been called and the data point type was created there (the OK button was pressed).

OnLButtonClk Left-click on a DpTreeView.

Resized Is executed when the object's 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:

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.

TabCloseRequested Only available for the tab widget. The event is activated when closing a tab is attempted.

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.

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 the 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.

Event Trigger

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.

Note:

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.

Note:

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

Figure 1. Events for an object of type rectangle

Notes

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.

Note:

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

Restriction:

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.

Note:

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

Wheel Event Example

The 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);
}