Handling .NET Events (Magic xpa 4.x)
At runtime, .NET objects can trigger events. The Magic xpa event handlers can handle these events.
There are the common events available in most .NET controls, such as OnMouseClick, and there are others that are specific to that control. Within Magic xpa you can catch or trap the .NET events and handle them, a capability that allows you different levels of interaction with a .NET object.
To handle a .NET event create a handler, and set its type to .NET.
You can select a .NET event by defining the .NET variable or a .NET class.
Instead of creating a handler for each control, you can synchronize the .NET control and the Magic xpa field without any logic. You do this by creating a .NET model and setting the binding properties.
If the event handler is defined for a .NET variable, then the handler will be a specific handler for the selected variable.
If the event handler is defined without specifying a .NET variable, then the handler will be a general handler for any instance of the object in the task or the runtime task tree. This is useful in Main Program logic units.
Note: This is referring to object-level events of any object, rather than static events.
When you select the event to be handled, Magic xpa checks if the object passes an argument. If an argument is passed, Magic xpa offers to automatically create parameter variables according to the passed arguments of the event.
In the selection list of available events, you will see that some events are similar to Magic xpa events, such as OnDoubleClick, which is similar to the Magic xpa DblClick event. When using a .NET control, handle the .NET event and not the Magic xpa event.
In Magic xpa, you can handle an event and then propagate the event so it will be handled in a parent task in the Runtime task tree. This is the same when using .NET objects, which are controls on the form.
To handle the event in a parent task, you can define a logic unit for the .NET object type. When you have .NET objects that are not controls on the form, the .NET object can be referenced from different variables in different tasks, for example, when passing the variable as a parameter to a task. When an event is raised by the .NET object, it will be handled in all the tasks that have a variable referencing to that object. There is no propagation for these events, so if you want to handle the event in a parent task, you will need to have a reference to that object in the parent task as well.
Magic xpa distinguishes between two types of .NET objects and reacts accordingly.
-
For .NET objects that are placed on the form:
Events on .NET controls are handled as Magic xpa events.
This means you can use the Propagate property for them by simply selecting the Object type in the parent task.
-
For .NET objects that are not placed on the form:
Since two different .NET variables can refer to the same .NET object, whenever the .NET object raises an event, Magic xpa will raise the event in each task in which the variable is defined.
For example, If you have var A in prog 1 and var B in prog 2 and var B is updated by var A (by sending A as an argument to prog 2) and both progs have handlers on a .NET event, then whenever the .NET object raises the event, it will be handled in both progs.
In Online, the events will be raised in all contexts and in Rich Client, only in the current context.
Since version: 2.1
-
The Propagate and Scope properties are not relevant for such events.
-
If a task has only a handler defined, with no variable defined, the event will not be raised in that task, meaning the handler will never be used.
-
It is possible to use a generic handler for a .NET class in a task, but in order for it to work, the variables from that class should be defined in that task.
The .NET event may have arguments as in Magic xpa events.
When defining a handler for a .NET event, in most cases (depending on the event), two arguments (sender and e) are added to the handler. The sender is the object that raises the event and the e is the event arguments. Now, the sender has a .NET type of 'Object'. This is a generic object, and it is not easy to manipulate.
These arguments only exist for the scope of the logic.
Using the DNCast() function to cast the object type into a specific .NET object, such a: 'System.Windows.Forms.TextBox' will let you refer to this object and get all the properties/methods of 'System.Windows.Forms.TextBox'.
You can even use them directly after the DNCast function, for example: DNCast(A,DotNet.System.Windows.Forms.TextBox).Text
Note: .NET events are handled asynchronously. This means that updating the event parameters will not affect the object that raised the event.
