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