uiConnectUserData()

The function allows to connect to a specific event with a callback function and call this callback function in case the connected event is triggerd. This is a similar behavior to e.g. dpConnect(). Additionally to uiConnect() specific user data can be passed to the callback function.

Synopsis

int uiConnectUserData(string|function_ptr callback, anytype userData, function_ptr event)

int uiConnectUserData(string|function_ptr callback, anytype userData, string|shape source, string event)

int uiConnectUserData(string|shape target, string callback, anytype userData, string|shape source, string event)

int uiConnectUserData(class target,string|function_ptr callback, anytype userData, string|shape source, string event)

Parameters

Parameter Description
callback Name or pointer for the callback function that should be triggered in case of the event.
target The object or the shared_ptr of an object and the method that should be called.
userData The given user data which must be used as first argument of the callback function.
event Event for which the callback should be used. The event is triggered by using the triggerEvent() Function.
source

Object which has to trigger the event. Can be stated as string or shape.

Note: The usage of a shape object has an increased performance.
target

Target object which calls the callback function for the event. Can be stated as string or shape.

Note: The usage of a shape object has an increased performance.

Return value

The function returns 0 on being successful and -1 in case of an error.

Errors

Wrong or missing arguments.

Description

The function is used to react to specific events inside of the UI. These events can either be custom events using the triggerEvent() function or UI global events.

UI Global Events

Following UI global events are available:

"fileAdded", "fileRemoved"

A file has been added to or was removed from the project.

These events return an absolute path to the file that has been added or removed as string argument inside of the callback.

"projectViewReloaded"

The Project View has been reloaded.

This event does not return any additional argument to the callback.

"windowMoved", "windowResized", "windowStateChanged"

The window has been moved, resized or the windows state has changed.

Some of these events return a mapping which contains additional information as seen below.

Mapping content

General mappinng content
  • mapping.type = "windowMoved"
  • mapping.moduleName - Name of the module
  • mapping.panel = "ModuleName.PanelName:" - Absolute scripting "path" to the panel, used e.g. for getValue()
  • mapping.panelName - Name of the panel
"windowMoved" specific content
  • mapping.pos.(x, y) - Position of the panel excluding the window frame
  • mapping.oldPos.(x, y) - Previous position of the panel excluding the window frame

The windowMoved event is always triggered if the content of the window is redrawn, i.a. by default the event is triggered multiple times when moving a panel. To only get an event if the movement is finished and the mouse has been released changes to the OS settings are required. For Windows following setting must be deactivated: Advanced System properties > Performance > Show window contents while dragging.

"windowResized" specific content
  • mapping.size.(width, height) - Panel size excluding the window frame
  • mapping.oldSize.(width, height) - Previous panel size excluding the window frame
"windowStateChanged" specific content
  • mapping.state - Currently applied window states, see "windowState"
  • mapping.oldState - Previously applied window states, see "windowState"
Note: Additional information on custom events can be found under Object-Oriented Panel References.

Using the Object Oriented Panel References the event "#event valueChanged(int value)" has been specified. A connection is then established by using uiConnectUserData() as followed:

uiConnectUserData("callback", "myUserData", MY_PANEL.valueChanged);

The callback now needs to have following syntax to handle the expected user data:

callback(string userData, int value)

For an example where a class is used, see chapter uiConnect().

Assignment

OOP

Availability

UI, CTRL

Return value

uiConnect(), uiDisconnect()