uiConnect()

The function allows you 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()

Synopsis

int uiConnect(string|function_ptr callback, function_ptr event)

int uiConnect(string|function_ptr callback, string|shape source, string event)

int uiConnect(string|shape target, string callback, string|shape source, string event)

int uiConnect(class target, string|function_ptr callback, string|shape source, string event);

int uiConnect(string|function_ptr callback, string ui_eventName)

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.
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.
ui_eventName Name of a predefined UI manager global events. See description below.

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" - A new file has been added to the project
  • "fileRemoved" - A file has been removed from the project
  • "projectViewReloaded" - The Project View has been reloaded
  • "windowMoved" -The windows is moved. The event returns a mapping which must be handled by the callback function.
  • "windowResized" - The window has been resized. The event returns a mapping which must be handled by the callback function.
  • "windowStateChanged" - The window state has been changed. The event returns a mapping which must be handled by the callback function.
  • "colorSchemeChanged" - The color scheme has changed.
  • "iconThemeChanged" - The icon theme has changed.
"fileAdded", "fileRemoved"

A file has been added to or 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", "colorSchemeChanged", "iconThemeChanged"

The Project View has been reloaded or the color scheme / icon theme has been changes.

These events do not return any additional argument to the callback.

"windowMoved", "windowResized", "windowStateChanged"

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"

Deactivating or a activating a panel does not trigger the "windowStateChanged" event.

Note: Additional information on custom events can be found under Object-Oriented Panel References.

windowMoved

In the following example the callback function "myCallbackFunction" is triggered if the window is moved (UI global event "windowMoved"). In the callback function a corresponding output is written to the LogViewer.

main()
{
  uiConnect("myCallbackFunction", "windowMoved");
}

myCallbackFunction(mapping event)
{
  string s;
  getValue(event.panel, "panelFileName", s);
  DebugN("panelFileName", s);  DebugN("Window moved!");
}

triggered

The reference "ref_button_trigger_event" contains an event called "triggered". The event is triggered when a button is clicked. The main panel uiConnect_class_method receives the event in an instance of the class CallbackClass and starts here the own method "callback".

  • The Referenz "ref_button_trigger_event" contains an event with the name "triggered".

    The scopelib of the panel "ref_button_trigger_event":

    #event triggered()

  • The event is triggered when a button is clicked.

    The button of the panel "ref_button_trigger_event":

    main(mapping event)
{
  triggerEvent("triggered");
}

  • The main panel receives the event in an instance of the class CallbackClass and starts here the own method "callback".

    The scopelib of the panel "uiConnect_class_method":

    class CallbackClass
{
  public connect(shape source)
  {
    /* whenever the given source triggers the "triggered" event, our own
       callback method will be started */
    uiConnect(this, callback, source, "triggered");
  }
  callback()
  {
    DebugN("callback triggered");
  }
};

CallbackClass cb;  // instance with lifetime of the panel

  • The main panel uiConnect_class_method starts the local method "callback" here.

    The initialize script of the panel "uiConnect_class_method":

    main()
{
  cb.connect(getShape("PANEL_REF1"));
}

Assignment

OOP

Availability

UI, CTRL

Return value

uiConnectUserData(), uiDisconnect()