External Event (Magic xpa 4.x)
This event is raised from external 3rd party software. The event enables easier integration between Magic xpa and external programs running on the same computer, by enabling Magic xpa to receive and process events and data from external programs.
This event is triggered upon receiving a Windows message or upon activating the JavaScript function of the MGExternal event in a Browser client task.
From inside your HTML, you can use the special script called MGExternalEvent. Calling this script will activate Magic xpa's event called External Event, and pass the parameters you specified.
The MGExternalEvent function provided by the Browser Client JS module enables Magic xpa to invoke the Magic xpa External Event from an external JS module that is executed from a Browser Client page. When the MGExternalEvent function is executed, the External Event is added to the Magic xpa event queue and is recognized as a regular Magic xpa event.
|
Syntax:
|
MGExternalEvent(parameter 1, parameter 2)
|
|
Parameters:
|
parameter: A string value passed as a parameter. The passed values will be received by the Handler’s virtual variables according to their order. There is no limit to the number of parameters allowed.
|
|
Returns:
|
The function returns a True value if the Browser Client is loaded or a False value if the Browser Client cannot be loaded.
|
This event is an alternative to the Browser Status Text Change event, which is blocked by default in Internet Explorer 7.
This event can be raised from within a script in the Browser control's HTML page by using the following syntax:
window.external.MGExternalEvent(parameter)
As opposed to Browser Client tasks, in Rich Client tasks, only one BLOB Unicode parameter can be sent.
Since version: 1.8
See also: the HG45 and RHG45 sample programs in the Online and RIA samples
On Android devices, this event can be raised from a Browser control using the following syntax (as in RIA desktop):
window.external.MGExternalEvent(parameter)
On iOS devices, this event can be raised from a Browser control using the following syntax
window.location.href=’MGExternalEvent:’+parameter
In the example below, a VBScript script calls the MGExternalEvent script, passing three parameters, the Day, Month, and Year. The event handler catches those three parameters, and responds by updating a field and refreshing the screen.
Note that in Rich Client, only one parameter can be sent, so you should concatenate those values into one string.
Raising an external event in Magic xpa is done using a SendMessage window API command with the WM_COPYDATA message type. This message contains a pointer to a COPYDATASTRUCT structure. Magic xpa places these parameters into the event queue, and the handler receiving the event receives its parameters.
COPYDATASTRUCT Format – This structure contains the three members listed below:
-
dwData – number indicating the number of parameters sent
-
lpData – pointer to a buffer containing the parameters
-
cbData – length of data in lpData.
Parameters – The parameters placed in the cbData member are placed as null terminated strings in the buffer. Magic xpa accepts four types of parameters:
-
-A – Alpha parameter
-
-N – Whole numeric parameter
-
-F – Floating point parameter
-
-L – Logical parameter (T or F values)
Example: Suppose we are to send 4 parameters containing “XXX”, 17, True, 643.23. The created buffer should be in the following form:
-AXXX?-N17?-LT?-F643.23?
Where the ? sign, represents a null character.
To handle the external event, you need to create a handler on the ‘External event’ part of the Internal type of events. In this handler you can create the virtual variables that will receive the passed arguments.
The Magic xpa installation provides an executable file, Msg2mgic.exe, that demonstrates the invocation of the external event in Magic xpa. For more information, see MSG2MGIC Utility.
The External Event has no default Keyboard Mapping.
How Do I Interact with a Web Page Running in a Browser Control?
